@gotcos/glasses-server 6.94.4 → 6.98.0

package/server/lib/speaker-shadow-numeric.ts

@@ -0,0 +1,143 @@
+// Python-compatible numerics for the speaker shadow port (6.95.0).
+//
+// The shadow gates are a byte-for-byte port of the research tool
+// (community-1-fluidaudio-v1/scripts/hybrid.py and round3/propose.py), which ran on
+// CPython 3.15. Four Python behaviours differ from the obvious JavaScript and each one
+// changes a gate or a reason string on real meetings, so each is replicated here:
+//
+//   1. `round(x)` and `round(x, n)` round half to EVEN on the exact binary value.
+//      Math.round and toFixed round half up, and `coveredFraction`, `majority` and
+//      `seconds` are compared AFTER rounding (0.7996 rounds to 0.8 and passes 0.8).
+//   2. `'%.2f' % x` is correctly rounded half to even as well: 0.125 formats as 0.12,
+//      where (0.125).toFixed(2) is 0.13.
+//   3. `sum()` of floats is Neumaier-compensated since CPython 3.12, so a plain loop
+//      drifts in the last bits of every cosine distance and norm.
+//   4. String order is by code point, not UTF-16 unit.
+//
+// No I/O and no clock. Verified against CPython 3.15 vectors in speaker-shadow-numeric.test.ts.
+
+const view = new DataView(new ArrayBuffer(8))
+
+/** x = (neg ? -1 : 1) * mant * 2^exp, exactly. Finite x only. */
+function decompose(x: number): { neg: boolean; mant: bigint; exp: number } {
+  view.setFloat64(0, x)
+  const hi = view.getUint32(0), lo = view.getUint32(4)
+  const neg = hi >>> 31 === 1
+  const biased = (hi >>> 20) & 0x7ff
+  let mant = (BigInt(hi & 0xfffff) << 32n) | BigInt(lo)
+  let exp: number
+  if (biased === 0) exp = -1074
+  else { mant |= 1n << 52n; exp = biased - 1075 }
+  return { neg, mant, exp }
+}
+
+/** |x| * 10^digits rounded half to even, as an exact integer. */
+function scaledHalfEven(x: number, digits: number): { neg: boolean; q: bigint } {
+  const { neg, mant, exp } = decompose(x)
+  let num = mant * 10n ** BigInt(digits)
+  let den = 1n
+  if (exp >= 0) num <<= BigInt(exp)
+  else den <<= BigInt(-exp)
+  let q = num / den
+  const twice = (num % den) * 2n
+  if (twice > den || (twice === den && (q & 1n) === 1n)) q += 1n
+  return { neg, q }
+}
+
+function decimalString(neg: boolean, q: bigint, digits: number): string {
+  let text = q.toString()
+  if (digits > 0) {
+    text = text.padStart(digits + 1, '0')
+    text = `${text.slice(0, -digits)}.${text.slice(-digits)}`
+  }
+  return neg ? `-${text}` : text
+}
+
+/** Python `'%.{digits}f' % x`. */
+export function pyFixed(x: number, digits: number): string {
+  if (Number.isNaN(x)) return 'nan'
+  if (!Number.isFinite(x)) return x > 0 ? 'inf' : '-inf'
+  const { neg, q } = scaledHalfEven(x, digits)
+  return decimalString(neg, q, digits)
+}
+
+/** Python `round(x, digits)` for digits >= 1 (a float). */
+export function pyRound(x: number, digits: number): number {
+  if (!Number.isFinite(x)) return x
+  const { neg, q } = scaledHalfEven(x, digits)
+  return Number.parseFloat(decimalString(neg, q, digits))
+}
+
+/** Python `round(x)` with no digits (an int, half to even). */
+export function pyRoundInt(x: number): number {
+  const floor = Math.floor(x)
+  const fraction = x - floor
+  if (fraction > 0.5) return floor + 1
+  if (fraction < 0.5) return floor
+  return floor % 2 === 0 ? floor : floor + 1
+}
+
+/**
+ * CPython (>= 3.12) `sum()` of floats from the int start 0: the first item is added to
+ * 0 exactly, then Neumaier's improved Kahan-Babuska compensation, and the compensation is
+ * added once at the end only when it is finite and non-zero (Python/bltinmodule.c).
+ * Integral JSON values (only exact zeros occur in FluidAudio output) contribute nothing
+ * under either of CPython's int and float paths, so treating them as floats is exact.
+ */
+export function pySum(values: ArrayLike<number>): number {
+  const n = values.length
+  if (n === 0) return 0
+  let total = 0 + values[0]
+  let compensation = 0
+  for (let i = 1; i < n; i++) {
+    const x = values[i]
+    const t = total + x
+    if (Math.abs(total) >= Math.abs(x)) compensation += (total - t) + x
+    else compensation += (x - t) + total
+    total = t
+  }
+  if (compensation !== 0 && Number.isFinite(compensation)) total += compensation
+  return total
+}
+
+/** Python str ordering (by code point). */
+export function codePointCompare(a: string, b: string): number {
+  if (a === b) return 0
+  const n = Math.min(a.length, b.length)
+  for (let i = 0; i < n;) {
+    const ca = a.codePointAt(i)!, cb = b.codePointAt(i)!
+    if (ca !== cb) return ca < cb ? -1 : 1
+    i += ca > 0xffff ? 2 : 1
+  }
+  return a.length < b.length ? -1 : a.length > b.length ? 1 : 0
+}
+
+/** Python `str.isspace()` characters, which is what `\s` matches in a str pattern. */
+export const PY_SPACE_CLASS = '[\\t\\n\\v\\f\\r\\x1c-\\x1f \\x85\\xa0\\u1680\\u2000-\\u200a\\u2028\\u2029\\u202f\\u205f\\u3000]'
+/** Python `re.compile(r'Voice\s*\d+').fullmatch` (Unicode `\s` and `\d`). */
+export const PY_VOICE_LABEL = new RegExp(`^Voice${PY_SPACE_CLASS}*\\p{Nd}+$`, 'u')
+
+const ND = /^\p{Nd}$/u
+/** Python `int(re.findall(r'\d+', label)[0])`, or null when the label has no digit. */
+export function pyFirstInt(label: string): number | null {
+  const run = /\p{Nd}+/u.exec(label)
+  if (!run) return null
+  let value = 0
+  for (const ch of run[0]) {
+    const cp = ch.codePointAt(0)!
+    // Unicode keeps every decimal digit set as ten contiguous code points from its zero,
+    // and adjacent sets (mathematical digits) are whole multiples of ten.
+    let zero = cp
+    while (zero > 0 && ND.test(String.fromCodePoint(zero - 1))) zero--
+    value = value * 10 + ((cp - zero) % 10)
+  }
+  return value
+}
+
+/** Python `'%d:%02d:%02d' % (h, m, s) if h else '%d:%02d' % (m, s)` after `int(round(sec))`. */
+export function pyClock(seconds: number): string {
+  const sec = pyRoundInt(seconds)
+  const h = Math.floor(sec / 3600), m = Math.floor(sec / 60) % 60, s = sec % 60
+  const two = (n: number) => String(n).padStart(2, '0')
+  return h ? `${h}:${two(m)}:${two(s)}` : `${m}:${two(s)}`
+}

