@gotcos/glasses-server 6.94.1 → 6.94.3

package/server/lib/mac-speaker-repair-projection.ts

@@ -0,0 +1,301 @@
+/** Pure, conservative label projection. No file access, capture, inference or enrollment.
+ * V1 accepts whole automatic anonymous chunks only. Mixed chunks and words crossing
+ * their boundaries require a future, independently reviewed span-level projection.
+ * The caller owns durable intents, byte-level file CAS, revisions and rendering.
+ */
+import { createHash } from 'node:crypto'
+import { checkSpeakerName } from './speaker-name.js'
+import { hasMacSpeakerProtectedRows, isMacSpeakerHumanProtected as isProtected } from './mac-speaker-protection.js'
+
+type Doc = Record<string, any>
+export type MacSpeakerRepairPath = Array<string | number>
+export interface MacSpeakerRepairPatch {
+  path: MacSpeakerRepairPath
+  before: unknown
+  after: unknown
+}
+export interface MacSpeakerWordBinding {
+  segmentIndex: number
+  wordIndex: number
+  from: string
+  word: string
+  /** Exact segment-relative seconds, not rounded timestamps. */
+  start: number
+  end: number
+}
+export interface MacProfileMatchEvidence {
+  kind: 'profile-match'
+  profileName: string
+  profileSha256: string
+  modelSha256: string
+  algorithmVersion: string
+  /** Complete-link consistency; every independent pair must meet .90. */
+  crossWindowCosines: number[][]
+  windows: Array<{
+    id: string
+    captureStartSample: number
+    captureEndSample: number
+    pcmSha256: string
+    similarity: number
+    runnerUpSimilarity: number
+    rawChunks: Array<{ rawChunkIndex: number; audioSha256: string; sampleCount: number }>
+  }>
+}
+export interface MacSpeakerRepairAssignment {
+  rawChunkIndex: number
+  from: string
+  /** A settled Voice N label, or an existing profile name with targetEvidence. */
+  to: string
+  evidenceId: string
+  batchWords: MacSpeakerWordBinding[]
+  targetEvidence?: MacProfileMatchEvidence
+}
+export interface MacSpeakerRepairPlan {
+  id: string
+  evidenceHash: string
+  expectedDocumentHash: string
+  /** Explicit ledger-only protection, even for legacy edits without markers. */
+  protectedRawChunkIndices: number[]
+  /** Verified mono 16 kHz PCM sample counts, including silent/untranscribed raw files. */
+  rawAudioSampleCounts: Record<string, number>
+  assignments: MacSpeakerRepairAssignment[]
+  /** Explicitly withheld words partly outside qualified chunk unions. */
+  withheldBatchWords?: Array<MacSpeakerWordBinding & { reason: 'outside-qualified-span' }>
+}
+export interface MacSpeakerRepairReceipt {
+  version: 1
+  id: string
+  evidenceHash: string
+  beforeHash: string
+  afterHash: string
+  rawChunkIndices: number[]
+  evidenceIds: string[]
+  patches: MacSpeakerRepairPatch[]
+  assignments: MacSpeakerRepairAssignment[]
+  withheldBatchWords: Array<MacSpeakerWordBinding & { reason: 'outside-qualified-span' }>
+  receiptHash: string
+}
+/** Persisted model/profile proof; never a human confirmation or training input. */
+export interface MacSpeakerMachineEvidence {
+  version: 1
+  correctionRevision: number
+  documentBinding: string
+  receipt: MacSpeakerRepairReceipt
+  rawAudioSampleCounts: Record<string, number>
+}
+/** Exact current speech surfaces, independent of lifecycle/sync metadata and
+ * the proof itself. This deliberately binds diagnostics as well as labels. */
+export function hashMacSpeakerMachineBinding(doc: Doc): string {
+  return hashMacSpeakerDocument({
+    sessionId: doc.sessionId, sourceType: doc.sourceType, captureSource: doc.captureSource,
+    startTime: doc.startTime, durationMs: doc.durationMs,
+    chunks: doc.chunks, chunkEntries: doc.chunkEntries,
+    batchSegments: doc.batchSegments, batchTranscript: doc.batchTranscript, speakers: doc.speakers,
+  })
+}
+export function hashMacSpeakerDocument(doc: Doc): string {
+  return createHash('sha256').update(JSON.stringify(doc)).digest('hex')
+}
+const equal = (a: unknown, b: unknown) => JSON.stringify(a) === JSON.stringify(b)
+const anonymous = (label: unknown): label is string => typeof label === 'string' && /^(?:Ext|Unknown|Unidentified(?: \d+)?|Speaker \d+|Voice \d+)$/.test(label)
+const hashPattern = /^[a-f0-9]{64}$/
+function fail(message: string): never { throw new Error(`Mac speaker repair: ${message}`) }
+/** Validate compacted position -> exact ordered raw chunk, without nearest joins. */
+function rawMap(doc: Doc): Array<{ raw: number; entry: number }> {
+  if (!Array.isArray(doc.chunks) || !Array.isArray(doc.chunkEntries)) fail('missing raw chunk map')
+  const all = doc.chunkEntries.map((entry: any, i: number) => ({ entry, i }))
+  if (all.some(({ entry }: any) => !entry || !Number.isInteger(entry.chunkIndex) || entry.chunkIndex < 0)) fail('invalid raw chunk entry')
+  const indexes = all.map(({ entry }: any) => entry.chunkIndex)
+  if (new Set(indexes).size !== indexes.length || indexes.some((raw: number, i: number) => i > 0 && raw <= indexes[i - 1])) fail('ambiguous raw index ordering')
+  const spoken = all.filter(({ entry }: any) => entry.chunk?.text)
+  if (spoken.length !== doc.chunks.length || spoken.some(({ entry }: any, i: number) => entry.chunk.text !== doc.chunks[i]?.text)) fail('raw map and ordered text disagree')
+  return spoken.map(({ entry, i }: any) => ({ raw: entry.chunkIndex, entry: i }))
+}
+function labelRows(chunk: Doc, path: MacSpeakerRepairPath): Array<{ row: Doc; path: MacSpeakerRepairPath }> {
+  const rows = [{ row: chunk, path }]
+  for (const key of ['segments', 'finalSegments', 'words']) {
+    if (chunk[key] !== undefined && !Array.isArray(chunk[key])) fail(`invalid ${key} surface`)
+    for (const [i, row] of (chunk[key] ?? []).entries()) {
+      if (!row || typeof row !== 'object') fail(`invalid ${key} row`)
+      // Plain ASR words do not necessarily have any speaker field.
+      if (key !== 'words' || 'speaker' in row) rows.push({ row, path: [...path, key, i] })
+    }
+  }
+  return rows
+}
+function requireClosed(doc: Doc) {
+  if (doc.finalizationState !== 'complete' || doc.claimPending === true || doc.active === true || doc.isActive === true || doc.status === 'recording') fail('capture is not closed and finalized')
+  if (doc.sourceType !== 'mac_system_audio' || !/^mac_/.test(doc.sessionId ?? '') || doc.mergedFrom || doc.sourceSessionIds || doc.isMerged) fail('expected an original Mac capture')
+}
+function receiptDigest(receipt: Omit<MacSpeakerRepairReceipt, 'receiptHash'>): string { return hashMacSpeakerDocument(receipt) }
+
+export function validateMacSpeakerTargetEvidence(input: Doc, plan: MacSpeakerRepairPlan, assignment: MacSpeakerRepairAssignment) {
+  if (/^Voice (?:[1-9]|[1-9]\d)$/.test(assignment.to)) return
+  const proof = assignment.targetEvidence
+  if (!checkSpeakerName(assignment.to).ok || !assignment.to || assignment.to.trim() !== assignment.to || assignment.to.length > 120 || /[\[\]\r\n]/.test(assignment.to) || anonymous(assignment.to) || !proof || proof.kind !== 'profile-match' || proof.profileName !== assignment.to || !hashPattern.test(proof.profileSha256) || !hashPattern.test(proof.modelSha256) || !proof.algorithmVersion?.trim() || !Array.isArray(proof.windows) || proof.windows.length < 2) fail('named target requires immutable independent profile evidence')
+  if (!Array.isArray(proof.crossWindowCosines) || proof.crossWindowCosines.length !== proof.windows.length || proof.crossWindowCosines.some(row => !Array.isArray(row) || row.length !== proof.windows.length)) fail('complete cross-window evidence matrix required')
+  for (let i = 0; i < proof.windows.length; i++) for (let j = 0; j < proof.windows.length; j++) {
+    const cosine = proof.crossWindowCosines[i][j]
+    if (!Number.isFinite(cosine) || cosine < .9 || cosine > 1.000001 || Math.abs(cosine - proof.crossWindowCosines[j][i]) > 1e-8 || (i === j && Math.abs(cosine - 1) > 1e-6)) fail('cross-window evidence is inconsistent')
+  }
+  const rawSeen = new Set<number>(), pcmSeen = new Set<string>(), ids = new Set<string>(), spans: Array<[number, number]> = []
+  let covered = false
+  for (const window of proof.windows) {
+    if (!window.id || ids.has(window.id) || !hashPattern.test(window.pcmSha256) || pcmSeen.has(window.pcmSha256) || !Number.isSafeInteger(window.captureStartSample) || !Number.isSafeInteger(window.captureEndSample) || window.captureStartSample < 0 || window.captureEndSample <= window.captureStartSample || !Number.isFinite(window.similarity) || window.similarity < .88 || window.similarity > 1 || !Number.isFinite(window.runnerUpSimilarity) || window.runnerUpSimilarity < -1 || window.runnerUpSimilarity > 1 || window.similarity - window.runnerUpSimilarity < .05 || !Array.isArray(window.rawChunks) || !window.rawChunks.length) fail('weak, repeated or invalid profile evidence')
+    if (spans.some(([start, end]) => window.captureStartSample < end && window.captureEndSample > start)) fail('overlapping profile evidence windows')
+    spans.push([window.captureStartSample, window.captureEndSample]); pcmSeen.add(window.pcmSha256); ids.add(window.id)
+    const duration = (window.captureEndSample - window.captureStartSample) / 16000
+    if (duration < 28 || duration > 31) fail('profile evidence requires full 28-31s windows')
+    let samples = 0, previous = -1, pureSeconds = 0
+    for (const raw of window.rawChunks) {
+      if (!Number.isInteger(raw.rawChunkIndex) || rawSeen.has(raw.rawChunkIndex) || (previous >= 0 && raw.rawChunkIndex !== previous + 1) || !hashPattern.test(raw.audioSha256) || !Number.isSafeInteger(raw.sampleCount) || raw.sampleCount <= 0 || plan.rawAudioSampleCounts[String(raw.rawChunkIndex)] !== raw.sampleCount) fail('profile evidence raw bindings disagree')
+      const chunk = input.chunkEntries.find((entry: Doc) => entry.chunkIndex === raw.rawChunkIndex)?.chunk
+      if (!chunk || chunk.audioSha256 !== raw.audioSha256 || !Number.isFinite(chunk.elapsed) || chunk.elapsed * 16 !== window.captureStartSample + samples) fail('profile evidence capture coordinates disagree')
+      if (chunk.speakerPolicy === 'anonymous' || !anonymous(chunk.speaker) || hasMacSpeakerProtectedRows(chunk) || labelRows(chunk, []).some(({row}) => isProtected(row) || row.speaker !== chunk.speaker)) fail('profile evidence contains named/manual/mixed or anonymous-policy chunks')
+      const segments = chunk.finalSegments?.length ? chunk.finalSegments : chunk.segments
+      if (!Array.isArray(segments) || !segments.length) fail('profile evidence lacks automatic pure segment coverage')
+      const ranges: Array<[number, number]> = segments.map((segment: Doc) => [segment.startSec, segment.endSec])
+      if (ranges.some(([start,end]) => !Number.isFinite(start) || !Number.isFinite(end) || start < 0 || end < start || end > raw.sampleCount / 16000)) fail('profile evidence segment coordinates disagree')
+      ranges.sort((a,b)=>a[0]-b[0]); let end = 0
+      for (const [start,stop] of ranges) { pureSeconds += Math.max(0,stop-Math.max(start,end)); end=Math.max(end,stop) }
+      if (raw.rawChunkIndex === assignment.rawChunkIndex) covered = true
+      rawSeen.add(raw.rawChunkIndex); previous = raw.rawChunkIndex; samples += raw.sampleCount
+    }
+    if (pureSeconds < 20) fail('profile evidence needs at least20s of automatic pure segment coverage')
+    if (samples !== window.captureEndSample - window.captureStartSample) fail('profile evidence sample span disagrees')
+  }
+  if (!covered) fail('assignment lies outside qualified profile evidence')
+}
+
+export function projectMacSpeakerRepair(input: Doc, plan: MacSpeakerRepairPlan): { doc: Doc; receipt: MacSpeakerRepairReceipt } {
+  requireClosed(input)
+  if (!plan.id?.trim() || !hashPattern.test(plan.evidenceHash) || plan.expectedDocumentHash !== hashMacSpeakerDocument(input)) fail('plan evidence or document CAS mismatch')
+  if (!Array.isArray(plan.protectedRawChunkIndices) || plan.protectedRawChunkIndices.some(i => !Number.isInteger(i) || i < 0)) fail('explicit ledger protection is required')
+  if (!Array.isArray(plan.assignments) || plan.assignments.length === 0) fail('no explicit assignments')
+  const mapping = rawMap(input)
+  const doc = structuredClone(input)
+  const patches: MacSpeakerRepairPatch[] = []
+  const patch = (path: MacSpeakerRepairPath, after: unknown) => {
+    let row = doc
+    for (const key of path.slice(0, -1)) row = row[key]
+    const key = path.at(-1)!
+    if (equal(row[key], after)) return
+    patches.push({ path, before: structuredClone(row[key]), after: structuredClone(after) })
+    row[key] = structuredClone(after)
+  }
+  if (!plan.rawAudioSampleCounts || typeof plan.rawAudioSampleCounts !== 'object') fail('verified raw audio sample counts are required')
+  const selected = new Map<number, { assignment: MacSpeakerRepairAssignment }>()
+  for (const assignment of plan.assignments) {
+    if (selected.has(assignment.rawChunkIndex) || plan.protectedRawChunkIndices.includes(assignment.rawChunkIndex)) fail('duplicate or ledger-protected chunk')
+    if (!anonymous(assignment.from) || !assignment.evidenceId?.trim() || !Array.isArray(assignment.batchWords)) fail('assignment requires anonymous labels and explicit evidence')
+    validateMacSpeakerTargetEvidence(input, plan, assignment)
+    const position = mapping.findIndex(row => row.raw === assignment.rawChunkIndex)
+    if (position < 0) fail('unknown raw chunk')
+    const chunk = input.chunks[position]
+    const entry = input.chunkEntries[mapping[position].entry].chunk
+    if (!Number.isFinite(chunk.elapsed) || !Number.isFinite(chunk.audioDurationMs) || chunk.audioDurationMs <= 0 || entry.elapsed !== chunk.elapsed || entry.audioDurationMs !== chunk.audioDurationMs) fail('raw chunk timing disagreement')
+    // Surface identity must match, including text/times/original diagnostic fields.
+    for (const key of ['speaker', 'segments', 'finalSegments', 'words']) if (!equal(chunk[key], entry[key])) fail('chunk and entry label surfaces disagree')
+    if (hasMacSpeakerProtectedRows(chunk) || hasMacSpeakerProtectedRows(entry)) fail('named or manual span is protected')
+    for (const target of [{ chunk, path: ['chunks', position] }, { chunk: entry, path: ['chunkEntries', mapping[position].entry, 'chunk'] }]) {
+      for (const { row, path } of labelRows(target.chunk, target.path)) {
+        if (isProtected(row) || !anonymous(row.speaker)) fail('named or manual span is protected')
+        if (row.speaker !== assignment.from) fail('mixed chunk requires exact span repair')
+        patch([...path, 'speaker'], assignment.to)
+      }
+    }
+    selected.set(assignment.rawChunkIndex, { assignment })
+  }
+  const withheld = new Map<string, MacSpeakerWordBinding>(), usedWithheld = new Set<string>()
+  for (const binding of plan.withheldBatchWords ?? []) {
+    const key = `${binding.segmentIndex}:${binding.wordIndex}`
+    if (binding.reason !== 'outside-qualified-span' || withheld.has(key) || !Number.isInteger(binding.segmentIndex) || !Number.isInteger(binding.wordIndex)) fail('invalid withheld boundary word binding')
+    withheld.set(key, binding)
+  }
+  const expectedWords = new Map<string, MacSpeakerRepairAssignment>()
+  const batchSegments = input.batchSegments ?? []
+  if (!Array.isArray(batchSegments)) fail('invalid batch segments')
+  for (const [si, segment] of batchSegments.entries()) {
+    if (!Array.isArray(segment.speakerWords)) fail('batch speaker words are missing')
+    const rangeSelected = [...selected.keys()].some(raw => raw >= segment.startChunkIdx && raw <= segment.endChunkIdx)
+    if (!rangeSelected) continue
+    if (!Number.isInteger(segment.startChunkIdx) || !Number.isInteger(segment.endChunkIdx) || segment.startChunkIdx < 0 || segment.endChunkIdx < segment.startChunkIdx) fail('invalid batch raw range')
+    // Batch seconds index concatenated PCM files, including silent files. They
+    // are NOT startElapsed + seconds on the compacted transcript timeline.
+    const intervals: Array<{ raw: number; start: number; end: number }> = []
+    let offset = 0
+    for (let raw = segment.startChunkIdx; raw <= segment.endChunkIdx; raw++) {
+      const samples = plan.rawAudioSampleCounts[String(raw)]
+      if (!Number.isSafeInteger(samples) || samples <= 0) fail('missing verified raw audio sample count')
+      const end = offset + samples / 16000
+      intervals.push({ raw, start: offset, end })
+      offset = end
+    }
+    for (const [wi, word] of segment.speakerWords.entries()) {
+      if (!Number.isFinite(word.start) || !Number.isFinite(word.end) || word.start < 0 || word.end < word.start || word.end > offset) fail('invalid batch word timing')
+      const overlaps = intervals.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))) continue
+      if (overlaps.some(s => !selected.has(s.raw))) {
+        const key = `${si}:${wi}`, binding = withheld.get(key)
+        if (!binding || word.word !== binding.word || word.start !== binding.start || word.end !== binding.end || word.speaker !== binding.from) fail('batch word crosses selected raw chunk boundaries')
+        usedWithheld.add(key); continue
+      }
+      if (new Set(overlaps.map(s => selected.get(s.raw)?.assignment.to)).size !== 1) fail('batch word crosses selected raw chunk boundaries')
+      const span = selected.get(overlaps[0].raw)!
+      if (isProtected(word) || !anonymous(word.speaker)) fail('named or manual batch word is protected')
+      expectedWords.set(`${si}:${wi}`, span.assignment)
+    }
+  }
+  if (usedWithheld.size !== withheld.size) fail('withheld boundary word is not outside qualified span')
+  const seen = new Set<string>()
+  for (const assignment of plan.assignments) for (const binding of assignment.batchWords) {
+    const key = `${binding.segmentIndex}:${binding.wordIndex}`
+    if (!Number.isInteger(binding.segmentIndex) || !Number.isInteger(binding.wordIndex) || seen.has(key) || expectedWords.get(key) !== assignment) fail('unexpected or duplicate batch word binding')
+    seen.add(key)
+    const word = batchSegments[binding.segmentIndex].speakerWords[binding.wordIndex]
+    if (word.word !== binding.word || word.start !== binding.start || word.end !== binding.end || word.speaker !== binding.from) fail('batch word evidence disagrees')
+    patch(['batchSegments', binding.segmentIndex, 'speakerWords', binding.wordIndex, 'speaker'], assignment.to)
+  }
+  if (seen.size !== expectedWords.size) fail('incomplete batch word coverage')
+  const labels: string[] = []
+  for (const chunk of doc.chunks) for (const { row } of labelRows(chunk, [])) if (typeof row.speaker === 'string' && row.speaker && !anonymous(row.speaker)) labels.push(row.speaker)
+  for (const segment of doc.batchSegments ?? []) for (const word of segment.speakerWords ?? []) if (typeof word.speaker === 'string' && word.speaker && !anonymous(word.speaker)) labels.push(word.speaker)
+  // Do not invent identities, and do not carry anonymous voices into a real-name list.
+  patch(['speakers'], [...new Set(labels)])
+  const unsigned: Omit<MacSpeakerRepairReceipt, 'receiptHash'> = {
+    version: 1, id: plan.id, evidenceHash: plan.evidenceHash,
+    beforeHash: hashMacSpeakerDocument(input), afterHash: hashMacSpeakerDocument(doc),
+    assignments: structuredClone(plan.assignments), withheldBatchWords: structuredClone(plan.withheldBatchWords ?? []),
+    rawChunkIndices: plan.assignments.map(row => row.rawChunkIndex), evidenceIds: plan.assignments.map(row => row.evidenceId), patches,
+  }
+  return { doc, receipt: { ...unsigned, receiptHash: receiptDigest(unsigned) } }
+}
+
+/** Full-document CAS is intentionally conservative: even unrelated drift needs
+ * a fresh review. This pure operation never overwrites a later correction.
+ * Replaying a completed apply/undo is idempotent; partial states fail closed.
+ */
+export function applyMacSpeakerRepair(input: Doc, receipt: MacSpeakerRepairReceipt, direction: 'forward' | 'reverse' = 'forward'): Doc {
+  const { receiptHash, ...unsigned } = receipt
+  if (receipt.version !== 1 || receiptDigest(unsigned) !== receiptHash) fail('receipt integrity mismatch')
+  const forward = direction === 'forward'
+  const before = forward ? receipt.beforeHash : receipt.afterHash
+  const after = forward ? receipt.afterHash : receipt.beforeHash
+  const current = hashMacSpeakerDocument(input)
+  if (current === after) return structuredClone(input)
+  if (current !== before) fail('document drift; review before apply or undo')
+  const doc = structuredClone(input)
+  const ordered = forward ? receipt.patches : [...receipt.patches].reverse()
+  for (const patch of ordered) {
+    if (!patch.path.length || patch.path.some(key => ['__proto__', 'prototype', 'constructor'].includes(String(key)))) fail('unsafe patch path')
+    let row = doc
+    for (const key of patch.path.slice(0, -1)) { if (!row || typeof row !== 'object' || !(key in row)) fail('patch shape drift'); row = row[key] }
+    const key = patch.path.at(-1)!
+    if (!equal(row[key], forward ? patch.before : patch.after)) fail('patch value drift')
+    const value = forward ? patch.after : patch.before
+    if (value === undefined) delete row[key]
+    else row[key] = structuredClone(value)
+  }
+  if (hashMacSpeakerDocument(doc) !== after) fail('projection postimage mismatch')
+  return doc
+}

