@gotcos/glasses-server 6.76.1 → 6.77.0

package/server/lib/transcript-cleanup-context.ts

@@ -0,0 +1,234 @@
+// Transcript cleanup (6.77.0): what the cleanup knows about a meeting besides its audio.
+//
+// TEXTUAL AWARENESS. The meeting's title and attendees, the enrolled speaker names (COS
+// people), the owner card (meeting-ask-owner.ts), the profile vocabulary and the
+// heard-to-written corrections (the COS dictionary, which dictation also uses), the text
+// of files dropped on the meeting (the Meeting Ask file list), and a few local notes hits
+// for the names the doubtful passages are near (searchMemories and searchMeetingLibrary in
+// keyword-only mode: nothing leaves the Mac).
+//
+// SCREEN AWARENESS. On-screen text lines COS Control recorded during the meeting
+// (transcript-cleanup-screen.ts), shown beside each passage by time.
+//
+// TERMS. Every source contributes terms: capitalised words and runs of them ("Queen
+// Ukaoma", "Jewel360"). Terms are the per-meeting vocabulary: deterministic correction
+// may write a term from this meeting's screen or files, the model may write any term,
+// and a term the model writes that came from the meeting (not the dictionary) becomes a
+// dictionary SUGGESTION, never an automatic addition.
+
+import { isCommonEnglishWord } from './fuzzy-correct.js'
+import { redactSecrets } from './lens-gist-engines.js'
+import type { OwnerCard } from './meeting-ask-owner.js'
+import { fold } from './transcript-cleanup-text.js'
+import type { ScreenLine } from './transcript-cleanup-screen.js'
+
+/** Where a term came from. vocabulary and correction are the dictionary itself; the rest are evidence. */
+export type TermSource = 'vocabulary' | 'correction' | 'speaker' | 'owner' | 'attendee' | 'screen' | 'file' | 'notes'
+/** Sources that make a written form a dictionary suggestion. Matches Control's evidence enum. */
+export type EvidenceSource = 'screen' | 'file' | 'owner' | 'people' | 'notes'
+
+export interface ContextTerm {
+  display: string
+  key: string
+  sources: Set<TermSource>
+  /** A file name, memory id or app name for the evidence row. Never transcript or OCR text. */
+  details: Map<TermSource, string>
+}
+
+export interface CleanupFile { name: string; text: string }
+/** `id` is the prompt's own label (N1, N2); `ref` the memory id or meeting record id, for evidence rows. */
+export interface CleanupNote { id: string; ref: string; kind: 'memory' | 'meeting'; title: string; snippet: string; query: string }
+
+export interface ContextPack {
+  title: string
+  date: string
+  attendees: string[]
+  speakers: string[]
+  owner: OwnerCard | null
+  vocabulary: string[]
+  corrections: Array<{ heard: string; written: string }>
+  files: Array<{ name: string; excerpt: string }>
+  screen: ScreenLine[]
+  notes: CleanupNote[]
+  terms: Map<string, ContextTerm>
+}
+
+export const CONTEXT_LIMITS = {
+  speakers: 150,
+  vocabulary: 300,
+  corrections: 120,
+  files: 6,
+  fileChars: 60_000,
+  fileExcerptChars: 900,
+  termsPerSource: 400,
+  notes: 6,
+  noteChars: 280,
+  noteQueries: 4,
+} as const
+
+const WORD = /[\p{L}\p{N}][\p{L}\p{N}'’-]*/gu
+
+function looksLikeName(word: string): boolean {
+  if (!/^\p{Lu}/u.test(word)) return false
+  const f = fold(word)
+  if (f.length < 4) return false
+  if (isCommonEnglishWord(f)) return false
+  // An all-caps run of five letters or fewer is an acronym or a UI label, not a name.
+  if (/^\p{Lu}+$/u.test(word) && f.length <= 5) return false
+  return true
+}
+
+/** Capitalised name-like words of a text, and runs of two or three of them. */
+export function extractTerms(text: string, max: number = CONTEXT_LIMITS.termsPerSource): string[] {
+  const out = new Set<string>()
+  const words = [...text.matchAll(WORD)].map(m => ({ w: m[0].replace(/['’]s$/i, ''), at: m.index ?? 0, end: (m.index ?? 0) + m[0].length }))
+  for (let i = 0; i < words.length && out.size < max; i++) {
+    const w = words[i].w
+    const capital = /^\p{Lu}/u.test(w)
+    if (looksLikeName(w)) out.add(w)
+    // "Queen Ukaoma": a capitalised word directly before a name-like word, with nothing but a space between.
+    if (capital && i + 1 < words.length && text.slice(words[i].end, words[i + 1].at) === ' ' && looksLikeName(words[i + 1].w)) {
+      out.add(`${w} ${words[i + 1].w}`)
+    }
+  }
+  return [...out].slice(0, max)
+}
+
+function addTerm(terms: Map<string, ContextTerm>, display: string, source: TermSource, detail?: string): void {
+  const clean = display.replace(/\s+/g, ' ').trim()
+  const key = fold(clean)
+  if (!key || key.length < 2 || clean.length > 100) return
+  const existing = terms.get(key)
+  if (existing) {
+    existing.sources.add(source)
+    if (detail && !existing.details.has(source)) existing.details.set(source, detail)
+    return
+  }
+  terms.set(key, { display: clean, key, sources: new Set([source]), details: new Map(detail ? [[source, detail]] : []) })
+}
+
+export interface ContextInputs {
+  title: string
+  date: string
+  attendees: string[]
+  speakers: string[]
+  owner: OwnerCard | null
+  vocabulary: string[]
+  corrections: Record<string, string>
+  files: CleanupFile[]
+  screen: ScreenLine[]
+  notes?: CleanupNote[]
+}
+
+const SPEAKER_TOKENS = new Set(['ext', 'unknown', 'me', 'speaker'])
+
+/** The pack, with every text bounded and passed through redactSecrets. */
+export function buildContextPack(input: ContextInputs): ContextPack {
+  const terms = new Map<string, ContextTerm>()
+  const vocabulary = input.vocabulary.map(v => v.trim()).filter(Boolean).slice(0, CONTEXT_LIMITS.vocabulary)
+  for (const v of vocabulary) {
+    addTerm(terms, v, 'vocabulary')
+    for (const part of v.split(/\s+/)) if (looksLikeName(part)) addTerm(terms, part, 'vocabulary')
+  }
+  const corrections = Object.entries(input.corrections).slice(0, CONTEXT_LIMITS.corrections).map(([heard, written]) => ({ heard, written }))
+  for (const c of corrections) addTerm(terms, c.written, 'correction')
+  const speakers = [...new Set(input.speakers.map(s => s.trim()).filter(s => s && !SPEAKER_TOKENS.has(s.toLowerCase()) && !/^Unidentified \d+$/.test(s)))].slice(0, CONTEXT_LIMITS.speakers)
+  for (const s of speakers) {
+    addTerm(terms, s, 'speaker')
+    for (const part of s.split(/\s+/)) if (looksLikeName(part)) addTerm(terms, part, 'speaker')
+  }
+  const attendees = [...new Set(input.attendees.map(s => s.trim()).filter(s => s && !SPEAKER_TOKENS.has(s.toLowerCase())))].slice(0, 40)
+  for (const a of attendees) {
+    addTerm(terms, a, 'attendee')
+    for (const part of a.split(/\s+/)) if (looksLikeName(part)) addTerm(terms, part, 'attendee')
+  }
+  if (input.owner) {
+    addTerm(terms, input.owner.name, 'owner')
+    for (const part of input.owner.name.split(/\s+/)) if (looksLikeName(part)) addTerm(terms, part, 'owner')
+    if (input.owner.notes) for (const t of extractTerms(input.owner.notes, 60)) addTerm(terms, t, 'owner')
+  }
+  const files: ContextPack['files'] = []
+  for (const file of input.files.slice(0, CONTEXT_LIMITS.files)) {
+    const text = redactSecrets(file.text.slice(0, CONTEXT_LIMITS.fileChars))
+    const name = file.name.replace(/[\u0000-\u001f]/g, ' ').slice(0, 120)
+    for (const t of extractTerms(text)) addTerm(terms, t, 'file', name)
+    files.push({ name, excerpt: text.replace(/\s+/g, ' ').trim().slice(0, CONTEXT_LIMITS.fileExcerptChars) })
+  }
+  const screen = input.screen.map(l => ({ ...l, text: redactSecrets(l.text) }))
+  for (const line of screen.slice(0, 2_000)) for (const t of extractTerms(line.text, 20)) addTerm(terms, t, 'screen', line.app)
+  const notes = (input.notes ?? []).slice(0, CONTEXT_LIMITS.notes).map(n => ({ ...n, title: redactSecrets(n.title).slice(0, 120), snippet: redactSecrets(n.snippet).replace(/\s+/g, ' ').slice(0, CONTEXT_LIMITS.noteChars) }))
+  for (const n of notes) for (const t of extractTerms(`${n.title}. ${n.snippet}`, 40)) addTerm(terms, t, 'notes', n.ref)
+  return {
+    title: redactSecrets(input.title).slice(0, 200),
+    date: input.date.slice(0, 40),
+    attendees,
+    speakers,
+    owner: input.owner,
+    vocabulary,
+    corrections,
+    files,
+    screen,
+    notes,
+    terms,
+  }
+}
+
+/** Add notes found after the pack was built (the search is async and runs only for spans' names). */
+export function addNotes(pack: ContextPack, notes: CleanupNote[]): void {
+  for (const n of notes.slice(0, CONTEXT_LIMITS.notes - pack.notes.length)) {
+    const note = { ...n, title: redactSecrets(n.title).slice(0, 120), snippet: redactSecrets(n.snippet).replace(/\s+/g, ' ').slice(0, CONTEXT_LIMITS.noteChars) }
+    pack.notes.push(note)
+    for (const t of extractTerms(`${note.title}. ${note.snippet}`, 40)) addTerm(pack.terms, t, 'notes', note.ref)
+  }
+}
+
+/** A term the dictionary already holds (vocabulary, a correction's written form) is never suggested. */
+export function inDictionary(term: ContextTerm): boolean {
+  return term.sources.has('vocabulary') || term.sources.has('correction')
+}
+
+/** The evidence a term carries for a dictionary suggestion, or [] when it has none. */
+export function evidenceSources(term: ContextTerm): Array<{ source: EvidenceSource; detail: string | null }> {
+  const out: Array<{ source: EvidenceSource; detail: string | null }> = []
+  const map: Array<[TermSource, EvidenceSource]> = [['screen', 'screen'], ['file', 'file'], ['owner', 'owner'], ['speaker', 'people'], ['attendee', 'people'], ['notes', 'notes']]
+  const seen = new Set<EvidenceSource>()
+  for (const [from, to] of map) {
+    if (!term.sources.has(from) || seen.has(to)) continue
+    seen.add(to)
+    out.push({ source: to, detail: term.details.get(from)?.slice(0, 120) ?? null })
+  }
+  return out
+}
+
+/** Name-like targets for near-name detection and deterministic correction, each with where it came from. */
+export interface NameTarget { display: string; key: string; fromMeeting: boolean }
+
+/**
+ * Single-word name targets. `fromMeeting` marks a target ONLY this meeting's screen or
+ * files supplied: deterministic correction holds those to stricter rules (the source word
+ * must be capitalised and not an inflection of the target), because screen text carries UI
+ * labels a dictionary never would.
+ */
+export function nameTargets(pack: ContextPack): NameTarget[] {
+  const out: NameTarget[] = []
+  for (const term of pack.terms.values()) {
+    if (term.display.includes(' ')) continue
+    if (!/^\p{Lu}/u.test(term.display) || term.key.length < 4) continue
+    const trusted = ['vocabulary', 'correction', 'speaker', 'owner', 'attendee', 'notes'].some(s => term.sources.has(s as TermSource))
+    out.push({ display: term.display, key: term.key, fromMeeting: !trusted })
+  }
+  return out
+}
+
+/** Every known spelling, single words and phrases, folded. An exact match is not doubtful. */
+export function knownKeys(pack: ContextPack): Set<string> {
+  const keys = new Set<string>()
+  for (const term of pack.terms.values()) {
+    keys.add(term.key)
+    for (const part of term.display.split(/\s+/)) {
+      const k = fold(part)
+      if (k.length >= 3) keys.add(k)
+    }
+  }
+  return keys
+}

package/server/lib/transcript-cleanup-ledger.ts

@@ -0,0 +1,304 @@
+// Transcript cleanup (6.77.0): the undoable record of every edit, and the one place that
+// writes a cleaned transcript.
+//
+// Modelled on meeting-corrections.ts: the ledger is written FIRST, as intent, and the
+// files follow. Each applied edit keeps the ORIGINAL words beside the replacement and
+// enough of the surrounding line to find it again, so any one span can be restored later
+// (POST /api/meeting/:id/transcript-cleanup/undo) without touching the edits around it.
+//
+// WRITES. Sidecar first, markdown second, as the meeting store does: the markdown is the
+// visible commit. Both files are re-read immediately before writing and compared with the
+// copies the cleanup started from; any difference (a human relabel, a summary, a second
+// writer) and nothing is written: `changed_during_cleanup`. Only the `## Transcript`
+// section and the sidecar's `batchTranscript` (kept equal to the canonical text, as the
+// Nemotron final pass keeps it), `transcriptCleanup` summary and `lifecycleRevision` change.
+//
+// One ledger per meeting, `transcript-cleanup/ledger/<id>.jsonl`, deleted with the meeting
+// (sweepTranscriptCleanupData). A torn or unknown row is counted, never trusted.
+
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs'
+import { createHash, randomUUID } from 'node:crypto'
+import { durableAtomicWriteFileSync } from './atomic-fs.js'
+import { cleanupDir, sessionFile } from './transcript-cleanup-screen.js'
+import { joinTranscriptLines, parseTranscriptLines, type TranscriptLine } from './transcript-cleanup-text.js'
+
+export const TRANSCRIPT_SECTION = /## Transcript\n\n([\s\S]*)$/
+export function readTranscriptSection(markdown: string): string | null {
+  const match = TRANSCRIPT_SECTION.exec(markdown)
+  return match ? match[1].replace(/\n+$/, '') : null
+}
+export function replaceTranscriptSection(markdown: string, transcript: string): string | null {
+  if (!TRANSCRIPT_SECTION.test(markdown)) return null
+  return markdown.replace(TRANSCRIPT_SECTION, () => `## Transcript\n\n${transcript}\n`)
+}
+export const sha256 = (text: string): string => createHash('sha256').update(text).digest('hex')
+
+export type RunPhase = 'intent' | 'done' | 'skipped' | 'failed'
+export interface RunRow {
+  kind: 'run'
+  runId: string
+  phase: RunPhase
+  at: string
+  inputSha: string
+  outputSha?: string
+  model?: string
+  reason?: string
+  /** Why the model was not asked, while fuzzy fixes still applied (correction_skipped style). */
+  modelSkipped?: string
+}
+export interface EditRow {
+  kind: 'edit'
+  id: string
+  runId: string
+  at: string
+  line: number
+  /** Offset of the replacement in the cleaned line. */
+  offset: number
+  original: string
+  replacement: string
+  before: string
+  after: string
+  /** sha-256 of the whole cleaned line when the run committed: while it still matches, offsets are exact. */
+  lineSha: string
+  source: 'fuzzy' | 'model'
+  reasons?: string[]
+}
+export interface RevertRow { kind: 'revert'; editId: string; at: string }
+export type LedgerRow = RunRow | EditRow | RevertRow
+
+export function appendLedger(sessionId: string, rows: LedgerRow[]): boolean {
+  const path = sessionFile('ledger', sessionId)
+  if (!path || rows.length === 0) return false
+  try {
+    mkdirSync(cleanupDir('ledger'), { recursive: true, mode: 0o700 })
+    appendFileSync(path, rows.map(r => JSON.stringify(r)).join('\n') + '\n', { mode: 0o600 })
+    return true
+  } catch {
+    return false
+  }
+}
+
+export function readLedger(sessionId: string): { rows: LedgerRow[]; unusable: number } {
+  const path = sessionFile('ledger', sessionId)
+  if (!path || !existsSync(path)) return { rows: [], unusable: 0 }
+  let raw = ''
+  try { raw = readFileSync(path, 'utf8') } catch { return { rows: [], unusable: 0 } }
+  const rows: LedgerRow[] = []
+  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 (o.kind === 'run' && typeof o.runId === 'string' && typeof o.inputSha === 'string' && ['intent', 'done', 'skipped', 'failed'].includes(o.phase as string)) rows.push(o as unknown as RunRow)
+      else if (o.kind === 'edit' && typeof o.id === 'string' && typeof o.line === 'number' && typeof o.offset === 'number'
+        && typeof o.original === 'string' && typeof o.replacement === 'string' && typeof o.before === 'string' && typeof o.after === 'string'
+        && typeof o.lineSha === 'string') rows.push(o as unknown as EditRow)
+      else if (o.kind === 'revert' && typeof o.editId === 'string') rows.push(o as unknown as RevertRow)
+      else unusable++
+    } catch { unusable++ }
+  }
+  return { rows, unusable }
+}
+
+/** A completed run already produced (or started from) this exact transcript: do not run again. */
+export function alreadyCleaned(sessionId: string, transcriptSha: string): boolean {
+  return readLedger(sessionId).rows.some(r => r.kind === 'run' && (r.phase === 'done' || r.phase === 'skipped')
+    && (r.outputSha === transcriptSha || r.inputSha === transcriptSha))
+}
+
+export interface PlannedEdit {
+  line: number
+  start: number
+  end: number
+  replacement: string
+  source: 'fuzzy' | 'model'
+  reasons?: string[]
+}
+
+const CONTEXT_CHARS = 24
+
+export type AppliedEdit = PlannedEdit & { original: string; offset: number; before: string; after: string; lineSha: string }
+
+/**
+ * Apply non-overlapping edits to the lines. Returns the new lines and, per edit, where its
+ * replacement now sits and the text around it. An overlapping edit is dropped (the earlier
+ * one in the line wins), which cannot happen for spans and fixes built from distinct tokens.
+ */
+export function applyPlannedEdits(lines: readonly TranscriptLine[], edits: readonly PlannedEdit[]): {
+  lines: TranscriptLine[]
+  applied: AppliedEdit[]
+} {
+  const next = lines.map(l => ({ ...l }))
+  const applied: AppliedEdit[] = []
+  const byLine = new Map<number, PlannedEdit[]>()
+  for (const e of edits) byLine.set(e.line, [...(byLine.get(e.line) ?? []), e])
+  for (const [lineIndex, list] of byLine) {
+    const line = next.find(l => l.index === lineIndex)
+    if (!line || !line.editable) continue
+    const sorted = [...list].sort((a, b) => a.start - b.start)
+    const source = line.text
+    let out = ''
+    let cursor = 0
+    const placed: Array<{ edit: PlannedEdit; offset: number }> = []
+    for (const e of sorted) {
+      if (e.start < cursor || e.end > source.length || e.start >= e.end) continue
+      out += source.slice(cursor, e.start)
+      placed.push({ edit: e, offset: out.length })
+      out += e.replacement
+      cursor = e.end
+    }
+    out += source.slice(cursor)
+    line.text = out
+    for (const { edit, offset } of placed) {
+      applied.push({
+        ...edit,
+        original: source.slice(edit.start, edit.end),
+        offset,
+        before: out.slice(Math.max(0, offset - CONTEXT_CHARS), offset),
+        after: out.slice(offset + edit.replacement.length, offset + edit.replacement.length + CONTEXT_CHARS),
+        lineSha: sha256(out),
+      })
+    }
+  }
+  return { lines: next, applied }
+}
+
+export class CleanupWriteError extends Error {
+  constructor(readonly code: 'changed_during_cleanup' | 'no_transcript' | 'sidecar_unreadable' | 'write_failed', message?: string) { super(message ?? code) }
+}
+
+/**
+ * Write a new transcript section into the meeting, if neither file changed since it was
+ * read. `summary` lands under the sidecar's `transcriptCleanup`; it must hold counts only.
+ */
+export function commitCleanTranscript(options: {
+  meetingPath: string
+  sidecarPath: string
+  markdown: string
+  sidecarText: string
+  transcript: string
+  summary: Record<string, unknown>
+  write?: (path: string, data: string) => void
+}): void {
+  const write = options.write ?? ((path: string, data: string) => durableAtomicWriteFileSync(path, data, { mode: 0o600 }))
+  const oldSection = readTranscriptSection(options.markdown)
+  const nextMarkdown = replaceTranscriptSection(options.markdown, options.transcript)
+  if (oldSection === null || nextMarkdown === null) throw new CleanupWriteError('no_transcript')
+  let sidecar: Record<string, unknown>
+  try {
+    const parsed = JSON.parse(options.sidecarText) as unknown
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) throw new Error('not an object')
+    sidecar = parsed as Record<string, unknown>
+  } catch { throw new CleanupWriteError('sidecar_unreadable') }
+  if (typeof sidecar.batchTranscript === 'string' && sidecar.batchTranscript.replace(/\n+$/, '') === oldSection) sidecar.batchTranscript = options.transcript
+  sidecar.transcriptCleanup = options.summary
+  sidecar.lifecycleRevision = Number(sidecar.lifecycleRevision ?? 0) + 1
+  let markdownNow: string, sidecarNow: string
+  try {
+    markdownNow = readFileSync(options.meetingPath, 'utf8')
+    sidecarNow = readFileSync(options.sidecarPath, 'utf8')
+  } catch { throw new CleanupWriteError('changed_during_cleanup', 'meeting files unreadable at commit') }
+  if (markdownNow !== options.markdown || sidecarNow !== options.sidecarText) throw new CleanupWriteError('changed_during_cleanup')
+  try {
+    write(options.sidecarPath, JSON.stringify(sidecar, null, 2))
+  } catch (error) { throw new CleanupWriteError('write_failed', `sidecar: ${error instanceof Error ? error.message : String(error)}`.slice(0, 200)) }
+  try {
+    write(options.meetingPath, nextMarkdown)
+  } catch (error) {
+    try { write(options.sidecarPath, options.sidecarText) } catch { /* the two files now disagree; say so */ }
+    throw new CleanupWriteError('write_failed', `markdown: ${error instanceof Error ? error.message : String(error)}`.slice(0, 200))
+  }
+}
+
+export type UndoOutcome =
+  | { ok: true; reverted: string[] }
+  | { ok: false; status: number; error: string }
+
+/**
+ * Restore the original words of one edit, or of every live edit of one run. Refuses
+ * (409 stale) when the cleaned words are no longer where the ledger left them: a later
+ * edit by hand, a relabel that split the line, or a re-transcription.
+ */
+export function undoCleanupEdits(options: {
+  sessionId: string
+  meetingPath: string
+  sidecarPath: string
+  editId?: string
+  runId?: string
+  now?: () => Date
+  write?: (path: string, data: string) => void
+}): UndoOutcome {
+  const { rows } = readLedger(options.sessionId)
+  const reverted = new Set(rows.filter((r): r is RevertRow => r.kind === 'revert').map(r => r.editId))
+  const edits = rows.filter((r): r is EditRow => r.kind === 'edit' && !reverted.has(r.id))
+  const targets = options.editId ? edits.filter(e => e.id === options.editId) : options.runId ? edits.filter(e => e.runId === options.runId) : []
+  if (!targets.length) {
+    const known = rows.some(r => r.kind === 'edit' && (r.id === options.editId || r.runId === options.runId))
+    return known ? { ok: false, status: 409, error: 'already_reverted' } : { ok: false, status: 404, error: 'edit_not_found' }
+  }
+  let markdown: string, sidecarText: string
+  try {
+    markdown = readFileSync(options.meetingPath, 'utf8')
+    sidecarText = readFileSync(options.sidecarPath, 'utf8')
+  } catch { return { ok: false, status: 404, error: 'meeting_missing' } }
+  const section = readTranscriptSection(markdown)
+  if (section === null) return { ok: false, status: 409, error: 'no_transcript' }
+  const lines = parseTranscriptLines(section)
+  // Later edits first inside a line, so earlier offsets stay true.
+  const ordered = [...targets].sort((a, b) => a.line - b.line || b.offset - a.offset)
+  // A line still exactly as the run left it: every offset is exact. Otherwise each edit is
+  // found again by its words and their surroundings, and must be found exactly once.
+  const untouched = new Map<number, boolean>()
+  for (const edit of ordered) {
+    const line = lines.find(l => l.index === edit.line)
+    if (!line) return { ok: false, status: 409, error: 'stale' }
+    if (!untouched.has(line.index)) untouched.set(line.index, sha256(line.text) === edit.lineSha)
+    let at = -1
+    if (untouched.get(line.index) && line.text.slice(edit.offset, edit.offset + edit.replacement.length) === edit.replacement) at = edit.offset
+    else {
+      const needle = edit.before + edit.replacement + edit.after
+      const first = line.text.indexOf(needle)
+      if (first >= 0 && line.text.indexOf(needle, first + 1) < 0) at = first + edit.before.length
+    }
+    if (at < 0) return { ok: false, status: 409, error: 'stale' }
+    line.text = line.text.slice(0, at) + edit.original + line.text.slice(at + edit.replacement.length)
+  }
+  const transcript = joinTranscriptLines(lines)
+  const now = (options.now ?? (() => new Date()))().toISOString()
+  const live = edits.length - targets.length
+  try {
+    commitCleanTranscript({
+      meetingPath: options.meetingPath, sidecarPath: options.sidecarPath, markdown, sidecarText, transcript,
+      summary: { ...currentSummary(sidecarText), liveEdits: live, revertedAt: now },
+      write: options.write,
+    })
+  } catch (error) {
+    const code = error instanceof CleanupWriteError ? error.code : 'write_failed'
+    return { ok: false, status: code === 'changed_during_cleanup' ? 409 : 500, error: code }
+  }
+  appendLedger(options.sessionId, targets.map(t => ({ kind: 'revert' as const, editId: t.id, at: now })))
+  return { ok: true, reverted: targets.map(t => t.id) }
+}
+
+function currentSummary(sidecarText: string): Record<string, unknown> {
+  try {
+    const s = (JSON.parse(sidecarText) as Record<string, unknown>).transcriptCleanup
+    return s && typeof s === 'object' && !Array.isArray(s) ? s as Record<string, unknown> : {}
+  } catch { return {} }
+}
+
+/** The ledger as the review route shows it: runs, and each edit with whether it is still live. */
+export function ledgerView(sessionId: string): { runs: RunRow[]; edits: Array<EditRow & { reverted: boolean }>; unusable: number } {
+  const { rows, unusable } = readLedger(sessionId)
+  const reverted = new Set(rows.filter((r): r is RevertRow => r.kind === 'revert').map(r => r.editId))
+  const runs = new Map<string, RunRow>()
+  for (const r of rows) if (r.kind === 'run') runs.set(r.runId, r)
+  return {
+    runs: [...runs.values()],
+    edits: rows.filter((r): r is EditRow => r.kind === 'edit').map(e => ({ ...e, reverted: reverted.has(e.id) })),
+    unusable,
+  }
+}
+
+export const newRunId = (): string => `tc_${randomUUID().replace(/-/g, '').slice(0, 16)}`
+export const newEditId = (): string => `te_${randomUUID().replace(/-/g, '').slice(0, 16)}`