@gotcos/glasses-server 6.94.1 → 6.94.3

package/server/lib/mac-speaker-profile-finalizer.ts

@@ -0,0 +1,257 @@
+/** Qualified, named, exact-window finalization only. No anonymous merging,
+ * enrollment, guessed participant count, model-channel naming or lower floor.
+ * A durable attempt and two-file before/after journal make retries fail closed. */
+import { createHash } from 'node:crypto'
+import { existsSync, lstatSync, readFileSync } from 'node:fs'
+import { readFile, stat } from 'node:fs/promises'
+import { join, resolve } from 'node:path'
+import { durableAtomicWriteFileSync } from './atomic-fs.js'
+import { MAC_CAPTURE_ID } from './mac-recording.js'
+import { dataPath } from './data-dir.js'
+import { readPcm16Mono, wavHeader } from './nemotron-segments.js'
+import { planMacSpeakerWindows, qualifyMacSpeakerWindows, type VerifiedMacRawChunk, type MacWindowEmbeddingReceipt } from './mac-speaker-windows.js'
+import { normalizedSpeakerCosine, type MacSpeakerProfile } from './mac-speaker-reconcile.js'
+import { hashMacSpeakerDocument, hashMacSpeakerMachineBinding, projectMacSpeakerRepair, type MacProfileMatchEvidence, type MacSpeakerRepairAssignment, type MacSpeakerWordBinding } from './mac-speaker-repair-projection.js'
+import { boundWords, renderBoundSpeakerLabels, renderMarkdown } from './mac-speaker-repair-render.js'
+import { readMacSpeakerMachineEvidence } from './mac-speaker-machine-evidence.js'
+import { extractQualifiedMacWindow } from './mac-speaker-profile-extractor.js'
+type Doc = Record<string, any>
+const sha = (v: string | Buffer) => createHash('sha256').update(v).digest('hex')
+const yieldLoop = () => new Promise<void>(r => setImmediate(r))
+const MAX_WINDOWS = 12, MAX_RAW = 2048, MAX_MS = 90_000
+export const MAX_PROFILE_BYTES = 32 * 1024 * 1024
+function fail(reason: string): never { throw new Error(`qualified Mac profile pass: ${reason}`) }
+export interface QualifiedMacProfileInput { sidecarPath: string; meetingPath: string; audioDir: string; resumeOnly?: boolean }
+export interface QualifiedMacProfileDeps {
+  /** Test seams never invoke native inference. Production freezes the complete cohort. */
+  runtime?: () => Promise<{ modelPath: string; profilesPath: string } | null>
+  extract?: (pcm: Buffer, modelPath: string, timeoutMs: number) => Promise<readonly number[][] | null>
+  ledgerPath?: (sessionId: string) => string
+  now?: () => number
+  beforeCommit?: () => void
+  afterWrite?: (index: number) => void
+}
+export interface QualifiedMacProfileOutcome { status: 'applied' | 'skipped'; reason: string; assignments?: number }
+interface Image { path: string; before: string; after: string }
+interface Journal { version: 1; status: 'attempted' | 'prepared' | 'complete'; sessionId: string; sourceSidecarHash: string; imageBinding?: string; rawBindings?: Array<{ name: string; sha256: string }>; reason?: string; images?: Image[]; ledgerPath: string; ledgerHash: string | null; profilePath: string; profileHash: string; modelPath: string; modelHash: string }
+const active = new Set<string>()
+let extractionBusy = false
+function regularRead(path: string, max = 12 * 1024 * 1024): string {
+  const s = lstatSync(path)
+  if (!s.isFile() || s.isSymbolicLink() || s.size > max) fail('unsafe or oversized file')
+  return readFileSync(path, 'utf8')
+}
+function ledgerHash(path: string): string | null {
+  try { return sha(regularRead(path, 4 * 1024 * 1024)) } catch (e) { if ((e as NodeJS.ErrnoException).code === 'ENOENT') return null; throw e }
+}
+function ledgerClear(path: string): boolean {
+  const digest = ledgerHash(path)
+  if (digest === null) return true
+  // Every historical human action (including intent/revert) protects the capture.
+  return regularRead(path).trim() === ''
+}
+
+function strictPcm(wav: Buffer) {
+  if (wav.length < 44 || wav.readUInt32LE(4) !== wav.length - 8 || wav.toString('ascii', 12, 16) !== 'fmt ' || wav.readUInt32LE(16) !== 16 || wav.readUInt16LE(20) !== 1 || wav.readUInt16LE(22) !== 1 || wav.readUInt32LE(24) !== 16000 || wav.readUInt32LE(28) !== 32000 || wav.readUInt16LE(32) !== 2 || wav.readUInt16LE(34) !== 16 || wav.toString('ascii', 36, 40) !== 'data' || wav.readUInt32LE(40) !== wav.length - 44 || (wav.length - 44) % 2) return null
+  return readPcm16Mono(wav)
+}
+async function runtimeDefault() {
+  const { speakerModelState } = await import('./speaker-embeddings.js')
+  const model = speakerModelState()
+  return model.state === 'active' && model.path ? { modelPath: model.path, profilesPath: dataPath('voice-profiles.json') } : null
+}
+function recover(journalPath: string, journal: Journal, input: QualifiedMacProfileInput, deps: QualifiedMacProfileDeps): QualifiedMacProfileOutcome {
+  if (journal.version !== 1 || !MAC_CAPTURE_ID.test(journal.sessionId) || journal.images?.length !== 2
+    || journal.images[0].path !== resolve(input.meetingPath) || journal.images[1].path !== resolve(input.sidecarPath)
+    || ledgerHash(journal.ledgerPath) !== journal.ledgerHash) fail('journal or human history drift')
+  if (journal.status !== 'complete' && (sha(regularRead(journal.profilePath, MAX_PROFILE_BYTES)) !== journal.profileHash || sha(readFileSync(journal.modelPath)) !== journal.modelHash)) fail('journal profile/model drift')
+  const images = journal.images
+  if (journal.imageBinding !== hashMacSpeakerDocument(images) || sha(images[1].before) !== journal.sourceSidecarHash) fail('journal image integrity drift')
+  const beforeDoc = JSON.parse(images[1].before), afterDoc = JSON.parse(images[1].after)
+  const proofRead = readMacSpeakerMachineEvidence({ ...afterDoc, finalizationState: 'complete' })
+  if (beforeDoc.sessionId !== journal.sessionId || afterDoc.sessionId !== journal.sessionId || proofRead.status !== 'qualified' || !proofRead.positions.size || !afterDoc.speakerRepair?.machineEvidence?.receipt) fail('journal proof rejected')
+  const expectedSequence = boundWords(beforeDoc, afterDoc)
+  if (renderBoundSpeakerLabels(beforeDoc.batchTranscript, expectedSequence) !== afterDoc.batchTranscript || renderMarkdown(images[0].before, expectedSequence) !== images[0].after) fail('journal word invariant drift')
+  if (journal.status !== 'complete') {
+    if (!Array.isArray(journal.rawBindings) || !journal.rawBindings.length || journal.rawBindings.length > MAX_RAW) fail('journal raw bindings invalid')
+    for (const raw of journal.rawBindings) { if (!/^chunk_\d{4,}\.wav$/.test(raw.name) || sha(readFileSync(join(input.audioDir, raw.name))) !== raw.sha256) fail('journal raw drift') }
+  }
+  const current = images.map(image => regularRead(image.path))
+  if (journal.status !== 'complete' && current.some((bytes, i) => bytes !== images[i].before && bytes !== images[i].after)) fail('journal precondition drift')
+  // Completed transactions never reapply over a later change; the exact speech
+  // binding/revision guard in readers separately invalidates later stale claims.
+  if (journal.status === 'complete') {
+    if (current.every((bytes, i) => bytes === images[i].after)) return { status: 'applied', reason: 'already_applied' }
+    const saved = JSON.parse(images[1].after), currentDoc = JSON.parse(current[1])
+    if (hashMacSpeakerMachineBinding(currentDoc) === hashMacSpeakerMachineBinding(saved) && currentDoc.correctionRevision === saved.correctionRevision && readMacSpeakerMachineEvidence(currentDoc).status === 'qualified') return { status: 'applied', reason: 'already_applied' }
+    fail('completed journal changed')
+  }
+  for (let i = 0; i < images.length; i++) {
+    if (ledgerHash(journal.ledgerPath) !== journal.ledgerHash) fail('human history changed')
+    for (let j = 0; j < images.length; j++) {
+      const bytes = regularRead(images[j].path)
+      if (bytes !== (j < i ? images[j].after : current[j])) fail('transaction changed during commit')
+    }
+    if (current[i] !== images[i].after) durableAtomicWriteFileSync(images[i].path, images[i].after)
+    deps.afterWrite?.(i)
+  }
+  if (images.some(image => regularRead(image.path) !== image.after)) fail('postimage changed')
+  journal.status = 'complete'; durableAtomicWriteFileSync(journalPath, JSON.stringify(journal))
+  return { status: 'applied', reason: 'qualified_profile' }
+}
+/** Six deterministic adjacent pairs spread across the entire call. Scheduling
+ * hints never add identity votes; each pair still needs acoustic qualification. */
+export function selectQualifiedProfileWindows<T>(windows: readonly T[]): T[] {
+  if (windows.length <= MAX_WINDOWS) return [...windows]
+  const indexes = new Set<number>()
+  for (let i = 0; i < MAX_WINDOWS / 2; i++) { const index = Math.floor(i * (windows.length - 2) / (MAX_WINDOWS / 2 - 1)); indexes.add(index); indexes.add(index + 1) }
+  return [...indexes].sort((a, b) => a - b).map(i => windows[i])
+}
+/** Called twice by the finalizer: resumeOnly BEFORE any ASR retry, and ordinary
+ * mode AFTER ASR+diarization, before raw deletion or downstream copies/sync. */
+export async function runQualifiedMacProfilePass(input: QualifiedMacProfileInput, deps: QualifiedMacProfileDeps = {}): Promise<QualifiedMacProfileOutcome> {
+  const key = resolve(input.sidecarPath), journalPath = `${key}.speaker-profile-pass.json`
+  if (active.has(key)) return { status: 'skipped', reason: 'active' }
+  active.add(key)
+  let ownsExtraction = false
+  try {
+    if (existsSync(journalPath)) {
+      const prior = JSON.parse(regularRead(journalPath, 64 * 1024 * 1024)) as Journal
+      if (prior.status === 'prepared' || prior.status === 'complete') return recover(journalPath, prior, input, deps)
+      if (prior.version !== 1 || prior.status !== 'attempted') fail('invalid attempt journal')
+      return { status: 'skipped', reason: prior.reason ?? 'previous_attempt' }
+    }
+    if (input.resumeOnly) return { status: 'skipped', reason: 'no_transaction' }
+    const now = deps.now ?? Date.now, deadline = now() + MAX_MS
+    const budget = () => { if (now() >= deadline) fail('budget_exhausted') }
+    const beforeSidecar = regularRead(key), source = JSON.parse(beforeSidecar) as Doc
+    if (source.sourceType !== 'mac_system_audio' || !MAC_CAPTURE_ID.test(source.sessionId) || !['batch_pending', 'ops_pending', 'complete'].includes(source.finalizationState)
+      || source.claimPending || source.active || source.isActive || source.status === 'recording' || source.isMerged || source.mergedFrom || source.sourceSessionIds || source.supersededBy || source.superseded || source.speakerRepair
+      || (source.correctionRevision ?? 0) !== 0 || source.batchApplied !== true || !Array.isArray(source.batchSegments) || !Array.isArray(source.chunkEntries) || source.chunkEntries.length > MAX_RAW) return { status: 'skipped', reason: 'source_ineligible' }
+    const ledgerPath = deps.ledgerPath?.(source.sessionId) ?? dataPath('meeting-corrections', `${source.sessionId}.jsonl`)
+    if (!ledgerClear(ledgerPath)) return { status: 'skipped', reason: 'human_corrected' }
+    const ledger = ledgerHash(ledgerPath), beforeMarkdown = regularRead(input.meetingPath, 4 * 1024 * 1024)
+    const runtime = await (deps.runtime ?? runtimeDefault)()
+    if (!runtime) return { status: 'skipped', reason: 'model_unavailable' }
+    const profileBytes = regularRead(runtime.profilesPath, MAX_PROFILE_BYTES), profileSHA256 = sha(profileBytes)
+    const cohort = JSON.parse(profileBytes).profiles
+    if (!Array.isArray(cohort) || !cohort.length || cohort.length > 1024) return { status: 'skipped', reason: 'profile_cohort_invalid' }
+    if ((await stat(runtime.modelPath)).size > 128 * 1024 * 1024) return { status: 'skipped', reason: 'model_oversized' }
+    const modelBytes = await readFile(runtime.modelPath); budget()
+    if (modelBytes.length > 128 * 1024 * 1024) return { status: 'skipped', reason: 'model_oversized' }
+    if (cohort.some(p => !p || typeof p.name !== 'string' || !Array.isArray(p.embeddings) || !p.embeddings.length || p.embeddings.length > 128 || p.embeddings.some((r: unknown) => !Array.isArray(r) || r.length !== 192 || r.some(v => !Number.isFinite(v)))) || cohort.reduce((n, p) => n + p.embeddings.length, 0) > 8192) return { status: 'skipped', reason: 'profile_cohort_invalid' }
+    const modelSHA256 = sha(modelBytes)
+    const profiles: MacSpeakerProfile[] = cohort.map(p => ({ name: p.name, embeddings: p.embeddings, profileSHA256 }))
+    // One bounded native profile job server-wide. A concurrent capture keeps
+    // its saved labels rather than multiplying native processes/CPU load.
+    if (extractionBusy) return { status: 'skipped', reason: 'profile_lane_busy' }
+    extractionBusy = true; ownsExtraction = true
+    const journal: Journal = { version: 1, status: 'attempted', sessionId: source.sessionId, sourceSidecarHash: sha(beforeSidecar), ledgerPath, ledgerHash: ledger, profilePath: resolve(runtime.profilesPath), profileHash: profileSHA256, modelPath: resolve(runtime.modelPath), modelHash: modelSHA256 }
+    durableAtomicWriteFileSync(journalPath, JSON.stringify(journal))
+    try {
+      const raw: VerifiedMacRawChunk[] = [], counts: Record<string, number> = {}
+      for (const entry of source.chunkEntries) {
+        budget()
+        if (!Number.isSafeInteger(entry.chunkIndex) || entry.chunkIndex < 0) fail('invalid raw index')
+        const path = join(input.audioDir, `chunk_${String(entry.chunkIndex).padStart(4, '0')}.wav`)
+        const info = await stat(path)
+        if (!info.isFile() || info.size > 960044) fail('invalid raw file')
+        const wav = await readFile(path), audioSHA256 = sha(wav), pcm = strictPcm(wav)
+        if (!pcm || pcm.sampleRate !== 16000 || wav.length > 960044 || (entry.chunk.audioSha256 !== undefined && audioSHA256 !== entry.chunk.audioSha256)) fail('raw hash/format drift')
+        const sampleCount = pcm.pcm.length / 2
+        counts[entry.chunkIndex] = sampleCount
+        raw.push({ chunkIndex: entry.chunkIndex, audioSHA256, pcmSHA256: sha(pcm.pcm), sampleRate: 16000, channels: 1, format: 'pcm_s16le', sampleCount, verified: true })
+        if (raw.length % 4 === 0) await yieldLoop()
+      }
+      const plan = planMacSpeakerWindows({ sidecar: source as any, rawChunks: raw, correctionHistory: 'verified-clear' })
+      plan.windows = selectQualifiedProfileWindows(plan.windows)
+      if (plan.windows.length < 2) fail('insufficient_long_windows')
+      const receipts: MacWindowEmbeddingReceipt[] = []
+      for (const window of plan.windows) {
+        budget(); await yieldLoop()
+        const buffers: Buffer[] = []
+        for (const s of window.sources) {
+          const wav = await readFile(join(input.audioDir, `chunk_${String(s.chunkIndex).padStart(4, '0')}.wav`)), pcm = strictPcm(wav)
+          if (sha(wav) !== s.audioSHA256 || !pcm || sha(pcm.pcm) !== s.pcmSHA256) fail('raw changed before extraction')
+          buffers.push(pcm.pcm)
+        }
+        const pcm = Buffer.concat(buffers), wav = Buffer.concat([wavHeader(pcm.length), pcm])
+        const vectors = await (deps.extract ?? extractQualifiedMacWindow)(pcm, runtime.modelPath, Math.min(15_000, deadline - now()))
+        budget()
+        if (!vectors || vectors.length !== 3) continue
+        receipts.push({ windowId: window.id, windowBindingSHA256: window.bindingSHA256, modelSHA256, audioSHA256: sha(wav), pcmSHA256: sha(pcm), sampleCount: pcm.length / 2, embedding: vectors[0], halfEmbeddings: [vectors[1], vectors[2]] })
+      }
+      const qualified = qualifyMacSpeakerWindows(plan, receipts, profiles, modelSHA256)
+      const byWindow = new Map(plan.windows.map(w => [w.id, w])), byReceipt = new Map(receipts.map(r => [r.windowId, r]))
+      const assignments: MacSpeakerRepairAssignment[] = []
+      const groups = new Map<string, typeof qualified>()
+      for (const c of qualified) if (c.status === 'qualified' && c.profileName) { const k = `${c.acousticIdentity}:${c.profileName}`; groups.set(k, [...(groups.get(k) ?? []), c]) }
+      for (const group of groups.values()) {
+        if (group.length < 2) continue
+        const profile = profiles.find(p => p.name === group[0].profileName)!
+        // Same raw-average centroid used by the production recognizer. The
+        // qualifier already rejected corrupt/mismatched rows and profile ties.
+        const rows = profile.embeddings, dimensions = rows[0].length
+        const centroid = Array.from({ length: dimensions }, (_, i) => rows.reduce((n, r) => n + r[i] / rows.length, 0))
+        const centroids = profiles.map(p => ({ name: p.name, vector: Array.from({ length: dimensions }, (_, i) => p.embeddings.reduce((n, r) => n + r[i] / p.embeddings.length, 0)) }))
+        const proof: MacProfileMatchEvidence = { kind: 'profile-match', profileName: profile.name, profileSha256: profileSHA256, modelSha256: modelSHA256, algorithmVersion: 'qualified-long-window-profile-v1',
+          crossWindowCosines: group.map(a => group.map(b => normalizedSpeakerCosine(byReceipt.get(a.windowId)!.embedding, byReceipt.get(b.windowId)!.embedding)!)),
+          windows: group.map(c => { const w = byWindow.get(c.windowId)!, r = byReceipt.get(c.windowId)!; return { id: w.id, captureStartSample: w.startSample, captureEndSample: w.endSample, pcmSha256: r.pcmSHA256,
+            similarity: normalizedSpeakerCosine(r.embedding, centroid)!, runnerUpSimilarity: Math.max(-1, ...centroids.filter(p => p.name !== profile.name).map(p => normalizedSpeakerCosine(r.embedding, p.vector)!)),
+            rawChunks: w.sources.map(s => ({ rawChunkIndex: s.chunkIndex, audioSha256: s.audioSHA256, sampleCount: s.sampleCount })) } }) }
+        for (const c of group) for (const s of byWindow.get(c.windowId)!.sources) assignments.push({ rawChunkIndex: s.chunkIndex, from: c.originalVoiceHint, to: profile.name, evidenceId: c.acousticIdentity!, targetEvidence: proof, batchWords: [] })
+      }
+      if (!assignments.length) fail('no_qualified_profile')
+      const selected = new Map(assignments.map(a => [a.rawChunkIndex, a])), withheldBatchWords: Array<MacSpeakerWordBinding & { reason: 'outside-qualified-span' }> = []
+      source.batchSegments.forEach((segment: Doc, segmentIndex: number) => {
+        const spans: { raw: number; start: number; end: number }[] = []; let end = 0
+        if (!Number.isSafeInteger(segment.startChunkIdx) || !Number.isSafeInteger(segment.endChunkIdx) || segment.endChunkIdx - segment.startChunkIdx > MAX_RAW) fail('invalid batch range')
+        for (let raw = segment.startChunkIdx; raw <= segment.endChunkIdx; raw++) { if (!counts[raw]) fail('missing batch raw clock'); spans.push({ raw, start: end, end: end + counts[raw] / 16000 }); end += counts[raw] / 16000 }
+        segment.speakerWords.forEach((word: Doc, wordIndex: number) => {
+          const overlaps = spans.filter(s => word.end === word.start ? word.start >= s.start && word.start < s.end : word.start < s.end && word.end > s.start)
+          if (!overlaps.some(s => selected.has(s.raw))) return
+          const binding = { segmentIndex, wordIndex, word: word.word, from: word.speaker, start: word.start, end: word.end }
+          if (overlaps.some(s => !selected.has(s.raw))) withheldBatchWords.push({ ...binding, reason: 'outside-qualified-span' })
+          else if (new Set(overlaps.map(s => selected.get(s.raw)!.to)).size === 1) selected.get(overlaps[0].raw)!.batchWords.push(binding)
+          else fail('crossed identities')
+        })
+      })
+      budget()
+      const staging = { ...source, finalizationState: 'complete' }, repairPlan = { id: `profile_${sha(beforeSidecar).slice(0, 24)}`, evidenceHash: hashMacSpeakerDocument(receipts), expectedDocumentHash: hashMacSpeakerDocument(staging), protectedRawChunkIndices: [], rawAudioSampleCounts: counts, assignments, withheldBatchWords }
+      const projected = projectMacSpeakerRepair(staging, repairPlan), after = projected.doc, sequence = boundWords(staging, after)
+      after.batchTranscript = renderBoundSpeakerLabels(source.batchTranscript, sequence)
+      const afterMarkdown = renderMarkdown(beforeMarkdown, sequence)
+      after.finalizationState = source.finalizationState
+      after.correctionRevision = 1; after.lifecycleRevision = (source.lifecycleRevision ?? 0) + 1
+      after.speakerRepair = { version: 1, id: repairPlan.id, evidenceHash: repairPlan.evidenceHash, machineEvidence: { version: 1, correctionRevision: 1, documentBinding: hashMacSpeakerMachineBinding(after), receipt: projected.receipt, rawAudioSampleCounts: counts } }
+      after.speakerProfilePass = { version: 1, status: 'applied', windows: receipts.length, assignments: assignments.length }
+      deps.beforeCommit?.(); budget()
+      for (const c of assignments) {
+        const rawBytes = await readFile(join(input.audioDir, `chunk_${String(c.rawChunkIndex).padStart(4, '0')}.wav`))
+        if (sha(rawBytes) !== raw.find(r => r.chunkIndex === c.rawChunkIndex)!.audioSHA256) fail('raw changed before commit')
+      }
+      const currentModelHash = sha(await readFile(runtime.modelPath))
+      if (regularRead(key) !== beforeSidecar || regularRead(input.meetingPath) !== beforeMarkdown || ledgerHash(ledgerPath) !== ledger || sha(regularRead(runtime.profilesPath, MAX_PROFILE_BYTES)) !== profileSHA256 || currentModelHash !== modelSHA256) fail('source/profile/model/history drift')
+      journal.images = [{ path: resolve(input.meetingPath), before: beforeMarkdown, after: afterMarkdown }, { path: key, before: beforeSidecar, after: JSON.stringify(after, null, 2) + '\n' }]
+      journal.imageBinding = hashMacSpeakerDocument(journal.images)
+      journal.rawBindings = assignments.map(a => ({ name: `chunk_${String(a.rawChunkIndex).padStart(4, '0')}.wav`, sha256: raw.find(r => r.chunkIndex === a.rawChunkIndex)!.audioSHA256 }))
+      journal.status = 'prepared'; durableAtomicWriteFileSync(journalPath, JSON.stringify(journal))
+      const outcome = recover(journalPath, journal, input, deps)
+      return { ...outcome, assignments: assignments.length }
+    } catch (error) {
+      // Prepared transactions must be retried before ASR, never reported as an
+      // ordinary no-match that permits downstream filing of mixed generations.
+      if (journal.status === 'prepared') throw error
+      journal.reason = error instanceof Error ? error.message : 'unqualified'; durableAtomicWriteFileSync(journalPath, JSON.stringify(journal))
+      return { status: 'skipped', reason: journal.reason }
+    }
+  } catch (error) {
+    // Recovery failures must block ASR/copying; ordinary unavailable resources
+    // leave the already saved recording alone.
+    if (existsSync(journalPath)) {
+      const saved = JSON.parse(regularRead(journalPath, 64 * 1024 * 1024)) as Journal
+      if (saved.status === 'prepared' || saved.status === 'complete') throw error
+    }
+    return { status: 'skipped', reason: error instanceof Error ? error.message : 'unavailable' }
+  } finally { if (ownsExtraction) extractionBusy = false; active.delete(key) }
+}

