@gotcos/glasses-server 6.21.14 → 6.21.18

package/server/lib/meeting-audio-archive.ts

@@ -0,0 +1,314 @@
+// Meeting audio kept long enough for a human to review who was speaking.
+//
+// WHY IT DID NOT EXIST. Chunk WAVs lived in `session-audio` only until a meeting
+// was saved, then moved to `pending-batch` for HQ re-transcription and deleted
+// when that finished. Measured 2026-08-06: `session-audio` held 0 files. So the
+// review panel could show a phrase but never let anyone HEAR it, and its own
+// copy said "naming this needs its audio, which is no longer held."
+//
+// Miles's decision: keep a week, so review can happen on a weekend rather than
+// only within hours of the meeting, and stay under 8 GB.
+//
+// SIZING IS MEASURED, NOT GUESSED. Real recording volume over the 14 days to
+// 2026-08-06 was 3.1 h/day mean, 6.9 h peak. A 7-day window is ~22 hours, which
+// at 16 kHz mono 16-bit (32 KB/s) is ~2.5 GB — comfortably inside 8 GB. So the
+// audio is kept UNCOMPRESSED and stays usable for re-transcription, not just
+// playback. The cap is a runaway backstop: it would take a sustained 10 h/day
+// week to reach it.
+//
+// HARD LINKS, NOT COPIES. Archiving happens at the moment audio moves to
+// `pending-batch`, and links the same inodes rather than duplicating them. A
+// copy would double disk for the whole batch window — 260 MB for a two-hour
+// meeting — and introduce an ordering hazard against the batch purge. With links
+// the pipeline can delete its directory whenever it likes and the bytes survive.
+
+import {
+  copyFileSync, existsSync, linkSync, mkdirSync, readdirSync, rmSync, statSync,
+} from 'node:fs'
+import { join, resolve } from 'node:path'
+import { dataPath } from './data-dir.js'
+
+export const MEETING_AUDIO_DIR = 'meeting-audio'
+
+/** One week, per Miles: review should survive until a weekend. */
+export function meetingAudioTtlMs(): number {
+  const raw = Number(process.env.COS_MEETING_AUDIO_RETENTION_DAYS)
+  const days = Number.isFinite(raw) && raw > 0 ? raw : 7
+  return days * 24 * 60 * 60 * 1000
+}
+
+/** Total budget for retained meeting audio. Miles: stay under 8 GB. */
+export function meetingAudioMaxBytes(): number {
+  const raw = Number(process.env.COS_MEETING_AUDIO_MAX_BYTES)
+  return Number.isFinite(raw) && raw > 0 ? raw : 8 * 1024 * 1024 * 1024
+}
+
+/** Master switch. Default ON — with it off, review has no audio at all. */
+export function meetingAudioEnabled(): boolean {
+  return process.env.COS_MEETING_AUDIO !== '0'
+}
+
+function sessionDir(sessionId: string): string | null {
+  if (!/^[A-Za-z0-9:_-]{3,96}$/.test(sessionId)) return null
+  const root = dataPath(MEETING_AUDIO_DIR)
+  const path = join(root, sessionId.replace(/:/g, '_'))
+  return resolve(path).startsWith(resolve(root) + '/') ? path : null
+}
+
+/** Chunk WAVs as written by the capture path (`chunk_0000.wav`). */
+function isChunkWav(name: string): boolean {
+  return /^chunk_\d+\.wav$/.test(name)
+}
+
+export interface ArchiveResult {
+  linked: number
+  /** Files that had to be copied because the link failed (e.g. cross-device). */
+  copied: number
+  failed: number
+  bytes: number
+}
+
+/**
+ * Bring one session's chunk WAVs into the archive.
+ *
+ * Never throws: this runs on the save path, and losing review audio must never
+ * cost a meeting. Individual failures are counted rather than aborting the rest,
+ * because a partially-archived meeting is still partially reviewable.
+ */
+export function archiveSessionAudio(sessionId: string, sourceDir: string): ArchiveResult {
+  const out: ArchiveResult = { linked: 0, copied: 0, failed: 0, bytes: 0 }
+  if (!meetingAudioEnabled()) return out
+  const dest = sessionDir(sessionId)
+  if (!dest || !existsSync(sourceDir)) return out
+  let names: string[]
+  try {
+    names = readdirSync(sourceDir).filter(isChunkWav)
+  } catch {
+    return out
+  }
+  if (names.length === 0) return out
+  try {
+    mkdirSync(dest, { recursive: true, mode: 0o700 })
+  } catch {
+    return out
+  }
+  for (const name of names) {
+    const from = resolve(sourceDir, name)
+    const to = resolve(dest, name)
+    if (existsSync(to)) continue
+    try {
+      linkSync(from, to)
+      out.linked++
+    } catch {
+      // A link can fail across filesystems or if the source vanished mid-sweep.
+      // Copy rather than skip: the point is that the audio survives.
+      try { copyFileSync(from, to); out.copied++ } catch { out.failed++; continue }
+    }
+    try { out.bytes += statSync(to).size } catch { /* counted as linked regardless */ }
+  }
+  return out
+}
+
+/** Bytes and age for one archived session. */
+function sessionSize(dir: string): { bytes: number; mtimeMs: number; files: number } {
+  let bytes = 0, mtimeMs = 0, files = 0
+  try {
+    for (const name of readdirSync(dir).filter(isChunkWav)) {
+      try {
+        const st = statSync(join(dir, name))
+        bytes += st.size
+        files++
+        mtimeMs = Math.max(mtimeMs, st.mtimeMs)
+      } catch { /* skip unreadable */ }
+    }
+  } catch { /* unreadable dir reports zero */ }
+  return { bytes, mtimeMs, files }
+}
+
+export interface SweepResult {
+  removed: string[]
+  retained: string[]
+  bytesFreed: number
+}
+
+/**
+ * Drop sessions past the retention window.
+ *
+ * A session whose age cannot be read is RETAINED — treating an unreadable stat
+ * as ancient would delete the audio a pending review depends on.
+ */
+export function sweepMeetingAudio(nowMs: number, ttlMs = meetingAudioTtlMs()): SweepResult {
+  const root = dataPath(MEETING_AUDIO_DIR)
+  const out: SweepResult = { removed: [], retained: [], bytesFreed: 0 }
+  if (!existsSync(root)) return out
+  let names: string[]
+  try { names = readdirSync(root) } catch { return out }
+  for (const name of names) {
+    const dir = join(root, name)
+    const { bytes, mtimeMs } = sessionSize(dir)
+    if (mtimeMs <= 0) { out.retained.push(name); continue }
+    if (nowMs - mtimeMs > ttlMs) {
+      try { rmSync(dir, { recursive: true, force: true }); out.removed.push(name); out.bytesFreed += bytes }
+      catch { out.retained.push(name) }
+    } else {
+      out.retained.push(name)
+    }
+  }
+  return out
+}
+
+export interface CapResult {
+  evicted: string[]
+  bytesBefore: number
+  bytesAfter: number
+}
+
+/**
+ * Evict OLDEST SESSIONS FIRST until the archive fits its budget.
+ *
+ * Whole sessions, not individual chunks: half a meeting's audio is a confusing
+ * artefact, and predictable eviction beats squeezing in a few more megabytes.
+ *
+ * Note on accounting: while `pending-batch` still holds the same inodes, these
+ * hard-linked files are counted at full size in BOTH places, so the total reads
+ * high during the batch window. That is deliberately conservative — it can sweep
+ * slightly early, never late.
+ */
+export function enforceMeetingAudioCap(maxBytes = meetingAudioMaxBytes()): CapResult {
+  const root = dataPath(MEETING_AUDIO_DIR)
+  const out: CapResult = { evicted: [], bytesBefore: 0, bytesAfter: 0 }
+  if (!existsSync(root)) return out
+  let names: string[]
+  try { names = readdirSync(root) } catch { return out }
+
+  const entries = names.map(name => ({ name, ...sessionSize(join(root, name)) }))
+  out.bytesBefore = entries.reduce((n, e) => n + e.bytes, 0)
+  out.bytesAfter = out.bytesBefore
+  if (out.bytesAfter <= maxBytes) return out
+
+  // Oldest first. A session with an unreadable mtime sorts LAST so it is evicted
+  // only as a final resort, matching the sweeper's bias toward keeping evidence.
+  entries.sort((a, b) => (a.mtimeMs || Number.MAX_SAFE_INTEGER) - (b.mtimeMs || Number.MAX_SAFE_INTEGER))
+  for (const e of entries) {
+    if (out.bytesAfter <= maxBytes) break
+    try {
+      rmSync(join(root, e.name), { recursive: true, force: true })
+      out.evicted.push(e.name)
+      out.bytesAfter -= e.bytes
+    } catch { /* leave it counted; the next pass will try again */ }
+  }
+  return out
+}
+
+/** Absolute path to one chunk's WAV, or null when it is not retained. */
+export function meetingAudioChunkPath(sessionId: string, chunkIndex: number): string | null {
+  const dir = sessionDir(sessionId)
+  if (!dir) return null
+  // No integer guard: `chunkIndex` is a number, so the interpolation can never
+  // contain a path separator, and a nonsense value simply names a file that does
+  // not exist. Mutation confirmed an explicit check here is unreachable behind
+  // the existence test below.
+  const path = resolve(dir, `chunk_${String(chunkIndex).padStart(4, '0')}.wav`)
+  if (!resolve(path).startsWith(resolve(dir) + '/')) return null
+  return existsSync(path) ? path : null
+}
+
+/** Chunk indices retained for a session, ascending. */
+export function listMeetingAudioChunks(sessionId: string): number[] {
+  const dir = sessionDir(sessionId)
+  if (!dir || !existsSync(dir)) return []
+  try {
+    return readdirSync(dir)
+      .filter(isChunkWav)
+      .map(n => Number(n.slice('chunk_'.length, -'.wav'.length)))
+      .filter(n => Number.isInteger(n))
+      .sort((a, b) => a - b)
+  } catch {
+    return []
+  }
+}
+
+/**
+ * Cached stats for /api/health.
+ *
+ * The uncached walk statSyncs EVERY retained chunk: a 7-day window at the
+ * measured rate is roughly 2,000-3,000 files, and COS Control polls health every
+ * 12 seconds — thousands of synchronous stats on the same event loop that ingests
+ * live audio. The sibling chunkEmbeddingStoreStats is one stat per session for
+ * the same reason. A 30s cache keeps the number useful without the cost.
+ */
+let statsCache: { at: number; value: ReturnType<typeof computeMeetingAudioStats> } | null = null
+const STATS_TTL_MS = 30_000
+
+export function meetingAudioStats(): ReturnType<typeof computeMeetingAudioStats> {
+  const now = Date.now()
+  if (statsCache && now - statsCache.at < STATS_TTL_MS) return statsCache.value
+  const value = computeMeetingAudioStats()
+  statsCache = { at: now, value }
+  return value
+}
+
+/** Invalidate after a sweep or eviction so health does not report stale usage. */
+export function invalidateMeetingAudioStats(): void {
+  statsCache = null
+}
+
+/** Counts for /api/health, so retention can be seen rather than assumed. */
+function computeMeetingAudioStats(): {
+  enabled: boolean
+  sessions: number
+  bytes: number
+  maxBytes: number
+  retentionDays: number
+  oldestAgeHours: number | null
+} {
+  const root = dataPath(MEETING_AUDIO_DIR)
+  const retentionDays = Math.round((meetingAudioTtlMs() / (24 * 60 * 60 * 1000)) * 10) / 10
+  const base = {
+    enabled: meetingAudioEnabled(),
+    maxBytes: meetingAudioMaxBytes(),
+    retentionDays,
+  }
+  if (!existsSync(root)) return { ...base, sessions: 0, bytes: 0, oldestAgeHours: null }
+  let sessions = 0, bytes = 0, oldest = Number.POSITIVE_INFINITY
+  try {
+    for (const name of readdirSync(root)) {
+      const { bytes: b, mtimeMs, files } = sessionSize(join(root, name))
+      if (files === 0) continue
+      sessions++
+      bytes += b
+      if (mtimeMs > 0) oldest = Math.min(oldest, mtimeMs)
+    }
+  } catch { /* report what we have */ }
+  return {
+    ...base,
+    sessions,
+    bytes,
+    oldestAgeHours: Number.isFinite(oldest) ? Math.round(((Date.now() - oldest) / 3_600_000) * 10) / 10 : null,
+  }
+}
+
+/**
+ * One retention pass: expire first, then enforce the budget.
+ *
+ * ORDER IS LOAD-BEARING and that is why this is a named function rather than two
+ * calls inline in an interval. Enforcing the cap first would let it EVICT audio
+ * that the sweeper was about to expire anyway — counting those bytes against the
+ * budget and so evicting extra sessions that were still inside their window. Run
+ * the other way round, the cap only ever sees audio a human could still want.
+ */
+/** Retention window in days — a pure config read, no filesystem. */
+export function meetingAudioRetentionDays(): number {
+  return Math.round((meetingAudioTtlMs() / (24 * 60 * 60 * 1000)) * 10) / 10
+}
+
+export function runMeetingAudioRetention(nowMs = Date.now()): {
+  swept: SweepResult
+  capped: CapResult
+} {
+  const swept = sweepMeetingAudio(nowMs)
+  const capped = enforceMeetingAudioCap()
+  // Usage just changed; do not let health report the pre-sweep figure.
+  if (swept.removed.length > 0 || capped.evicted.length > 0) invalidateMeetingAudioStats()
+  return { swept, capped }
+}

