@gotcos/glasses-server 6.46.1 → 6.48.0

package/server/lib/meeting-corrections.ts

@@ -108,11 +108,35 @@ function sessionFile(sessionId: string): string | null {
   return resolve(path).startsWith(resolve(dir) + '/') ? path : null
 }
 
+export type CorrectionListener = (sessionId: string, row: CorrectionRow) => void
+
+const correctionListeners = new Set<CorrectionListener>()
+
+/**
+ * Be told when a speaker correction lands, wherever it came from.
+ *
+ * ONE PLACE, NOT THREE ROUTES. Relabel, confirm and de-attribute are three handlers today
+ * and a fourth is a plausible next release; a listener wired into each of them is a listener
+ * the fourth silently does not get. Every one of them closes its correction here, so this is
+ * where "a human changed who said what in this meeting" actually happens.
+ *
+ * A listener that throws is contained: a correction has already been recorded by the time
+ * this runs, and a downstream reaction failing must never make the correction look failed.
+ */
+export function onCorrectionApplied(listener: CorrectionListener): () => void {
+  correctionListeners.add(listener)
+  return () => { correctionListeners.delete(listener) }
+}
+
 /**
  * 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.
+ *
+ * Listeners run only AFTER the row is durable, and only when it was written: a
+ * subscriber told about a correction that never landed would act on a change
+ * that does not exist.
  */
 export function appendCorrection(sessionId: string, row: CorrectionRow): boolean {
   const path = sessionFile(sessionId)
@@ -120,10 +144,17 @@ export function appendCorrection(sessionId: string, row: CorrectionRow): boolean
   try {
     mkdirSync(dataPath(CORRECTIONS_DIR), { recursive: true, mode: 0o700 })
     appendFileSync(path, JSON.stringify(row) + '\n', { mode: 0o600 })
-    return true
   } catch {
     return false
   }
+  for (const listener of correctionListeners) {
+    try {
+      listener(sessionId, row)
+    } catch (error) {
+      console.warn('[meeting-corrections] listener failed:', error)
+    }
+  }
+  return true
 }
 
 export interface CorrectionReadResult {

package/server/lib/meeting-decisions.ts

@@ -0,0 +1,223 @@
+/**
+ * Decision files: one per action, the only thing the pipeline reads (6.47.0, WS4).
+ *
+ * WHY ONE FILE PER ACTION (v3 blocker 12). The first design had the server and the pipeline
+ * both writing `merge-decisions.json`. Two writers on one JSON file is a lost update waiting
+ * for a slow disk, and neither side can tell afterwards which write survived. Here the
+ * server writes `decisions/<actionId>.json` and nothing else touches it; the pipeline reads
+ * it, does its work, and reports through stdout. The server then writes the report back into
+ * the same file under `result`, so a later Revert can read what actually happened rather
+ * than what was intended.
+ *
+ * WHY THE RENDERED CONTENT LIVES HERE AND NOT IN `.actions.json`. The patch holds transcript
+ * text — the whole G2 capture, alternate transcripts. `.actions.json` is read on every
+ * status poll and every list; putting megabytes of transcript in it would make a status call
+ * cost a transcript read, and would put meeting content in a file whose purpose is
+ * bookkeeping. The action record names the decision; the decision holds the content.
+ *
+ * MODE 0600 IN A 0700 DIRECTORY. These files contain meeting transcripts.
+ */
+
+import { createHash } from 'node:crypto'
+import { existsSync, readFileSync, readdirSync, unlinkSync } from 'node:fs'
+import { join } from 'node:path'
+import { durableAtomicWriteFileSync } from './atomic-fs.js'
+import { importsRoot } from './imported-meeting-library.js'
+import type { PipelinePatch } from './meeting-engine/render.js'
+import { securePrivateDirectory } from './secure-user-config.js'
+
+export const DECISIONS_DIR_NAME = 'decisions'
+export const DECISION_SCHEMA = 1
+
+/** The prefix the pipeline prints its one report line with. */
+export const MERGE_RESULT_PREFIX = 'COS_MERGE_RESULT='
+
+/**
+ * Exit codes, as the pipeline command defines them (WS8b).
+ *
+ * 3 is NOT a failure. It means another pipeline process held the sync lock, which happens
+ * every hour when the scheduled sync runs; the action stays `pending` and is retried.
+ */
+export const PIPELINE_EXIT_LOCK_BUSY = 3
+/** The decision does not match the files on disk. Terminal: retrying cannot help. */
+export const PIPELINE_EXIT_DECISION_INVALID = 4
+/** A step failed part way, or the whole apply failed. Retried once. */
+export const PIPELINE_EXIT_PARTIAL_OR_FAILED = 5
+
+/** `a_` plus 16 hex. Enforced before the id reaches a path. */
+export const ACTION_ID_PATTERN = /^a_[0-9a-f]{16}$/
+
+export type MergeDecisionKind = 'merge' | 'split'
+
+export interface MergeDecisionG2Input {
+  kind: 'g2'
+  sessionId: string
+  /** Operations-relative path of the `.g2-chunks.json`. */
+  sidecarRelPath: string
+  /** Operations-relative path of the standalone G2 scribe, when one exists. */
+  scribeRelPath?: string
+  sha256: string
+}
+
+export interface MergeDecisionFirefliesInput {
+  kind: 'fireflies'
+  firefliesId: string
+  /** Operations-relative path of the Fireflies scribe the patch is spliced into. */
+  scribeRelPath: string
+  /** Operations-relative path of its `.fireflies.json` sentences sidecar. */
+  sidecarRelPath: string
+  sha256: string
+}
+
+export type MergeDecisionInput = MergeDecisionG2Input | MergeDecisionFirefliesInput
+
+export interface MergeDecisionResultOutput { path: string; sha256: string }
+export interface MergeDecisionResultArchive { original: string; archive: string; sha256: string }
+export interface MergeDecisionResultStamp { sidecar: string; blended_into: string }
+
+export type MergePipelineStatus = 'applied' | 'reverted' | 'partial' | 'failed'
+
+export interface MergePipelineResult {
+  schema: number
+  action_id: string
+  status: MergePipelineStatus
+  outputs: MergeDecisionResultOutput[]
+  archived: MergeDecisionResultArchive[]
+  retired: MergeDecisionResultArchive[]
+  stamps: MergeDecisionResultStamp[]
+  transcript_map: 'applied' | 'skipped'
+  step?: string
+  error_code?: string
+}
+
+export interface MergeDecision {
+  schema: number
+  actionId: string
+  kind: MergeDecisionKind
+  inputs: MergeDecisionInput[]
+  patch: PipelinePatch
+  speakerMap: PipelinePatch['speakerMap']
+  /** Operations-relative G2 scribe paths the pipeline archives and removes. */
+  retire: string[]
+  /** Written back by the server after the pipeline reports. */
+  result?: MergePipelineResult
+}
+
+export class DecisionError extends Error {
+  constructor(message: string, readonly code: string) {
+    super(message)
+    this.name = 'DecisionError'
+  }
+}
+
+export function assertActionId(actionId: string): string {
+  if (!ACTION_ID_PATTERN.test(actionId)) {
+    throw new DecisionError('Invalid action id', 'invalid_action_id')
+  }
+  return actionId
+}
+
+export function decisionsDir(root: string = importsRoot()): string {
+  return join(root, DECISIONS_DIR_NAME)
+}
+
+export function decisionPath(actionId: string, root?: string): string {
+  return join(decisionsDir(root), `${assertActionId(actionId)}.json`)
+}
+
+export function sha256OfFile(path: string): string | null {
+  try {
+    return createHash('sha256').update(readFileSync(path)).digest('hex')
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Does this patch add anything at all?
+ *
+ * A patch with no sections, no rows and no markers is a decision the pipeline can apply
+ * successfully while changing nothing: it archives the Fireflies scribe, retires the G2
+ * standalone, writes the same bytes back, and reports `applied`. The capture disappears from
+ * the list and nothing takes its place. That is the one outcome an additive design must not
+ * be able to produce, and the cheapest place to make it impossible is the writer, which
+ * every apply and every re-drive goes through.
+ */
+export function patchIsEmpty(patch: Pick<PipelinePatch, 'sections' | 'rows' | 'markers'> | null | undefined): boolean {
+  if (!patch) return true
+  return (patch.sections?.length ?? 0) === 0
+    && (patch.rows?.length ?? 0) === 0
+    && (patch.markers?.length ?? 0) === 0
+}
+
+/** Write one decision. The directory is created 0700 and the file 0600 every time. */
+export function writeDecision(decision: MergeDecision, root?: string): string {
+  if (patchIsEmpty(decision.patch)) {
+    throw new DecisionError('A merge decision must add something to the scribe', 'patch_empty')
+  }
+  const path = decisionPath(decision.actionId, root)
+  securePrivateDirectory(decisionsDir(root))
+  durableAtomicWriteFileSync(path, `${JSON.stringify(decision, null, 2)}\n`, { mode: 0o600 })
+  return path
+}
+
+export function readDecision(actionId: string, root?: string): MergeDecision | null {
+  const path = decisionPath(actionId, root)
+  if (!existsSync(path)) return null
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf8')) as Partial<MergeDecision>
+    if (parsed?.schema !== DECISION_SCHEMA || parsed.actionId !== actionId) return null
+    return parsed as MergeDecision
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Record what the pipeline reported, in the decision it was given.
+ *
+ * Revert reads this, not the action record: the archive paths and their sha256 are what let
+ * a restore prove it is putting back the same bytes that were moved aside.
+ */
+export function writeDecisionResult(actionId: string, result: MergePipelineResult, root?: string): boolean {
+  const decision = readDecision(actionId, root)
+  if (!decision) return false
+  writeDecision({ ...decision, result }, root)
+  return true
+}
+
+export function deleteDecision(actionId: string, root?: string): void {
+  try { unlinkSync(decisionPath(actionId, root)) } catch { /* already gone */ }
+}
+
+export function listDecisionIds(root?: string): string[] {
+  try {
+    return readdirSync(decisionsDir(root))
+      .filter(name => name.endsWith('.json'))
+      .map(name => name.slice(0, -'.json'.length))
+      .filter(id => ACTION_ID_PATTERN.test(id))
+      .sort()
+  } catch {
+    return []
+  }
+}
+
+/**
+ * Is this a report the server may act on?
+ *
+ * Deliberately strict about the three fields a Revert depends on and permissive about the
+ * rest: a pipeline that grows a field must not make every apply unreadable, but one that
+ * omits `archived` has not told us how to undo what it did.
+ */
+export function isMergePipelineResult(value: unknown): value is MergePipelineResult {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false
+  const row = value as Record<string, unknown>
+  if (row.schema !== DECISION_SCHEMA) return false
+  if (typeof row.action_id !== 'string' || !ACTION_ID_PATTERN.test(row.action_id)) return false
+  if (row.status !== 'applied' && row.status !== 'reverted' && row.status !== 'partial' && row.status !== 'failed') return false
+  if (row.transcript_map !== 'applied' && row.transcript_map !== 'skipped') return false
+  for (const key of ['outputs', 'archived', 'retired', 'stamps']) {
+    if (!Array.isArray(row[key])) return false
+  }
+  return true
+}

package/server/lib/meeting-engine/align.ts

@@ -0,0 +1,167 @@
+/**
+ * Fine alignment between a G2 capture and a Fireflies transcript (6.47.0, WS3).
+ *
+ * PURE. No filesystem, no network, no clock.
+ *
+ * Alignment exists ONLY to decide whether per-sentence relabelling is allowed. A capture
+ * that fails to align is still attached to the merged record in full — nothing is dropped,
+ * the Fireflies labels simply stand.
+ *
+ * WHY SENTENCE STARTS. Fireflies gives an exact `start_time` per sentence, while word
+ * times inside a sentence are interpolated by this engine. Anchoring on the first trigram
+ * of a sentence measures against a real timestamp; anchoring on arbitrary words measures
+ * against the interpolation and inflates the spread. Measured on 10 real pairs, sentence
+ * starts land at MAD 1.5 to 3.3 s.
+ */
+
+import {
+  type FirefliesSentenceInput,
+  type TimedWord,
+  firefliesTimedWords,
+  median,
+  medianAbsoluteDeviation,
+  normalizeWords,
+  trigramKey,
+  uniqueTrigrams,
+} from './evidence.js'
+
+/** How far an anchor's offset may sit from the coarse offset before it is a different conversation. */
+export const ALIGN_BAND_S = 300
+
+/** Anchors needed before the offsets are a measurement rather than a coincidence. */
+export const ALIGN_MIN_ANCHORS = 8
+
+/**
+ * Spread allowed around the median offset, in ms.
+ *
+ * Chosen from the same 10 pairs it is measured on, which is a real weakness and is why
+ * the share gate and the 0.55 similarity floor, not this threshold, are what keep a wrong
+ * name off a sentence.
+ */
+export const ALIGN_MAX_MAD_MS = 3500
+
+/** Clock drift is not constant over an hour, so the offset is re-measured per window. */
+export const ALIGN_WINDOW_MS = 120_000
+
+/** A window with fewer anchors than this has no offset of its own and inherits one. */
+export const ALIGN_WINDOW_MIN_ANCHORS = 3
+
+export type AttributionState = 'aligned' | 'unaligned' | 'capture_only'
+
+export interface AlignmentAnchor {
+  /** Milliseconds from the G2 capture start. */
+  g2Ms: number
+  /** `firefliesMs - g2Ms`. */
+  offsetMs: number
+}
+
+export interface Alignment {
+  aligned: boolean
+  anchors: number
+  /** Null when there were too few anchors to measure. */
+  madMs: number | null
+  /** Median offset across all anchors. Null when unmeasured. */
+  offsetMs: number | null
+  samples: AlignmentAnchor[]
+  windows: Map<number, number>
+}
+
+/**
+ * Anchors: Fireflies sentence-initial trigrams that are unique in BOTH transcripts.
+ *
+ * Unique on both sides for the same reason pairing needs it — a phrase that recurs cannot
+ * say which moment this is — and sentence-initial so the Fireflies time is exact.
+ */
+export function sentenceStartAnchors(
+  g2Words: readonly TimedWord[],
+  sentences: readonly FirefliesSentenceInput[],
+  coarseOffsetMs: number,
+  bandS: number = ALIGN_BAND_S,
+): AlignmentAnchor[] {
+  const g2Trigrams = uniqueTrigrams(g2Words)
+  const firefliesTrigrams = uniqueTrigrams(firefliesTimedWords(sentences))
+  const anchors: AlignmentAnchor[] = []
+  for (const sentence of sentences) {
+    const tokens = normalizeWords(sentence.text)
+    if (tokens.length < 3) continue
+    const key = trigramKey(tokens[0], tokens[1], tokens[2])
+    if (!firefliesTrigrams.has(key)) continue
+    const g2Ms = g2Trigrams.get(key)
+    if (g2Ms === undefined) continue
+    const firefliesMs = (Number(sentence.start_time ?? 0) || 0) * 1000
+    const offsetMs = firefliesMs - g2Ms
+    if (Math.abs(offsetMs - coarseOffsetMs) <= bandS * 1000) anchors.push({ g2Ms, offsetMs })
+  }
+  return anchors
+}
+
+/**
+ * Per-window offsets over G2 time.
+ *
+ * A sparse window inherits from the nearest window that has enough anchors, earlier one
+ * first on a tie. Inheriting a neighbour keeps a quiet stretch on its neighbours' drift
+ * instead of snapping it back to the whole-meeting median, which is the larger error by
+ * the end of a long call.
+ */
+export function windowOffsets(
+  anchors: readonly AlignmentAnchor[],
+  windowMs: number = ALIGN_WINDOW_MS,
+  minAnchors: number = ALIGN_WINDOW_MIN_ANCHORS,
+): Map<number, number> {
+  const byWindow = new Map<number, number[]>()
+  for (const anchor of anchors) {
+    const index = Math.floor(anchor.g2Ms / windowMs)
+    const bucket = byWindow.get(index)
+    if (bucket) bucket.push(anchor.offsetMs)
+    else byWindow.set(index, [anchor.offsetMs])
+  }
+  const resolved = new Map<number, number>()
+  for (const [index, offsets] of byWindow) {
+    if (offsets.length >= minAnchors) resolved.set(index, median(offsets))
+  }
+  if (resolved.size === 0) return resolved
+  for (const index of byWindow.keys()) {
+    if (resolved.has(index)) continue
+    let best: number | null = null
+    let bestDistance = Infinity
+    for (const candidate of resolved.keys()) {
+      const distance = Math.abs(candidate - index)
+      if (distance < bestDistance || (distance === bestDistance && best !== null && candidate < best)) {
+        best = candidate
+        bestDistance = distance
+      }
+    }
+    if (best !== null) resolved.set(index, resolved.get(best)!)
+  }
+  return resolved
+}
+
+/** Measure the alignment of one capture against one transcript. */
+export function alignRecording(
+  g2Words: readonly TimedWord[],
+  sentences: readonly FirefliesSentenceInput[],
+  coarseOffsetMs: number,
+): Alignment {
+  const samples = sentenceStartAnchors(g2Words, sentences, coarseOffsetMs)
+  if (samples.length < ALIGN_MIN_ANCHORS) {
+    return { aligned: false, anchors: samples.length, madMs: null, offsetMs: null, samples, windows: new Map() }
+  }
+  const offsets = samples.map(s => s.offsetMs)
+  const offsetMs = median(offsets)
+  const madMs = medianAbsoluteDeviation(offsets)
+  return {
+    aligned: madMs <= ALIGN_MAX_MAD_MS,
+    anchors: samples.length,
+    madMs,
+    offsetMs,
+    samples,
+    windows: windowOffsets(samples),
+  }
+}
+
+/** The offset to use for a moment in G2 time. */
+export function offsetAt(alignment: Alignment, g2Ms: number, windowMs: number = ALIGN_WINDOW_MS): number {
+  const fallback = alignment.offsetMs ?? 0
+  if (alignment.windows.size === 0) return fallback
+  return alignment.windows.get(Math.floor(g2Ms / windowMs)) ?? fallback
+}