@gotcos/glasses-server 6.46.1 → 6.47.0

package/server/lib/meeting-suggestion-sides.ts

@@ -0,0 +1,242 @@
+/**
+ * What a suggestion is ABOUT, resolved on the server (6.47.0, QA1).
+ *
+ * WHY THIS EXISTS. A suggestion carries canonical ids and a phrase count: a G2 `sessionId`
+ * and a Fireflies vendor id. That is everything the engine needs and nothing a person does.
+ * "Shares 47 phrases" between `s_9f2a...` and `01JQ...` is not a question anyone can answer.
+ *
+ * WHY THE SERVER AND NOT THE CLIENT. COS Control tried to resolve the two sides itself and
+ * could only do it in imports mode: it re-derived `imported:fireflies:<h16>` from the vendor
+ * id and looked the row up in the imported library. On a PIPELINE Mac — the one surface
+ * where a person actually reviews these, because advise mode is the whole point of the
+ * review gate — there is no imported library. The Fireflies side lives in the operations
+ * tree under a path only the server knows, so the row never resolved and every suggestion
+ * rendered as two opaque ids with `resolved` hard-coded from whether an index was empty.
+ *
+ * THREE PLACES A SIDE CAN LIVE, tried in order, and `resolved: false` when it is in none of
+ * them — which is a real state (a deleted recording, a transcript the vendor removed) and is
+ * reported rather than papered over.
+ */
+
+import { existsSync, readFileSync, statSync } from 'node:fs'
+import { basename, join } from 'node:path'
+import {
+  findCosOperationsMeetingBySessionId,
+  resolveCosOperationsDir,
+} from './cos-operations-meetings.js'
+import {
+  type ImportedMeetingLibrary,
+  getImportedMeetingLibrary,
+  importHash,
+  importRecordId,
+} from './imported-meeting-library.js'
+import type { CanonicalInputs, MergeSuggestionRecord } from './meeting-actions-store.js'
+import { getMeetingStore, parseField, type MeetingStore } from './meeting-store.js'
+
+/** Bounded read for an operations `.fireflies.json`. Same ceiling the engine uses. */
+export const SIDE_SIDECAR_MAX_BYTES = 64 * 1024 * 1024
+
+export type SuggestionSideKind = 'g2' | 'fireflies'
+
+export interface SuggestionSide {
+  kind: SuggestionSideKind
+  /** The canonical id: a G2 `sessionId`, or the Fireflies vendor id. */
+  id: string
+  /** The record that still holds it, in the form `/api/meetings` uses. */
+  recordId?: string
+  title?: string
+  /** Epoch ms. Absent when nothing on disk could say when this happened. */
+  startMs?: number
+  durationMinutes?: number
+  /** Which library the side was found in. */
+  source?: 'imported' | 'cos_operations' | 'standalone_recordings'
+  /** False when nothing on this Mac holds this id any more. */
+  resolved: boolean
+}
+
+export interface SuggestionWithSides extends MergeSuggestionRecord {
+  sides: SuggestionSide[]
+}
+
+export interface SideResolverDeps {
+  library?: ImportedMeetingLibrary
+  store?: MeetingStore
+  /** Operations-relative `.fireflies.json` path per vendor id, from the engine's own scan. */
+  firefliesScribeRelPaths?: Record<string, { sidecarRelPath?: string; scribeRelPath?: string }>
+}
+
+function minutesFromDurationField(value: string | undefined): number | undefined {
+  const match = value?.match(/(\d+)/)
+  return match ? Number(match[1]) : undefined
+}
+
+function epochFromDateField(date: string | undefined, time: string | undefined): number | undefined {
+  if (!date) return undefined
+  const parsed = Date.parse(time ? `${date}T${time}` : date)
+  return Number.isFinite(parsed) ? parsed : undefined
+}
+
+/** The imported library's own row for a Fireflies id, when this Mac imported it. */
+function firefliesFromImports(id: string, library: ImportedMeetingLibrary): SuggestionSide | null {
+  const recordId = importRecordId('fireflies', importHash(id))
+  const row = library.list().find(candidate => candidate.recordId === recordId)
+  if (!row) return null
+  return {
+    kind: 'fireflies',
+    id,
+    recordId,
+    title: row.title,
+    ...(epochFromDateField(row.date, row.time) !== undefined ? { startMs: epochFromDateField(row.date, row.time)! } : {}),
+    ...(row.durationMinutes !== undefined ? { durationMinutes: row.durationMinutes } : {}),
+    source: 'imported',
+    resolved: true,
+  }
+}
+
+/**
+ * The operations tree's own scribe for a Fireflies id, on a pipeline Mac.
+ *
+ * The `.fireflies.json` sidecar is the only file that maps a vendor id to a path, so the
+ * caller hands over the map the engine's collector already built. Without it this side is
+ * unresolvable on exactly the Macs where the review happens.
+ */
+function firefliesFromOperations(
+  id: string,
+  paths: SideResolverDeps['firefliesScribeRelPaths'],
+): SuggestionSide | null {
+  const entry = paths?.[id]
+  const operationsDir = resolveCosOperationsDir()
+  if (!entry || !operationsDir) return null
+  const relPath = entry.scribeRelPath ?? entry.sidecarRelPath?.replace(/\.fireflies\.json$/, '.md')
+  if (!relPath) return null
+  const absolute = join(operationsDir, relPath)
+  const parts = relPath.split('/')
+  // `<domain>/meetings/<month>/<filename>` is the operations shape; anything else is a path
+  // this server did not write and has no record id for.
+  const recordId = parts.length >= 4 && parts[1] === 'meetings'
+    ? `ops:${parts[0]}:${parts[2]}:${parts[parts.length - 1]}`
+    : undefined
+  let title = basename(relPath, '.md')
+  let startMs: number | undefined
+  let durationMinutes: number | undefined
+  if (existsSync(absolute)) {
+    try {
+      const head = readFileSync(absolute, 'utf8').slice(0, 4096)
+      title = head.match(/^#\s+(.+)$/m)?.[1]?.trim() || title
+      const dateField = parseField(head, 'Date')
+      const [datePart, timePart] = (dateField ?? '').split(/\s+/)
+      startMs = epochFromDateField(datePart, timePart)
+      durationMinutes = minutesFromDurationField(parseField(head, 'Duration'))
+    } catch {
+      // A scribe that cannot be read still resolves to a path and a name.
+    }
+  }
+  // The sidecar is authoritative about the vendor's own clock and length.
+  const sidecarRel = entry.sidecarRelPath
+  if (sidecarRel) {
+    const sidecarPath = join(operationsDir, sidecarRel)
+    try {
+      if (statSync(sidecarPath).size <= SIDE_SIDECAR_MAX_BYTES) {
+        const doc = JSON.parse(readFileSync(sidecarPath, 'utf8')) as Record<string, unknown>
+        if (typeof doc.date === 'number' && Number.isFinite(doc.date)) startMs = doc.date
+        if (typeof doc.duration === 'number' && Number.isFinite(doc.duration)) durationMinutes = Math.round(doc.duration)
+        if (typeof doc.title === 'string' && doc.title.trim()) title = doc.title.trim()
+      }
+    } catch {
+      // Fall back to whatever the scribe said.
+    }
+  }
+  return {
+    kind: 'fireflies',
+    id,
+    ...(recordId ? { recordId } : {}),
+    title,
+    ...(startMs !== undefined ? { startMs } : {}),
+    ...(durationMinutes !== undefined ? { durationMinutes } : {}),
+    source: 'cos_operations',
+    resolved: true,
+  }
+}
+
+/** `Date` and `Duration` out of a meeting file's metadata table. */
+function stampFromMeetingHead(path: string): { title?: string; startMs?: number; durationMinutes?: number } {
+  try {
+    const head = readFileSync(path, 'utf8').slice(0, MEETING_HEAD_BYTES)
+    const [datePart, timePart] = (parseField(head, 'Date') ?? '').split(/\s+/)
+    return {
+      ...(head.match(/^#\s+(.+)$/m)?.[1]?.trim() ? { title: head.match(/^#\s+(.+)$/m)![1].trim() } : {}),
+      ...(epochFromDateField(datePart, timePart) !== undefined ? { startMs: epochFromDateField(datePart, timePart)! } : {}),
+      ...(minutesFromDurationField(parseField(head, 'Duration')) !== undefined
+        ? { durationMinutes: minutesFromDurationField(parseField(head, 'Duration'))! }
+        : {}),
+    }
+  } catch {
+    return {}
+  }
+}
+
+/** Enough to clear a scribe's title and metadata table whatever order its rows are in. */
+export const MEETING_HEAD_BYTES = 4096
+
+/** A G2 capture: the operations copy first, then this Mac's own recordings store. */
+function g2Side(sessionId: string, store: MeetingStore): SuggestionSide {
+  const operations = findCosOperationsMeetingBySessionId(sessionId)
+  if (operations) {
+    const stamp = stampFromMeetingHead(operations.meetingPath)
+    return {
+      kind: 'g2',
+      id: sessionId,
+      recordId: `ops:${operations.domain}:${operations.month}:${operations.filename}`,
+      title: stamp.title ?? operations.title,
+      ...(stamp.startMs !== undefined ? { startMs: stamp.startMs } : {}),
+      ...(stamp.durationMinutes !== undefined ? { durationMinutes: stamp.durationMinutes } : {}),
+      source: 'cos_operations',
+      resolved: true,
+    }
+  }
+  try {
+    const found = store.findBySessionId(sessionId)
+    if (found) {
+      const stamp = stampFromMeetingHead(found.filepath)
+      return {
+        kind: 'g2',
+        id: sessionId,
+        recordId: `standalone:${sessionId}`,
+        title: stamp.title ?? found.title,
+        ...(stamp.startMs !== undefined ? { startMs: stamp.startMs } : {}),
+        durationMinutes: stamp.durationMinutes ?? found.durationMin,
+        source: 'standalone_recordings',
+        resolved: true,
+      }
+    }
+  } catch {
+    // An unreadable store is an unresolved side, not a failed request.
+  }
+  return { kind: 'g2', id: sessionId, resolved: false }
+}
+
+/** Every side of one suggestion, in a stable order: captures first, then transcripts. */
+export function resolveSuggestionSides(
+  inputs: CanonicalInputs,
+  deps: SideResolverDeps = {},
+): SuggestionSide[] {
+  const library = deps.library ?? getImportedMeetingLibrary()
+  const store = deps.store ?? getMeetingStore()
+  const sides: SuggestionSide[] = inputs.sessionIds.map(sessionId => g2Side(sessionId, store))
+  for (const id of inputs.firefliesIds) {
+    sides.push(
+      firefliesFromImports(id, library)
+      ?? firefliesFromOperations(id, deps.firefliesScribeRelPaths)
+      ?? { kind: 'fireflies', id, resolved: false },
+    )
+  }
+  return sides
+}
+
+/** Attach sides to every row of a suggestion list. */
+export function withSuggestionSides(
+  rows: readonly MergeSuggestionRecord[],
+  deps: SideResolverDeps = {},
+): SuggestionWithSides[] {
+  return rows.map(row => ({ ...row, sides: resolveSuggestionSides(row.inputs, deps) }))
+}

package/server/lib/morning-brief-runtime.ts

@@ -35,12 +35,11 @@ import {
   type TasksProbe,
 } from './morning-brief-coverage.js'
 import {
-  listCosOperationsMeetingDays,
   listCosOperationsMeetingMonths,
-  listDirectLibraryMeetingDays,
   listDirectLibraryMeetingMonths,
   resolveMeetingLibrary,
 } from './cos-operations-meetings.js'
+import { importedLibraryMonths, supersededDayCounts } from './imported-library-rows.js'
 import { getMeetingStore } from './meeting-store.js'
 import { COS_SCRIPTS_DIR, callPython, contextSourceAvailable, pythonBridgeAvailable } from './python-bridge.js'
 import { resolveProviderWorkDir } from './launch-dir.js'
@@ -68,20 +67,33 @@ function sumDayCounts(months: string[], days: (month: string) => Array<{ count:
   return total
 }
 
+/**
+ * How many meetings this Mac holds, counted the way the LIST counts them.
+ *
+ * Shares `supersededDayCounts` with `/api/meetings`, so the brief and the
+ * Meetings list can never disagree about a day: a merged record replaced its
+ * import and its capture in the list, and it replaces them here too. On a Mac
+ * with no derived records the helper is the same uncapped filename scan it has
+ * always been.
+ */
 export function probeMeetings(): MeetingsProbe | null {
   const library = resolveMeetingLibrary()
   if (library.layout === 'direct') {
-    const months = listDirectLibraryMeetingMonths()
-    return { count: sumDayCounts(months, listDirectLibraryMeetingDays), newestMonth: months[0] ?? null, layout: library.layout }
+    const months = uniqueMonths([listDirectLibraryMeetingMonths(), importedLibraryMonths()])
+    return { count: sumDayCounts(months, month => supersededDayCounts(month, 'direct')), newestMonth: months[0] ?? null, layout: library.layout }
   }
   if (library.layout === 'multi_domain') {
-    const months = listCosOperationsMeetingMonths('all')
-    return { count: sumDayCounts(months, month => listCosOperationsMeetingDays(month, 'all')), newestMonth: months[0] ?? null, layout: library.layout }
+    const months = uniqueMonths([listCosOperationsMeetingMonths('all'), importedLibraryMonths()])
+    return { count: sumDayCounts(months, month => supersededDayCounts(month, 'multi_domain')), newestMonth: months[0] ?? null, layout: library.layout }
   }
   if (library.layout === 'invalid_explicit_root') return null
   const store = getMeetingStore()
-  const months = store.listMonths()
-  return { count: sumDayCounts(months, month => store.listDayCounts(month)), newestMonth: months[0] ?? null, layout: 'standalone' }
+  const months = uniqueMonths([store.listMonths(), importedLibraryMonths()])
+  return { count: sumDayCounts(months, month => supersededDayCounts(month, 'standalone', { store })), newestMonth: months[0] ?? null, layout: 'standalone' }
+}
+
+function uniqueMonths(groups: string[][]): string[] {
+  return [...new Set(groups.flat())].sort().reverse()
 }
 
 export async function probeContext(): Promise<ContextProbe | null> {

package/server/lib/pipeline-runner.ts

@@ -0,0 +1,227 @@
+/**
+ * Spawning one COS pipeline command and reading its single result line (6.47.0, WS4).
+ *
+ * GENERALIZED FROM `g2-enrichment-runner.ts`, which stays exactly as it is. That runner
+ * bakes in one command (`--g2-file`), one prefix (`COS_G2_RESULT=`), one retry ladder and
+ * one outcome shape. The merge apply needs a different command, a different prefix, a much
+ * tighter wall and a retry decision made by the caller from the EXIT CODE, so the shape is
+ * lifted here rather than bent there.
+ *
+ * NO SERVER-SIDE LOCK AROUND THE SPAWN (v3 blocker 1). The child takes the pipeline's own
+ * lock with zero retries and exits 3 within a second when another pipeline process holds
+ * it. A server-side lock around a child that also locks is how a 75 s spawn becomes a
+ * deadlock that outlives COS Control's 90 s drain timeout.
+ *
+ * STREAMED STDOUT. A long apply prints progress, and a caller that only sees the output
+ * after the child exits cannot say what step it died in. Lines are handed over as they
+ * arrive; only a bounded tail is kept for diagnostics.
+ *
+ * EXPLICIT ENVIRONMENT. The caller passes the whole env. The server runs from a
+ * LaunchAgent whose PATH does not include Homebrew, and `PYTHON_BIN` resolving its own
+ * helpers depends on it, so `pipelinePath()` is the one helper here that reaches into
+ * `process.env`.
+ */
+
+import { spawn } from 'node:child_process'
+
+/** The apply wall. Under COS Control's 90 s drain limit, with room for the kill grace. */
+export const PIPELINE_DEFAULT_TIMEOUT_MS = 75_000
+
+/** SIGTERM, then this long, then SIGKILL. */
+export const PIPELINE_DEFAULT_KILL_GRACE_MS = 2_000
+
+/** Diagnostics tail kept per stream. */
+export const PIPELINE_MAX_CAPTURE_CHARS = 64 * 1024
+
+export interface PipelineSpawnOptions {
+  pythonBin: string
+  /** Absolute path to the script, passed as the first argument. */
+  script: string
+  args: readonly string[]
+  cwd: string
+  /** The complete child environment. Nothing is inherited implicitly. */
+  env: NodeJS.ProcessEnv
+  /** Lines starting with this are collected as result lines. */
+  resultPrefix: string
+  timeoutMs?: number
+  killGraceMs?: number
+  /** Every complete stdout line, as it arrives. */
+  onLine?: (line: string) => void
+  maxCaptureChars?: number
+}
+
+export interface PipelineAttempt {
+  /** Null when the child never ran, or was killed by a signal. */
+  code: number | null
+  signal: NodeJS.Signals | null
+  timedOut: boolean
+  /** Bounded tail. */
+  stdout: string
+  stderr: string
+  /** Every stdout line that started with `resultPrefix`, in order, prefix removed. */
+  resultLines: string[]
+  /** Set when the child could not be spawned at all. */
+  spawnError?: string
+  elapsedMs: number
+}
+
+export interface PipelineRunnerDependencies {
+  /** Injected by tests so the result-line and exit-code contract can be exercised
+   *  without a Python interpreter. */
+  run?: (options: PipelineSpawnOptions) => Promise<PipelineAttempt>
+}
+
+/**
+ * PATH for a pipeline child.
+ *
+ * A Finder- or launchd-started server does NOT inherit a login shell's PATH, and the COS
+ * venv's python resolves `git`, `node` and its own helpers through it. Prepending rather
+ * than replacing keeps a developer's own PATH intact.
+ */
+export function pipelinePath(basePath: string | undefined = process.env.PATH): string {
+  const base = basePath ?? ''
+  return base.split(':').includes('/opt/homebrew/bin') ? base : `/opt/homebrew/bin:${base}`
+}
+
+function appendBounded(current: string, chunk: string, max: number): string {
+  const next = current + chunk
+  return next.length <= max ? next : next.slice(-max)
+}
+
+/**
+ * Kill the child's whole process group where the platform has one.
+ *
+ * sync_meetings.py spawns its own children. Signalling only the direct child leaves those
+ * running and holding the pipeline lock, which is the failure the timeout exists to end.
+ */
+function signalChildTree(child: ReturnType<typeof spawn>, signal: NodeJS.Signals): void {
+  if (!child.pid) return
+  try {
+    if (process.platform !== 'win32') {
+      process.kill(-child.pid, signal)
+      return
+    }
+  } catch {
+    // The group is gone, or was never created. Fall through to the direct child.
+  }
+  try { child.kill(signal) } catch { /* already dead */ }
+}
+
+/** Spawn one pipeline command and resolve with what it printed and how it ended. */
+export async function runPipelineCommand(options: PipelineSpawnOptions): Promise<PipelineAttempt> {
+  const startedAt = Date.now()
+  const maxCapture = options.maxCaptureChars ?? PIPELINE_MAX_CAPTURE_CHARS
+  const timeoutMs = options.timeoutMs ?? PIPELINE_DEFAULT_TIMEOUT_MS
+  const killGraceMs = Math.max(25, options.killGraceMs ?? PIPELINE_DEFAULT_KILL_GRACE_MS)
+
+  return await new Promise<PipelineAttempt>(resolve => {
+    let child: ReturnType<typeof spawn>
+    try {
+      child = spawn(options.pythonBin, [options.script, ...options.args], {
+        cwd: options.cwd,
+        stdio: ['ignore', 'pipe', 'pipe'],
+        env: options.env,
+        detached: process.platform !== 'win32',
+      })
+    } catch (error) {
+      resolve({
+        code: null,
+        signal: null,
+        timedOut: false,
+        stdout: '',
+        stderr: '',
+        resultLines: [],
+        spawnError: error instanceof Error ? error.message : String(error),
+        elapsedMs: Date.now() - startedAt,
+      })
+      return
+    }
+
+    let stdout = ''
+    let stderr = ''
+    let pending = ''
+    const resultLines: string[] = []
+    let settled = false
+    let timedOut = false
+    let timer: ReturnType<typeof setTimeout> | null = null
+    let killTimer: ReturnType<typeof setTimeout> | null = null
+
+    const takeLine = (line: string): void => {
+      if (line.startsWith(options.resultPrefix)) resultLines.push(line.slice(options.resultPrefix.length))
+      options.onLine?.(line)
+    }
+
+    const finish = (attempt: Omit<PipelineAttempt, 'elapsedMs'>): void => {
+      if (settled) return
+      settled = true
+      if (timer) clearTimeout(timer)
+      if (killTimer) clearTimeout(killTimer)
+      // A final line with no trailing newline is still a line.
+      if (pending.trim() !== '') takeLine(pending.trim())
+      pending = ''
+      resolve({ ...attempt, resultLines, elapsedMs: Date.now() - startedAt })
+    }
+
+    child.stdout?.on('data', (chunk: Buffer) => {
+      const text = chunk.toString()
+      stdout = appendBounded(stdout, text, maxCapture)
+      pending += text
+      const parts = pending.split(/\r?\n/)
+      pending = parts.pop() ?? ''
+      for (const part of parts) {
+        const line = part.trim()
+        if (line !== '') takeLine(line)
+      }
+    })
+    child.stderr?.on('data', (chunk: Buffer) => { stderr = appendBounded(stderr, chunk.toString(), maxCapture) })
+
+    child.on('error', error => finish({
+      code: null,
+      signal: null,
+      timedOut,
+      stdout,
+      stderr,
+      resultLines,
+      spawnError: error.message,
+    }))
+    child.on('close', (code, signal) => finish({ code, signal, timedOut, stdout, stderr, resultLines }))
+
+    timer = setTimeout(() => {
+      timedOut = true
+      signalChildTree(child, 'SIGTERM')
+      killTimer = setTimeout(() => signalChildTree(child, 'SIGKILL'), killGraceMs)
+      killTimer.unref?.()
+    }, timeoutMs)
+    timer.unref?.()
+  })
+}
+
+export type ResultLineFailure = 'missing' | 'malformed' | 'duplicated'
+
+export type ResultLineOutcome<T> =
+  | { ok: true; value: T }
+  | { ok: false; reason: ResultLineFailure }
+
+/**
+ * Read the one result line a pipeline command is contracted to print.
+ *
+ * THREE DISTINCT FAILURES, not one. A command that printed nothing died before its report;
+ * a command that printed two reported twice and neither can be trusted as the outcome; a
+ * command that printed something unparseable has changed its contract. All three are
+ * `result_unreadable` to the caller, but they are different bugs and the reason says which.
+ */
+export function parseResultLine<T>(
+  resultLines: readonly string[],
+  validate: (value: unknown) => value is T,
+): ResultLineOutcome<T> {
+  if (resultLines.length === 0) return { ok: false, reason: 'missing' }
+  if (resultLines.length > 1) return { ok: false, reason: 'duplicated' }
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(resultLines[0])
+  } catch {
+    return { ok: false, reason: 'malformed' }
+  }
+  if (!validate(parsed)) return { ok: false, reason: 'malformed' }
+  return { ok: true, value: parsed }
+}

package/server/lib/voice-evidence-guard.ts

@@ -0,0 +1,87 @@
+/**
+ * What may be used as VOICE EVIDENCE (6.47.0, WS5).
+ *
+ * A voice profile is built from audio this Mac captured. An imported meeting has
+ * no audio at all — Fireflies sends text — and a derived record (a merge, or one
+ * piece of a split) is a FUNCTION of other records rather than a recording. Its
+ * speaker names came from the vendor's own diarization or from a voice match
+ * suggestion, so training a profile on either would fold a cloud label back into
+ * the local identity store and then present it as local evidence. That is the
+ * one loop the speaker system must never close (CLAUDE.md: "Cloud speaker names
+ * training voice profiles (never)").
+ *
+ * REFUSES BY ID KIND ONLY. The rule is a property of the identifier in hand:
+ * an `imported:` or `blended:` record id, or an `.import.json` / `.derived.json`
+ * evidence path. It is NOT a property of the underlying meeting. A G2 session
+ * that happens to have a merged record derived from it is still a real capture
+ * with real audio, and relabelling it is exactly how its profile gets better —
+ * so this guard must never refuse a G2 session merely because derived records
+ * exist. The plan states that explicitly, and the execution gate pins it.
+ *
+ * PURE. No filesystem, no lookups: a guard that has to read the disk to decide
+ * fails open the moment the disk is slow, and this one runs before every voice
+ * mutation.
+ */
+
+/** A record id that names an imported or derived record rather than a capture. */
+export const IMPORTED_EVIDENCE_ID_PATTERN = /^(imported|blended):/
+
+/** The two sidecars of the imported library. Never chunk audio, never `.g2-chunks.json`. */
+export const IMPORTED_EVIDENCE_PATH_PATTERN = /\.(?:import|derived)\.json$/i
+
+export type VoiceEvidenceReason = 'imported_read_only' | 'blended_derived_record'
+
+export interface VoiceEvidenceRefusal {
+  status: 409
+  body: {
+    error: string
+    reason: VoiceEvidenceReason
+    /** The exact value that was refused, so a caller can say which input failed. */
+    source: string
+  }
+}
+
+/** The kind of an id, or null when it names neither. */
+export function importedEvidenceKind(value: unknown): 'imported' | 'blended' | null {
+  if (typeof value !== 'string') return null
+  const id = value.match(IMPORTED_EVIDENCE_ID_PATTERN)
+  if (id) return id[1] as 'imported' | 'blended'
+  // A path is only ever evidence of a derived record, so it refuses as `blended`
+  // when it is a `.derived.json` and as `imported` when it is an `.import.json`.
+  if (IMPORTED_EVIDENCE_PATH_PATTERN.test(value)) {
+    return /\.derived\.json$/i.test(value) ? 'blended' : 'imported'
+  }
+  return null
+}
+
+export function isImportedVoiceEvidence(value: unknown): boolean {
+  return importedEvidenceKind(value) !== null
+}
+
+/**
+ * Refuse the first value that names an imported or derived record.
+ *
+ * Returns null when every value is acceptable, so a caller reads as
+ * `const refusal = assertVoiceEvidenceSource([...]); if (refusal) ...`.
+ */
+export function assertVoiceEvidenceSource(values: ReadonlyArray<unknown>): VoiceEvidenceRefusal | null {
+  for (const value of values) {
+    const kind = importedEvidenceKind(value)
+    if (!kind) continue
+    return {
+      status: 409,
+      body: kind === 'imported'
+        ? {
+          error: 'Imported meetings carry no audio, so they cannot train or correct a voice',
+          reason: 'imported_read_only',
+          source: String(value),
+        }
+        : {
+          error: 'This record was derived from other meetings. Open the recording it came from',
+          reason: 'blended_derived_record',
+          source: String(value),
+        },
+    }
+  }
+  return null
+}