package/server/lib/meeting-corrections.ts

@@ -0,0 +1,218 @@
+// The record of every speaker correction a human has made, per meeting.
+//
+// WHY A LEDGER AND NOT JUST A REWRITE. A relabel mutates files in place: the
+// chunk sidecar, the attendee list, the transcript turn labels. If that is all
+// that happens, three things become impossible:
+//
+//   1. UNDO. Once "Luke H" has become "Luke Henry" in the sidecar, nothing
+//      remembers it was ever anything else. A mistaken correction is permanent.
+//   2. CRASH RECOVERY. A rewrite touches several files. Die between them and the
+//      meeting is half-corrected with no trace of what was intended.
+//   3. TRAINING. Piece 3 turns a correction into an enrollment. It needs to know
+//      WHICH chunks a human vouched for, and to be able to retract that vouching
+//      later if the correction is undone.
+//
+// So the ledger is written FIRST, as intent, and the rewrite follows. A row with
+// an intent and no outcome is a correction that did not finish — visible rather
+// than silent.
+//
+// WHAT IS DELIBERATELY NOT CORRECTED. The meeting markdown's Summary, Topics,
+// Decisions and Action Items are LLM prose that refers to people by BARE FIRST
+// NAME ("Jeremy pushed back", "Chris raised Beamer sentiment"). Verified on a
+// real scribe: 6 of 12 speakers appear that way. This org has two Kyles, two
+// Jacobuses and two Chrises, so a find/replace on a first name in narrative text
+// would silently rewrite a sentence about a different person. Prose is left
+// alone and flagged stale instead — `proseStale` on the applied row.
+
+import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { dataPath } from './data-dir.js'
+
+export const CORRECTIONS_DIR = 'meeting-corrections'
+
+/**
+ * A correction is recorded in two phases sharing one id.
+ * `intent` goes down before any file is touched; `applied` or `failed` closes it.
+ * An unclosed intent is an incomplete correction, not a successful one.
+ */
+export type CorrectionPhase = 'intent' | 'applied' | 'failed'
+
+export interface CorrectionSurfaces {
+  /** Chunks whose `speaker` changed in the sidecar. */
+  sidecar: number
+  /** Lines changed in the markdown attendee list. */
+  attendees: number
+  /** `[Name]:` turn labels changed in the markdown transcript. */
+  transcript: number
+}
+
+export interface CorrectionRow {
+  id: string
+  phase: CorrectionPhase
+  /** ISO timestamp, supplied by the caller so this module stays deterministic. */
+  at: string
+  from: string
+  to: string
+  /**
+   * The exact chunk indices this correction covers. Explicit rather than derived,
+   * because piece 3 enrolls precisely these and must be able to retract
+   * precisely these. An empty array means "every chunk carrying `from`", which
+   * is resolved at apply time and written back onto the applied row.
+   */
+  chunks: number[]
+  /**
+   * 'meeting' is the only scope. Corrections are per-meeting BY DESIGN: the
+   * identifier mishearing one voice in one room does not mean every past chunk
+   * was wrong, and rewriting history on a single correction is how a small
+   * mistake becomes an unrecoverable one.
+   */
+  scope: 'meeting'
+  surfaces?: CorrectionSurfaces
+  /** True when narrative prose still carries the old label. See the header. */
+  proseStale?: boolean
+  /** Why an attempt failed, on a `failed` row. */
+  error?: string
+}
+
+function sessionFile(sessionId: string): string | null {
+  if (!/^[A-Za-z0-9:_-]{3,96}$/.test(sessionId)) return null
+  const dir = dataPath(CORRECTIONS_DIR)
+  const path = join(dir, `${sessionId.replace(/:/g, '_')}.jsonl`)
+  return resolve(path).startsWith(resolve(dir) + '/') ? path : null
+}
+
+/**
+ * Append one row. Returns false rather than throwing on a bad session id or an
+ * unwritable directory — but note the caller's contract: if the INTENT row
+ * cannot be written, the rewrite must not proceed. An unrecorded mutation is
+ * exactly what this file exists to prevent.
+ */
+export function appendCorrection(sessionId: string, row: CorrectionRow): boolean {
+  const path = sessionFile(sessionId)
+  if (!path) return false
+  try {
+    mkdirSync(dataPath(CORRECTIONS_DIR), { recursive: true, mode: 0o700 })
+    appendFileSync(path, JSON.stringify(row) + '\n', { mode: 0o600 })
+    return true
+  } catch {
+    return false
+  }
+}
+
+export interface CorrectionReadResult {
+  rows: CorrectionRow[]
+  /** Lines that could not be parsed. Surfaced, because a correction history read
+   *  partially is a correction history that lies about what a human decided. */
+  unusable: number
+  missing: boolean
+}
+
+export function readCorrections(sessionId: string): CorrectionReadResult {
+  const path = sessionFile(sessionId)
+  if (!path || !existsSync(path)) return { rows: [], unusable: 0, missing: true }
+  let raw: string
+  try {
+    raw = readFileSync(path, 'utf-8')
+  } catch {
+    return { rows: [], unusable: 0, missing: true }
+  }
+  const rows: CorrectionRow[] = []
+  let unusable = 0
+  for (const line of raw.split('\n')) {
+    if (line.trim() === '') continue
+    try {
+      const o = JSON.parse(line) as Record<string, unknown>
+      if (typeof o.id !== 'string' || typeof o.from !== 'string' || typeof o.to !== 'string') { unusable++; continue }
+      if (o.phase !== 'intent' && o.phase !== 'applied' && o.phase !== 'failed') { unusable++; continue }
+      rows.push({
+        id: o.id,
+        phase: o.phase,
+        at: typeof o.at === 'string' ? o.at : '',
+        from: o.from,
+        to: o.to,
+        chunks: Array.isArray(o.chunks) ? o.chunks.filter((n): n is number => typeof n === 'number') : [],
+        scope: 'meeting',
+        surfaces: isSurfaces(o.surfaces) ? o.surfaces : undefined,
+        proseStale: typeof o.proseStale === 'boolean' ? o.proseStale : undefined,
+        error: typeof o.error === 'string' ? o.error : undefined,
+      })
+    } catch {
+      unusable++
+    }
+  }
+  return { rows, unusable, missing: false }
+}
+
+function isSurfaces(v: unknown): v is CorrectionSurfaces {
+  if (!v || typeof v !== 'object') return false
+  const o = v as Record<string, unknown>
+  return typeof o.sidecar === 'number' && typeof o.attendees === 'number' && typeof o.transcript === 'number'
+}
+
+/**
+ * Corrections that recorded an intent and never closed it.
+ *
+ * This is the crash signal. A process that died mid-rewrite leaves exactly this,
+ * and a meeting with a pending correction should be treated as possibly
+ * half-written rather than clean.
+ */
+export function pendingCorrections(sessionId: string): CorrectionRow[] {
+  const { rows } = readCorrections(sessionId)
+  const closed = new Set(rows.filter(r => r.phase !== 'intent').map(r => r.id))
+  return rows.filter(r => r.phase === 'intent' && !closed.has(r.id))
+}
+
+/** Only the corrections that actually landed — the ones piece 3 may train on. */
+export function appliedCorrections(sessionId: string): CorrectionRow[] {
+  return readCorrections(sessionId).rows.filter(r => r.phase === 'applied')
+}
+
+/**
+ * Follow a chain of applied corrections to the label a voice now carries.
+ *
+ * Chains happen: a voice labelled 'Ext' is corrected to 'Luke H', then later to
+ * 'Luke Henry'. Asking "what is Ext now?" must answer 'Luke Henry', not stop at
+ * the first hop. Cycles are possible if a human corrects A→B then B→A, so the
+ * walk is bounded by the number of corrections and returns the last label
+ * reached rather than looping.
+ */
+export function currentLabelFor(sessionId: string, originalLabel: string): string {
+  const applied = appliedCorrections(sessionId)
+  let label = originalLabel
+  const seen = new Set<string>([label])
+  for (let hop = 0; hop < applied.length; hop++) {
+    // Latest applied correction FROM the current label wins: a later human
+    // decision supersedes an earlier one.
+    const next = [...applied].reverse().find(r => r.from === label)
+    if (!next || seen.has(next.to)) break
+    label = next.to
+    seen.add(label)
+  }
+  return label
+}
+
+/** Counts for /api/health — pending is the number that matters. */
+export function correctionStoreStats(): {
+  sessions: number
+  applied: number
+  pending: number
+  failed: number
+} {
+  const dir = dataPath(CORRECTIONS_DIR)
+  if (!existsSync(dir)) return { sessions: 0, applied: 0, pending: 0, failed: 0 }
+  let sessions = 0, applied = 0, pending = 0, failed = 0
+  try {
+    for (const name of readdirSync(dir).filter(n => n.endsWith('.jsonl'))) {
+      try {
+        statSync(join(dir, name))
+        sessions++
+        const id = name.replace(/\.jsonl$/, '')
+        const { rows } = readCorrections(id)
+        applied += rows.filter(r => r.phase === 'applied').length
+        failed += rows.filter(r => r.phase === 'failed').length
+        pending += pendingCorrections(id).length
+      } catch { /* skip unreadable */ }
+    }
+  } catch { /* report what we have */ }
+  return { sessions, applied, pending, failed }
+}