@gotcos/glasses-server 6.94.1 → 6.95.0

package/server/lib/speaker-shadow-numeric.ts

@@ -0,0 +1,143 @@
+// Python-compatible numerics for the speaker shadow port (6.95.0).
+//
+// The shadow gates are a byte-for-byte port of the research tool
+// (community-1-fluidaudio-v1/scripts/hybrid.py and round3/propose.py), which ran on
+// CPython 3.15. Four Python behaviours differ from the obvious JavaScript and each one
+// changes a gate or a reason string on real meetings, so each is replicated here:
+//
+//   1. `round(x)` and `round(x, n)` round half to EVEN on the exact binary value.
+//      Math.round and toFixed round half up, and `coveredFraction`, `majority` and
+//      `seconds` are compared AFTER rounding (0.7996 rounds to 0.8 and passes 0.8).
+//   2. `'%.2f' % x` is correctly rounded half to even as well: 0.125 formats as 0.12,
+//      where (0.125).toFixed(2) is 0.13.
+//   3. `sum()` of floats is Neumaier-compensated since CPython 3.12, so a plain loop
+//      drifts in the last bits of every cosine distance and norm.
+//   4. String order is by code point, not UTF-16 unit.
+//
+// No I/O and no clock. Verified against CPython 3.15 vectors in speaker-shadow-numeric.test.ts.
+
+const view = new DataView(new ArrayBuffer(8))
+
+/** x = (neg ? -1 : 1) * mant * 2^exp, exactly. Finite x only. */
+function decompose(x: number): { neg: boolean; mant: bigint; exp: number } {
+  view.setFloat64(0, x)
+  const hi = view.getUint32(0), lo = view.getUint32(4)
+  const neg = hi >>> 31 === 1
+  const biased = (hi >>> 20) & 0x7ff
+  let mant = (BigInt(hi & 0xfffff) << 32n) | BigInt(lo)
+  let exp: number
+  if (biased === 0) exp = -1074
+  else { mant |= 1n << 52n; exp = biased - 1075 }
+  return { neg, mant, exp }
+}
+
+/** |x| * 10^digits rounded half to even, as an exact integer. */
+function scaledHalfEven(x: number, digits: number): { neg: boolean; q: bigint } {
+  const { neg, mant, exp } = decompose(x)
+  let num = mant * 10n ** BigInt(digits)
+  let den = 1n
+  if (exp >= 0) num <<= BigInt(exp)
+  else den <<= BigInt(-exp)
+  let q = num / den
+  const twice = (num % den) * 2n
+  if (twice > den || (twice === den && (q & 1n) === 1n)) q += 1n
+  return { neg, q }
+}
+
+function decimalString(neg: boolean, q: bigint, digits: number): string {
+  let text = q.toString()
+  if (digits > 0) {
+    text = text.padStart(digits + 1, '0')
+    text = `${text.slice(0, -digits)}.${text.slice(-digits)}`
+  }
+  return neg ? `-${text}` : text
+}
+
+/** Python `'%.{digits}f' % x`. */
+export function pyFixed(x: number, digits: number): string {
+  if (Number.isNaN(x)) return 'nan'
+  if (!Number.isFinite(x)) return x > 0 ? 'inf' : '-inf'
+  const { neg, q } = scaledHalfEven(x, digits)
+  return decimalString(neg, q, digits)
+}
+
+/** Python `round(x, digits)` for digits >= 1 (a float). */
+export function pyRound(x: number, digits: number): number {
+  if (!Number.isFinite(x)) return x
+  const { neg, q } = scaledHalfEven(x, digits)
+  return Number.parseFloat(decimalString(neg, q, digits))
+}
+
+/** Python `round(x)` with no digits (an int, half to even). */
+export function pyRoundInt(x: number): number {
+  const floor = Math.floor(x)
+  const fraction = x - floor
+  if (fraction > 0.5) return floor + 1
+  if (fraction < 0.5) return floor
+  return floor % 2 === 0 ? floor : floor + 1
+}
+
+/**
+ * CPython (>= 3.12) `sum()` of floats from the int start 0: the first item is added to
+ * 0 exactly, then Neumaier's improved Kahan-Babuska compensation, and the compensation is
+ * added once at the end only when it is finite and non-zero (Python/bltinmodule.c).
+ * Integral JSON values (only exact zeros occur in FluidAudio output) contribute nothing
+ * under either of CPython's int and float paths, so treating them as floats is exact.
+ */
+export function pySum(values: ArrayLike<number>): number {
+  const n = values.length
+  if (n === 0) return 0
+  let total = 0 + values[0]
+  let compensation = 0
+  for (let i = 1; i < n; i++) {
+    const x = values[i]
+    const t = total + x
+    if (Math.abs(total) >= Math.abs(x)) compensation += (total - t) + x
+    else compensation += (x - t) + total
+    total = t
+  }
+  if (compensation !== 0 && Number.isFinite(compensation)) total += compensation
+  return total
+}
+
+/** Python str ordering (by code point). */
+export function codePointCompare(a: string, b: string): number {
+  if (a === b) return 0
+  const n = Math.min(a.length, b.length)
+  for (let i = 0; i < n;) {
+    const ca = a.codePointAt(i)!, cb = b.codePointAt(i)!
+    if (ca !== cb) return ca < cb ? -1 : 1
+    i += ca > 0xffff ? 2 : 1
+  }
+  return a.length < b.length ? -1 : a.length > b.length ? 1 : 0
+}
+
+/** Python `str.isspace()` characters, which is what `\s` matches in a str pattern. */
+export const PY_SPACE_CLASS = '[\\t\\n\\v\\f\\r\\x1c-\\x1f \\x85\\xa0\\u1680\\u2000-\\u200a\\u2028\\u2029\\u202f\\u205f\\u3000]'
+/** Python `re.compile(r'Voice\s*\d+').fullmatch` (Unicode `\s` and `\d`). */
+export const PY_VOICE_LABEL = new RegExp(`^Voice${PY_SPACE_CLASS}*\\p{Nd}+$`, 'u')
+
+const ND = /^\p{Nd}$/u
+/** Python `int(re.findall(r'\d+', label)[0])`, or null when the label has no digit. */
+export function pyFirstInt(label: string): number | null {
+  const run = /\p{Nd}+/u.exec(label)
+  if (!run) return null
+  let value = 0
+  for (const ch of run[0]) {
+    const cp = ch.codePointAt(0)!
+    // Unicode keeps every decimal digit set as ten contiguous code points from its zero,
+    // and adjacent sets (mathematical digits) are whole multiples of ten.
+    let zero = cp
+    while (zero > 0 && ND.test(String.fromCodePoint(zero - 1))) zero--
+    value = value * 10 + ((cp - zero) % 10)
+  }
+  return value
+}
+
+/** Python `'%d:%02d:%02d' % (h, m, s) if h else '%d:%02d' % (m, s)` after `int(round(sec))`. */
+export function pyClock(seconds: number): string {
+  const sec = pyRoundInt(seconds)
+  const h = Math.floor(sec / 3600), m = Math.floor(sec / 60) % 60, s = sec % 60
+  const two = (n: number) => String(n).padStart(2, '0')
+  return h ? `${h}:${two(m)}:${two(s)}` : `${m}:${two(s)}`
+}