package/server/lib/speaker-shadow-pair-source.ts

@@ -0,0 +1,91 @@
+// Bounded read-only clock diagnostics. File dates and timestamps are not alignment proof.
+import { open, readdir, lstat } from 'node:fs/promises'
+import { constants } from 'node:fs'
+import { basename, dirname, join } from 'node:path'
+import { createHash } from 'node:crypto'
+
+export interface ShadowPairSource {
+  status: 'time_only' | 'ambiguous' | 'unpaired'
+  reason: string
+  sessionId?: string
+  sourceSha256?: string
+  g2?: { startTime: number; chunks: Array<{ speaker: string; elapsed: number; audioDurationMs: number }> }
+}
+const finite = (n: unknown): n is number => typeof n === 'number' && Number.isFinite(n)
+function bounds(value: Record<string, unknown>, durationOverride?: number): [number, number] | null {
+  if (!finite(value.startTime) || !Array.isArray(value.chunks)) return null
+  const duration = durationOverride ?? value.durationMs
+  if (!finite(duration) || duration <= 0 || duration > 4 * 3600_000) return null
+  return [value.startTime, value.startTime + duration]
+}
+const day = (ms: number) => { const d = new Date(ms); return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}` }
+/** Only the current recording directory is searched; absent cross-month pairs remain unpaired. */
+export async function findShadowPairSource(sidecarPath: string, mac: Record<string, unknown>, durationMs?: number): Promise<ShadowPairSource> {
+  const target = bounds(mac, durationMs)
+  if (!target) return { status: 'unpaired', reason: 'invalid Mac clock or duration' }
+  const dir = dirname(sidecarPath)
+  // Official sidecars use this Mac's local calendar-day prefix. Include a four-hour
+  // lookback for a G2 capture that started before this Mac capture (maximum call length).
+  const days = new Set([day(target[0] - 4 * 3600_000), day(target[0]), day(target[1])])
+  const all = await readdir(dir)
+  const names = all.filter(n => n.endsWith('.g2-chunks.json') && n !== basename(sidecarPath))
+    .filter(n => { const prefix = n.match(/^(\d{4}-\d{2}-\d{2})_/); return !prefix || days.has(prefix[1]) }).sort()
+  if (names.length > 256) return { status: 'ambiguous', reason: 'day-window discovery file limit exceeded; no pair selected' }
+  let bytes = 0, estimated = false
+  const candidates: ShadowPairSource[] = []
+  for (const name of names) {
+    const path = join(dir, name)
+    let raw: string, value: Record<string, unknown>
+    try {
+      const stat = await lstat(path)
+      if (!stat.isFile() || stat.isSymbolicLink()) return { status: 'ambiguous', reason: 'unreadable day-window candidate; no pair selected' }
+      if (stat.size > 16 * 1024 * 1024 || bytes + stat.size > 128 * 1024 * 1024) return { status: 'ambiguous', reason: 'day-window discovery byte limit exceeded; no pair selected' }
+      const parts: Buffer[] = []
+      let size = 0
+      // A candidate can change between lstat and open. Never wait on a FIFO/device
+      // substituted in that interval; verify the actual descriptor before reading.
+      const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK)
+      try {
+        if (!(await handle.stat()).isFile()) throw new Error('candidate is no longer a regular file')
+        const buffer = Buffer.alloc(64 * 1024)
+        while (true) {
+          const { bytesRead } = await handle.read(buffer)
+          if (!bytesRead) break
+          size += bytesRead
+          if (size > 16 * 1024 * 1024 || bytes + size > 128 * 1024 * 1024) throw new Error('candidate grew beyond byte budget')
+          parts.push(Buffer.from(buffer.subarray(0, bytesRead)))
+        }
+      } finally { await handle.close() }
+      raw = Buffer.concat(parts).toString('utf8')
+      bytes += size
+      if (Buffer.byteLength(raw) > 16 * 1024 * 1024 || bytes > 128 * 1024 * 1024) return { status: 'ambiguous', reason: 'day-window discovery changed beyond byte limit; no pair selected' }
+      const parsed: unknown = JSON.parse(raw)
+      if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) throw new Error('invalid sidecar')
+      value = parsed as Record<string, unknown>
+      if (typeof value.sessionId !== 'string') throw new Error('missing source identity')
+    } catch { return { status: 'ambiguous', reason: 'unreadable or malformed day-window candidate; no pair selected' } }
+    if (typeof value.sessionId !== 'string' || !value.sessionId.startsWith('meeting_') || value.finalizationState !== 'complete') continue
+    const span = bounds(value)
+    if (!span) return { status: 'ambiguous', reason: 'complete G2 candidate lacks valid clock/duration; no pair selected' }
+    const overlap = Math.max(0, Math.min(target[1], span[1]) - Math.max(target[0], span[0]))
+    const macDuration = target[1] - target[0], g2Duration = span[1] - span[0]
+    if (overlap / Math.max(macDuration, g2Duration) < .5 || Math.min(macDuration, g2Duration) / Math.max(macDuration, g2Duration) < .5) continue
+    const chunks: NonNullable<ShadowPairSource['g2']>['chunks'] = []
+    for (const item of value.chunks as unknown[]) {
+      if (!item || typeof item !== 'object') return { status: 'ambiguous', reason: 'invalid G2 chunk; no pair selected' }
+      const row = item as Record<string, unknown>
+      if (typeof row.speaker !== 'string' || !finite(row.elapsed) || row.elapsed < 0) return { status: 'ambiguous', reason: 'invalid G2 timing or label; no pair selected' }
+      const exactDuration = row.audioDurationMs ?? row.durationMs
+      if (exactDuration !== undefined && (!finite(exactDuration) || exactDuration <= 0 || (row.audioDurationMs !== undefined && row.durationMs !== undefined && row.audioDurationMs !== row.durationMs))) return { status: 'ambiguous', reason: 'invalid G2 duration; no pair selected' }
+      // Historical G2 sidecars lack chunk durations: disclose the fixed-window
+      // approximation. This function can NEVER qualify alignment or transfer a name.
+      const duration = exactDuration === undefined ? 6000 : exactDuration as number
+      estimated ||= exactDuration === undefined
+      chunks.push({ speaker: row.speaker, elapsed: row.elapsed, audioDurationMs: duration })
+    }
+    candidates.push({ status: 'time_only', reason: '', sessionId: value.sessionId, sourceSha256: createHash('sha256').update(raw).digest('hex'), g2: { startTime: span[0], chunks } })
+  }
+  const scope = `Day-window scan: ${names.length} files, ${bytes} bytes, current directory only.`
+  return candidates.length === 1 ? { ...candidates[0], reason: `Clock overlap only; text offset/drift alignment has not been qualified. G2 names are estimates.${estimated ? ' G2 chunk durations use an approximate 6-second window where absent.' : ''} ${scope}` }
+    : { status: candidates.length ? 'ambiguous' : 'unpaired', reason: `${candidates.length ? `${candidates.length} overlapping G2 candidates; no pair chosen` : 'no complete overlapping G2 capture'}. ${scope}` }
+}

package/server/lib/speaker-shadow-paired.ts

@@ -0,0 +1,268 @@
+/** Paired G2/Mac diagnostics only. No remap, identity proof, meeting write or training. */
+import { checkSpeakerName } from './speaker-name.js'
+import { SHADOW_GATES, SHADOW_SAMPLE_RATE, isShadowVoiceLabel, type ShadowAccepted, type ShadowSegment, type ShadowTurn, type ShadowVoiceEntry } from './speaker-shadow-decide.js'
+
+export const PAIRED_SHADOW_GATES = Object.freeze({ nameAllSpeechFraction: 0.8, nameSupportSeconds: 30, shortMinSeconds: 5, shortMaxSeconds: 15, shortAnchorRatio: 1.1 })
+export type ShadowPairAlignment =
+  | { status: 'qualified'; evidenceId: string; offsetMs: number; maxErrorMs: number }
+  | { status: 'unpaired' | 'ambiguous' | 'time_only' }
+export interface ShadowG2Chunk { speaker: string; elapsed: number; audioDurationMs?: number; durationMs?: number }
+export interface ShadowG2Recording { startTime: string | number; chunks: readonly ShadowG2Chunk[] }
+/** Raw anchorRatio is required for short nominations. Rounded compatibility values cannot qualify them. */
+export type PairedShadowAcousticEvidence = ShadowVoiceEntry & { anchorRatio?: number | null }
+export interface PairedShadowInput {
+  macStartTime: string | number
+  totalSamples: number
+  segments: readonly ShadowSegment[]
+  regularTurns: readonly ShadowTurn[]
+  /** Final accepted groups only; rejected/co-located voices must not be added here. */
+  acceptedGroups: readonly ShadowAccepted[]
+  /** Existing acoustic rows, including rejected short fragments. Never recomputed from names. */
+  voiceEvidence: readonly PairedShadowAcousticEvidence[]
+  g2?: ShadowG2Recording
+  alignment: ShadowPairAlignment
+}
+export interface PairedNameSupport { name: string; seconds: number; fractionOfAllSpeech: number; fractionOfKnownName: number }
+export interface PairedShadowAgreement {
+  allSpeechSeconds: number
+  knownNameSeconds: number
+  unknownOrUnpairedSeconds: number
+  conflictingG2Seconds: number
+  productionConflictSeconds: number
+  nativeUncoveredSeconds: number
+  nativeConflictSeconds: number
+  wrongClusterSeconds: number
+  names: PairedNameSupport[]
+  diagnosticTopName: string | null
+  diagnosticAllSpeechGate: boolean
+}
+export interface PairedShadowGroup extends PairedShadowAgreement {
+  agreementScope: 'accepted_voice_speech'
+  wholeCluster: PairedShadowAgreement & { scope: 'whole_native_cluster_speech' }
+  cluster: string
+  voices: string[]
+  candidateName: string | null
+  reasons: string[]
+}
+export interface PairedShadowVoice extends PairedShadowAgreement { voice: string; cluster: string | null }
+export interface PairedShadowSpan { startSample: number; endSample: number; cluster: string; candidateName: string }
+export interface PairedShadowShortCandidate { voice: string; cluster: string; candidateName: string; seconds: number }
+export interface PairedShadowReport {
+  mode: 'provisional_shadow_only'
+  alignmentStatus: ShadowPairAlignment['status']
+  candidateNominationAllowed: boolean
+  accuracyClaim: false
+  humanTruthClaim: false
+  warnings: string[]
+  groups: PairedShadowGroup[]
+  voices: PairedShadowVoice[]
+  extCandidates: PairedShadowSpan[]
+  shortCandidates: PairedShadowShortCandidate[]
+  shortWithheld: Array<{ voice: string; reasons: string[] }>
+}
+
+/** A plausible saved G2 name is still a machine label, never human ground truth. */
+export function isPairedShadowName(label: string): boolean {
+  const name = label.trim().replace(/\s+/gu, ' ')
+  if (/^(?:ext|unknown|mu|me|speaker(?:[\s_-]*(?:\d+|n))?|voice(?:[\s_-]*(?:\d+|n))?)$/iu.test(name)) return false
+  return checkSpeakerName(name).ok
+}
+
+type Row = readonly [number, number, string]
+type Counts = Map<string, number>
+interface Stats { all: number; known: number; unknown: number; conflict: number; production: number; uncovered: number; nativeConflict: number; wrong: number; names: Counts }
+const stats = (): Stats => ({ all: 0, known: 0, unknown: 0, conflict: 0, production: 0, uncovered: 0, nativeConflict: 0, wrong: 0, names: new Map() })
+const add = (map: Counts, key: string, amount: number) => { const n = (map.get(key) ?? 0) + amount; if (n) map.set(key, n); else map.delete(key) }
+const epoch = (value: string | number): number => typeof value === 'number' ? value : Date.parse(value)
+const finite = (value: unknown): value is number => typeof value === 'number' && Number.isFinite(value)
+const SR = SHADOW_SAMPLE_RATE
+
+function accumulate(s: Stats, amount: number, production: Counts, native: Counts, g2: Counts, cluster: string | null, allowUnlabelledProduction = false): void {
+  s.all += amount
+  const name = g2.size === 1 ? [...g2.keys()][0] : null
+  if (g2.size > 1) s.conflict += amount
+  else if (name && isPairedShadowName(name)) s.known += amount
+  else s.unknown += amount
+  if (production.size > 1) s.production += amount
+  if (!native.size) s.uncovered += amount
+  else if (native.size > 1) s.nativeConflict += amount
+  else if (cluster !== null && !native.has(cluster)) s.wrong += amount
+  if ((production.size === 1 || (allowUnlabelledProduction && production.size === 0)) && native.size === 1 && cluster !== null && native.has(cluster) && name && g2.size === 1 && isPairedShadowName(name)) add(s.names, name, amount)
+}
+
+function agreement(s: Stats): PairedShadowAgreement {
+  const names = [...s.names].map(([name, n]) => ({ name, seconds: n / SR, fractionOfAllSpeech: s.all ? n / s.all : 0, fractionOfKnownName: s.known ? n / s.known : 0 }))
+    .sort((a, b) => b.seconds - a.seconds || a.name.localeCompare(b.name))
+  const best = names[0]
+  const unique = !!best && (!names[1] || names[1].seconds !== best.seconds)
+  return { allSpeechSeconds: s.all / SR, knownNameSeconds: s.known / SR, unknownOrUnpairedSeconds: s.unknown / SR, conflictingG2Seconds: s.conflict / SR,
+    productionConflictSeconds: s.production / SR, nativeUncoveredSeconds: s.uncovered / SR, nativeConflictSeconds: s.nativeConflict / SR, wrongClusterSeconds: s.wrong / SR,
+    names, diagnosticTopName: unique ? best.name : null,
+    diagnosticAllSpeechGate: unique && best.fractionOfAllSpeech >= PAIRED_SHADOW_GATES.nameAllSpeechFraction && best.seconds >= PAIRED_SHADOW_GATES.nameSupportSeconds }
+}
+
+/**
+ * Sweep half-open sample intervals once. Duplicate same-label rows union; different
+ * simultaneous labels withhold votes. Every group/voice denominator includes its
+ * unknown, uncovered and conflicting time, so named-only percentages cannot qualify it.
+ * offsetMs adds to the G2 wall clock. Only caller-qualified alignment enables nominations;
+ * timestamp coincidence alone is diagnostic. maxErrorMs erodes G2 vote intervals.
+ */
+export function evaluatePairedSpeakerShadow(input: PairedShadowInput): PairedShadowReport {
+  if (!Number.isSafeInteger(input.totalSamples) || input.totalSamples <= 0 || input.totalSamples > 4 * 3600 * SR) throw new Error('invalid paired shadow timeline')
+  if (input.segments.length + input.regularTurns.length + (input.g2?.chunks.length ?? 0) > 100_000) throw new Error('paired shadow interval budget exceeded')
+  const warnings = new Set<string>()
+  let safe = true
+  const macStart = epoch(input.macStartTime)
+  if (!finite(macStart)) { warnings.add('invalid Mac startTime'); safe = false }
+  const align = input.alignment
+  let qualified = align.status === 'qualified' && !!align.evidenceId.trim() && finite(align.offsetMs) && finite(align.maxErrorMs) && align.maxErrorMs >= 0
+  if (align.status === 'qualified' && !qualified) { warnings.add('invalid qualified alignment evidence'); safe = false }
+  if (align.status !== 'qualified') warnings.add(`${align.status}: time alignment is uncertain; diagnostic only`)
+  // Time-only still reports wall-clock overlap; it cannot transfer names.
+  const offset = qualified && align.status === 'qualified' ? align.offsetMs : 0
+  const erosion = qualified && align.status === 'qualified' ? Math.ceil(align.maxErrorMs * SR / 1000) : 0
+  const production: Row[] = [], native: Row[] = [], paired: Row[] = []
+  const clip = (rows: Row[], lo: number, hi: number, label: string, source: string) => {
+    if (!Number.isSafeInteger(lo) || !Number.isSafeInteger(hi) || hi <= lo || typeof label !== 'string' || !label.trim()) { warnings.add(`invalid ${source} interval`); safe = false; return }
+    const a = Math.max(0, lo), b = Math.min(input.totalSamples, hi)
+    if (a < b) rows.push([a, b, label.trim().replace(/\s+/gu, ' ')])
+  }
+  for (const [lo, hi, label] of input.segments) clip(production, lo, hi, label, 'production')
+  for (const turn of input.regularTurns) clip(native, Math.round(turn.start * SR), Math.round(turn.end * SR), turn.speaker, 'native')
+  if (!input.g2) { warnings.add('no paired G2 recording'); qualified = false }
+  else {
+    const g2Start = epoch(input.g2.startTime)
+    if (!finite(g2Start)) { warnings.add('invalid G2 startTime'); safe = false }
+    for (const chunk of input.g2.chunks) {
+      const duration = chunk.audioDurationMs ?? chunk.durationMs
+      if (!finite(chunk.elapsed) || chunk.elapsed < 0 || !finite(duration) || duration <= 0 || (chunk.audioDurationMs !== undefined && chunk.durationMs !== undefined && chunk.audioDurationMs !== chunk.durationMs)) {
+        warnings.add('invalid or conflicting G2 elapsed/duration'); safe = false; continue
+      }
+      const lo = Math.round((g2Start - macStart + offset + chunk.elapsed) * SR / 1000) + erosion
+      const hi = Math.round((g2Start - macStart + offset + chunk.elapsed + duration) * SR / 1000) - erosion
+      // Entire interval inside alignment uncertainty contributes no name support.
+      if (hi <= lo && finite(lo) && finite(hi)) continue
+      clip(paired, lo, hi, chunk.speaker, 'G2')
+    }
+  }
+  const groups = new Map<string, { voices: string[]; stats: Stats; wholeStats: Stats }>()
+  const groupOfVoice = new Map<string, string>()
+  for (const group of input.acceptedGroups) {
+    const voices = [group.keepLabel, ...group.merge]
+    if (!group.cluster || groups.has(group.cluster) || new Set(voices).size !== voices.length || voices.some(v => !isShadowVoiceLabel(v) || groupOfVoice.has(v))) throw new Error('ambiguous accepted paired group')
+    groups.set(group.cluster, { voices, stats: stats(), wholeStats: stats() })
+    for (const voice of voices) groupOfVoice.set(voice, group.cluster)
+  }
+  const evidence = new Map<string, PairedShadowAcousticEvidence>()
+  for (const row of input.voiceEvidence) {
+    if (evidence.has(row.voice)) throw new Error('duplicate paired voice evidence')
+    evidence.set(row.voice, row)
+  }
+  const byVoice = new Map<string, Stats>()
+  for (const [, , label] of production) if (isShadowVoiceLabel(label) && !byVoice.has(label)) byVoice.set(label, stats())
+  type Event = { at: number; kind: number; label: string; delta: number }
+  const events: Event[] = []
+  for (const [kind, rows] of [production, native, paired].entries()) for (const [lo, hi, label] of rows) {
+    events.push({ at: lo, kind, label, delta: 1 }, { at: hi, kind, label, delta: -1 })
+  }
+  events.sort((a, b) => a.at - b.at)
+  const active = [new Map<string, number>(), new Map<string, number>(), new Map<string, number>()]
+  const ext: Array<{ lo: number; hi: number; cluster: string; name: string }> = []
+  for (let i = 0; i < events.length;) {
+    const at = events[i].at
+    while (i < events.length && events[i].at === at) { const event = events[i++]; add(active[event.kind], event.label, event.delta) }
+    const end = events[i]?.at
+    if (end === undefined || end <= at) continue
+    const touched = new Set<string>()
+    for (const voice of active[0].keys()) {
+      const s = byVoice.get(voice)
+      if (s) accumulate(s, end - at, active[0], active[1], active[2], evidence.get(voice)?.topCluster ?? groupOfVoice.get(voice) ?? null)
+      const group = groupOfVoice.get(voice)
+      if (group) touched.add(group)
+    }
+    for (const cluster of touched) accumulate(groups.get(cluster)!.stats, end - at, active[0], active[1], active[2], cluster)
+    // Full native-cluster union includes Ext, rejected/named labels and no-ASR time.
+    // Concurrent different clusters/production labels remain in the denominator but cannot vote.
+    for (const cluster of active[1].keys()) {
+      const group = groups.get(cluster)
+      if (group) accumulate(group.wholeStats, end - at, active[0], active[1], active[2], cluster, true)
+    }
+    if (active[0].size === 1 && active[0].has('Ext') && active[1].size === 1 && active[2].size === 1) {
+      const cluster = [...active[1].keys()][0], name = [...active[2].keys()][0]
+      if (groups.has(cluster) && isPairedShadowName(name)) ext.push({ lo: at, hi: end, cluster, name })
+    }
+  }
+  const allow = qualified && safe
+  const groupRows: PairedShadowGroup[] = [...groups].map(([cluster, group]) => {
+    const result = agreement(group.stats), wholeCluster = { ...agreement(group.wholeStats), scope: 'whole_native_cluster_speech' as const }, reasons: string[] = []
+    if (!allow) reasons.push('paired alignment is not qualified')
+    if (!result.diagnosticAllSpeechGate) reasons.push('name requires 80% of ALL accepted-voice speech and at least 30s support')
+    if (!wholeCluster.diagnosticAllSpeechGate) reasons.push('name requires 80% of ALL native-cluster speech and at least 30s support')
+    if (result.diagnosticTopName !== wholeCluster.diagnosticTopName) reasons.push('accepted voices and whole native cluster disagree on G2 name')
+    const both = result.diagnosticAllSpeechGate && wholeCluster.diagnosticAllSpeechGate && result.diagnosticTopName === wholeCluster.diagnosticTopName
+    return { ...result, agreementScope: 'accepted_voice_speech', wholeCluster, cluster, voices: group.voices, candidateName: allow && both ? result.diagnosticTopName : null, reasons }
+  })
+  const named = new Map(groupRows.filter(g => g.candidateName).map(g => [g.cluster, g.candidateName!]))
+  const voices = [...byVoice].map(([voice, s]) => ({ ...agreement(s), voice, cluster: evidence.get(voice)?.topCluster ?? groupOfVoice.get(voice) ?? null }))
+  const extCandidates: PairedShadowSpan[] = []
+  if (allow) for (const span of ext) if (named.get(span.cluster) === span.name) {
+    const previous = extCandidates.at(-1)
+    if (previous && previous.endSample === span.lo && previous.cluster === span.cluster && previous.candidateName === span.name) previous.endSample = span.hi
+    else extCandidates.push({ startSample: span.lo, endSample: span.hi, cluster: span.cluster, candidateName: span.name })
+  }
+  const shortCandidates: PairedShadowShortCandidate[] = [], shortWithheld: PairedShadowReport['shortWithheld'] = []
+  for (const voice of voices) {
+    if (voice.allSpeechSeconds < PAIRED_SHADOW_GATES.shortMinSeconds || voice.allSpeechSeconds > PAIRED_SHADOW_GATES.shortMaxSeconds) continue
+    const row = evidence.get(voice.voice), reasons: string[] = []
+    if (!allow) reasons.push('paired alignment is not qualified')
+    if (!row || !finite(row.seconds) || Math.abs(row.seconds - voice.allSpeechSeconds) > 1 / SR) reasons.push('missing or inconsistent acoustic evidence')
+    if (!row || !finite(row.majority) || row.majority < SHADOW_GATES.majority) reasons.push('acoustic majority below 0.8')
+    if (!row || !finite(row.coveredFraction) || row.coveredFraction < SHADOW_GATES.minCoveredFraction) reasons.push('acoustic coverage below 0.5')
+    if (!row?.outlierPass) reasons.push('acoustic outlier check failed')
+    if (!row || !finite(row.anchorRatio) || row.anchorRatio < 0 || row.anchorRatio > PAIRED_SHADOW_GATES.shortAnchorRatio) reasons.push('raw anchor ratio unavailable or above 1.1')
+    const name = voice.cluster ? named.get(voice.cluster) : undefined
+    const support = voice.names.find(n => n.name === name)
+    if (!name || !support || support.fractionOfAllSpeech < PAIRED_SHADOW_GATES.nameAllSpeechFraction || voice.diagnosticTopName !== name) reasons.push('fragment and group lack same-time G2 name agreement')
+    if (reasons.length) shortWithheld.push({ voice: voice.voice, reasons })
+    else shortCandidates.push({ voice: voice.voice, cluster: voice.cluster!, candidateName: name!, seconds: voice.allSpeechSeconds })
+  }
+  return { mode: 'provisional_shadow_only', alignmentStatus: align.status, candidateNominationAllowed: allow, accuracyClaim: false, humanTruthClaim: false,
+    warnings: [...warnings], groups: groupRows, voices, extCandidates, shortCandidates, shortWithheld }
+}
+
+/** Readable paired-recording diagnostics. All labels here remain provisional. */
+export function renderPairedSpeakerShadow(report: PairedShadowReport): string {
+  const esc = (value: string) => value.replace(/[|\r\n]/gu, ' ').replace(/[*`<>]/gu, '')
+  const seconds = (n: number) => `${n.toFixed(1)} s`
+  const lines = ['## Paired G2 diagnostics', '',
+    `Alignment: **${report.alignmentStatus}**. ${report.candidateNominationAllowed ? 'Provisional shadow nominations are allowed.' : 'Nominations withheld; overlap statistics are diagnostic only.'}`,
+    'Saved G2 names are machine labels. This comparison makes no accuracy or human-truth claim.', '',
+    'Accepted-voice scope: only the final accepted keep/merge voices; this is not the whole native cluster.', '',
+    '| Cluster | All accepted-voice speech | Unique known-name time | Top name support / all speech | Top name support / known-name time | Name nomination |',
+    '|---|---:|---:|---|---|---|']
+  for (const group of report.groups) {
+    const best = group.names[0]
+    const support = best ? `${esc(best.name)}: ${seconds(best.seconds)}` : 'None'
+    lines.push(`| ${esc(group.cluster)} | ${seconds(group.allSpeechSeconds)} | ${seconds(group.knownNameSeconds)} | ${support}; ${((best?.fractionOfAllSpeech ?? 0) * 100).toFixed(1)}% | ${((best?.fractionOfKnownName ?? 0) * 100).toFixed(1)}% | ${group.candidateName ? esc(group.candidateName) + ' (provisional)' : 'Withheld'} |`)
+  }
+  lines.push('', 'Whole native-cluster scope includes Ext, other source labels and native speech without ASR labels.', '',
+    '| Cluster | All native-cluster speech | Unique known-name time | Top name support / all speech | Top name support / known-name time |',
+    '|---|---:|---:|---|---|')
+  for (const group of report.groups) {
+    const whole = group.wholeCluster, best = whole.names[0]
+    lines.push(`| ${esc(group.cluster)} | ${seconds(whole.allSpeechSeconds)} | ${seconds(whole.knownNameSeconds)} | ${best ? `${esc(best.name)}: ${seconds(best.seconds)}` : 'None'}; ${((best?.fractionOfAllSpeech ?? 0) * 100).toFixed(1)}% | ${((best?.fractionOfKnownName ?? 0) * 100).toFixed(1)}% |`)
+  }
+  lines.push('', 'A name must pass 80% of ALL speech and 30 seconds in BOTH scopes with the same name. Known-name percentages alone cannot qualify it.', '',
+    '| Voice | All speech | Known-name time | Top name / all speech | Production conflict | Native conflict / uncovered |',
+    '|---|---:|---:|---|---:|---|')
+  for (const voice of report.voices) {
+    const best = voice.names[0]
+    lines.push(`| ${esc(voice.voice)} | ${seconds(voice.allSpeechSeconds)} | ${seconds(voice.knownNameSeconds)} | ${best ? `${esc(best.name)} ${((best.fractionOfAllSpeech) * 100).toFixed(1)}%` : 'None'} | ${seconds(voice.productionConflictSeconds)} | ${seconds(voice.nativeConflictSeconds)} / ${seconds(voice.nativeUncoveredSeconds)} |`)
+  }
+  lines.push('', `Ext span nominations: ${report.extCandidates.length}. Short-fragment nominations: ${report.shortCandidates.length}. These lists do not change labels or remaps.`)
+  for (const group of report.groups) if (group.reasons.length) lines.push(`- ${esc(group.cluster)}: ${group.reasons.map(esc).join('; ')}.`)
+  for (const row of report.shortWithheld) lines.push(`- ${esc(row.voice)} short fragment withheld: ${row.reasons.map(esc).join('; ')}.`)
+  for (const warning of report.warnings) lines.push(`- ${esc(warning)}.`)
+  return lines.join('\n') + '\n'
+}

