@gotcos/glasses-server 6.94.1 → 6.95.0

package/server/lib/voice-directory.ts

@@ -13,6 +13,7 @@
 import { lstat, readFile, readdir, realpath } from 'node:fs/promises'
 import { basename, dirname, join } from 'node:path'
 import { setImmediate as yieldToEventLoop } from 'node:timers/promises'
+import { readMacSpeakerMachineEvidence } from './mac-speaker-machine-evidence.js'
 import { dataPath } from './data-dir.js'
 import { confirmedLabels, confirmedChunks } from './meeting-corrections.js'
 import { resolveCosOperationsDir, resolveMeetingLibrary } from './cos-operations-meetings.js'
@@ -294,11 +295,14 @@ export async function buildVoiceDirectorySnapshot(): Promise<VoiceDirectorySnaps
         storedTitle,
       )
 
+      const machineEvidence = readMacSpeakerMachineEvidence(record)
       const review = reviewMeetingSpeakers(chunks as ReviewChunk[], {
         owner,
         phrasesPerVoice: 1,
         confirmed: confirmedLabels(sessionId),
-      confirmedChunks: confirmedChunks(sessionId),
+        confirmedChunks: confirmedChunks(sessionId),
+        machineQualifiedPositions: machineEvidence.positions,
+        machineEvidenceStatus: machineEvidence.status,
         durationMs: typeof record.durationMs === 'number' ? record.durationMs : undefined,
         batchSegments: Array.isArray(record.batchSegments)
           ? record.batchSegments as SpeakerWordSegment[]

package/server/routes/health.ts

@@ -16,6 +16,7 @@ import { localFirstMeetingsCapability } from '../lib/local-first-meetings-contra
 import { isSileroAvailable } from '../lib/vad-silero.js'
 import { profileProvenanceSummary, speakerModelState, speakerReadiness } from '../lib/speaker-embeddings.js'
 import { nemotronLive } from '../lib/nemotron-live.js'
+import { speakerShadowHealthFields } from '../lib/speaker-shadow.js'
 import { finalPassSnapshot } from '../lib/nemotron-final.js'
 import { chunkEmbeddingStoreStats } from '../lib/chunk-embedding-store.js'
 import { mintDisplayTicket, DISPLAY_TICKET_TTL_SECONDS } from '../lib/display-ticket.js'
@@ -579,6 +580,10 @@ healthRouter.get('/health', async (_req, res) => {
     // count only (health is public); the items and their Retry are behind the token at
     // GET /api/maintenance/status.
     crash_loop_parking: crashLoopParkingHealth(),
+    // 6.95.0: speaker merge shadow mode, only while it is on (absent when off). Codes and counts
+    // only (health is public): the proposals and the last error's text are behind the token at
+    // /api/speaker-shadow/*.
+    ...speakerShadowHealthFields(),
     // Key lanes (plan v4 3.1): `details.keyLanes` only while enabled. Absent, never null, when off.
     ...keyLanesHealthFields(),
   })

package/server/routes/meeting.ts

@@ -1,3 +1,5 @@
+import { runQualifiedMacProfilePass } from '../lib/mac-speaker-profile-finalizer.js'
+import { readMacSpeakerMachineEvidence } from '../lib/mac-speaker-machine-evidence.js'
 import { dataPath } from '../lib/data-dir.js'
 import { PHONE_CAPTURE_ID, PHONE_SOURCE_TYPE, assertPhoneProvenance, readPhoneRecording, requirePhoneRecording, closePhoneRecording } from '../lib/phone-recording.js'
 import { MAC_CAPTURE_ID, readMacRecording, requireMacRecording, macChunkReceipt, closeMacRecording } from '../lib/mac-recording.js'
@@ -201,6 +203,7 @@ import { enrichStandaloneMeeting } from '../lib/meeting-summary-persistence.js'
 import { bootResumeGate, type BootResumeGate } from '../lib/boot-resume.js'
 import { recordFinalPassSkip, runNemotronFinalPass, type FinalPassOptions, type FinalPassOutcome } from '../lib/nemotron-final.js'
 import { runTranscriptCleanup, type CleanupOutcome } from '../lib/transcript-cleanup.js'
+import { notifySpeakerShadowFinalized } from '../lib/speaker-shadow.js'
 import { sweepTranscriptCleanupData } from '../lib/transcript-cleanup-screen.js'
 import type { TranscriptCleanupRouteDeps } from './transcript-cleanup.js'
 
@@ -309,6 +312,7 @@ export interface MeetingRouteDependencies {
   emit?: typeof emitDisplay
   finalizationJobs?: MeetingFinalizationJobStore
   finalDiarize?: FinalDiarize
+  qualifiedProfilePass?: typeof runQualifiedMacProfilePass
   /** Control's stop requests for live G2 meetings (lib/meeting-stop-requests.ts). */
   stopRequests?: StopRequestStore
   /** 6.77.0: the post-save transcript cleanup (lib/transcript-cleanup.ts). */
@@ -334,6 +338,7 @@ interface FinalizationRuntime {
   scheduleBackground: (task: Promise<void>) => void
   sessions?: MeetingSessionSource
   finalDiarize?: FinalDiarize
+  qualifiedProfilePass?: typeof runQualifiedMacProfilePass
   transcriptCleanup?: TranscriptCleanupRunner
 }
 
@@ -367,7 +372,7 @@ function validReplayEntries(raw: unknown[]): IndexedTranscriptChunk[] | null {
   return entries.length > 0 ? entries : null
 }
 
-function scheduleFinalizationJob(job: MeetingFinalizationJob, runtime: FinalizationRuntime): void {
+export function scheduleFinalizationJob(job: MeetingFinalizationJob, runtime: FinalizationRuntime): void {
   const key = `${runtime.finalizationJobs.root}:${job.sessionId}`
   if (activeFinalizationJobs.has(key)) return
   activeFinalizationJobs.add(key)
@@ -452,8 +457,12 @@ function scheduleFinalizationJob(job: MeetingFinalizationJob, runtime: Finalizat
           sessionId: current.sessionId,
           runBatch: runtime.runBatch,
           finalDiarize: runtime.finalDiarize ?? runNemotronFinalPass,
+          qualifiedProfilePass: runtime.qualifiedProfilePass,
         })
       } else {
+        // A torn profile transaction must block filing even if pending audio
+        // vanished. Missing audio never waives journal/proof recovery gates.
+        if (MAC_CAPTURE_ID.test(current.sessionId)) await (runtime.qualifiedProfilePass ?? runQualifiedMacProfilePass)({ meetingPath: current.meetingPath, sidecarPath: current.sidecarPath, audioDir: current.audioDir ?? '', resumeOnly: true })
         console.warn(`[meeting/save] Pending HQ audio missing for ${current.sessionId}; preserving streaming canonical`)
       }
       current = runtime.finalizationJobs.save({
@@ -483,6 +492,9 @@ function scheduleFinalizationJob(job: MeetingFinalizationJob, runtime: Finalizat
       await enrichStandaloneMeeting(current.meetingPath, jobStartedAt)
     }
     markCanonicalFinalizationState(current.sidecarPath, 'complete', false)
+    // 6.95.0: speaker merge shadow mode (off unless COS_SPEAKER_SHADOW=1). Log only and
+    // fire-and-forget: it queues, defers under live work, and never throws back here.
+    if (MAC_CAPTURE_ID.test(current.sessionId)) notifySpeakerShadowFinalized({ sessionId: current.sessionId, sidecarPath: current.sidecarPath })
     // The capture is finished and its files are durable, so the merge engine may score it.
     // Fire-and-forget by contract: the runner queues, defers under a drain or a live
     // capture, and never throws back at the finalization path.
@@ -720,6 +732,7 @@ export function createMeetingRouter(deps: MeetingRouteDependencies = {}): Router
   const emit = deps.emit ?? emitDisplay
   const finalizationJobs = deps.finalizationJobs ?? new MeetingFinalizationJobStore()
   const finalDiarize = deps.finalDiarize ?? runNemotronFinalPass
+  const qualifiedProfilePass = deps.qualifiedProfilePass ?? runQualifiedMacProfilePass
   const transcriptCleanup = deps.transcriptCleanup
   const router = Router()
   const captureActive = deps.captureActive ?? (() => getTranscriptionSessionLiveness().live > 0)
@@ -1206,6 +1219,7 @@ export function createMeetingRouter(deps: MeetingRouteDependencies = {}): Router
           scheduleBackground,
           sessions,
           finalDiarize,
+          qualifiedProfilePass,
         })
         if (origin === 'phone') notePhoneAfterAutonomousSave(sessionId, 'save_replay')
         respond(200, publicSaveResponse(alreadySaved, true), true)
@@ -1403,6 +1417,7 @@ export function createMeetingRouter(deps: MeetingRouteDependencies = {}): Router
           scheduleBackground,
           sessions,
           finalDiarize,
+          qualifiedProfilePass,
           transcriptCleanup,
         })
       }