package/server/lib/speaker-shadow-report.ts

@@ -0,0 +1,113 @@
+// Speaker shadow mode (6.95.0): the readable per-meeting report Miles checks by ear.
+//
+// A port of round3/propose.py `render()`: "N voices would become M", every accepted merge
+// with its seconds, gate values and two or three listen pointers (file, time, text),
+// every rejection with its reasons, and the named labels sharing a cluster as a hint
+// ("this group also holds 65 s labelled ..."). Pure: it returns text, and the runner
+// writes it under <data>/speaker-shadow/reports/. It proposes; it never applies anything.
+
+import { join } from 'node:path'
+import { SHADOW_GATES, type ShadowProposals, type ShadowVoiceEntry } from './speaker-shadow-decide.js'
+import { PY_SPACE_CLASS, pyFixed } from './speaker-shadow-numeric.js'
+
+export interface ShadowReportInput {
+  title: string
+  sessionId: string
+  proposals: ShadowProposals
+  facts: { minutes: number; originals: number; verifiedAgainstSidecar: number; unhashedOriginals: number; unhashedWithText: number[]; humanProtectedVoices: string[] }
+  /** Where the chunk WAVs are, so each pointer names a file Miles can play. */
+  audioDir: string
+  /** The original chunk text by raw chunk index (the first 140 characters are quoted). */
+  chunkText: ReadonlyMap<number, string>
+}
+
+const STRIP = new RegExp(`^${PY_SPACE_CLASS}+|${PY_SPACE_CLASS}+$`, 'gu')
+const quote = (text: string | undefined) => Array.from((text ?? '').replace(STRIP, '')).slice(0, 140).join('')
+const chunkFile = (dir: string, index: number) => join(dir, `chunk_${String(index).padStart(4, '0')}.wav`)
+const HEADER = ['| Voice | Speech | Covered | Top cluster, majority | Outlier check | Anchor ratio (post-hoc) |', '|---|---:|---:|---|---|---|']
+
+/** propose.py fmt_voice. */
+export function shadowVoiceRow(m: ShadowVoiceEntry): string {
+  const o = m.outlierPass && m.outlierDistance !== null
+    ? `outlier ${pyFixed(m.outlierDistance, 3)} ≤ p95 ${pyFixed(m.outlierP95!, 3)}`
+    : m.outlierDistance !== null ? `outlier ${pyFixed(m.outlierDistance, 3)} > p95 ${pyFixed(m.outlierP95!, 3)}` : `outlier: ${m.outlierNote}`
+  const ar = m.anchorRatioPostHoc === null ? '—' : `${pyFixed(m.anchorRatioPostHoc, 2)}x${m.anchorRatioPostHoc > SHADOW_GATES.anchorRatioPostHoc ? ' (above 1.5x)' : ''}`
+  return `| ${m.voice} | ${pyFixed(m.seconds, 1)} s | ${pyFixed(100 * m.coveredFraction, 0)}% | ${m.topCluster ?? 'None'} ${pyFixed(m.majority, 2)} | ${o} | ${ar} |`
+}
+
+function listenLines(m: ShadowVoiceEntry, input: ShadowReportInput): string[] {
+  return m.listen.map(p => `  - ${m.voice}: \`${chunkFile(input.audioDir, p.chunkIndex)}\` ${pyFixed(p.inFileStart, 1)} to ${pyFixed(p.inFileEnd, 1)} s (call time ${p.callTime}) "${quote(input.chunkText.get(p.chunkIndex))}"`)
+}
+
+export function renderShadowReport(input: ShadowReportInput): string {
+  const P = input.proposals, F = input.facts
+  const L: string[] = [
+    `# ${input.title}`, '',
+    `**${P.productionVoices} voices would become ${P.voicesAfter}.** FluidAudio proposed ${P.proposedMerges} merges; ${P.acceptedMerges} pass every gate, ${P.rejectedMerges} do not. Shadow mode only: nothing was renamed or written.`, '',
+    F.unhashedWithText.length
+      ? `- Meeting: ${pyFixed(F.minutes, 1)} min, ${F.originals} originals (${F.verifiedAgainstSidecar} verified; ${F.unhashedOriginals} unhashed, of which ${F.unhashedWithText.length} have text: check them).`
+      : `- Meeting: ${pyFixed(F.minutes, 1)} min, ${F.originals} originals (${F.verifiedAgainstSidecar} verified against the sidecar hashes; ${F.unhashedOriginals} had no hash, all empty-text).`,
+    `- FluidAudio found ${P.fluidAudioClusters} clusters. Labels never merged: ${P.frozenOtherLabels.join(', ') || 'none'}.`,
+    '- Gates: majority ≥0.8 of covered speech on one cluster (and ≥50% covered), ≥15 s of speech, embedding centroid inside the cluster spread (p95).',
+    '- "Anchor ratio" is an UNVALIDATED extra check (fragment vs the kept voice\'s own spread); it decides nothing. Above 1.5x is worth a listen.',
+    '- How to check: play two or three pointers for each voice in a row. Same person? The merge is right.',
+    ...(F.humanProtectedVoices.length ? [`- A person already edited chunks holding ${F.humanProtectedVoices.join(', ')}. Those edits outrank any proposal here.`] : []),
+    `- Session \`${input.sessionId}\`.`, '',
+    '## Accepted proposals', '',
+  ]
+  if (!P.accepted.length) L.push('None.')
+  for (const a of P.accepted) {
+    L.push(`### ${a.cluster}: merge ${a.merge.join(', ')} into **${a.keepLabel}**`)
+    // Names first: Ext is speech no one was attributed to, not a label anyone gave.
+    const named = a.otherLabelsInCluster.filter(o => o.label !== 'Ext'), ext = a.otherLabelsInCluster.find(o => o.label === 'Ext')
+    const extText = ext ? `${pyFixed(ext.seconds, 0)} s of Ext speech (no voice label)` : ''
+    if (named.length) {
+      L.push(`Caution: this group also holds ${named.map(o => `${pyFixed(o.seconds, 0)} s labelled ${o.label}`).join(', ')}. Those labels stay as they are.${ext ? ` It also holds ${extText}.` : ''}`)
+    } else if (ext) {
+      L.push(`Note: this group also holds ${extText}.`)
+    }
+    const touched = a.voices.map(m => m.voice).filter(v => F.humanProtectedVoices.includes(v))
+    if (touched.length) L.push(`Human edit: ${touched.join(', ')} carries a person's correction on some chunks.`)
+    L.push('', ...HEADER, ...a.voices.map(shadowVoiceRow), '', 'Listen:')
+    for (const m of a.voices) L.push(...listenLines(m, input))
+    L.push('')
+  }
+  L.push('## Rejected proposals', '')
+  const rejected = P.rejected.filter(r => r.wouldJoin)
+  if (!rejected.length) L.push('None.')
+  for (const r of rejected) {
+    L.push(`- **${r.voice}** would have joined ${r.wouldJoin} on ${r.cluster}. Rejected: ${r.reasons.join('; ')}.`)
+    L.push('', HEADER[0], HEADER[1], shadowVoiceRow(r), '', ...listenLines(r, input), '')
+  }
+  L.push('## Untouched voices', '')
+  const kept = P.rejected.filter(r => !r.wouldJoin)
+  for (const r of kept) {
+    const fails = r.eligible ? '' : ` (it also fails: ${r.reasons.filter(x => !x.startsWith('no other')).join('; ')})`
+    L.push(`- ${r.voice} (${pyFixed(r.seconds, 1)} s): kept as is; it shares ${r.cluster} with other voices, but none of them passed every gate${fails}.`)
+  }
+  for (const u of P.untouched) L.push(`- ${u.voice} (${pyFixed(u.seconds, 1)} s): ${u.why}.`)
+  if (!kept.length && !P.untouched.length) L.push('None.')
+  L.push('')
+  return L.join('\n')
+}
+
+/** A meeting the run skipped or failed: one short page, so every finished meeting has a report. */
+export function renderShadowSkipReport(input: { title: string; sessionId: string; status: 'skipped' | 'failed'; reason: string | null; detail: string | null }): string {
+  return [`# ${input.title}`, '', `**No proposals: ${input.status}** (\`${input.reason ?? 'unknown'}\`). ${input.detail ?? ''}`.trimEnd(), '', `- Session \`${input.sessionId}\`. Shadow mode only: nothing was renamed or written.`, ''].join('\n')
+}
+
+/** The run's own facts, appended by the runner (it alone knows wall time and memory). */
+export function renderShadowRunFacts(input: { rebuildMs: number; nativeMs: number; wallMs: number; peakRssBytes: number | null; osTempDirsLeft: number; sidecarPath: string; pcmSHA256: string; cliTrust: string | null }): string {
+  return ['## Run facts', '',
+    `- Rebuild ${pyFixed(input.rebuildMs / 1000, 1)} s, diarization ${pyFixed(input.nativeMs / 1000, 1)} s, total ${pyFixed(input.wallMs / 1000, 1)} s. Peak memory ${input.peakRssBytes === null ? 'not sampled' : `${Math.round(input.peakRssBytes / 1048576)} MB`}.`,
+    `- fluidaudiocli trust: ${input.cliTrust ?? 'unknown'}. Network denied by sandbox-exec. Empty OS temp dirs left: ${input.osTempDirsLeft}.`,
+    `- Sidecar: \`${input.sidecarPath}\`. The timeline WAV was a temporary input and was deleted (PCM SHA ${input.pcmSHA256.slice(0, 12)}…).`, ''].join('\n')
+}
+
+/** The report's place: reports/<YYYY-MM-DD>/<title stem>__<session>.md, named like meeting-store names meetings. */
+export function shadowReportRelativePath(title: string, sessionId: string, day: string): string {
+  const stem = title.normalize('NFKD').replace(/[\u0300-\u036f]/g, '').replace(/[^A-Za-z0-9_-]+/g, '_').replace(/^[_-]+|[_-]+$/g, '').replace(/_{2,}/g, '_').slice(0, 72) || 'Mac_recording'
+  const safeDay = /^\d{4}-\d{2}-\d{2}$/.test(day) ? day : 'undated'
+  // The whole session id: two meetings can share a title and a long id prefix.
+  return join('reports', safeDay, `${stem}__${sessionId.replace(/[^A-Za-z0-9_-]/g, '_').slice(0, 96)}.md`)
+}

