@gotcos/glasses-server 6.94.1 → 6.94.2

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,
+  } })
+}

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
+}