package/server/lib/mac-speaker-repair-render.ts

@@ -0,0 +1,105 @@
+// Pure exact-token rendering shared by offline repair and saved Mac finalization.
+type Doc = Record<string, any>
+function refuse(message: string): never { throw new Error(`Mac speaker repair: ${message}`) }
+export interface BoundWord { word: string; before: string; after: string }
+export function boundWords(before: Doc, after: Doc): BoundWord[] {
+  if (before.batchApplied !== true || !Array.isArray(before.batchSegments) || !before.batchSegments.length) refuse('v1 requires complete canonical batch speaker words')
+  return before.batchSegments.flatMap((segment: Doc, si: number) => {
+    if (!Array.isArray(segment.speakerWords) || segment.speakerWords.length !== after.batchSegments[si]?.speakerWords?.length) refuse('incomplete batch speaker words')
+    return segment.speakerWords.flatMap((row: Doc, wi: number) => {
+      const next = after.batchSegments[si].speakerWords[wi]
+      if (typeof row.word !== 'string' || typeof row.speaker !== 'string' || typeof next.speaker !== 'string') refuse('invalid canonical word binding')
+      return row.word.match(/\S+/gu)?.map((word: string) => ({ word, before: row.speaker, after: next.speaker })) ?? []
+    })
+  })
+}
+/** Exact ordered tokens + exact old labels, no nearest/anchor/substring guessing.
+ * Spoken token bytes and original separators remain; only prefixes are replaced
+ * or inserted when an existing turn must split at a proven word boundary.
+ */
+export function renderBoundSpeakerLabels(transcript: string, words: BoundWord[], preserveUnlabelled = false): string {
+  let pointer = 0
+  const result = transcript.split('\n').map(line => {
+    const match = /^(\[([^\]\r\n]+)\]:[ \t]*)(.*)$/.exec(line)
+    if (!match) { if (line.trim() && !preserveUnlabelled) refuse('unbound nonempty transcript line'); return line }
+    const tokens = [...match[3].matchAll(/\S+/gu)]
+    if (!tokens.length) return line
+    let out = '', previous: string | null = null, consumed = 0
+    for (const token of tokens) {
+      const bound = words[pointer++]
+      if (!bound || bound.word !== token[0] || bound.before !== match[2]) refuse('transcript words/labels do not exactly match canonical evidence')
+      const offset = token.index!
+      out += match[3].slice(consumed, offset)
+      if (previous === null) out = match[1].replace(`[${match[2]}]`, `[${bound.after}]`) + out
+      else if (previous !== bound.after) out += `\n[${bound.after}]: `
+      out += token[0]; consumed = offset + token[0].length; previous = bound.after
+    }
+    return out + match[3].slice(consumed)
+  }).join('\n')
+  if (pointer !== words.length) refuse('transcript has missing canonical words')
+  return result
+}
+/** Omitted/cleaned unaffected lines may stay. Every changed canonical token
+ * must still be covered by exactly one full-line, exact-token + old-label join. */
+export function renderSparseBoundSpeakerLabels(transcript: string, words: BoundWord[]): string {
+  const covered = new Set<number>()
+  let lastEnd = 0
+  const out = transcript.split('\n').map(line => {
+    const match = /^(\[([^\]\r\n]+)\]:[ \t]*)(.*)$/.exec(line)
+    if (!match) return line
+    const tokens = match[3].match(/\S+/gu) ?? []
+    if (!tokens.length) return line
+    const candidates: number[] = []
+    for (let start = 0; start <= words.length - tokens.length; start++) {
+      if (tokens.every((token, offset) => words[start + offset].word === token && words[start + offset].before === match[2])) candidates.push(start)
+    }
+    const affects = (start: number) => words.slice(start, start + tokens.length).some(word => word.before !== word.after)
+    if (candidates.length !== 1) {
+      if (candidates.some(affects)) refuse('changed markdown line has ambiguous canonical binding')
+      return line
+    }
+    const start = candidates[0], end = start + tokens.length
+    if (start < lastEnd) refuse('markdown canonical line order disagrees')
+    lastEnd = end
+    for (let index = start; index < end; index++) covered.add(index)
+    return affects(start) ? renderBoundSpeakerLabels(line, words.slice(start, end)) : line
+  }).join('\n')
+  if (words.some((word, index) => word.before !== word.after && !covered.has(index))) refuse('changed canonical words lack unique complete markdown binding')
+  return out
+}
+/** The operations importer writes this literal marker after a character-limited
+ * canonical preview. Only an exact ordered prefix may waive omitted tail words. */
+export function renderTruncatedBoundSpeakerLabels(body: string, words: BoundWord[]): string {
+  const marker = '... [Transcript truncated for length]'
+  const position = body.indexOf(marker)
+  if (position < 0 || body.indexOf(marker, position + marker.length) >= 0) refuse('one explicit transcript truncation marker required')
+  const shown = body.slice(0, position), suffix = body.slice(position)
+  if (/^\[[^\]\r\n]+\]:/m.test(suffix)) refuse('spoken lines follow transcript truncation marker')
+  const tokens: Array<{word: string; label: string}> = []
+  for (const line of shown.split('\n')) {
+    const match = /^\[([^\]\r\n]+)\]:[ \t]*(.*)$/.exec(line)
+    if (match) for (const word of match[2].match(/\S+/gu) ?? []) tokens.push({word, label:match[1]})
+  }
+  if (!tokens.length || tokens.length >= words.length) refuse('truncation marker does not describe a canonical prefix')
+  const visible = tokens.map((token, index) => {
+    const bound = words[index]
+    const partial = index === tokens.length - 1 && bound.word.startsWith(token.word)
+    if (bound.before !== token.label || (bound.word !== token.word && !partial)) refuse('truncated preview is not an exact canonical prefix')
+    return {...bound, word:token.word}
+  })
+  return renderBoundSpeakerLabels(shown, visible, true) + suffix
+}
+export function renderMarkdown(markdown: string, words: BoundWord[]): string {
+  const headings = [...markdown.matchAll(/^## Transcript[^\n]*\n/gm)]
+  if (headings.length !== 1) refuse('exactly one Transcript section required')
+  const start = headings[0].index! + headings[0][0].length
+  const next = /^## /m.exec(markdown.slice(start)), end = next ? start + next.index : markdown.length
+  const body = markdown.slice(start, end)
+  let rendered: string
+  if (body.includes('... [Transcript truncated for length]')) rendered = renderTruncatedBoundSpeakerLabels(body, words)
+  else {
+    try { rendered = renderBoundSpeakerLabels(body, words, true) }
+    catch { rendered = renderSparseBoundSpeakerLabels(body, words) }
+  }
+  return markdown.slice(0, start) + rendered + markdown.slice(end)
+}

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

@@ -0,0 +1,239 @@
+// Pure preparation/qualification only. The caller verifies WAVs, runs extraction,
+// authenticates these receipts and applies reviewed exact-span candidates.
+import { createHash } from 'node:crypto'
+import { isVoiceLabel } from './mac-voice-labels.js'
+import { hasMacSpeakerProtectedRows } from './mac-speaker-protection.js'
+import {
+  createMacSpeakerMemory, matchMacSpeakerProfile, normalizedSpeakerCosine, normalizedSpeakerEmbedding,
+  reconcileMacSpeakerObservation, type MacSpeakerObservation, type MacSpeakerProfile,
+} from './mac-speaker-reconcile.js'
+import type { SidecarEntry } from './nemotron-final.js'
+const SR = 16_000
+const SHA = /^[a-f0-9]{64}$/
+const uint = (n: unknown): n is number => Number.isSafeInteger(n) && Number(n) >= 0
+const samplePosition = (value: number): number => Number.isFinite(value) && Math.abs(value - Math.round(value)) <= 1e-6 ? Math.round(value) : Number.NaN
+const hash = (v: unknown): string => createHash('sha256').update(JSON.stringify(v)).digest('hex')
+export const MAC_SPEAKER_WINDOW_VERSION = 'exact-window-v1'
+export interface VerifiedMacRawChunk {
+  chunkIndex: number
+  audioSHA256: string
+  pcmSHA256: string
+  sampleRate: 16000
+  channels: 1
+  format: 'pcm_s16le'
+  sampleCount: number
+  verified: true
+}
+export interface MacWindowSource extends VerifiedMacRawChunk {
+  startSample: number
+  endSample: number
+  /** Automatic segment span coverage, not independent VAD/purity ground truth. */
+  speechSamples: number
+  textSHA256: string
+  segmentsSHA256: string
+}
+export interface PreparedMacSpeakerWindow {
+  id: string
+  captureId: string
+  originalVoiceHint: string
+  startSample: number
+  endSample: number
+  sampleCount: number
+  speechSamples: number
+  sources: MacWindowSource[]
+  bindingSHA256: string
+}
+export interface MacSpeakerWindowPlan {
+  version: typeof MAC_SPEAKER_WINDOW_VERSION
+  captureId: string
+  /** These families are candidate scheduling hints, never speaker identities. */
+  families: { originalVoiceHint: string; windowIds: string[] }[]
+  windows: PreparedMacSpeakerWindow[]
+  rejected: { chunkIndexes: number[]; reason: string }[]
+  thresholds: { windowSamples: number; minimumWindowSamples: number; minimumSpeechSamples: number }
+}
+export interface MacSpeakerWindowInput {
+  sidecar: { sessionId: string; correctionRevision?: number; chunkEntries?: SidecarEntry[] }
+  rawChunks: VerifiedMacRawChunk[]
+  /** Includes ledger-only legacy corrections; unavailable must fail closed. */
+  correctionHistory: 'verified-clear' | 'human-corrected' | 'unavailable'
+  correctedChunkIndexes?: readonly number[]
+  minimumSpeechSamples?: number
+}
+function sourceOf(entry: SidecarEntry, raw: VerifiedMacRawChunk | undefined): { source?: MacWindowSource; hint?: string; reason?: string } {
+  const c = entry?.chunk
+  if (!c || !raw || !uint(entry.chunkIndex) || raw.chunkIndex !== entry.chunkIndex || raw.verified !== true
+    || raw.sampleRate !== SR || raw.channels !== 1 || raw.format !== 'pcm_s16le' || !uint(raw.sampleCount) || !raw.sampleCount || raw.sampleCount > 480_000
+    || !SHA.test(raw.audioSHA256) || !SHA.test(raw.pcmSHA256) || c.audioSha256 !== raw.audioSHA256) return { reason: 'unverified_raw_binding' }
+  if (c.speakerPolicy !== 'high-confidence' || !isVoiceLabel(c.speaker) || typeof c.text !== 'string' || !c.text.trim()) return { reason: 'not_automatic_homogeneous' }
+  if (hasMacSpeakerProtectedRows(c)) return { reason: 'human_corrected' }
+  const segments = c.segments
+  if (!Array.isArray(segments) || !segments.length || segments.length > 1024 || segments.some(s => s?.speaker !== c.speaker)
+    || segments.map(s => s.text).join(' ').trim().split(/\s+/).join(' ') !== c.text.trim().split(/\s+/).join(' ')) return { reason: 'not_automatic_homogeneous' }
+  const startSample = samplePosition(Number(c.elapsed) * SR / 1000)
+  if (!uint(startSample) || !Number.isSafeInteger(startSample + raw.sampleCount)) return { reason: 'bad_clock' }
+  let end = 0, speechSamples = 0
+  for (const s of segments) {
+    const a = samplePosition(Number(s.startSec) * SR), b = samplePosition(Number(s.endSec) * SR)
+    if (!uint(a) || !uint(b) || a < end || b <= a || b > raw.sampleCount || (s as unknown as Record<string, unknown>).overlap === true || (s as unknown as Record<string, unknown>).mixedSpeakers === true) return { reason: 'mixed_or_invalid_segments' }
+    speechSamples += b - a; end = b
+  }
+  return { source: { ...structuredClone(raw), startSample, endSample: startSample + raw.sampleCount, speechSamples,
+    textSHA256: hash(c.text), segmentsSHA256: hash(segments) }, hint: c.speaker }
+}
+/** Non-overlapping original chunks only. No cross-label concatenation, gap
+ * filling, arbitrary crops, inferred names or automatic enrollment. */
+export function planMacSpeakerWindows(input: MacSpeakerWindowInput): MacSpeakerWindowPlan {
+  const captureId = input.sidecar.sessionId
+  const minimumSpeechSamples = input.minimumSpeechSamples ?? 320_000
+  const plan: MacSpeakerWindowPlan = { version: MAC_SPEAKER_WINDOW_VERSION, captureId, families: [], windows: [], rejected: [], thresholds: { windowSamples: 480_000, minimumWindowSamples: 448_000, minimumSpeechSamples } }
+  if (typeof captureId !== 'string' || !captureId || captureId.length > 200 || !uint(minimumSpeechSamples) || minimumSpeechSamples < 32_000 || minimumSpeechSamples > 480_000) throw new Error('mac_window_input')
+  const entries = input.sidecar.chunkEntries
+  if (!Array.isArray(entries) || entries.length > 65536 || !Array.isArray(input.rawChunks) || input.rawChunks.length > 65536) throw new Error('mac_window_bound')
+  const refuse = (indexes: number[], reason: string) => { plan.rejected.push({ chunkIndexes: indexes, reason }) }
+  if (input.correctionHistory !== 'verified-clear' || !uint(input.sidecar.correctionRevision ?? 0) || Number(input.sidecar.correctionRevision ?? 0) > 0) {
+    refuse(entries.map(e => e.chunkIndex), 'human_history_not_clear'); return plan
+  }
+  const raw = new Map<number, VerifiedMacRawChunk>()
+  const duplicates = new Set<number>()
+  for (const r of input.rawChunks) { if (raw.has(r.chunkIndex)) duplicates.add(r.chunkIndex); raw.set(r.chunkIndex, r) }
+  const entryCounts = new Map<number, number>()
+  for (const e of entries) entryCounts.set(e.chunkIndex, (entryCounts.get(e.chunkIndex) ?? 0) + 1)
+  for (const [index, count] of entryCounts) if (count > 1) duplicates.add(index)
+  const seenChunks = new Set<number>(), seenAudio = new Set<string>(), seenPCM = new Set<string>()
+  const corrected = new Set(input.correctedChunkIndexes ?? [])
+  let pending: MacWindowSource[] = [], hint = ''
+  let lastSource: MacWindowSource | undefined
+  const flush = (reason: string) => { if (pending.length) refuse(pending.map(s => s.chunkIndex), reason); pending = []; hint = '' }
+  const finish = () => {
+    const first = pending[0], last = pending.at(-1)!
+    const sampleCount = pending.reduce((n, s) => n + s.sampleCount, 0)
+    const speechSamples = pending.reduce((n, s) => n + s.speechSamples, 0)
+    if (speechSamples < minimumSpeechSamples) { flush('insufficient_speech'); return }
+    const body = { captureId, originalVoiceHint: hint, startSample: first.startSample, endSample: last.endSample, sampleCount, speechSamples, sources: pending }
+    const bindingSHA256 = hash(body)
+    plan.windows.push({ ...structuredClone(body), id: `window_${bindingSHA256}`, bindingSHA256 })
+    pending = []; hint = ''
+  }
+  const close = (reason: string) => {
+    if (pending.reduce((n, s) => n + s.sampleCount, 0) >= plan.thresholds.minimumWindowSamples) finish()
+    else flush(reason)
+  }
+  for (const entry of entries) {
+    const index = entry?.chunkIndex
+    if (seenChunks.has(index) || duplicates.has(index)) { close('duplicate_raw_index'); refuse([index], 'duplicate_raw_index'); continue }
+    seenChunks.add(index)
+    const candidate = sourceOf(entry, raw.get(index))
+    if (corrected.has(index) || candidate.reason) { close('interrupted_window'); refuse([index], corrected.has(index) ? 'human_corrected' : candidate.reason!); continue }
+    const source = candidate.source!
+    if (seenAudio.has(source.audioSHA256) || seenPCM.has(source.pcmSHA256)) { close('duplicate_audio'); refuse([index], 'duplicate_audio'); continue }
+    seenAudio.add(source.audioSHA256); seenPCM.add(source.pcmSHA256)
+    if (lastSource && source.startSample < lastSource.endSample) { close('clock_overlap'); refuse([index], 'clock_overlap'); continue }
+    lastSource = source
+    if (pending.length && (source.startSample !== pending.at(-1)!.endSample || index !== pending.at(-1)!.chunkIndex + 1)) close('clock_or_raw_gap')
+    if (pending.length && candidate.hint !== hint) close('hint_changed')
+    if (pending.reduce((n, s) => n + s.sampleCount, 0) + source.sampleCount > 480_000) close('partial_window')
+    if (pending.length >= 240) close('source_count_bound')
+    hint = candidate.hint!; pending.push(source)
+    if (pending.reduce((n, s) => n + s.sampleCount, 0) === 480_000) finish()
+  }
+  close('partial_window')
+  const families = new Map<string, string[]>()
+  for (const w of plan.windows) { const ids = families.get(w.originalVoiceHint) ?? []; ids.push(w.id); families.set(w.originalVoiceHint, ids) }
+  plan.families = [...families].map(([originalVoiceHint, windowIds]) => ({ originalVoiceHint, windowIds }))
+  return plan
+}
+export interface MacWindowEmbeddingReceipt {
+  windowId: string
+  windowBindingSHA256: string
+  modelSHA256: string
+  /** Verified bytes of the exact prepared concatenation, not a crop. */
+  audioSHA256: string
+  pcmSHA256: string
+  sampleCount: number
+  embedding: readonly number[]
+  /** Sensitivity evidence only, never two additional independent observations. */
+  halfEmbeddings?: readonly [readonly number[], readonly number[]]
+}
+export interface QualifiedMacWindowCandidate {
+  windowId: string
+  startSample: number
+  endSample: number
+  originalVoiceHint: string
+  status: 'qualified' | 'preserve'
+  reason: string
+  /** Opaque cohort identity. Never a global rename of originalVoiceHint. */
+  acousticIdentity?: string
+  profileName?: string
+  evidence: string[]
+  provenance: { algorithm: typeof MAC_SPEAKER_WINDOW_VERSION; modelSHA256: string; profileSHA256?: string; anonymousCosine: .90; anonymousMargin: .06; identityCosine: .88; identityMargin: .05 }
+}
+function preparedWindowValid(w: PreparedMacSpeakerWindow, plan: MacSpeakerWindowPlan): boolean {
+  if (!w || w.captureId !== plan.captureId || !isVoiceLabel(w.originalVoiceHint) || !uint(w.startSample) || !uint(w.endSample)
+    || !uint(w.sampleCount) || w.sampleCount < 448_000 || w.sampleCount > 480_000 || w.endSample - w.startSample !== w.sampleCount || !uint(w.speechSamples)
+    || w.speechSamples < plan.thresholds.minimumSpeechSamples || w.speechSamples > w.sampleCount || !Array.isArray(w.sources) || !w.sources.length || w.sources.length > 240) return false
+  let samples = 0, speech = 0
+  for (let i = 0; i < w.sources.length; i++) {
+    const s = w.sources[i], previous = w.sources[i - 1]
+    if (!s || s.verified !== true || s.sampleRate !== SR || s.channels !== 1 || s.format !== 'pcm_s16le' || !uint(s.chunkIndex)
+      || !uint(s.startSample) || !uint(s.endSample) || !uint(s.sampleCount) || s.sampleCount <= 0 || s.endSample - s.startSample !== s.sampleCount
+      || !uint(s.speechSamples) || s.speechSamples > s.sampleCount || !SHA.test(s.audioSHA256) || !SHA.test(s.pcmSHA256) || !SHA.test(s.textSHA256) || !SHA.test(s.segmentsSHA256)
+      || (previous && (s.chunkIndex !== previous.chunkIndex + 1 || s.startSample !== previous.endSample))) return false
+    samples += s.sampleCount; speech += s.speechSamples
+  }
+  return samples === w.sampleCount && speech === w.speechSamples && w.sources[0].startSample === w.startSample && w.sources.at(-1)!.endSample === w.endSample
+}
+
+/** Cohorts require independent whole windows. Old Voice labels supply no votes.
+ * A qualified candidate is a proposal for this exact span, never permission to
+ * rename every occurrence of its hint. Frozen profiles are only read. */
+export function qualifyMacSpeakerWindows(plan: MacSpeakerWindowPlan, receipts: readonly MacWindowEmbeddingReceipt[], profiles: readonly MacSpeakerProfile[], modelSHA256: string, dimensions = 192): QualifiedMacWindowCandidate[] {
+  if (plan.version !== MAC_SPEAKER_WINDOW_VERSION || plan.thresholds.windowSamples !== 480_000 || plan.thresholds.minimumWindowSamples !== 448_000 || !uint(plan.thresholds.minimumSpeechSamples) || plan.thresholds.minimumSpeechSamples < 32_000 || plan.thresholds.minimumSpeechSamples > 480_000 || !SHA.test(modelSHA256) || !uint(dimensions) || !dimensions || dimensions > 4096 || plan.windows.length > 8192 || receipts.length > 8192) throw new Error('mac_window_qualification_input')
+  let memory = createMacSpeakerMemory(plan.captureId, modelSHA256, { dimensions, maxIdentities: 128, maxOriginals: 8192 })
+  const byId = new Map<string, MacWindowEmbeddingReceipt>(), duplicate = new Set<string>()
+  for (const r of receipts) { if (byId.has(r.windowId)) duplicate.add(r.windowId); byId.set(r.windowId, r) }
+  const candidates: QualifiedMacWindowCandidate[] = []
+  const cohorts = new Map<number, { index: number; observation: MacSpeakerObservation }[]>()
+  const seenSources = new Set<number>(), seenRawPCM = new Set<string>(), seenRawAudio = new Set<string>()
+  for (let i = 0; i < plan.windows.length; i++) {
+    const w = plan.windows[i], r = byId.get(w.id)
+    const provenance: QualifiedMacWindowCandidate['provenance'] = { algorithm: MAC_SPEAKER_WINDOW_VERSION, modelSHA256, anonymousCosine: .90 as const, anonymousMargin: .06 as const, identityCosine: .88 as const, identityMargin: .05 as const }
+    const candidate: QualifiedMacWindowCandidate = { windowId: w.id, startSample: w.startSample, endSample: w.endSample, originalVoiceHint: w.originalVoiceHint, status: 'preserve', reason: 'missing_embedding', evidence: [], provenance }
+    candidates.push(candidate)
+    const { id: _id, bindingSHA256, ...body } = w
+    if (!r) continue
+    if (!preparedWindowValid(w, plan) || duplicate.has(w.id) || r.modelSHA256 !== modelSHA256 || r.windowBindingSHA256 !== bindingSHA256 || hash(body) !== bindingSHA256 || w.id !== `window_${bindingSHA256}`
+      || w.captureId !== plan.captureId || !uint(w.sampleCount) || w.sampleCount < 448_000 || w.sampleCount > 480_000 || w.endSample - w.startSample !== w.sampleCount || r.sampleCount !== w.sampleCount
+      || !SHA.test(r.audioSHA256) || !SHA.test(r.pcmSHA256) || !normalizedSpeakerEmbedding(r.embedding, dimensions)
+      || w.sources.some(s => seenSources.has(s.chunkIndex) || seenRawPCM.has(s.pcmSHA256) || seenRawAudio.has(s.audioSHA256))) { candidate.reason = 'receipt_or_lineage_conflict'; continue }
+    for (const source of w.sources) { seenSources.add(source.chunkIndex); seenRawPCM.add(source.pcmSHA256); seenRawAudio.add(source.audioSHA256) }
+    if (r.halfEmbeddings && (r.halfEmbeddings.length !== 2 || r.halfEmbeddings.some(v => !normalizedSpeakerEmbedding(v, dimensions))
+      || normalizedSpeakerCosine(r.halfEmbeddings[0], r.halfEmbeddings[1])! < .90
+      || r.halfEmbeddings.some(v => normalizedSpeakerCosine(v, r.embedding)! < .90))) { candidate.reason = 'incoherent_halves'; continue }
+    const observation: MacSpeakerObservation = { captureId: plan.captureId, modelSHA256,
+      original: { chunkIndex: i, audioSHA256: r.audioSHA256, pcmSHA256: r.pcmSHA256, startSample: w.startSample, sampleCount: w.sampleCount },
+      startSample: w.startSample, endSample: w.endSample, exclusiveSamples: w.speechSamples, purity: 1, overlapSamples: 0, mixedSpeakers: false, embedding: r.embedding }
+    const next = reconcileMacSpeakerObservation(memory, observation)
+    memory = next.state; candidate.reason = next.decision.reason; candidate.evidence = next.decision.evidence
+    if (next.decision.identityId !== undefined) {
+      const group = cohorts.get(next.decision.identityId) ?? []; group.push({ index: i, observation }); cohorts.set(next.decision.identityId, group)
+    }
+  }
+  for (const [identity, group] of cohorts) {
+    if (memory.identities[identity - 1]?.voice === null || group.length < 2) continue
+    if (group.some(a => group.some(b => normalizedSpeakerCosine(a.observation.embedding, b.observation.embedding)! < .90))) {
+      for (const item of group) candidates[item.index].reason = 'inconsistent_complete_link'
+      continue
+    }
+    const acousticIdentity = `acoustic_${hash(group.map(g => plan.windows[g.index].bindingSHA256).sort())}`
+    const proposal = matchMacSpeakerProfile(memory, group.map(g => g.observation), profiles)
+    const evidence = group.map(g => plan.windows[g.index].bindingSHA256)
+    for (const item of group) {
+      const c = candidates[item.index]
+      c.status = 'qualified'; c.reason = proposal.reason === 'matched_profile' ? 'qualified_profile' : 'qualified_anonymous'
+      c.acousticIdentity = acousticIdentity; c.evidence = evidence
+      if (proposal.reason === 'matched_profile') { c.profileName = proposal.label!; c.provenance.profileSHA256 = proposal.provenance.profileSHA256 }
+    }
+  }
+  return candidates
+}