package/server/lib/mac-speaker-protection.ts

@@ -0,0 +1,22 @@
+/** One conservative predicate for automatic acoustic support and label writes.
+ * Human markers protect even still-anonymous labels and unlabeled ASR words. */
+export function isMacSpeakerHumanProtected(value: unknown): boolean {
+  if (!value || typeof value !== 'object') return false
+  const row = value as Record<string, unknown>
+  if (['speakerCorrectionBatchId', 'speakerCorrectionId', 'manualSpeaker', 'speakerManuallyAssigned', 'confirmedByHuman', 'manuallyAssigned', 'manuallyCorrected'].some(key => !!row[key])) return true
+  return ['speakerOrigin', 'speakerSource', 'speakerPolicy', 'speakerProvenance', 'source'].some(key =>
+    typeof row[key] === 'string' && /(?:manual|human|correction|confirmed)/i.test(row[key] as string))
+}
+/** Inspect every stored chunk representation before using any of its audio as
+ * positive evidence. Malformed declared surfaces also fail closed. */
+export function hasMacSpeakerProtectedRows(value: unknown): boolean {
+  if (!value || typeof value !== 'object') return true
+  const chunk = value as Record<string, unknown>
+  if (isMacSpeakerHumanProtected(chunk)) return true
+  for (const key of ['segments', 'finalSegments', 'words']) {
+    if (chunk[key] === undefined) continue
+    if (!Array.isArray(chunk[key])) return true
+    if ((chunk[key] as unknown[]).some(row => !row || typeof row !== 'object' || isMacSpeakerHumanProtected(row))) return true
+  }
+  return false
+}