package/server/lib/speaker-shadow-timeline.ts

@@ -0,0 +1,210 @@
+// Speaker shadow mode (6.95.0): the whole-call timeline and the production segments.
+//
+// A port of round3/propose.py `build_timeline` and its segment loop. READ ONLY: it reads
+// the finalized sidecar and the retained chunk WAVs and returns buffers; it never writes.
+//
+// Placement policy (the canary's): each original chunk starts at floor(elapsed_ms*16+.5),
+// rows sort by (start, raw index), an original's tail that runs into the next one's start
+// is trimmed, and gaps stay zero. Every original with an `audioSha256` must still match
+// it, and each file is read twice with the second read required to hash the same as the
+// first, which is what the tool's "rebuild twice, same PCM SHA" check proves.
+
+import { createHash } from 'node:crypto'
+import { readFile } from 'node:fs/promises'
+import { basename } from 'node:path'
+import { hasMacSpeakerProtectedRows } from './mac-speaker-protection.js'
+import { SHADOW_SAMPLE_RATE, isShadowVoiceLabel, type ShadowSegment, type ShadowSegmentSource } from './speaker-shadow-decide.js'
+import { PY_SPACE_CLASS, pyRoundInt } from './speaker-shadow-numeric.js'
+
+/** A meeting longer than this is not reconstructed (the timeline buffer is 115 MB per hour). */
+export const SHADOW_MAX_TIMELINE_SECONDS = 4 * 60 * 60
+
+export class ShadowInputError extends Error {
+  constructor(readonly reason: 'bad_sidecar' | 'audio_missing' | 'audio_format' | 'audio_drift' | 'too_long', message: string) {
+    super(message)
+    this.name = 'ShadowInputError'
+  }
+}
+
+export interface ShadowChunkEntry { chunkIndex: number; chunk: Record<string, unknown> }
+export interface ShadowTimelineRow { rawChunkIndex: number; startSample: number; sampleCount: number; usedSampleCount: number }
+export interface ShadowTimeline {
+  rows: ShadowTimelineRow[]
+  pcm: Buffer
+  total: number
+  verified: number
+  unhashed: number
+  unhashedWithText: number[]
+  pcmSHA256: string
+}
+
+const sha256 = (data: Buffer) => createHash('sha256').update(data).digest('hex')
+const PY_STRIP = new RegExp(`^${PY_SPACE_CLASS}+|${PY_SPACE_CLASS}+$`, 'gu')
+
+/** Validated entries in sidecar order, or a bad_sidecar error. */
+export function shadowEntries(sidecar: Record<string, unknown>): ShadowChunkEntry[] {
+  const raw = sidecar.chunkEntries
+  if (!Array.isArray(raw) || !raw.length) throw new ShadowInputError('bad_sidecar', 'the sidecar has no chunkEntries')
+  const seen = new Set<number>()
+  return raw.map(item => {
+    const e = item as { chunkIndex?: unknown; chunk?: unknown }
+    if (!e || typeof e !== 'object' || !Number.isInteger(e.chunkIndex) || (e.chunkIndex as number) < 0 || (e.chunkIndex as number) > 99_999) throw new ShadowInputError('bad_sidecar', 'a chunk entry has no valid chunkIndex')
+    if (!e.chunk || typeof e.chunk !== 'object' || Array.isArray(e.chunk)) throw new ShadowInputError('bad_sidecar', 'a chunk entry has no chunk')
+    const chunk = e.chunk as Record<string, unknown>
+    if (typeof chunk.elapsed !== 'number' || !Number.isFinite(chunk.elapsed)) throw new ShadowInputError('bad_sidecar', 'a chunk has no elapsed clock')
+    if (chunk.segments !== undefined && !Array.isArray(chunk.segments)) throw new ShadowInputError('bad_sidecar', 'a chunk has malformed segments')
+    if (seen.has(e.chunkIndex as number)) throw new ShadowInputError('bad_sidecar', 'duplicate chunkIndex')
+    seen.add(e.chunkIndex as number)
+    return { chunkIndex: e.chunkIndex as number, chunk }
+  })
+}
+
+/** propose.py labels_of: what a later correction would change. Hashed, so a run can refuse labels that moved after finalize. */
+export function shadowLabelsHash(entries: readonly ShadowChunkEntry[]): string {
+  const projection = entries.map(e => [
+    e.chunkIndex,
+    e.chunk.speaker ?? null,
+    ((e.chunk.segments as unknown[] | undefined) ?? []).map(s => {
+      const seg = (s ?? {}) as Record<string, unknown>
+      return [seg.speaker ?? null, seg.startSec ?? null, seg.endSec ?? null]
+    }),
+  ])
+  return createHash('sha256').update(JSON.stringify(projection)).digest('hex')
+}
+
+/** Python `wave` read of a 16 kHz mono 16-bit PCM file: the declared frames and their bytes. */
+export function readPcm16Wav(wav: Buffer): { sampleCount: number; pcm: Buffer } {
+  if (wav.length < 12 || wav.toString('ascii', 0, 4) !== 'RIFF' || wav.toString('ascii', 8, 12) !== 'WAVE') throw new ShadowInputError('audio_format', 'not a RIFF/WAVE file')
+  let offset = 12, fmtOk = false
+  while (offset + 8 <= wav.length) {
+    const id = wav.toString('ascii', offset, offset + 4)
+    const size = wav.readUInt32LE(offset + 4)
+    const body = offset + 8
+    if (id === 'fmt ') {
+      if (body + 16 > wav.length) throw new ShadowInputError('audio_format', 'truncated fmt chunk')
+      const format = wav.readUInt16LE(body), channels = wav.readUInt16LE(body + 2), rate = wav.readUInt32LE(body + 4), bits = wav.readUInt16LE(body + 14)
+      if (format !== 1 || channels !== 1 || rate !== SHADOW_SAMPLE_RATE || bits !== 16) throw new ShadowInputError('audio_format', `expected 16 kHz mono PCM16, got format ${format}, ${channels} ch, ${rate} Hz, ${bits} bit`)
+      fmtOk = true
+    } else if (id === 'data') {
+      if (!fmtOk) throw new ShadowInputError('audio_format', 'data before fmt')
+      const sampleCount = Math.floor(size / 2)
+      if (body + sampleCount * 2 > wav.length) throw new ShadowInputError('audio_format', 'truncated data chunk')
+      return { sampleCount, pcm: wav.subarray(body, body + sampleCount * 2) }
+    }
+    offset = body + size + (size % 2)
+  }
+  throw new ShadowInputError('audio_format', 'no data chunk')
+}
+
+/** The 44-byte header Python's wave writer emits, then the PCM. */
+export function pcm16WavFile(pcm: Buffer): Buffer {
+  const header = Buffer.alloc(44)
+  header.write('RIFF', 0); header.writeUInt32LE(36 + pcm.length, 4); header.write('WAVE', 8); header.write('fmt ', 12)
+  header.writeUInt32LE(16, 16); header.writeUInt16LE(1, 20); header.writeUInt16LE(1, 22); header.writeUInt32LE(SHADOW_SAMPLE_RATE, 24)
+  header.writeUInt32LE(SHADOW_SAMPLE_RATE * 2, 28); header.writeUInt16LE(2, 32); header.writeUInt16LE(16, 34); header.write('data', 36); header.writeUInt32LE(pcm.length, 40)
+  return Buffer.concat([header, pcm])
+}
+
+async function readOriginal(path: string): Promise<Buffer> {
+  try { return await readFile(path) } catch (error) {
+    const code = (error as NodeJS.ErrnoException)?.code
+    throw new ShadowInputError(code === 'ENOENT' ? 'audio_missing' : 'audio_format', `original ${path.split('/').pop()}: ${code ?? 'unreadable'}`)
+  }
+}
+
+/** Every original verified, placed and copied into one PCM buffer. Async reads, one file at a time. */
+export async function buildShadowTimeline(entries: readonly ShadowChunkEntry[], originalPath: (chunkIndex: number) => string): Promise<ShadowTimeline> {
+  const SR = SHADOW_SAMPLE_RATE
+  let verified = 0
+  const unhashed: number[] = [], unhashedWithText: number[] = []
+  const firstHash = new Map<number, string>()
+  const rows: Array<ShadowTimelineRow & { path: string }> = []
+  for (const e of entries) {
+    const path = originalPath(e.chunkIndex)
+    const bytes = await readOriginal(path)
+    const digest = sha256(bytes)
+    const want = e.chunk.audioSha256
+    if (typeof want === 'string' && want) {
+      if (digest !== want) throw new ShadowInputError('audio_drift', `original ${e.chunkIndex} no longer matches the sidecar audioSha256`)
+      verified++
+    } else {
+      unhashed.push(e.chunkIndex)
+      const text = typeof e.chunk.text === 'string' ? e.chunk.text : ''
+      if (text.replace(PY_STRIP, '')) unhashedWithText.push(e.chunkIndex)
+    }
+    const { sampleCount } = readPcm16Wav(bytes)
+    firstHash.set(e.chunkIndex, digest)
+    rows.push({ rawChunkIndex: e.chunkIndex, startSample: Math.floor((e.chunk.elapsed as number) * 16 + 0.5), sampleCount, usedSampleCount: 0, path })
+  }
+  rows.sort((a, b) => (a.startSample - b.startSample) || (a.rawChunkIndex - b.rawChunkIndex))
+  if (rows[0].startSample < 0) throw new ShadowInputError('bad_sidecar', 'a chunk starts before the recording')
+  const total = Math.max(...rows.map(x => x.startSample + x.sampleCount))
+  if (total > SHADOW_MAX_TIMELINE_SECONDS * SR) throw new ShadowInputError('too_long', `the meeting is longer than ${SHADOW_MAX_TIMELINE_SECONDS / 3600} h`)
+  const pcm = Buffer.alloc(total * 2)
+  for (let i = 0; i < rows.length; i++) {
+    const x = rows[i]
+    const bytes = await readOriginal(x.path)
+    if (sha256(bytes) !== firstHash.get(x.rawChunkIndex)) throw new ShadowInputError('audio_drift', `original ${x.rawChunkIndex} changed while the timeline was built`)
+    const raw = readPcm16Wav(bytes).pcm
+    const use = i + 1 < rows.length ? Math.min(x.sampleCount, Math.max(0, rows[i + 1].startSample - x.startSample)) : x.sampleCount
+    if (!(use > 0)) throw new ShadowInputError('bad_sidecar', `original ${x.rawChunkIndex} is fully shadowed by the next one`)
+    x.usedSampleCount = use
+    raw.copy(pcm, x.startSample * 2, 0, use * 2)
+  }
+  return {
+    rows: rows.map(({ path: _path, ...row }) => row),
+    pcm, total, verified, unhashed: unhashed.length, unhashedWithText, pcmSHA256: sha256(pcm),
+  }
+}
+
+/** propose.py's segment loop: production labels on the timeline, plus where each came from. */
+export function shadowProductionSegments(entries: readonly ShadowChunkEntry[], rows: readonly ShadowTimelineRow[], total: number): { segs: ShadowSegment[]; sources: ShadowSegmentSource[] } {
+  const SR = SHADOW_SAMPLE_RATE
+  const placed = new Map(rows.map(x => [x.rawChunkIndex, x]))
+  // Python's isinstance(x, (int, float)) is true for a JSON boolean, which counts as 0 or 1.
+  const num = (x: unknown): number | null => typeof x === 'number' ? x : typeof x === 'boolean' ? Number(x) : null
+  const segs: ShadowSegment[] = [], sources: ShadowSegmentSource[] = []
+  for (const e of entries) {
+    const x = placed.get(e.chunkIndex)!
+    const off = x.startSample, end = Math.min(total, off + x.usedSampleCount)
+    for (const raw of (e.chunk.segments as unknown[] | undefined) ?? []) {
+      const s = (raw && typeof raw === 'object' ? raw : {}) as Record<string, unknown>
+      const a = num(s.startSec), b = num(s.endSec), label = s.speaker
+      if (a === null || b === null || !label) continue
+      if (typeof label !== 'string') throw new ShadowInputError('bad_sidecar', 'a segment speaker is not a string')
+      const lo = off + pyRoundInt(a * SR), hi = Math.min(end, off + pyRoundInt(b * SR))
+      if (lo < hi) {
+        segs.push([lo, hi, label])
+        sources.push({ chunkIndex: e.chunkIndex, start: a, end: Math.min(b, x.usedSampleCount / SR), abs: lo / SR })
+      }
+    }
+  }
+  return { segs, sources }
+}
+
+/** Voice labels that appear on any chunk a human touched. A hint in the record; it never changes a gate. */
+export function shadowHumanProtectedVoices(entries: readonly ShadowChunkEntry[]): string[] {
+  const out = new Set<string>()
+  for (const e of entries) {
+    if (!hasMacSpeakerProtectedRows(e.chunk)) continue
+    const labels = [e.chunk.speaker, ...((e.chunk.segments as unknown[] | undefined) ?? []).map(s => (s as Record<string, unknown> | null)?.speaker)]
+    for (const label of labels) if (typeof label === 'string' && isShadowVoiceLabel(label)) out.add(label)
+  }
+  return [...out].sort()
+}
+
+/** The meeting's title (the saved markdown's `# ` line), else the sidecar's file name. Read only. */
+export async function readShadowMeetingTitle(sidecarPath: string): Promise<string> {
+  const fallback = basename(sidecarPath).replace(/\.g2-chunks\.json$/, '')
+  try {
+    const text = await readFile(sidecarPath.replace(/\.g2-chunks\.json$/, '.md'), 'utf8')
+    const line = text.split('\n', 40).find(l => l.startsWith('# '))
+    const title = line?.slice(2).trim()
+    return title ? title.slice(0, 160) : fallback
+  } catch { return fallback }
+}
+
+/** The meeting day for the report folder: the sidecar name's YYYY-MM-DD prefix, else null. */
+export function shadowMeetingDay(sidecarPath: string): string | null {
+  return /^(\d{4}-\d{2}-\d{2})/.exec(basename(sidecarPath))?.[1] ?? null
+}