package/server/lib/speaker-shadow-report.ts

@@ -0,0 +1,113 @@
+// Speaker shadow mode (6.95.0): the readable per-meeting report Miles checks by ear.
+//
+// A port of round3/propose.py `render()`: "N voices would become M", every accepted merge
+// with its seconds, gate values and two or three listen pointers (file, time, text),
+// every rejection with its reasons, and the named labels sharing a cluster as a hint
+// ("this group also holds 65 s labelled ..."). Pure: it returns text, and the runner
+// writes it under <data>/speaker-shadow/reports/. It proposes; it never applies anything.
+
+import { join } from 'node:path'
+import { SHADOW_GATES, type ShadowProposals, type ShadowVoiceEntry } from './speaker-shadow-decide.js'
+import { PY_SPACE_CLASS, pyFixed } from './speaker-shadow-numeric.js'
+
+export interface ShadowReportInput {
+  title: string
+  sessionId: string
+  proposals: ShadowProposals
+  facts: { minutes: number; originals: number; verifiedAgainstSidecar: number; unhashedOriginals: number; unhashedWithText: number[]; humanProtectedVoices: string[] }
+  /** Where the chunk WAVs are, so each pointer names a file Miles can play. */
+  audioDir: string
+  /** The original chunk text by raw chunk index (the first 140 characters are quoted). */
+  chunkText: ReadonlyMap<number, string>
+}
+
+const STRIP = new RegExp(`^${PY_SPACE_CLASS}+|${PY_SPACE_CLASS}+$`, 'gu')
+const quote = (text: string | undefined) => Array.from((text ?? '').replace(STRIP, '')).slice(0, 140).join('')
+const chunkFile = (dir: string, index: number) => join(dir, `chunk_${String(index).padStart(4, '0')}.wav`)
+const HEADER = ['| Voice | Speech | Covered | Top cluster, majority | Outlier check | Anchor ratio gate |', '|---|---:|---:|---|---|---|']
+
+/** propose.py fmt_voice. */
+export function shadowVoiceRow(m: ShadowVoiceEntry): string {
+  const o = m.outlierPass && m.outlierDistance !== null
+    ? `outlier ${pyFixed(m.outlierDistance, 3)} ≤ p95 ${pyFixed(m.outlierP95!, 3)}`
+    : m.outlierDistance !== null ? `outlier ${pyFixed(m.outlierDistance, 3)} > p95 ${pyFixed(m.outlierP95!, 3)}` : `outlier: ${m.outlierNote}`
+  const ar = m.anchorRatioPostHoc === null ? '—' : `${pyFixed(m.anchorRatioPostHoc, 2)}x${m.anchorRatioPostHoc > SHADOW_GATES.anchorRatioPostHoc ? ' (above 1.5x)' : ''}`
+  return `| ${m.voice} | ${pyFixed(m.seconds, 1)} s | ${pyFixed(100 * m.coveredFraction, 0)}% | ${m.topCluster ?? 'None'} ${pyFixed(m.majority, 2)} | ${o} | ${ar} |`
+}
+
+function listenLines(m: ShadowVoiceEntry, input: ShadowReportInput): string[] {
+  return m.listen.map(p => `  - ${m.voice}: \`${chunkFile(input.audioDir, p.chunkIndex)}\` ${pyFixed(p.inFileStart, 1)} to ${pyFixed(p.inFileEnd, 1)} s (call time ${p.callTime}) "${quote(input.chunkText.get(p.chunkIndex))}"`)
+}
+
+export function renderShadowReport(input: ShadowReportInput): string {
+  const P = input.proposals, F = input.facts
+  const L: string[] = [
+    `# ${input.title}`, '',
+    `**${P.productionVoices} voices would become ${P.voicesAfter}.** FluidAudio proposed ${P.proposedMerges} merges; ${P.acceptedMerges} pass every gate, ${P.rejectedMerges} do not. Shadow mode only: nothing was renamed or written.`, '',
+    F.unhashedWithText.length
+      ? `- Meeting: ${pyFixed(F.minutes, 1)} min, ${F.originals} originals (${F.verifiedAgainstSidecar} verified; ${F.unhashedOriginals} unhashed, of which ${F.unhashedWithText.length} have text: check them).`
+      : `- Meeting: ${pyFixed(F.minutes, 1)} min, ${F.originals} originals (${F.verifiedAgainstSidecar} verified against the sidecar hashes; ${F.unhashedOriginals} had no hash, all empty-text).`,
+    `- FluidAudio found ${P.fluidAudioClusters} clusters. Labels never merged: ${P.frozenOtherLabels.join(', ') || 'none'}.`,
+    '- Gates: majority ≥0.8 of covered speech on one cluster (and ≥50% covered), ≥15 s of speech, embedding centroid inside the cluster spread (p95).',
+    '- Anchor ratio must be ≤1.5x against the kept voice\'s own spread; missing or degenerate evidence rejects a merge.',
+    '- How to check: play two or three pointers for each voice in a row. Same person? The merge is right.',
+    ...(F.humanProtectedVoices.length ? [`- A person already edited chunks holding ${F.humanProtectedVoices.join(', ')}. Those edits outrank any proposal here.`] : []),
+    `- Session \`${input.sessionId}\`.`, '',
+    '## Accepted proposals', '',
+  ]
+  if (!P.accepted.length) L.push('None.')
+  for (const a of P.accepted) {
+    L.push(`### ${a.cluster}: merge ${a.merge.join(', ')} into **${a.keepLabel}**`)
+    // Names first: Ext is speech no one was attributed to, not a label anyone gave.
+    const named = a.otherLabelsInCluster.filter(o => o.label !== 'Ext'), ext = a.otherLabelsInCluster.find(o => o.label === 'Ext')
+    const extText = ext ? `${pyFixed(ext.seconds, 0)} s of Ext speech (no voice label)` : ''
+    if (named.length) {
+      L.push(`Caution: this group also holds ${named.map(o => `${pyFixed(o.seconds, 0)} s labelled ${o.label}`).join(', ')}. Those labels stay as they are.${ext ? ` It also holds ${extText}.` : ''}`)
+    } else if (ext) {
+      L.push(`Note: this group also holds ${extText}.`)
+    }
+    const touched = a.voices.map(m => m.voice).filter(v => F.humanProtectedVoices.includes(v))
+    if (touched.length) L.push(`Human edit: ${touched.join(', ')} carries a person's correction on some chunks.`)
+    L.push('', ...HEADER, ...a.voices.map(shadowVoiceRow), '', 'Listen:')
+    for (const m of a.voices) L.push(...listenLines(m, input))
+    L.push('')
+  }
+  L.push('## Rejected proposals', '')
+  const rejected = P.rejected.filter(r => r.wouldJoin)
+  if (!rejected.length) L.push('None.')
+  for (const r of rejected) {
+    L.push(`- **${r.voice}** would have joined ${r.wouldJoin} on ${r.cluster}. Rejected: ${r.reasons.join('; ')}.`)
+    L.push('', HEADER[0], HEADER[1], shadowVoiceRow(r), '', ...listenLines(r, input), '')
+  }
+  L.push('## Untouched voices', '')
+  const kept = P.rejected.filter(r => !r.wouldJoin)
+  for (const r of kept) {
+    const fails = r.eligible ? '' : ` (it also fails: ${r.reasons.filter(x => !x.startsWith('no other')).join('; ')})`
+    L.push(`- ${r.voice} (${pyFixed(r.seconds, 1)} s): kept as is; it shares ${r.cluster} with other voices, but none of them passed every gate${fails}.`)
+  }
+  for (const u of P.untouched) L.push(`- ${u.voice} (${pyFixed(u.seconds, 1)} s): ${u.why}.`)
+  if (!kept.length && !P.untouched.length) L.push('None.')
+  L.push('')
+  return L.join('\n')
+}
+
+/** A meeting the run skipped or failed: one short page, so every finished meeting has a report. */
+export function renderShadowSkipReport(input: { title: string; sessionId: string; status: 'skipped' | 'failed'; reason: string | null; detail: string | null }): string {
+  return [`# ${input.title}`, '', `**No proposals: ${input.status}** (\`${input.reason ?? 'unknown'}\`). ${input.detail ?? ''}`.trimEnd(), '', `- Session \`${input.sessionId}\`. Shadow mode only: nothing was renamed or written.`, ''].join('\n')
+}
+
+/** The run's own facts, appended by the runner (it alone knows wall time and memory). */
+export function renderShadowRunFacts(input: { rebuildMs: number; nativeMs: number; wallMs: number; peakRssBytes: number | null; osTempDirsLeft: number; sidecarPath: string; pcmSHA256: string; cliTrust: string | null }): string {
+  return ['## Run facts', '',
+    `- Rebuild ${pyFixed(input.rebuildMs / 1000, 1)} s, diarization ${pyFixed(input.nativeMs / 1000, 1)} s, total ${pyFixed(input.wallMs / 1000, 1)} s. Peak memory ${input.peakRssBytes === null ? 'not sampled' : `${Math.round(input.peakRssBytes / 1048576)} MB`}.`,
+    `- fluidaudiocli trust: ${input.cliTrust ?? 'unknown'}. Network denied by sandbox-exec. Empty OS temp dirs left: ${input.osTempDirsLeft}.`,
+    `- Sidecar: \`${input.sidecarPath}\`. The timeline WAV was a temporary input and was deleted (PCM SHA ${input.pcmSHA256.slice(0, 12)}…).`, ''].join('\n')
+}
+
+/** The report's place: reports/<YYYY-MM-DD>/<title stem>__<session>.md, named like meeting-store names meetings. */
+export function shadowReportRelativePath(title: string, sessionId: string, day: string): string {
+  const stem = title.normalize('NFKD').replace(/[\u0300-\u036f]/g, '').replace(/[^A-Za-z0-9_-]+/g, '_').replace(/^[_-]+|[_-]+$/g, '').replace(/_{2,}/g, '_').slice(0, 72) || 'Mac_recording'
+  const safeDay = /^\d{4}-\d{2}-\d{2}$/.test(day) ? day : 'undated'
+  // The whole session id: two meetings can share a title and a long id prefix.
+  return join('reports', safeDay, `${stem}__${sessionId.replace(/[^A-Za-z0-9_-]/g, '_').slice(0, 96)}.md`)
+}