@@ -1659,9 +1674,10 @@ export function createMeetingRouter(deps: MeetingRouteDependencies = {}): Router
     const filename = operations?.filename ?? direct?.filename ?? saved!.filename
 
     let chunks: unknown
+    let sidecar: Record<string, unknown>
     try {
-      const raw = JSON.parse(readFileSync(sidecarPath, 'utf-8')) as Record<string, unknown>
-      chunks = Array.isArray(raw) ? raw : raw.chunks
+      sidecar = JSON.parse(readFileSync(sidecarPath, 'utf-8')) as Record<string, unknown>
+      chunks = Array.isArray(sidecar) ? sidecar : sidecar.chunks
     } catch {
       // Defensive: both lookups above already read this sidecar to match the
       // session, so a corrupt file 404s and never reaches here. This covers the
@@ -1678,8 +1694,8 @@ export function createMeetingRouter(deps: MeetingRouteDependencies = {}): Router
 
     // Raw capture indices, so a phrase can address its own audio. Position in
     // `chunks` is NOT the WAV number — see attachRawChunkIndices.
-    const sidecar = (JSON.parse(readFileSync(sidecarPath, 'utf-8')) ?? {}) as Record<string, unknown>
     const withIndices = attachRawChunkIndices(chunks as ReviewChunk[], sidecar.chunkEntries)
+    const machineEvidence = readMacSpeakerMachineEvidence(sidecar)
     const review = reviewMeetingSpeakers(withIndices, {
       owner: getOwnerSpeakerLabel(),
       // Labels a human already vouched for in this meeting. Without this the
@@ -1687,6 +1703,8 @@ export function createMeetingRouter(deps: MeetingRouteDependencies = {}): Router
       // confirms the same voice forever.
       confirmed: confirmedLabels(sessionId),
       confirmedChunks: confirmedChunks(sessionId),
+      machineQualifiedPositions: machineEvidence.positions,
+      machineEvidenceStatus: machineEvidence.status,
       phrasesPerVoice: Math.max(1, Math.min(6, Number(req.query.phrases) || 3)),
       // The sidecar's own durationMs is the meeting's true end. Deriving it from
       // max(elapsed) uses the START of the last chunk, which made the final
@@ -1791,10 +1809,13 @@ export function createMeetingRouter(deps: MeetingRouteDependencies = {}): Router
     }
     const chunks = rawChunks as ReviewChunk[]
 
+    const machineEvidence = readMacSpeakerMachineEvidence(sidecar)
     const review = reviewMeetingSpeakers(attachRawChunkIndices(chunks, sidecar.chunkEntries), {
       owner: getOwnerSpeakerLabel(),
       confirmed: confirmedLabels(sessionId),
       confirmedChunks: confirmedChunks(sessionId),
+      machineQualifiedPositions: machineEvidence.positions,
+      machineEvidenceStatus: machineEvidence.status,
       // This route renders no phrases; the default of 3 per voice computed and
       // discarded 48 transcript excerpts on a 16-voice meeting.
       phrasesPerVoice: 1,
@@ -1818,6 +1839,8 @@ export function createMeetingRouter(deps: MeetingRouteDependencies = {}): Router
       // "voice matching" for the wearer exemption and for names a human typed.
       isOwner: v.isOwner,
       confirmedByHuman: v.confirmedByHuman,
+      machineQualified: v.machineQualified,
+      machineQualifiedSegments: v.machineQualifiedSegments,
     }))
 
     // A missing .md is not fatal — the review and the sidecar still describe the
@@ -3152,7 +3175,7 @@ function synthesizeEntriesFromChunkWavs(audioDir: string): RecoveredCapture {
   return { entries, startTime, durationMs }
 }
 
-async function finalizeBatch(options: {
+export async function finalizeBatch(options: {
   audioDir: string
   entries: IndexedTranscriptChunk[]
   streamingWordCount: number
@@ -3161,7 +3184,11 @@ async function finalizeBatch(options: {
   sessionId?: string
   runBatch: NonNullable<MeetingRouteDependencies['runBatch']>
   finalDiarize?: FinalDiarize
+  qualifiedProfilePass?: typeof runQualifiedMacProfilePass
 }): Promise<void> {
+  const qualifiedProfilePass = options.qualifiedProfilePass ?? runQualifiedMacProfilePass
+  const mac = MAC_CAPTURE_ID.test(options.sessionId ?? '')
+  if (mac && (await qualifiedProfilePass({ ...options, resumeOnly: true })).status === 'applied') return
   const result = await options.runBatch(
     options.audioDir,
     options.entries,
@@ -3226,6 +3253,10 @@ async function finalizeBatch(options: {
     }
   }
 
+  // Exact qualified profile evidence runs before raw deletion and filing.
+  // Prepared-transaction failures propagate: mixed generations cannot be filed.
+  if (mac && metadataPersisted) await qualifiedProfilePass(options)
+
   if (canDeletePendingBatchAudio(transcriptApplied, metadataPersisted)) {
     rmSync(options.audioDir, { recursive: true, force: true })
   } else {

package/server/routes/speaker-shadow.ts

@@ -0,0 +1,79 @@
+// Speaker merge shadow mode (6.95.0). Token-protected by the /api middleware. READ ONLY.
+//
+//   GET /api/speaker-shadow/proposals   the logged proposal records, newest first
+//        ?limit=1..100 (default 10)  ?sessionId=mac_<uuid>
+//   GET /api/speaker-shadow/status      the switch, queue, daily cap, breaker, last error and
+//                                       setup readiness (models, CLI, sandbox)
+//   GET  /api/speaker-shadow/settings   { enabled, source }  source: env | setting | default
+//   POST /api/speaker-shadow/settings   {"enabled": true|false}: this Mac's saved switch (no
+//                                       restart); 409 env_forced when COS_SPEAKER_SHADOW pins it
+//
+// The settings POST is the only write, and it writes only <data>/speaker-shadow/settings.json.
+// Nothing on these routes changes a meeting, a label, a name or a profile. A 404 means a
+// server older than 6.95.0.
+
+import { Router } from 'express'
+import { getSpeakerShadowRunner, readSpeakerShadowRecords, resolveSpeakerShadowSwitch, speakerShadowEnvSwitch, writeSpeakerShadowSetting } from '../lib/speaker-shadow.js'
+import { speakerShadowRoot } from '../lib/speaker-shadow-models.js'
+
+export interface SpeakerShadowRouterDeps {
+  root?: () => string
+  env?: NodeJS.ProcessEnv
+  snapshot?: () => ReturnType<ReturnType<typeof getSpeakerShadowRunner>['snapshot']>
+  /** Called after the setting turns shadow mode on (the runner picks up anything still queued). */
+  onEnabled?: () => void
+}
+
+const SESSION_ID = /^mac_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/
+
+export function createSpeakerShadowRouter(deps: SpeakerShadowRouterDeps = {}): Router {
+  const router = Router()
+  const root = deps.root ?? speakerShadowRoot
+  const snapshot = deps.snapshot ?? (() => getSpeakerShadowRunner().snapshot({ detail: true }))
+  const env = deps.env ?? process.env
+  const onEnabled = deps.onEnabled ?? (() => getSpeakerShadowRunner().resume())
+
+  router.get('/speaker-shadow/proposals', async (req, res) => {
+    const rawLimit = Number(req.query.limit ?? 10)
+    if (!Number.isInteger(rawLimit) || rawLimit < 1 || rawLimit > 100) { res.status(400).json({ error: 'limit must be an integer from 1 to 100' }); return }
+    const sessionId = typeof req.query.sessionId === 'string' ? req.query.sessionId : undefined
+    if (sessionId !== undefined && !SESSION_ID.test(sessionId)) { res.status(400).json({ error: 'sessionId must be a mac_<uuid> session id' }); return }
+    try {
+      const records = await readSpeakerShadowRecords(root(), { limit: rawLimit, sessionId })
+      res.json({ logOnly: true, shadow: snapshot(), count: records.length, records })
+    } catch (error) {
+      res.status(500).json({ error: `could not read the shadow log: ${error instanceof Error ? error.message : String(error)}` })
+    }
+  })
+
+  router.get('/speaker-shadow/status', (_req, res) => {
+    res.json({ logOnly: true, ...snapshot() })
+  })
+
+  router.get('/speaker-shadow/settings', (_req, res) => {
+    res.set('Cache-Control', 'private, no-store')
+    res.json(resolveSpeakerShadowSwitch(env, root()))
+  })
+
+  router.post('/speaker-shadow/settings', (req, res) => {
+    res.set('Cache-Control', 'private, no-store')
+    const body = req.body as { enabled?: unknown } | undefined
+    if (!body || typeof body !== 'object' || Array.isArray(body) || typeof body.enabled !== 'boolean' || Object.keys(body).some(k => k !== 'enabled')) {
+      res.status(400).json({ error: 'invalid_request', expected: '{"enabled": true|false}' })
+      return
+    }
+    const pinned = speakerShadowEnvSwitch(env)
+    if (pinned !== null && pinned !== body.enabled) { res.status(409).json({ error: 'env_forced', ...resolveSpeakerShadowSwitch(env, root()) }); return }
+    try {
+      writeSpeakerShadowSetting(body.enabled, root())
+    } catch {
+      res.status(500).json({ error: 'settings_write_failed' })
+      return
+    }
+    const view = resolveSpeakerShadowSwitch(env, root())
+    if (view.enabled) { try { onEnabled() } catch { /* the next finished meeting starts it */ } }
+    res.json(view)
+  })
+
+  return router
+}

package/server/scripts/mac-speaker-repair.ts

@@ -0,0 +1,324 @@
+#!/usr/bin/env tsx
+import { boundWords, renderMarkdown, renderBoundSpeakerLabels } from '../lib/mac-speaker-repair-render.js'
+export { renderBoundSpeakerLabels, renderSparseBoundSpeakerLabels, renderTruncatedBoundSpeakerLabels } from '../lib/mac-speaker-repair-render.js'
+/** Offline-only, labels-only repair transaction. No server/data-home discovery.
+ * Default preview writes nothing. --prepare saves private durable before/after
+ * images; --apply/--undo can modify only explicit marker-certified offline copies.
+ * Live installation requires the deploying session's own sync/capture coordination.
+ */
+import { createHash } from 'node:crypto'
+import { closeSync, constants, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, realpathSync, unlinkSync, writeFileSync } from 'node:fs'
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { durableAtomicWriteFileSync } from '../lib/atomic-fs.js'
+import { hashMacSpeakerMachineBinding, projectMacSpeakerRepair, type MacSpeakerMachineEvidence, type MacSpeakerRepairPlan, type MacSpeakerRepairReceipt } from '../lib/mac-speaker-repair-projection.js'
+
+type Doc = Record<string, any>
+export interface RepairFileSnapshot { path: string; sha256: string | null }
+export interface MacRepairManifest {
+  version: 1
+  id: string
+  at: string
+  evidenceHash: string
+  offlineRoot: string
+  /** Read-only immutable evidence, including frozen profile/model versions. */
+  preconditions: RepairFileSnapshot[]
+  audioFiles: Array<{ rawChunkIndex: number; path: string; sha256: string }>
+  copies: Array<{
+    copy: 'local' | 'operations'
+    sidecar: RepairFileSnapshot
+    markdown: RepairFileSnapshot
+    ledger: RepairFileSnapshot
+    plan: MacSpeakerRepairPlan
+  }>
+}
+interface PreparedFile {
+  path: string
+  beforeHash: string
+  afterHash: string
+  beforeImage: string
+  afterImage: string
+  role: 'sidecar' | 'markdown'
+  copy: 'local' | 'operations'
+}
+interface TransactionPayload {
+  version: 1
+  id: string
+  at: string
+  evidenceHash: string
+  offlineRoot: string
+  preconditions: RepairFileSnapshot[]
+  files: PreparedFile[]
+  receipts: MacSpeakerRepairReceipt[]
+}
+export interface MacRepairTransaction extends TransactionPayload {
+  payloadHash: string
+  state: 'prepared' | 'applying' | 'applied' | 'undoing' | 'reverted' | 'partial'
+  completed: string[]
+  error?: string
+}
+export interface MacRepairPreview {
+  transaction: MacRepairTransaction
+  images: Array<{ name: string; bytes: string }>
+  summary: { copies: number; chunks: number; labelPatches: number; offlineOnly: true }
+}
+const sha = (data: string | Buffer) => createHash('sha256').update(data).digest('hex')
+const digest = (value: unknown) => sha(JSON.stringify(value))
+const HASH = /^[a-f0-9]{64}$/
+const MARKER = '.mac-speaker-repair-offline.json'
+function refuse(message: string): never { throw new Error(`Mac offline repair: ${message}`) }
+function absolute(path: string) { if (typeof path !== 'string' || !isAbsolute(path)) refuse('all paths must be explicit and absolute'); return resolve(path) }
+function safeRead(path: string): Buffer {
+  absolute(path)
+  const stat = lstatSync(path)
+  if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1 || realpathSync(path) !== resolve(path)) refuse('symlink, hardlink or nonregular source refused')
+  return readFileSync(path)
+}
+function snapshot(path: string): string | null { return existsSync(path) ? sha(safeRead(path)) : null }
+function checkSnapshot(file: RepairFileSnapshot) {
+  absolute(file.path)
+  if (file.sha256 !== null && !HASH.test(file.sha256)) refuse('invalid source hash')
+  if (snapshot(file.path) !== file.sha256) refuse('source/profile/ledger drift')
+}
+function inside(root: string, path: string) {
+  const rel = relative(root, absolute(path))
+  if (!rel || rel.startsWith('..') || isAbsolute(rel)) refuse('write target must be strictly inside offline root')
+}
+function offlineRoot(path: string): string {
+  const root = absolute(path)
+  if (realpathSync(root) !== root || lstatSync(root).isSymbolicLink()) refuse('offline root must not contain symlinks')
+  // An explicit marker is an offline-copy assertion, never a server maintenance
+  // authorization. Also reject recognizable production data locations.
+  if (root.split('/').includes('.cos-glasses') || /\/MU-Chief-Staff\/operations(?:\/|$)/.test(root)) refuse('production data path is not an offline root')
+  const marker = JSON.parse(safeRead(join(root, MARKER)).toString('utf8'))
+  if (marker.kind !== 'cos-mac-speaker-repair-offline' || marker.version !== 1) refuse('offline-copy marker required')
+  return root
+}
+/** Only WAV metadata + hash verification; never playback/ASR/native extraction. */
+function pcmSamples(bytes: Buffer): { count: number; pcm: Buffer } {
+  if (bytes.length < 44 || bytes.toString('ascii', 0, 4) !== 'RIFF' || bytes.toString('ascii', 8, 12) !== 'WAVE' || bytes.readUInt32LE(4) + 8 !== bytes.length) refuse('invalid WAV container')
+  let format = false, samples: number | null = null, pcm: Buffer | null = null
+  for (let offset = 12; offset + 8 <= bytes.length;) {
+    const tag = bytes.toString('ascii', offset, offset + 4), size = bytes.readUInt32LE(offset + 4), start = offset + 8
+    if (start + size > bytes.length) refuse('truncated WAV')
+    if (tag === 'fmt ') {
+      if (size < 16 || bytes.readUInt16LE(start) !== 1 || bytes.readUInt16LE(start + 2) !== 1 || bytes.readUInt32LE(start + 4) !== 16000 || bytes.readUInt16LE(start + 12) !== 2 || bytes.readUInt16LE(start + 14) !== 16) refuse('expected mono 16kHz PCM16 WAV')
+      format = true
+    }
+    if (tag === 'data') { if (samples !== null || size % 2) refuse('ambiguous PCM data'); samples = size / 2; pcm = bytes.subarray(start, start + size) }
+    offset = start + size + (size % 2)
+  }
+  if (!format || !samples) refuse('missing WAV PCM')
+  return { count: samples, pcm: pcm! }
+}
+
+function protectedRaw(doc: Doc, ledger: RepairFileSnapshot): number[] {
+  checkSnapshot(ledger)
+  if (ledger.sha256 === null) return []
+  const rows = safeRead(ledger.path).toString('utf8').split('\n').filter(line => line.trim()).map(line => JSON.parse(line))
+  const byId = new Map<string, Doc[]>()
+  for (const row of rows) {
+    if (!row.id || !['intent', 'applied', 'failed', 'confirmed', 'confirmed-chunks', 'reverted'].includes(row.phase)) refuse('unreadable correction ledger')
+    byId.set(row.id, [...(byId.get(row.id) ?? []), row])
+  }
+  const raw = doc.chunkEntries.filter((e: Doc) => e.chunk?.text).map((e: Doc) => e.chunkIndex)
+  const protectedIndexes = new Set<number>()
+  for (const history of byId.values()) {
+    const last = history.at(-1)!
+    if (last.phase === 'intent') refuse('incomplete prior correction intent')
+    if (last.phase === 'reverted' || last.phase === 'failed') continue
+    for (const row of history.filter(r => r.phase !== 'intent')) {
+      if (!Array.isArray(row.chunks) || row.chunks.some((position: number) => !Number.isInteger(position) || raw[position] === undefined)) refuse('ambiguous correction ledger positions')
+      if (!row.chunks.length) for (const index of raw) protectedIndexes.add(index)
+      else for (const position of row.chunks) protectedIndexes.add(raw[position])
+    }
+  }
+  return [...protectedIndexes]
+}
+function revision(value: any): number { if (value === undefined) return 0; if (!Number.isSafeInteger(value) || value < 0) refuse('invalid lifecycle/correction revision'); return value }
+export function previewMacSpeakerRepair(manifest: MacRepairManifest): MacRepairPreview {
+  if (manifest.version !== 1 || !/^[A-Za-z0-9_-]{3,100}$/.test(manifest.id) || !HASH.test(manifest.evidenceHash) || !Number.isFinite(Date.parse(manifest.at))) refuse('invalid manifest identity')
+  const root = offlineRoot(manifest.offlineRoot)
+  if (!Array.isArray(manifest.copies) || manifest.copies.length !== 2 || new Set(manifest.copies.map(copy => copy.copy)).size !== 2) refuse('explicit local and operations copies required')
+  if (!Array.isArray(manifest.preconditions) || !manifest.preconditions.length || !Array.isArray(manifest.audioFiles) || !manifest.audioFiles.length) refuse('frozen evidence and raw audio required')
+  if (!manifest.preconditions.some(file=>file.sha256===manifest.evidenceHash)) refuse('qualified evidence bytes must be a frozen precondition')
+  manifest.preconditions.forEach(checkSnapshot)
+  const pcm = new Map<number, Buffer>()
+  const samples: Record<string, number> = {}, audioPreconditions: RepairFileSnapshot[] = []
+  for (const audio of manifest.audioFiles) {
+    if (!Number.isInteger(audio.rawChunkIndex) || audio.rawChunkIndex < 0 || samples[String(audio.rawChunkIndex)] !== undefined || !HASH.test(audio.sha256)) refuse('invalid audio evidence binding')
+    const bytes = safeRead(audio.path)
+    if (sha(bytes) !== audio.sha256) refuse('raw audio drift')
+    const metadata = pcmSamples(bytes)
+    samples[String(audio.rawChunkIndex)] = metadata.count
+    pcm.set(audio.rawChunkIndex, metadata.pcm)
+    audioPreconditions.push({ path: audio.path, sha256: audio.sha256 })
+  }
+  const files: PreparedFile[] = [], images: MacRepairPreview['images'] = [], receipts: MacSpeakerRepairReceipt[] = []
+  const seen = new Set<string>(); let session: string | undefined, agreement: string | undefined
+  for (const [ci, copy] of manifest.copies.entries()) {
+    for (const file of [copy.sidecar, copy.markdown]) {
+      inside(root, file.path); if (seen.has(resolve(file.path))) refuse('duplicate target file'); seen.add(resolve(file.path)); checkSnapshot(file)
+    }
+    if (copy.sidecar.sha256 === null || copy.markdown.sha256 === null) refuse('source copies must exist')
+    const beforeSidecar = safeRead(copy.sidecar.path).toString('utf8'), beforeMarkdown = safeRead(copy.markdown.path).toString('utf8'), before = JSON.parse(beforeSidecar)
+    if (session && session !== before.sessionId) refuse('copy capture IDs disagree'); session = before.sessionId
+    const copyAgreement = digest({ assignments: copy.plan.assignments, samples: copy.plan.rawAudioSampleCounts, chunks: before.chunks.map((chunk: Doc) => [chunk.text, chunk.speaker, chunk.elapsed]), raw: before.chunkEntries.map((entry: Doc) => entry.chunkIndex) })
+    if (agreement && agreement !== copyAgreement) refuse('local and operations projection mappings disagree'); agreement = copyAgreement
+    if (copy.plan.id !== manifest.id || copy.plan.evidenceHash !== manifest.evidenceHash) refuse('copy plan identity disagrees')
+    for (const [raw, count] of Object.entries(copy.plan.rawAudioSampleCounts)) {
+      if (samples[raw] !== count) refuse('raw sample count not supported by WAV evidence')
+      const sourceChunk = before.chunkEntries.find((entry: Doc) => entry.chunkIndex === Number(raw))?.chunk
+      const verified = manifest.audioFiles.find(file => file.rawChunkIndex === Number(raw))
+      if (sourceChunk?.audioSha256 && sourceChunk.audioSha256 !== verified?.sha256) refuse('sidecar raw audio hash disagrees with verified WAV')
+    }
+    for (const assignment of copy.plan.assignments) {
+      const proof = assignment.targetEvidence
+      if (!proof) continue
+      const profileFile = manifest.preconditions.find(file => file.sha256 === proof.profileSha256)
+      if (!profileFile || !manifest.preconditions.some(file => file.sha256 === proof.modelSha256)) refuse('profile/model proof files are not frozen preconditions')
+      const profile = JSON.parse(safeRead(profileFile.path).toString('utf8'))
+      if (!Array.isArray(profile.profiles) || profile.profiles.filter((row: Doc) => row.name === proof.profileName).length !== 1) refuse('profile evidence name is missing or ambiguous')
+      for (const window of proof.windows) {
+        if (window.rawChunks.some(raw => !pcm.has(raw.rawChunkIndex)) || sha(Buffer.concat(window.rawChunks.map(raw => pcm.get(raw.rawChunkIndex)!))) !== window.pcmSha256) refuse('concatenated profile PCM proof disagrees')
+        for (const raw of window.rawChunks) {
+        if (!manifest.audioFiles.some(file => file.rawChunkIndex === raw.rawChunkIndex && file.sha256 === raw.audioSha256) || samples[String(raw.rawChunkIndex)] !== raw.sampleCount) refuse('profile evidence raw audio is not verified')
+        }
+      }
+    }
+    const plan = { ...copy.plan, protectedRawChunkIndices: [...new Set([...copy.plan.protectedRawChunkIndices, ...protectedRaw(before, copy.ledger)])] }
+    const projected = projectMacSpeakerRepair(before, plan), after = projected.doc, sequence = boundWords(before, after)
+    after.batchTranscript = renderBoundSpeakerLabels(before.batchTranscript, sequence)
+    const afterMarkdown = renderMarkdown(beforeMarkdown, sequence)
+    after.correctionRevision = revision(before.correctionRevision) + 1
+    after.lifecycleRevision = revision(before.lifecycleRevision) + 1
+    after.lifecycleUpdatedAt = manifest.at
+    after.labelsNewerThanGraph = true
+    after.proseStale = true
+    const rawChunkMap = Object.fromEntries(plan.assignments.map(assignment => [assignment.rawChunkIndex, assignment.to]))
+    after.speakerRepair = { version: 1, id: manifest.id, evidenceHash: manifest.evidenceHash, at: manifest.at, requiresSyncRefresh: true, rawChunkMap }
+    after.diarization = { engine: 'mac-speaker-repair-v1', status: 'applied', mode: 'labels-only', labels: plan.assignments.every(assignment => /^Voice (?:[1-9]|[1-9]\d)$/.test(assignment.to)) ? 'unnamed' : 'profile-matched', appliedAt: manifest.at, outputSha256: sha(after.batchTranscript), rawChunkMap }
+    const machineEvidence: MacSpeakerMachineEvidence = {
+      version: 1, correctionRevision: after.correctionRevision,
+      documentBinding: hashMacSpeakerMachineBinding(after),
+      receipt: projected.receipt, rawAudioSampleCounts: structuredClone(plan.rawAudioSampleCounts),
+    }
+    after.speakerRepair.machineEvidence = machineEvidence
+    // The receipt records aggregate model/profile confidence. It neither changes
+    // capture similarities nor fabricates ledger confirmations or enrollment.
+    // Original diarization/output maps remain byte-exact in the before-image.
+    const afterSidecar = JSON.stringify(after, null, 2) + '\n'
+    receipts.push(projected.receipt)
+    for (const [role, path, beforeBytes, afterBytes] of [['sidecar', copy.sidecar.path, beforeSidecar, afterSidecar], ['markdown', copy.markdown.path, beforeMarkdown, afterMarkdown]] as const) {
+      const stem = `${ci}-${role}`, beforeImage = `${stem}.before`, afterImage = `${stem}.after`
+      images.push({ name: beforeImage, bytes: beforeBytes }, { name: afterImage, bytes: afterBytes })
+      files.push({ path, beforeHash: sha(beforeBytes), afterHash: sha(afterBytes), beforeImage, afterImage, role, copy: copy.copy })
+    }
+  }
+  const payload: TransactionPayload = { version: 1, id: manifest.id, at: manifest.at, evidenceHash: manifest.evidenceHash, offlineRoot: root, preconditions: [...manifest.preconditions, ...audioPreconditions, ...manifest.copies.map(copy => copy.ledger)], files, receipts }
+  return { transaction: { ...payload, payloadHash: digest(payload), state: 'prepared', completed: [] }, images, summary: { copies: 2, chunks: receipts[0].rawChunkIndices.length, labelPatches: receipts.reduce((n, receipt) => n + receipt.patches.length, 0), offlineOnly: true } }
+}
+function writePrivate(path: string, bytes: string) { durableAtomicWriteFileSync(path, bytes, { mode: 0o600 }) }
+function saveTransaction(path: string, tx: MacRepairTransaction) { writePrivate(path, JSON.stringify(tx, null, 2) + '\n') }
+function lockRoot(root: string, resume = false): () => void {
+  const path = join(root, '.mac-speaker-repair.lock')
+  if (resume && existsSync(path)) {
+    const prior = JSON.parse(safeRead(path).toString('utf8'))
+    if (!Number.isSafeInteger(prior.pid) || prior.pid <= 0) refuse('invalid lock owner; manual review required')
+    try { process.kill(prior.pid, 0); refuse('offline repair lock owner is still alive') }
+    catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ESRCH') throw error }
+    unlinkSync(path)
+  }
+  const fd = openSync(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600)
+  try { writeFileSync(fd, JSON.stringify({ pid: process.pid })); fsyncSync(fd) } finally { closeSync(fd) }
+  return () => { unlinkSync(path) }
+}
+export function prepareMacSpeakerRepair(manifest: MacRepairManifest, transactionDir: string): MacRepairPreview {
+  const root = offlineRoot(manifest.offlineRoot); inside(root, transactionDir)
+  if (existsSync(transactionDir)) refuse('transaction directory already exists')
+  const parent = dirname(absolute(transactionDir)); if (realpathSync(parent) !== parent) refuse('transaction parent symlink refused')
+  const release = lockRoot(root)
+  try {
+    const preview = previewMacSpeakerRepair(manifest)
+    mkdirSync(transactionDir, { mode: 0o700 })
+    const parentFd = openSync(root, constants.O_RDONLY); try { fsyncSync(parentFd) } finally { closeSync(parentFd) }
+    for (const image of preview.images) writePrivate(join(transactionDir, image.name), image.bytes)
+    saveTransaction(join(transactionDir, 'transaction.json'), preview.transaction)
+    return preview
+  } finally { release() }
+}
+function payloadOf(tx: MacRepairTransaction): TransactionPayload {
+  const { payloadHash: _, state: __, completed: ___, error: ____, ...payload } = tx
+  return payload
+}
+export function executeMacSpeakerRepair(transactionDir: string, direction: 'apply' | 'undo', options: { resume?: boolean; beforeWrite?: (index: number) => void } = {}): MacRepairTransaction {
+  const transactionPath = join(absolute(transactionDir), 'transaction.json')
+  const tx = JSON.parse(safeRead(transactionPath).toString('utf8')) as MacRepairTransaction
+  if (tx.version !== 1 || digest(payloadOf(tx)) !== tx.payloadHash) refuse('transaction integrity mismatch')
+  const root = offlineRoot(tx.offlineRoot); inside(root, transactionDir)
+  if (realpathSync(transactionDir) !== resolve(transactionDir)) refuse('transaction directory symlink refused')
+  const release = lockRoot(root, options.resume)
+  try {
+    tx.preconditions.forEach(checkSnapshot)
+    const forward = direction === 'apply', wanted = forward ? 'applied' : 'reverted'
+    if ((tx.state === 'partial' || tx.state === 'applying' || tx.state === 'undoing') && !options.resume && forward) refuse('incomplete prior intent; explicit --resume or --undo required')
+    const writes: Array<{ file: PreparedFile; bytes: string; changed: boolean }> = []
+    for (const file of tx.files) {
+      inside(root, file.path)
+      for (const image of [file.beforeImage, file.afterImage]) if (image !== image.split('/').at(-1) || image.includes('..')) refuse('unsafe image path')
+      const before = safeRead(join(transactionDir, file.beforeImage)), after = safeRead(join(transactionDir, file.afterImage))
+      if (sha(before) !== file.beforeHash || sha(after) !== file.afterHash) refuse('before/after-image drift')
+      const current = snapshot(file.path), desired = forward ? file.afterHash : file.beforeHash, prior = forward ? file.beforeHash : file.afterHash
+      if (current !== desired && current !== prior) refuse('copy drift; restore would overwrite a later edit')
+      if (!options.resume && tx.state === 'prepared' && forward && current !== prior) refuse('copy changed before first apply')
+      const currentDoc = file.role === 'sidecar' ? JSON.parse(safeRead(file.path).toString('utf8')) : null
+      if (currentDoc && (currentDoc.finalizationState !== 'complete' || currentDoc.claimPending === true || currentDoc.active === true || currentDoc.isActive === true)) refuse('capture is active or no longer finalized')
+      writes.push({ file, bytes: (forward ? after : before).toString('utf8'), changed: current !== desired })
+    }
+    if (tx.state === wanted && writes.every(write => !write.changed)) return tx
+    tx.state = forward ? 'applying' : 'undoing'; tx.completed = []; delete tx.error
+    saveTransaction(transactionPath, tx) // durable intent before any copy mutation
+    try {
+      for (const [index, write] of writes.entries()) {
+        options.beforeWrite?.(index)
+        tx.preconditions.forEach(checkSnapshot)
+        // Recheck all remaining copies immediately before each publish. The
+        // offline lock excludes this tool; hash CAS also detects external edits.
+        for (const completed of writes.slice(0, index)) if (snapshot(completed.file.path) !== (forward ? completed.file.afterHash : completed.file.beforeHash)) refuse('completed copy drift after publish')
+        for (const pending of writes.slice(index)) {
+          const actual = snapshot(pending.file.path)
+          const expected = pending.changed ? (forward ? pending.file.beforeHash : pending.file.afterHash) : (forward ? pending.file.afterHash : pending.file.beforeHash)
+          if (actual !== expected) refuse('copy changed immediately before write')
+        }
+        if (write.changed) writePrivate(write.file.path, write.bytes)
+        if (snapshot(write.file.path) !== (forward ? write.file.afterHash : write.file.beforeHash)) refuse('post-write verification failed')
+        tx.completed.push(write.file.path); saveTransaction(transactionPath, tx)
+      }
+      for (const write of writes) if (snapshot(write.file.path) !== (forward ? write.file.afterHash : write.file.beforeHash)) refuse('final copy postimage drift')
+      tx.state = wanted; saveTransaction(transactionPath, tx)
+    } catch (error) {
+      tx.state = 'partial'; tx.error = error instanceof Error ? error.message : String(error); saveTransaction(transactionPath, tx); throw error
+    }
+    return tx
+  } finally { release() }
+}
+export function macSpeakerRepairMain(args = process.argv.slice(2)): void {
+  const known = new Set(['--manifest', '--transaction', '--prepare', '--apply', '--undo', '--resume'])
+  for (let i = 0; i < args.length; i++) { if (!known.has(args[i])) refuse('unknown command option'); if (args[i] === '--manifest' || args[i] === '--transaction') { if (!args[++i]) refuse('missing option value') } }
+  const value = (flag: string) => { const index = args.indexOf(flag); return index < 0 ? undefined : args[index + 1] }
+  const transactionDir = value('--transaction'), apply = args.includes('--apply'), undo = args.includes('--undo'), prepare = args.includes('--prepare')
+  if (Number(apply) + Number(undo) + Number(prepare) > 1) refuse('choose one of --prepare, --apply or --undo')
+  if (apply || undo) {
+    if (!transactionDir) refuse('--transaction required')
+    const tx = executeMacSpeakerRepair(transactionDir, undo ? 'undo' : 'apply', { resume: args.includes('--resume') })
+    console.log(JSON.stringify({ id: tx.id, state: tx.state, offlineOnly: true })); return
+  }
+  const manifestPath = value('--manifest'); if (!manifestPath) refuse('--manifest required for preview or prepare')
+  const manifest = JSON.parse(safeRead(manifestPath).toString('utf8')) as MacRepairManifest
+  if (prepare && !transactionDir) refuse('--transaction required for prepare')
+  const preview = prepare ? prepareMacSpeakerRepair(manifest, transactionDir!) : previewMacSpeakerRepair(manifest)
+  console.log(JSON.stringify({ id: manifest.id, mode: prepare ? 'prepared' : 'dry-run', ...preview.summary }))
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+  try { macSpeakerRepairMain() } catch (error) { console.error(error instanceof Error ? error.message : String(error)); process.exitCode = 1 }
+}