@gotcos/glasses-server 6.94.4 → 6.98.0

package/server/lib/mac-speaker-call-interval-projection.ts

@@ -0,0 +1,233 @@
+/** Pure derived presentation geometry. This module neither admits identities nor
+ * authenticates native execution. Its caller must validate the bound recurrence
+ * state/source before preparing support and qualify the resulting packet offline. */
+import { createHash } from 'node:crypto'
+import type { MacSpeaker256Group, MacSpeaker256State } from './mac-speaker-live-memory.js'
+import { hasMacSpeakerProtectedRows, isMacSpeakerHumanProtected } from './mac-speaker-protection.js'
+import { pyRoundInt } from './speaker-shadow-numeric.js'
+
+type Doc = Record<string, any>
+type RawBinding = MacSpeaker256State['rawBindings'][number]
+export type MacSpeakerCallIntervalMembership = 'accepted-only' | 'native-exclusive-members'
+export interface MacSpeakerCallNativeInterval { startSample: number; endSample: number; nativeCluster: string }
+export interface MacSpeakerCallSupportInterval {
+  identityId: string; rawChunkIndex: number; startSample: number; endSample: number
+  audioSHA256: string; pcmSHA256: string; evidenceIds: string[]
+  origin: 'accepted-interval' | 'native-exclusive-member'
+}
+export interface MacSpeakerCallIntervalSupport {
+  version: 1; membership: MacSpeakerCallIntervalMembership
+  sourceSHA256: string; nativeSHA256: string; timelinePCMSHA256: string; totalSamples: number
+  rawUsedSamples: number[]; nativeIntervals: MacSpeakerCallNativeInterval[]
+  intervals: MacSpeakerCallSupportInterval[]; supportSHA256: string
+}
+export interface MacSpeakerCallIntervalContext {
+  rawBindings: readonly RawBinding[]; groups: readonly MacSpeaker256Group[]
+  protectedRawChunkIndices: readonly number[]; displayLabels: Readonly<Record<string, string>>
+}
+/** Exact HQ words wholly supported by one accepted identity. These coordinates
+ * are issued by the projector, never supplied as a caller's naming selector. */
+export interface MacSpeakerCallHQWordBinding {
+  batchIndex: number; wordIndex: number; identityId: string
+  startElapsedMs: number; endElapsedMs: number; rawChunkIndices: number[]
+  pieces: Array<{ rawChunkIndex: number; startSample: number; endSample: number; audioSHA256: string; pcmSHA256: string; originalRowSHA256: string }>
+}
+/** Source geometry for explicit human word review. It carries no acoustic
+ * identity or admission claim and includes named/unknown source labels. */
+export type MacSpeakerCallHQWordSource = Omit<MacSpeakerCallHQWordBinding, 'identityId'>
+const HASH = /^[a-f0-9]{64}$/
+const GENERIC = /^(?:Voice [1-9]\d?|Ext|Unknown|Unidentified(?: \d+)?|Speaker \d+)$/
+const digest = (v: unknown) => createHash('sha256').update(JSON.stringify(v)).digest('hex')
+const fail = (reason: string): never => { throw new Error(`Mac call interval view: ${reason}`) }
+const range = (lo: number, hi: number) => Number.isSafeInteger(lo) && Number.isSafeInteger(hi) && lo >= 0 && hi > lo
+
+/** Sweep ALL native clusters, including withheld identities. A competing native
+ * cluster removes support even if it never passed recurrence admission. */
+function exclusive(intervals: readonly MacSpeakerCallNativeInterval[]): MacSpeakerCallNativeInterval[] {
+  const events = new Map<number, Array<[string, number]>>()
+  for (const row of intervals) for (const [point, delta] of [[row.startSample, 1], [row.endSample, -1]]) {
+    const list = events.get(point) ?? []; list.push([row.nativeCluster, delta]); events.set(point, list)
+  }
+  const points = [...events.keys()].sort((a, b) => a - b), active = new Map<string, number>(), out: MacSpeakerCallNativeInterval[] = []
+  for (let i = 0; i + 1 < points.length; i++) {
+    const lo = points[i], hi = points[i + 1]
+    for (const [cluster, delta] of events.get(lo)!) { const count = (active.get(cluster) ?? 0) + delta; if (count) active.set(cluster, count); else active.delete(cluster) }
+    if (active.size !== 1) continue
+    const nativeCluster = active.keys().next().value!, prior = out.at(-1)
+    if (prior?.nativeCluster === nativeCluster && prior.endSample === lo) prior.endSample = hi
+    else out.push({ startSample: lo, endSample: hi, nativeCluster })
+  }
+  return out
+}
+
+function expectedIntervals(context: MacSpeakerCallIntervalContext, support: Omit<MacSpeakerCallIntervalSupport, 'intervals' | 'supportSHA256'>): MacSpeakerCallSupportInterval[] {
+  const protectedRaw = new Set(context.protectedRawChunkIndices), admitted = new Map(context.groups.map(g => [g.nativeCluster, g]))
+  if (admitted.size !== context.groups.length) fail('duplicate admitted native cluster')
+  const native = exclusive(support.nativeIntervals), out: MacSpeakerCallSupportInterval[] = []
+  const add = (g: MacSpeaker256Group, r: RawBinding, startSample: number, endSample: number, origin: MacSpeakerCallSupportInterval['origin']) => {
+    if (protectedRaw.has(r.rawChunkIndex)) return
+    if (!range(startSample, endSample) || startSample < r.startSample || endSample > r.startSample + support.rawUsedSamples[r.rawChunkIndex]) fail('unsupported raw sample range')
+    out.push({ identityId: g.identityId, rawChunkIndex: r.rawChunkIndex, startSample, endSample, audioSHA256: r.audioSHA256, pcmSHA256: r.pcmSHA256, evidenceIds: g.witnesses.map(w => w.evidenceId), origin })
+  }
+  if (support.membership === 'accepted-only') {
+    for (const g of context.groups) for (const span of g.intervals) {
+      const r = context.rawBindings[span.rawChunkIndex]
+      if (!r || span.identityId !== g.identityId || span.audioSHA256 !== r.audioSHA256 || span.pcmSHA256 !== r.pcmSHA256) fail('accepted interval binding')
+      // Re-check exact native exclusivity instead of accepting a caller's span.
+      const cover = native.find(n => n.nativeCluster === g.nativeCluster && n.startSample <= span.startSample && n.endSample >= span.endSample)
+      if (!cover) fail('accepted interval outside exclusive native support')
+      add(g, r, span.startSample, span.endSample, 'accepted-interval')
+    }
+  } else {
+    for (const n of native) {
+      const g = admitted.get(n.nativeCluster); if (!g) continue
+      for (const r of context.rawBindings) {
+        const lo = Math.max(n.startSample, r.startSample), hi = Math.min(n.endSample, r.startSample + support.rawUsedSamples[r.rawChunkIndex])
+        if (hi > lo) add(g, r, lo, hi, 'native-exclusive-member')
+      }
+    }
+  }
+  return out.sort((a, b) => a.rawChunkIndex - b.rawChunkIndex || a.startSample - b.startSample || a.endSample - b.endSample || a.identityId.localeCompare(b.identityId))
+}
+
+function checkSource(context: MacSpeakerCallIntervalContext, support: Omit<MacSpeakerCallIntervalSupport, 'intervals' | 'supportSHA256'>): void {
+  if (support.version !== 1 || !['accepted-only', 'native-exclusive-members'].includes(support.membership) || !HASH.test(support.sourceSHA256) || !HASH.test(support.nativeSHA256) || !HASH.test(support.timelinePCMSHA256) || !Number.isSafeInteger(support.totalSamples) || support.totalSamples <= 0 || support.totalSamples > 4 * 3600 * 16000) fail('support identity')
+  if (!Array.isArray(support.rawUsedSamples) || support.rawUsedSamples.length !== context.rawBindings.length || !Array.isArray(support.nativeIntervals) || support.nativeIntervals.length > 20000 || context.rawBindings.length > 6000 || context.groups.length > 99) fail('support bounds')
+  for (const [i, r] of context.rawBindings.entries()) if (r.rawChunkIndex !== i || !HASH.test(r.audioSHA256) || !HASH.test(r.pcmSHA256) || !HASH.test(r.originalRowSHA256) || !range(r.startSample, r.endSample) || r.endSample > support.totalSamples || !Number.isSafeInteger(support.rawUsedSamples[i]) || support.rawUsedSamples[i] <= 0 || support.rawUsedSamples[i] > r.endSample - r.startSample) fail('raw PCM binding')
+  if (new Set(context.protectedRawChunkIndices).size !== context.protectedRawChunkIndices.length || context.protectedRawChunkIndices.some(i => !Number.isInteger(i) || !context.rawBindings[i])) fail('protected source indices')
+  // The used prefix must be the actual reconstructed raw intersection. A packet
+  // cannot hide an overlapping raw tail by supplying a larger usable count.
+  const ordered = [...context.rawBindings].sort((a, b) => a.startSample - b.startSample || a.rawChunkIndex - b.rawChunkIndex)
+  if (!ordered.length || Math.max(...ordered.map(r => r.endSample)) !== support.totalSamples) fail('timeline sample bound')
+  for (const [i, r] of ordered.entries()) if (support.rawUsedSamples[r.rawChunkIndex] !== Math.min(r.endSample - r.startSample, i + 1 < ordered.length ? ordered[i + 1].startSample - r.startSample : Infinity)) fail('raw used-sample geometry')
+  for (const n of support.nativeIntervals) if (!range(n.startSample, n.endSample) || n.endSample > support.totalSamples || typeof n.nativeCluster !== 'string' || !n.nativeCluster || n.nativeCluster.length > 100) fail('native geometry')
+  const identities = new Set<string>(), labels = new Set<string>()
+  for (const g of context.groups) {
+    const label = context.displayLabels[g.identityId]
+    if (!/^fluid256_[a-f0-9]{64}$/.test(g.identityId) || identities.has(g.identityId) || typeof label !== 'string' || !/^Anonymous group [1-9]\d{0,5}$/.test(label) || labels.has(label)) fail('anonymous identity namespace')
+    if (!Array.isArray(g.witnesses) || g.witnesses.length !== 2 || g.witnesses.some(w => !HASH.test(w.evidenceId) || !range(w.startSample, w.endSample) || !w.rawChunkIndices.length || w.rawChunkIndices.length !== w.pcmSHA256s.length || w.pcmSHA256s.some(h => !HASH.test(h)))) fail('missing identity witnesses')
+    const [a, b] = g.witnesses
+    if (a.startSample < b.endSample && b.startSample < a.endSample || a.rawChunkIndices.some(i => b.rawChunkIndices.includes(i)) || a.pcmSHA256s.some(h => b.pcmSHA256s.includes(h))) fail('dependent identity witnesses')
+    identities.add(g.identityId); labels.add(label)
+  }
+  if (Object.keys(context.displayLabels).length !== identities.size) fail('display identity cardinality')
+}
+
+/** Only call after full-source/state validation in the trusted offline producer.
+ * Hashes bind the supplied source; they are not a native-authentication grant. */
+export function prepareMacSpeakerCallIntervalSupport(context: MacSpeakerCallIntervalContext, source: Omit<MacSpeakerCallIntervalSupport, 'intervals' | 'supportSHA256'>): MacSpeakerCallIntervalSupport {
+  checkSource(context, source)
+  const body = { ...structuredClone(source), intervals: expectedIntervals(context, source) }
+  if (body.intervals.length > 40000) fail('interval bound')
+  return { ...body, supportSHA256: digest(body) }
+}
+
+/** Reconstruct support from the bound packet geometry and admitted groups. A
+ * missing, expanded, reidentified or rehashed arbitrary interval list refuses. */
+export function validateMacSpeakerCallIntervalSupport(context: MacSpeakerCallIntervalContext, support: MacSpeakerCallIntervalSupport): void {
+  if (!support || !Array.isArray(support.intervals) || support.intervals.length > 40000) fail('missing support')
+  const { supportSHA256, ...body } = support
+  if (!HASH.test(supportSHA256) || digest(body) !== supportSHA256) fail('support hash')
+  checkSource(context, support)
+  if (digest(expectedIntervals(context, support)) !== digest(support.intervals)) fail('support reconstruction')
+}
+
+/** Build a closed-over validated projector, avoiding caller-made label maps or
+ * mutable projections after validation. The output is a clone; BASE is untouched. */
+export function createMacSpeakerCallIntervalProjector(contextInput: MacSpeakerCallIntervalContext, supportInput: MacSpeakerCallIntervalSupport) {
+  validateMacSpeakerCallIntervalSupport(contextInput, supportInput)
+  const context = structuredClone(contextInput), support = structuredClone(supportInput), protectedRaw = new Set(context.protectedRawChunkIndices)
+  const labels = context.displayLabels, byRaw = new Map<number, MacSpeakerCallSupportInterval[]>()
+  for (const s of support.intervals) { const list = byRaw.get(s.rawChunkIndex) ?? []; list.push(s); byRaw.set(s.rawChunkIndex, list) }
+  const identityFor = (raw: number, lo: number, hi: number): string | null => {
+    const r = context.rawBindings[raw]
+    if (!r || protectedRaw.has(raw) || !range(lo, hi) || lo < r.startSample || hi > r.endSample) return null
+    let end = lo, identity: string | null = null
+    for (const s of byRaw.get(raw) ?? []) {
+      if (s.endSample <= lo || s.startSample >= hi) continue
+      if (identity && identity !== s.identityId || s.startSample > end) return null
+      identity = s.identityId; end = Math.max(end, s.endSample)
+    }
+    return end >= hi ? identity : null
+  }
+  const eligible = (r: Doc) => !!r && typeof r.speaker === 'string' && GENERIC.test(r.speaker) && !isMacSpeakerHumanProtected(r)
+  const samples = (start: unknown, end: unknown): [number, number] | null => {
+    if (typeof start !== 'number' || typeof end !== 'number' || !Number.isFinite(start) || !Number.isFinite(end) || start < 0 || end <= start) return null
+    if (!Number.isFinite(start * 16000) || !Number.isFinite(end * 16000)) return null
+    const lo = pyRoundInt(start * 16000), hi = pyRoundInt(end * 16000)
+    return range(lo, hi) ? [lo, hi] : null
+  }
+  // Presentation and human-review scopes must share this exact geometry. In
+  // particular a word crossing raw files cannot jump a gap or an overlap.
+  const hqSourceGeometry = (base: Doc): { usableHQWords: number; words: MacSpeakerCallHQWordSource[] } => {
+    let usableHQWords = 0
+    const words: MacSpeakerCallHQWordSource[] = []
+    for (const [batchIndex, batch] of (base.batchSegments ?? []).entries()) {
+      if (!Number.isInteger(batch.startChunkIdx) || !Number.isInteger(batch.endChunkIdx) || batch.startChunkIdx < 0 || batch.endChunkIdx < batch.startChunkIdx || batch.endChunkIdx >= context.rawBindings.length || !Array.isArray(batch.speakerWords)) fail('batch geometry')
+      const clock: Array<{ raw: number; lo: number; hi: number }> = []; let offset = 0
+      for (let raw = batch.startChunkIdx; raw <= batch.endChunkIdx; raw++) { const r = context.rawBindings[raw], n = r.endSample - r.startSample; clock.push({ raw, lo: offset, hi: offset + n }); offset += n }
+      for (const [wordIndex, word] of batch.speakerWords.entries()) {
+        if (typeof word?.word !== 'string' || !word.word.trim()) continue
+        const span = samples(word?.start, word?.end)
+        if (!span || span[1] > offset) continue
+        usableHQWords++
+        if (isMacSpeakerHumanProtected(word)) continue
+        const [lo, hi] = span
+        let left = 0, right = clock.length
+        while (left < right) { const mid = (left + right) >>> 1; if (clock[mid].hi <= lo) left = mid + 1; else right = mid }
+        let captureEnd: number | null = null, covered = 0, valid = true
+        const pieces: MacSpeakerCallHQWordBinding['pieces'] = []
+        for (let i = left; i < clock.length && clock[i].lo < hi; i++) {
+          const part = clock[i], r = context.rawBindings[part.raw], a = r.startSample + Math.max(0, lo - part.lo), b = r.startSample + Math.min(part.hi - part.lo, hi - part.lo)
+          if (protectedRaw.has(part.raw) || b > r.startSample + support.rawUsedSamples[part.raw] || captureEnd !== null && captureEnd !== a) { valid = false; break }
+          captureEnd = b; covered += b - a
+          pieces.push({ rawChunkIndex: part.raw, startSample: a, endSample: b, audioSHA256: r.audioSHA256, pcmSHA256: r.pcmSHA256, originalRowSHA256: r.originalRowSHA256 })
+        }
+        if (valid && pieces.length && covered === hi - lo) words.push({ batchIndex, wordIndex, startElapsedMs: pieces[0].startSample / 16, endElapsedMs: pieces.at(-1)!.endSample / 16, rawChunkIndices: pieces.map(p => p.rawChunkIndex), pieces })
+      }
+    }
+    return { usableHQWords, words }
+  }
+  const hqGeometry = (base: Doc): { usableHQWords: number; words: MacSpeakerCallHQWordBinding[] } => {
+    const source = hqSourceGeometry(base), words: MacSpeakerCallHQWordBinding[] = []
+    for (const word of source.words) {
+      if (!eligible(base.batchSegments[word.batchIndex].speakerWords[word.wordIndex])) continue
+      let identity: string | null = null, valid = true
+      for (const piece of word.pieces) {
+        const id = identityFor(piece.rawChunkIndex, piece.startSample, piece.endSample)
+        if (!id || identity && identity !== id) { valid = false; break }
+        identity = id
+      }
+      if (valid && identity) words.push({ ...word, identityId: identity })
+    }
+    return { usableHQWords: source.usableHQWords, words }
+  }
+  return {
+    identityFor,
+    hqWords(base: Doc): MacSpeakerCallHQWordBinding[] { return hqGeometry(base).words },
+    hqWordSources(base: Doc): MacSpeakerCallHQWordSource[] { return hqSourceGeometry(base).words },
+    project(base: Doc) {
+      const doc = structuredClone(base), changedRaw = new Set<number>()
+      let position = 0
+      for (const e of doc.chunkEntries) {
+        const raw = e.chunkIndex, c = e.chunk, r = context.rawBindings[raw]
+        if (typeof c.text !== 'string' || !c.text.trim()) continue
+        const root = doc.chunks[position++]
+        if (!root || !r || protectedRaw.has(raw) || hasMacSpeakerProtectedRows(c) || hasMacSpeakerProtectedRows(root)) continue
+        for (const row of [root, c]) {
+          const whole = identityFor(raw, r.startSample, r.endSample)
+          if (whole && eligible(row)) { row.speaker = labels[whole]; changedRaw.add(raw) }
+          for (const key of ['segments', 'finalSegments', 'words']) for (const nested of row[key] ?? []) {
+            if (!eligible(nested)) continue
+            const span = samples(key === 'words' ? nested.start : nested.startSec, key === 'words' ? nested.end : nested.endSec)
+            const identity = span ? identityFor(raw, r.startSample + span[0], r.startSample + span[1]) : null
+            if (identity) { nested.speaker = labels[identity]; changedRaw.add(raw) }
+          }
+        }
+      }
+      const hq = hqGeometry(base)
+      for (const word of hq.words) doc.batchSegments[word.batchIndex].speakerWords[word.wordIndex].speaker = labels[word.identityId]
+      return { doc, changedChunks: changedRaw.size, changedWords: hq.words.length, usableHQWords: hq.usableHQWords }
+    },
+  }
+}