package/server/lib/mac-speaker-reconcile.ts

@@ -0,0 +1,300 @@
+// Pure, opt-in acoustic evidence engine. No audio/model loading, file IO, enrollment,
+// transcript mutation, attendee inference or production enablement belongs here.
+import { createHash } from 'node:crypto'
+import { checkSpeakerName } from './speaker-name.js'
+
+const SHA = /^[a-f0-9]{64}$/
+const uint = (n: unknown): n is number => Number.isSafeInteger(n) && Number(n) >= 0
+const digest = (value: unknown): string => createHash('sha256').update(JSON.stringify(value)).digest('hex')
+const fail = (why: string): never => { throw new Error(`mac_speaker_reconcile_${why}`) }
+export const MAC_SPEAKER_RECONCILE_VERSION = 'acoustic-memory-v1'
+export interface MacSpeakerThresholds {
+  dimensions: number
+  anonymousCosine: number
+  anonymousMargin: number
+  identityCosine: number
+  identityMargin: number
+  minimumIndependentMatches: number
+  minimumSamples: number
+  minimumPurity: number
+  maxIdentities: number
+  maxAnchorsPerIdentity: number
+  maxOriginals: number
+}
+/** Anonymous recurrence is not real-name recognition. These are conservative,
+ * unqualified defaults, not measured accuracy claims. Identity cannot go below .88. */
+export const DEFAULT_MAC_SPEAKER_THRESHOLDS: Readonly<MacSpeakerThresholds> = Object.freeze({
+  dimensions: 192, anonymousCosine: .90, anonymousMargin: .06,
+  identityCosine: .88, identityMargin: .05, minimumIndependentMatches: 2,
+  minimumSamples: 32_000, minimumPurity: .95,
+  maxIdentities: 128, maxAnchorsPerIdentity: 4, maxOriginals: 8192,
+})
+export interface MacSpeakerOriginal {
+  chunkIndex: number
+  audioSHA256: string
+  pcmSHA256: string
+  startSample: number
+  sampleCount: number
+}
+export interface MacSpeakerObservation {
+  captureId: string
+  modelSHA256: string
+  original: MacSpeakerOriginal
+  startSample: number
+  endSample: number
+  exclusiveSamples: number
+  purity: number
+  overlapSamples: number
+  mixedSpeakers: boolean
+  embedding: readonly number[]
+  /** Existing human/manual identity is immutable and never contributes training. */
+  protectedLabel?: { label: string; origin: 'named' | 'manual' }
+}
+export interface MacSpeakerAnchor {
+  original: MacSpeakerOriginal
+  startSample: number
+  endSample: number
+  exclusiveSamples: number
+  purity: number
+  embedding: number[]
+  /** Binds normalized vector + exact original/sample geometry to model/capture. */
+  observationSHA256: string
+}
+export interface MacAcousticIdentity {
+  id: number
+  /** Null means provisional evidence only; never display it as a settled voice. */
+  voice: number | null
+  anchors: MacSpeakerAnchor[]
+}
+export interface MacSpeakerMemory {
+  version: typeof MAC_SPEAKER_RECONCILE_VERSION
+  captureId: string
+  modelSHA256: string
+  thresholds: MacSpeakerThresholds
+  voiceHighWater: number
+  identities: MacAcousticIdentity[]
+  /** Compact lineage survives per-identity anchor retention. Never prune it to
+   * make a crop/replay appear independent; exhaustion explicitly withholds. */
+  originals: MacSpeakerOriginal[]
+}
+export type MacSpeakerReason = 'invalid_observation' | 'protected_label' | 'duplicate_source' | 'source_conflict'
+  | 'crossed_originals' | 'mixed_or_overlap' | 'insufficient_clean_audio' | 'budget_exhausted'
+  | 'ambiguous' | 'inconsistent_anchors' | 'provisional' | 'confirmed_anonymous' | 'recurring_anonymous'
+  | 'insufficient_independent_matches' | 'profile_below_floor' | 'profile_ambiguity' | 'profile_disagreement' | 'matched_profile'
+export interface MacSpeakerDecision {
+  reason: MacSpeakerReason
+  label: string | null
+  confidence: 'withheld' | 'provisional' | 'acoustic' | 'protected' | 'profile'
+  identityId?: number
+  evidence: string[]
+  scores: { candidate: string; minimumCosine: number; maximumCosine: number }[]
+  provenance: { algorithm: typeof MAC_SPEAKER_RECONCILE_VERSION; captureId: string; modelSHA256: string; thresholds: MacSpeakerThresholds; profileSHA256?: string }
+}
+function config(overrides: Partial<MacSpeakerThresholds> = {}): MacSpeakerThresholds {
+  const c = { ...DEFAULT_MAC_SPEAKER_THRESHOLDS, ...overrides }
+  for (const k of ['dimensions', 'minimumIndependentMatches', 'minimumSamples', 'maxIdentities', 'maxAnchorsPerIdentity', 'maxOriginals'] as const)
+    if (!uint(c[k]) || c[k] < 1) fail('thresholds')
+  if (c.dimensions > 4096 || c.minimumIndependentMatches < 2 || c.maxAnchorsPerIdentity < c.minimumIndependentMatches
+    || c.maxAnchorsPerIdentity > 64 || c.maxIdentities > 1024 || c.maxOriginals > 65536) fail('thresholds')
+  for (const k of ['anonymousCosine', 'anonymousMargin', 'identityCosine', 'identityMargin', 'minimumPurity'] as const)
+    if (!Number.isFinite(c[k]) || c[k] < 0 || c[k] > 1) fail('thresholds')
+  if (c.identityCosine < .88 || c.identityMargin <= 0 || c.anonymousMargin <= 0) fail('identity_floor_or_margin')
+  return c
+}
+/** Scale before norm to avoid overflow/underflow; no unnormalized dot products. */
+export function normalizedSpeakerEmbedding(values: readonly number[], dimensions: number): number[] | null {
+  if (!Array.isArray(values) || values.length !== dimensions || Object.keys(values).length !== values.length || values.some(v => !Number.isFinite(v))) return null
+  const scale = Math.max(...values.map(Math.abs))
+  if (!(scale > 0)) return null
+  const scaled = values.map(v => v / scale)
+  const norm = Math.sqrt(scaled.reduce((sum, v) => sum + v * v, 0))
+  return scaled.map(v => v / norm)
+}
+export function normalizedSpeakerCosine(a: readonly number[], b: readonly number[]): number | null {
+  if (a.length !== b.length || a.length < 1) return null
+  const x = normalizedSpeakerEmbedding(a, a.length), y = normalizedSpeakerEmbedding(b, b.length)
+  return x && y ? Math.max(-1, Math.min(1, x.reduce((sum, v, i) => sum + v * y[i], 0))) : null
+}
+function validOriginal(o: MacSpeakerOriginal): boolean {
+  return !!o && uint(o.chunkIndex) && SHA.test(o.audioSHA256) && SHA.test(o.pcmSHA256)
+    && uint(o.startSample) && uint(o.sampleCount) && o.sampleCount > 0 && o.sampleCount <= 480_000
+    && Number.isSafeInteger(o.startSample + o.sampleCount)
+}
+function anchorHash(s: Pick<MacSpeakerMemory, 'captureId' | 'modelSHA256'>, a: Omit<MacSpeakerAnchor, 'observationSHA256'>): string {
+  return digest({ captureId: s.captureId, modelSHA256: s.modelSHA256, ...a })
+}
+function independent(originals: readonly MacSpeakerOriginal[], o: MacSpeakerOriginal): MacSpeakerReason | null {
+  for (const previous of originals) {
+    if (previous.chunkIndex === o.chunkIndex) return digest(previous) === digest(o) ? 'duplicate_source' : 'source_conflict'
+    if (previous.audioSHA256 === o.audioSHA256 || previous.pcmSHA256 === o.pcmSHA256) return 'duplicate_source'
+    if (Math.max(previous.startSample, o.startSample) < Math.min(previous.startSample + previous.sampleCount, o.startSample + o.sampleCount)) return 'crossed_originals'
+  }
+  return null
+}
+export function createMacSpeakerMemory(captureId: string, modelSHA256: string, overrides: Partial<MacSpeakerThresholds> = {}): MacSpeakerMemory {
+  if (!captureId || captureId.length > 200 || !SHA.test(modelSHA256)) fail('binding')
+  return { version: MAC_SPEAKER_RECONCILE_VERSION, captureId, modelSHA256, thresholds: config(overrides), voiceHighWater: 0, identities: [], originals: [] }
+}
+/** Restored state never resets numbers or accepts modified observation receipts.
+ * Integrity is structural; the caller must authenticate persisted bytes and verify
+ * extractor/audio hashes. A receipt is not proof of acoustic speaker purity. */
+export function validateMacSpeakerMemory(s: MacSpeakerMemory): void {
+  if (!s || s.version !== MAC_SPEAKER_RECONCILE_VERSION || !s.captureId || s.captureId.length > 200 || !SHA.test(s.modelSHA256)) fail('state_binding')
+  const c = config(s.thresholds)
+  if (!uint(s.voiceHighWater) || s.voiceHighWater > 99 || !Array.isArray(s.identities) || s.identities.length > c.maxIdentities
+    || !Array.isArray(s.originals) || s.originals.length > c.maxOriginals) fail('state_bound')
+  const chunkKeys = new Set<number>(), audioKeys = new Set<string>(), pcmKeys = new Set<string>()
+  for (const o of s.originals) {
+    if (!validOriginal(o) || chunkKeys.has(o.chunkIndex) || audioKeys.has(o.audioSHA256) || pcmKeys.has(o.pcmSHA256)) fail('state_lineage')
+    chunkKeys.add(o.chunkIndex); audioKeys.add(o.audioSHA256); pcmKeys.add(o.pcmSHA256)
+  }
+  const ordered = [...s.originals].sort((a, b) => a.startSample - b.startSample)
+  if (ordered.some((o, i) => i > 0 && ordered[i - 1].startSample + ordered[i - 1].sampleCount > o.startSample)) fail('state_lineage')
+  const originalBindings = new Map(s.originals.map(o => [o.chunkIndex, digest(o)]))
+  const voices = new Set<number>()
+  const used = new Set<string>()
+  for (let i = 0; i < s.identities.length; i++) {
+    const t = s.identities[i]
+    if (!t || t.id !== i + 1 || !Array.isArray(t.anchors) || !t.anchors.length || t.anchors.length > c.maxAnchorsPerIdentity
+      || (t.voice !== null && (!uint(t.voice) || t.voice < 1 || t.voice > s.voiceHighWater || voices.has(t.voice)))
+      || (t.voice === null ? t.anchors.length >= c.minimumIndependentMatches : t.anchors.length < c.minimumIndependentMatches)) fail('state_identity')
+    if (t.voice !== null) voices.add(t.voice)
+    for (const a of t.anchors) {
+      const { observationSHA256, ...body } = a
+      const embedding = normalizedSpeakerEmbedding(a.embedding, c.dimensions)
+      if (!embedding || !validOriginal(a.original) || originalBindings.get(a.original.chunkIndex) !== digest(a.original) || used.has(a.original.pcmSHA256)
+        || !uint(a.startSample) || !uint(a.endSample) || a.startSample < a.original.startSample || a.endSample > a.original.startSample + a.original.sampleCount
+        || a.endSample - a.startSample < c.minimumSamples || !uint(a.exclusiveSamples) || a.exclusiveSamples < c.minimumSamples || a.exclusiveSamples > a.endSample - a.startSample
+        || !Number.isFinite(a.purity) || a.purity < c.minimumPurity || a.purity > 1
+        || Math.abs(a.embedding.reduce((sum, v) => sum + v * v, 0) - 1) > 1e-8 || anchorHash(s, body) !== observationSHA256) fail('state_anchor')
+      used.add(a.original.pcmSHA256)
+      if (t.anchors.some(b => normalizedSpeakerCosine(a.embedding, b.embedding)! < c.anonymousCosine)) fail('state_incoherent')
+    }
+  }
+  if (voices.size !== s.voiceHighWater) fail('state_high_water')
+}
+function decision(s: MacSpeakerMemory, reason: MacSpeakerReason, extras: Partial<MacSpeakerDecision> = {}): MacSpeakerDecision {
+  return { reason, label: null, confidence: 'withheld', evidence: [], scores: [],
+    provenance: { algorithm: MAC_SPEAKER_RECONCILE_VERSION, captureId: s.captureId, modelSHA256: s.modelSHA256, thresholds: { ...s.thresholds } }, ...extras }
+}
+function observationProblem(s: MacSpeakerMemory, o: MacSpeakerObservation): MacSpeakerReason | null {
+  if (!o || o.captureId !== s.captureId || o.modelSHA256 !== s.modelSHA256 || !validOriginal(o.original)
+    || !uint(o.startSample) || !uint(o.endSample) || o.startSample < o.original.startSample || o.endSample > o.original.startSample + o.original.sampleCount
+    || o.endSample <= o.startSample || !uint(o.exclusiveSamples) || o.exclusiveSamples > o.endSample - o.startSample
+    || !Number.isFinite(o.purity) || o.purity < 0 || o.purity > 1 || !uint(o.overlapSamples) || typeof o.mixedSpeakers !== 'boolean'
+    || !normalizedSpeakerEmbedding(o.embedding, s.thresholds.dimensions)) return 'invalid_observation'
+  if (o.mixedSpeakers || o.overlapSamples > 0) return 'mixed_or_overlap'
+  if (o.exclusiveSamples < s.thresholds.minimumSamples || o.purity < s.thresholds.minimumPurity) return 'insufficient_clean_audio'
+  return null
+}
+/** Immutable value transition: caller persists the returned state before publishing
+ * a decision. No elapsed-time eviction, silent merge, number reuse or enrollment.
+ * Memory budgets describe resources, never the number of people in a recording. */
+export function reconcileMacSpeakerObservation(input: MacSpeakerMemory, o: MacSpeakerObservation): { state: MacSpeakerMemory; decision: MacSpeakerDecision } {
+  validateMacSpeakerMemory(input)
+  const state = structuredClone(input)
+  const result = (reason: MacSpeakerReason, extras: Partial<MacSpeakerDecision> = {}) => ({ state, decision: decision(state, reason, extras) })
+  if (o?.protectedLabel && typeof o.protectedLabel.label === 'string' && o.protectedLabel.label.length > 0 && o.protectedLabel.label.length <= 200
+    && ['named', 'manual'].includes(o.protectedLabel.origin)) return result('protected_label', { label: o.protectedLabel.label, confidence: 'protected' })
+  if (o?.protectedLabel) return result('invalid_observation')
+  const problem = observationProblem(state, o)
+  if (problem) return result(problem)
+  const repeated = independent(state.originals, o.original)
+  if (repeated) return result(repeated)
+  if (state.originals.length >= state.thresholds.maxOriginals) return result('budget_exhausted')
+  const embedding = normalizedSpeakerEmbedding(o.embedding, state.thresholds.dimensions)!
+  const scores = state.identities.map(t => {
+    const cosines = t.anchors.map(a => normalizedSpeakerCosine(a.embedding, embedding)!)
+    return { candidate: String(t.id), minimumCosine: Math.min(...cosines), maximumCosine: Math.max(...cosines) }
+  }).sort((a, b) => b.minimumCosine - a.minimumCosine || Number(a.candidate) - Number(b.candidate))
+  const best = scores[0]
+  let target: MacAcousticIdentity | undefined
+  if (best && best.minimumCosine >= state.thresholds.anonymousCosine) {
+    const competitor = Math.max(-1, ...scores.slice(1).map(s => s.maximumCosine))
+    if (best.minimumCosine - competitor < state.thresholds.anonymousMargin) return result('ambiguous', { scores })
+    target = state.identities[Number(best.candidate) - 1]
+  } else if (scores.some(s => s.maximumCosine >= state.thresholds.anonymousCosine)) return result('inconsistent_anchors', { scores })
+  if (!target) {
+    if (state.identities.length >= state.thresholds.maxIdentities) return result('budget_exhausted', { scores })
+    target = { id: state.identities.length + 1, voice: null, anchors: [] }
+    state.identities.push(target)
+  }
+  if (target.voice === null && target.anchors.length + 1 >= state.thresholds.minimumIndependentMatches && state.voiceHighWater >= 99) return result('budget_exhausted', { scores })
+  const body = { original: structuredClone(o.original), startSample: o.startSample, endSample: o.endSample, exclusiveSamples: o.exclusiveSamples, purity: o.purity, embedding }
+  const anchor = { ...body, observationSHA256: anchorHash(state, body) }
+  state.originals.push(structuredClone(o.original))
+  const wasSettled = target.voice !== null
+  target.anchors.push(anchor)
+  // Keep initial independent witnesses forever; only replace later reference
+  // observations. This prevents a chain of moving centroids drifting identities.
+  if (target.anchors.length > state.thresholds.maxAnchorsPerIdentity) target.anchors.splice(state.thresholds.minimumIndependentMatches, 1)
+  if (target.voice === null && target.anchors.length >= state.thresholds.minimumIndependentMatches) {
+    if (state.voiceHighWater >= Number.MAX_SAFE_INTEGER) fail('number_exhausted')
+    target.voice = ++state.voiceHighWater
+  }
+  const evidence = [...new Set([...target.anchors.map(a => a.observationSHA256), anchor.observationSHA256])]
+  validateMacSpeakerMemory(state)
+  return result(target.voice === null ? 'provisional' : wasSettled ? 'recurring_anonymous' : 'confirmed_anonymous', {
+    confidence: target.voice === null ? 'provisional' : 'acoustic', label: target.voice === null ? null : `Voice ${target.voice}`, identityId: target.id, evidence, scores,
+  })
+}
+
+export interface MacSpeakerProfile {
+  name: string
+  /** Freeze/hash the source profile file separately; these are its raw rows. */
+  embeddings: readonly (readonly number[])[]
+  profileSHA256: string
+}
+/** Deliberately preserves production raw-average then normalize centroid math.
+ * Diagnostics based on best-row scores must never replace this recognition rule. */
+function profileCentroid(rows: readonly (readonly number[])[], dimensions: number): number[] | null {
+  if (!Array.isArray(rows) || !rows.length || rows.length > 8192 || Object.keys(rows).length !== rows.length || rows.some(r => !normalizedSpeakerEmbedding(r, dimensions))) return null
+  let scale = 0
+  for (const row of rows) for (const value of row) scale = Math.max(scale, Math.abs(value))
+  const mean = Array.from({ length: dimensions }, (_, i) => rows.reduce((sum, r) => sum + r[i] / scale / rows.length, 0))
+  return normalizedSpeakerEmbedding(mean, dimensions)
+}
+/** Separate, read-only real-name proposal. All independent query witnesses must
+ * agree on the same profile, individually clear .88 and the top-two margin.
+ * Does not mutate acoustic memory or enroll any evidence. */
+export function matchMacSpeakerProfile(memory: MacSpeakerMemory, observations: readonly MacSpeakerObservation[], profiles: readonly MacSpeakerProfile[]): MacSpeakerDecision {
+  validateMacSpeakerMemory(memory)
+  const result = (reason: MacSpeakerReason, extras: Partial<MacSpeakerDecision> = {}) => decision(memory, reason, extras)
+  if (!Array.isArray(observations) || observations.length > memory.thresholds.maxOriginals || !Array.isArray(profiles) || profiles.length > 1024) return result('invalid_observation')
+  if (Object.keys(profiles).length !== profiles.length || profiles.some(p => !p || typeof p.name !== 'string')) return result('invalid_observation')
+  const candidates = profiles.map(p => ({ ...p, centroid: profileCentroid(p.embeddings, memory.thresholds.dimensions) }))
+  if (candidates.some(p => !checkSpeakerName(p.name).ok || /^(?:Voice\s+\d+|Ext|Speaker\s+\d+)$/i.test(p.name) || !SHA.test(p.profileSHA256) || !p.centroid)
+    || new Set(candidates.map(p => p.name.toLowerCase())).size !== candidates.length) return result('invalid_observation')
+  const originals: MacSpeakerOriginal[] = []
+  const anchors: MacSpeakerAnchor[] = []
+  for (const o of observations) {
+    if (o?.protectedLabel) {
+      if (typeof o.protectedLabel.label !== 'string' || !o.protectedLabel.label.length || o.protectedLabel.label.length > 200 || !['named', 'manual'].includes(o.protectedLabel.origin)) return result('invalid_observation')
+      return result('protected_label', { label: o.protectedLabel.label, confidence: 'protected' })
+    }
+    const problem = observationProblem(memory, o)
+    if (problem) return result(problem)
+    const repeated = independent(originals, o.original)
+    if (repeated) return result(repeated)
+    originals.push(o.original)
+    const body = { original: structuredClone(o.original), startSample: o.startSample, endSample: o.endSample, exclusiveSamples: o.exclusiveSamples, purity: o.purity, embedding: normalizedSpeakerEmbedding(o.embedding, memory.thresholds.dimensions)! }
+    anchors.push({ ...body, observationSHA256: anchorHash(memory, body) })
+  }
+  if (anchors.length < memory.thresholds.minimumIndependentMatches) return result('insufficient_independent_matches')
+  if (anchors.some(a => anchors.some(b => normalizedSpeakerCosine(a.embedding, b.embedding)! < memory.thresholds.anonymousCosine))) return result('inconsistent_anchors')
+  let winner: typeof candidates[number] | undefined
+  const scores: MacSpeakerDecision['scores'] = candidates.map(p => {
+    const cosines = anchors.map(a => normalizedSpeakerCosine(a.embedding, p.centroid!)!)
+    return { candidate: p.name, minimumCosine: Math.min(...cosines), maximumCosine: Math.max(...cosines) }
+  }).sort((a, b) => b.minimumCosine - a.minimumCosine || a.candidate.localeCompare(b.candidate))
+  for (const a of anchors) {
+    const ranking = candidates.map(p => ({ profile: p, score: normalizedSpeakerCosine(a.embedding, p.centroid!)! })).sort((a, b) => b.score - a.score)
+    if (!ranking.length || ranking[0].score < memory.thresholds.identityCosine) return result('profile_below_floor', { scores })
+    if (ranking[0].score - (ranking[1]?.score ?? -1) < memory.thresholds.identityMargin) return result('profile_ambiguity', { scores })
+    if (winner && winner.name !== ranking[0].profile.name) return result('profile_disagreement', { scores })
+    winner = ranking[0].profile
+  }
+  return result('matched_profile', { label: winner!.name, confidence: 'profile', scores, evidence: anchors.map(a => a.observationSHA256), provenance: {
+    algorithm: MAC_SPEAKER_RECONCILE_VERSION, captureId: memory.captureId, modelSHA256: memory.modelSHA256, thresholds: { ...memory.thresholds }, profileSHA256: winner!.profileSHA256,
+  } })
+}