package/server/lib/mac-speaker-call-original-view.ts

@@ -0,0 +1,328 @@
+/** Explicit return to immutable BASE plus verified older human corrections.
+ * Only derived interval artifacts move. A durable archive precedes the prepared
+ * marker, which precedes every removal; recovery never invents a new intent. */
+import { createHash, randomUUID } from 'node:crypto'
+import { closeSync, constants, fsyncSync, linkSync, lstatSync, mkdirSync, openSync, realpathSync, renameSync, unlinkSync, writeFileSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { applyMacCallHumanAnnotation, macCallHumanPaths, readMacCallHumanFile, type MacCallHumanFiles } from './mac-speaker-call-human.js'
+import { applyMacIntervalHumanAnnotation, inspectMacIntervalHumanJournal, macIntervalHumanPaths } from './mac-speaker-call-interval-human.js'
+import type { MacSpeakerCallPacket, MacSpeakerCallView } from './mac-speaker-call-view.js'
+
+const POLICY = 'mac-speaker-call-original-view-v1'
+const SHA = /^[a-f0-9]{64}$/
+const MB = 1024 * 1024
+const hash = (s: string) => createHash('sha256').update(s).digest('hex')
+const digest = (v: unknown) => hash(JSON.stringify(v))
+const equal = (a: unknown, b: unknown) => JSON.stringify(a) === JSON.stringify(b)
+function fail(reason: string): never { throw Error(`Mac original view: ${reason}`) }
+
+type SourceKey = 'base' | 'markdown' | 'ledger' | 'legacyAnnotation' | 'legacyJournal'
+type ArtifactKey = 'packet' | 'intervalAnnotation' | 'intervalJournal' | 'state'
+interface Pin<K extends string> { key: K; hash: string | null }
+interface Intent {
+  version: 1; policy: typeof POLICY; captureId: string; scopeSHA256: string; archiveId: string
+  sourcePins: Pin<SourceKey>[]; artifacts: Pin<ArtifactKey>[]; previousTransactionSHA256: string | null
+}
+interface Journal extends Intent { phase: 'prepared' | 'complete'; journalSHA256: string }
+export interface OriginalViewPreview {
+  scopeSHA256: string; archiveId: string; artifacts: ArtifactKey[]; activeActions: 0
+}
+export interface OriginalViewTransactionStatus {
+  status: 'absent' | 'prepared' | 'complete' | 'recovery-invalid'; archiveId?: string; reason?: string
+}
+export function originalViewPaths(files: MacCallHumanFiles, captureId: string) {
+  const interval = macIntervalHumanPaths(files, captureId), stem = files.sidecarPath.replace(/\.g2-chunks\.json$/, '')
+  return { journal: `${stem}.speaker-call-original-view-transaction.json`, archiveRoot: `${stem}.speaker-call-original-view-archive`, lock: interval.lock }
+}
+function specifications(files: MacCallHumanFiles, captureId: string) {
+  const interval = macIntervalHumanPaths(files, captureId), legacy = macCallHumanPaths(files, captureId)
+  return {
+    sources: [
+      { key: 'base' as const, path: files.sidecarPath, maximum: 32 * MB, optional: false },
+      { key: 'markdown' as const, path: files.meetingPath, maximum: 16 * MB, optional: true },
+      { key: 'ledger' as const, path: legacy.ledger, maximum: 8 * MB, optional: true },
+      { key: 'legacyAnnotation' as const, path: legacy.annotation, maximum: 16 * MB, optional: true },
+      { key: 'legacyJournal' as const, path: legacy.journal, maximum: 64 * MB, optional: true },
+    ],
+    artifacts: [
+      { key: 'packet' as const, path: interval.packet, maximum: 16 * MB, archiveName: 'packet.json' },
+      { key: 'intervalAnnotation' as const, path: interval.annotation, maximum: 16 * MB, archiveName: 'interval-human.json' },
+      { key: 'intervalJournal' as const, path: interval.journal, maximum: 40 * MB, archiveName: 'interval-human-transaction.json' },
+      { key: 'state' as const, path: files.sidecarPath.replace(/\.g2-chunks\.json$/, '.speaker-call-state.json'), maximum: 16 * MB, archiveName: 'state.json' },
+    ],
+  }
+}
+function canonicalParent(path: string): string {
+  if (resolve(path) !== path) fail('absolute canonical path required')
+  const parent = dirname(path)
+  if (realpathSync(parent) !== parent || !lstatSync(parent).isDirectory()) fail('canonical parent required')
+  return parent
+}
+function syncParent(path: string) {
+  const fd = openSync(canonicalParent(path), constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW | constants.O_NONBLOCK)
+  try { fsyncSync(fd) } finally { closeSync(fd) }
+}
+function safeRead(path: string, maximum: number, optional = false) {
+  const result = readMacCallHumanFile(path, maximum, optional)
+  if (result) canonicalParent(path)
+  return result
+}
+function privateDirectory(path: string, create: boolean) {
+  canonicalParent(path)
+  if (create) { try { mkdirSync(path, { mode: 0o700 }); syncParent(path) } catch (e) { if ((e as NodeJS.ErrnoException).code !== 'EEXIST') throw e } }
+  const stat = lstatSync(path)
+  if (!stat.isDirectory() || stat.isSymbolicLink() || realpathSync(path) !== path || (stat.mode & 0o077) !== 0) fail('private canonical archive directory required')
+}
+function exclusiveCopy(path: string, text: string) {
+  canonicalParent(path)
+  const existing = safeRead(path, 80 * MB, true)
+  if (existing) { if (existing.text !== text) fail('archive collision'); return }
+  const temporary = `${path}.${randomUUID()}.tmp`
+  const fd = openSync(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW | constants.O_NONBLOCK, 0o600)
+  try { writeFileSync(fd, text); fsyncSync(fd) } finally { closeSync(fd) }
+  try { linkSync(temporary, path); syncParent(path) } finally { unlinkSync(temporary); syncParent(path) }
+  if (safeRead(path, 80 * MB)!.text !== text) fail('archive copy changed')
+}
+function atomic(path: string, text: string, before: () => void) {
+  canonicalParent(path)
+  const temporary = `${path}.${randomUUID()}.tmp`
+  const fd = openSync(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW | constants.O_NONBLOCK, 0o600)
+  try { writeFileSync(fd, text); fsyncSync(fd) } finally { closeSync(fd) }
+  try { before(); renameSync(temporary, path); syncParent(path) } finally { try { unlinkSync(temporary) } catch (e) { if ((e as NodeJS.ErrnoException).code !== 'ENOENT') throw e } }
+}
+function acquire(files: MacCallHumanFiles, captureId: string, recover: boolean) {
+  const paths = originalViewPaths(files, captureId), old = safeRead(paths.lock, 4096, true)
+  if (old) {
+    if (!recover) fail('capture locked')
+    const owner = JSON.parse(old.text)
+    if (owner.kind !== POLICY || owner.journal !== paths.journal || !Number.isSafeInteger(owner.pid) || owner.pid < 1) fail('foreign capture lock')
+    try { process.kill(owner.pid, 0); fail('capture lock owner alive') } catch (e) { if ((e as NodeJS.ErrnoException).code !== 'ESRCH') throw e }
+    if (safeRead(paths.lock, 4096)!.text !== old.text) fail('capture lock drift')
+    unlinkSync(paths.lock); syncParent(paths.lock)
+  }
+  canonicalParent(paths.lock)
+  const text = JSON.stringify({ kind: POLICY, journal: paths.journal, pid: process.pid, token: randomUUID() })
+  const fd = openSync(paths.lock, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW | constants.O_NONBLOCK, 0o600)
+  try { writeFileSync(fd, text); fsyncSync(fd) } finally { closeSync(fd) }
+  syncParent(paths.lock)
+  const assertOwned = () => { if (safeRead(paths.lock, 4096, true)?.text !== text) fail('capture lock drift') }
+  return { assertOwned, release: () => { assertOwned(); unlinkSync(paths.lock); syncParent(paths.lock) } }
+}
+function sealed(body: Omit<Journal, 'journalSHA256'>): Journal { return { ...body, journalSHA256: digest(body) } }
+function checkedJournal(files: MacCallHumanFiles, captureId: string, value: unknown): Journal {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) fail('transaction integrity')
+  const journal = value as Journal, { journalSHA256, phase, ...intent } = journal
+  const { scopeSHA256, archiveId, ...scope } = intent
+  const specs = specifications(files, captureId)
+  if (journal.version !== 1 || journal.policy !== POLICY || journal.captureId !== captureId || !SHA.test(journalSHA256)
+    || digest({ ...intent, phase }) !== journalSHA256 || !['prepared', 'complete'].includes(phase)
+    || !SHA.test(scopeSHA256) || archiveId !== scopeSHA256 || digest(scope) !== scopeSHA256
+    || !Array.isArray(journal.sourcePins) || !Array.isArray(journal.artifacts)
+    || !equal(journal.sourcePins.map(p => p?.key), specs.sources.map(s => s.key))
+    || !equal(journal.artifacts.map(p => p?.key), specs.artifacts.map(s => s.key))
+    || [...journal.sourcePins, ...journal.artifacts].some(p => p.hash !== null && !SHA.test(p.hash))
+    || journal.sourcePins[0].hash === null
+    || journal.previousTransactionSHA256 !== null && !SHA.test(journal.previousTransactionSHA256)) fail('transaction integrity')
+  return journal
+}
+function archiveDirectory(files: MacCallHumanFiles, captureId: string, archiveId: string, create: boolean) {
+  if (!SHA.test(archiveId)) fail('archive identity')
+  const paths = originalViewPaths(files, captureId), directory = join(paths.archiveRoot, archiveId)
+  privateDirectory(paths.archiveRoot, create); privateDirectory(directory, create)
+  return directory
+}
+function checkSources(files: MacCallHumanFiles, captureId: string, pins: Pin<SourceKey>[]) {
+  for (const [index, spec] of specifications(files, captureId).sources.entries()) {
+    if ((safeRead(spec.path, spec.maximum, spec.optional)?.hash ?? null) !== pins[index].hash) fail('source changed')
+  }
+}
+/** Complete older journals are archival: their packet pin is intentionally not
+ * current. Their integrity and human/ledger postimages must still agree. */
+function checkLegacyJournal(files: MacCallHumanFiles, captureId: string, text: string | null, ledger: string | null, annotation: string | null) {
+  if (text === null) return
+  const value = JSON.parse(text), { journalSHA256, ...body } = value ?? {}, legacy = macCallHumanPaths(files, captureId)
+  if (value?.version !== 1 || value.policy !== 'mac-speaker-call-human-v1' || value.captureId !== captureId || value.phase !== 'complete'
+    || !SHA.test(journalSHA256) || journalSHA256 !== digest(body) || !Array.isArray(value.images) || !Array.isArray(value.pins)
+    || !equal(value.pins.map((p: any) => p?.path), [files.sidecarPath, files.meetingPath, legacy.packet])
+    || !equal(value.pins.map((p: any) => p?.maximum), [32 * MB, 16 * MB, 16 * MB])
+    || value.pins.some((p: any) => p.hash !== null && !SHA.test(p.hash))
+    || !equal(value.images.map((i: any) => i?.path), [legacy.ledger, legacy.annotation])
+    || value.images.some((i: any) => i.before !== null && typeof i.before !== 'string' || typeof i.after !== 'string' || Buffer.byteLength(i.before ?? '') > 16 * MB || Buffer.byteLength(i.after) > 16 * MB)
+    || value.images[0].after !== ledger || value.images[1].after !== annotation) fail('legacy human recovery required')
+}
+function validateInactive(files: MacCallHumanFiles, captureId: string, sources: Array<string | null>, artifacts: Array<string | null>) {
+  const [baseJSON, markdownSource, ledger, legacyAnnotation, legacyJournal] = sources
+  if (baseJSON === null) fail('missing immutable source')
+  const markdown = markdownSource ?? ''
+  const base = JSON.parse(baseJSON)
+  if (base?.sessionId !== captureId) fail('capture source mismatch')
+  checkLegacyJournal(files, captureId, legacyJournal, ledger, legacyAnnotation)
+  const baseline: MacSpeakerCallView = { doc: base, metadata: { status: 'base', reason: 'original-view', mode: 'strict', changedChunks: 0, changedWords: 0, groups: [], localization: 'estimated-ASR-with-native-support', speakerPurityVerified: false } }
+  const legacy = applyMacCallHumanAnnotation(baseJSON, ledger ?? '', legacyAnnotation, baseline)
+  let packet: MacSpeakerCallPacket | null = null
+  if (artifacts[0] !== null) { try { packet = JSON.parse(artifacts[0]) } catch { /* Preserve unusable automatic bytes in the archive too. */ } }
+  const view = applyMacIntervalHumanAnnotation({ baseJSON, markdown, ledgerJSONL: ledger ?? '', legacyAnnotationJSON: legacyAnnotation, annotationJSON: artifacts[1], packet, view: legacy })
+  if (view.metadata.intervalHumanAnnotation?.activeActions.length) fail('active interval human actions must be undone first')
+  if (artifacts[2] !== null) {
+    const value = JSON.parse(artifacts[2]), { journalSHA256, ...body } = value ?? {}, interval = macIntervalHumanPaths(files, captureId)
+    if (value?.version !== 1 || value.policy !== 'mac-speaker-call-interval-human-v1' || value.captureId !== captureId || value.phase !== 'complete'
+      || !SHA.test(journalSHA256) || journalSHA256 !== digest(body) || value.after !== artifacts[1]
+      || value.before !== null && typeof value.before !== 'string' || typeof value.after !== 'string'
+      || Buffer.byteLength(value.before ?? '') > 16 * MB || Buffer.byteLength(value.after) > 16 * MB
+      || !equal(value.pins?.map((p: any) => p.path), [files.sidecarPath, files.meetingPath, interval.ledger, interval.legacyAnnotation, interval.packet])
+      || !equal(value.pins.map((p: any) => p.maximum), [32 * MB, 16 * MB, 8 * MB, 16 * MB, 16 * MB])
+      || value.pins.some((p: any) => p.hash !== null && !SHA.test(p.hash))
+      || !equal(value.pins.slice(0, 4).map((p: any) => p.hash), [hash(baseJSON), markdownSource === null ? null : hash(markdown), ledger === null ? null : hash(ledger), legacyAnnotation === null ? null : hash(legacyAnnotation)])) fail('interval human recovery required')
+  }
+}
+function snapshot(files: MacCallHumanFiles, captureId: string, ownedPreparation = false) {
+  const specs = specifications(files, captureId), paths = originalViewPaths(files, captureId)
+  canonicalParent(paths.journal)
+  const prior = safeRead(paths.journal, MB, true)
+  let status: OriginalViewTransactionStatus
+  if (ownedPreparation && prior === null) status = { status: 'absent' }
+  else if (ownedPreparation) {
+    const previous = checkedJournal(files, captureId, JSON.parse(prior!.text))
+    if (previous.phase === 'complete') { verifyArchive(files, captureId, previous); status = { status: 'complete' } }
+    else status = inspectOriginalViewTransaction(files, captureId)
+  } else status = inspectOriginalViewTransaction(files, captureId)
+  if (status.status === 'prepared' || status.status === 'recovery-invalid') fail('original view recovery required')
+  const sources = specs.sources.map(s => safeRead(s.path, s.maximum, s.optional))
+  const artifacts = specs.artifacts.map(s => safeRead(s.path, s.maximum, true))
+  const intervalJournal = inspectMacIntervalHumanJournal(files, captureId)
+  if (intervalJournal.status === 'prepared' || intervalJournal.status === 'recovery-invalid') fail('interval human recovery required')
+  validateInactive(files, captureId, sources.map(s => s?.text ?? null), artifacts.map(a => a?.text ?? null))
+  const body: Omit<Intent, 'scopeSHA256' | 'archiveId'> = { version: 1, policy: POLICY, captureId,
+    sourcePins: specs.sources.map((s, i) => ({ key: s.key, hash: sources[i]?.hash ?? null })),
+    artifacts: specs.artifacts.map((s, i) => ({ key: s.key, hash: artifacts[i]?.hash ?? null })), previousTransactionSHA256: prior?.hash ?? null }
+  const scopeSHA256 = digest(body), intent: Intent = { ...body, scopeSHA256, archiveId: scopeSHA256 }
+  checkSources(files, captureId, intent.sourcePins)
+  for (const [index, spec] of specs.artifacts.entries()) if ((safeRead(spec.path, spec.maximum, true)?.hash ?? null) !== intent.artifacts[index].hash) fail('artifact changed')
+  if ((safeRead(paths.journal, MB, true)?.hash ?? null) !== intent.previousTransactionSHA256) fail('transaction changed')
+  return { intent, sources, artifacts, prior }
+}
+export function previewOriginalViewTransaction(files: MacCallHumanFiles, captureId: string): OriginalViewPreview {
+  const { intent } = snapshot(files, captureId)
+  return { scopeSHA256: intent.scopeSHA256, archiveId: intent.archiveId, artifacts: intent.artifacts.filter(a => a.hash !== null).map(a => a.key), activeActions: 0 }
+}
+function verifyArchive(files: MacCallHumanFiles, captureId: string, journal: Journal) {
+  const archive = archiveDirectory(files, captureId, journal.archiveId, false), specs = specifications(files, captureId)
+  // Remove the old seal before resealing a phase; it is never part of the body.
+  const { journalSHA256: _, ...preparedBody } = journal
+  const intentText = `${JSON.stringify(sealed({ ...preparedBody, phase: 'prepared' }))}\n`
+  if (safeRead(join(archive, 'intent.json'), MB)!.text !== intentText) fail('archived intent changed')
+  const completion = safeRead(join(archive, 'complete.json'), MB, journal.phase !== 'complete')
+  if (completion && completion.text !== `${JSON.stringify(sealed({ ...preparedBody, phase: 'complete' }))}\n`) fail('archived completion changed')
+  const artifacts = specs.artifacts.map((s, i) => {
+    const read = safeRead(join(archive, s.archiveName), s.maximum, journal.artifacts[i].hash === null)
+    if ((read?.hash ?? null) !== journal.artifacts[i].hash) fail('archived artifact changed')
+    return read?.text ?? null
+  })
+  if ((safeRead(join(archive, 'previous-transaction.json'), MB, journal.previousTransactionSHA256 === null)?.hash ?? null) !== journal.previousTransactionSHA256) fail('archived prior transaction changed')
+  return artifacts
+}
+function verifyPrepared(files: MacCallHumanFiles, captureId: string, journal: Journal, expectedText: string) {
+  const paths = originalViewPaths(files, captureId), specs = specifications(files, captureId), artifacts = verifyArchive(files, captureId, journal)
+  checkSources(files, captureId, journal.sourcePins)
+  for (const [index, spec] of specs.artifacts.entries()) {
+    const current = safeRead(spec.path, spec.maximum, true)
+    if (current && current.hash !== journal.artifacts[index].hash) fail('later interval artifact changed')
+  }
+  const sources = specs.sources.map(s => safeRead(s.path, s.maximum, s.optional)?.text ?? null)
+  validateInactive(files, captureId, sources, artifacts)
+  checkSources(files, captureId, journal.sourcePins)
+  if (safeRead(paths.journal, MB)!.text !== expectedText) fail('transaction changed')
+}
+export function inspectOriginalViewTransaction(files: MacCallHumanFiles, captureId: string): OriginalViewTransactionStatus {
+  try {
+    const paths = originalViewPaths(files, captureId), stored = safeRead(paths.journal, MB, true)
+    if (!stored) {
+      const lock = safeRead(paths.lock, 4096, true)
+      if (lock) {
+        let owner: any
+        try { owner = JSON.parse(lock.text) } catch { /* Foreign lock handling belongs to its owner. */ }
+        if (owner?.kind === POLICY && owner.journal === paths.journal) return { status: 'recovery-invalid', reason: 'Original-view lock without a durable intent; explicit dead-owner recovery required' }
+      }
+      return { status: 'absent' }
+    }
+    const journal = checkedJournal(files, captureId, JSON.parse(stored.text))
+    if (journal.phase === 'prepared') verifyPrepared(files, captureId, journal, stored.text)
+    else {
+      verifyArchive(files, captureId, journal)
+      if (safeRead(paths.journal, MB)!.text !== stored.text) fail('transaction changed')
+      const lock = safeRead(paths.lock, 4096, true)
+      if (lock) {
+        let owner: any
+        try { owner = JSON.parse(lock.text) } catch { /* A different operation owns malformed/foreign locks. */ }
+        if (owner?.kind === POLICY && owner.journal === paths.journal) return { status: 'recovery-invalid', archiveId: journal.archiveId, reason: 'Original-view capture lock requires explicit owner recovery' }
+      }
+    }
+    // Completed receipts are historical. They deliberately do not pin current
+    // BASE, Markdown, ledger, legacy decisions, or newly generated packets.
+    return { status: journal.phase, archiveId: journal.archiveId }
+  } catch (error) { return { status: 'recovery-invalid', reason: error instanceof Error ? error.message : 'Invalid original-view transaction' } }
+}
+function run(files: MacCallHumanFiles, captureId: string, journal: Journal, expectedText: string, assertOwned: () => void, afterWrite?: (index: number) => void) {
+  const paths = originalViewPaths(files, captureId), specs = specifications(files, captureId)
+  const fence = () => { assertOwned(); verifyPrepared(files, captureId, journal, expectedText) }
+  if (journal.phase === 'complete') { assertOwned(); verifyArchive(files, captureId, journal); return }
+  fence()
+  for (const [index, spec] of specs.artifacts.entries()) {
+    fence()
+    if (safeRead(spec.path, spec.maximum, true)) { unlinkSync(spec.path); syncParent(spec.path) }
+    afterWrite?.(index)
+    fence()
+    for (const earlier of specs.artifacts.slice(0, index + 1)) if (safeRead(earlier.path, earlier.maximum, true)) fail('removed artifact reappeared')
+  }
+  const { journalSHA256: _, ...body } = journal, complete = `${JSON.stringify(sealed({ ...body, phase: 'complete' }))}\n`
+  fence()
+  for (const spec of specs.artifacts) if (safeRead(spec.path, spec.maximum, true)) fail('removed artifact reappeared')
+  exclusiveCopy(join(archiveDirectory(files, captureId, journal.archiveId, false), 'complete.json'), complete)
+  afterWrite?.(specs.artifacts.length)
+  atomic(paths.journal, complete, () => { fence(); for (const spec of specs.artifacts) if (safeRead(spec.path, spec.maximum, true)) fail('removed artifact reappeared') })
+  if (safeRead(paths.journal, MB)!.text !== complete) fail('completed transaction changed')
+}
+export function commitOriginalViewTransaction(input: { files: MacCallHumanFiles; captureId: string; expectedScopeSHA256: string; afterWrite?: (index: number) => void }): { archiveId: string; scopeSHA256: string } {
+  if (!SHA.test(input.expectedScopeSHA256)) fail('explicit reviewed scope required')
+  const guard = acquire(input.files, input.captureId, false)
+  try {
+    const state = snapshot(input.files, input.captureId, true)
+    if (state.intent.scopeSHA256 !== input.expectedScopeSHA256) fail('reviewed source changed')
+    const paths = originalViewPaths(input.files, input.captureId), archive = archiveDirectory(input.files, input.captureId, state.intent.archiveId, true)
+    const specs = specifications(input.files, input.captureId), journal = sealed({ ...state.intent, phase: 'prepared' }), text = `${JSON.stringify(journal)}\n`
+    state.artifacts.forEach((a, i) => { if (a) exclusiveCopy(join(archive, specs.artifacts[i].archiveName), a.text) })
+    if (state.prior) exclusiveCopy(join(archive, 'previous-transaction.json'), state.prior.text)
+    exclusiveCopy(join(archive, 'intent.json'), text)
+    verifyArchive(input.files, input.captureId, journal)
+    atomic(paths.journal, text, () => {
+      guard.assertOwned(); checkSources(input.files, input.captureId, state.intent.sourcePins)
+      for (const [i, spec] of specs.artifacts.entries()) if ((safeRead(spec.path, spec.maximum, true)?.hash ?? null) !== state.intent.artifacts[i].hash) fail('artifact changed')
+      if ((safeRead(paths.journal, MB, true)?.hash ?? null) !== state.intent.previousTransactionSHA256) fail('transaction changed')
+    })
+    input.afterWrite?.(-1) // The durable intent exists; no active artifact has moved.
+    run(input.files, input.captureId, journal, text, guard.assertOwned, input.afterWrite)
+    return { archiveId: state.intent.archiveId, scopeSHA256: state.intent.scopeSHA256 }
+  } finally { guard.release() }
+}
+export function recoverOriginalViewTransaction(files: MacCallHumanFiles, captureId: string, afterWrite?: (index: number) => void): void {
+  const paths = originalViewPaths(files, captureId), stored = safeRead(paths.journal, MB, true)
+  if (!stored) {
+    const lock = safeRead(paths.lock, 4096, true)
+    if (!lock) return
+    let owner: any
+    try { owner = JSON.parse(lock.text) } catch { return }
+    if (owner?.kind !== POLICY || owner.journal !== paths.journal) return
+    // A crash before the durable intent moved nothing. Only a proven dead lock
+    // owned by this operation may be cleared; no new intent is submitted.
+    const orphanGuard = acquire(files, captureId, true)
+    try { if (safeRead(paths.journal, MB, true)) fail('transaction appeared during orphan recovery') } finally { orphanGuard.release() }
+    return
+  }
+  const guard = acquire(files, captureId, true)
+  try {
+    if (safeRead(paths.journal, MB)!.text !== stored.text) fail('transaction changed')
+    const journal = checkedJournal(files, captureId, JSON.parse(stored.text))
+    if (journal.phase === 'complete') { verifyArchive(files, captureId, journal); return }
+    run(files, captureId, journal, stored.text, guard.assertOwned, afterWrite)
+  } finally { guard.release() }
+}