@xopcai/xopc 0.0.389 → 0.0.390

package/dist/src/discussions/processing.js

@@ -0,0 +1,125 @@
+import { getSqliteDatabase, init_transaction, runSqliteWriteTransaction } from "../storage/sqlite/transaction.js";
+import { getDiscussionCapture, updateDiscussionCapture } from "./repository.js";
+import { randomUUID } from "node:crypto";
+//#region src/discussions/processing.ts
+init_transaction();
+const LEASE_MS = 6e4;
+const PROCESSING_MAX_ATTEMPTS = 3;
+function getProcessingRun(id) {
+	return getSqliteDatabase().prepare("SELECT * FROM discussion_processing WHERE discussion_id=?").get(id);
+}
+/** A new original-audio generation leaves published transcript/summary revisions untouched. */
+function createProcessingRun(capture, forceAudio = false) {
+	return runSqliteWriteTransaction((db) => {
+		db.prepare("DELETE FROM discussion_processing WHERE discussion_id=?").run(capture.id);
+		db.prepare(`INSERT INTO discussion_processing (discussion_id, run_id, audio_sha256, base_transcript_revision, force_audio)
+      VALUES (?, ?, ?, ?, ?)`).run(capture.id, randomUUID(), capture.audioSha256 ?? null, capture.transcriptRevision, forceAudio ? 1 : 0);
+		return getProcessingRun(capture.id);
+	});
+}
+function ensureProcessingRun(capture, alignSource = false) {
+	const run = getProcessingRun(capture.id);
+	return !run || alignSource && (run.audio_sha256 !== (capture.audioSha256 ?? null) || run.base_transcript_revision !== capture.transcriptRevision) ? createProcessingRun(capture, run?.force_audio === 1) : run;
+}
+function resetProcessingRetry(id) {
+	getSqliteDatabase().prepare("UPDATE discussion_processing SET retry_stage=NULL, attempt_count=0, next_attempt_at=NULL WHERE discussion_id=?").run(id);
+}
+function processingProgress(id) {
+	const run = getProcessingRun(id);
+	if (!run) return void 0;
+	const row = getSqliteDatabase().prepare(`SELECT COUNT(*) count, COALESCE(SUM(ended_at_ms-started_at_ms),0) duration
+    FROM discussion_transcription_checkpoints WHERE run_id=?`).get(run.run_id);
+	return {
+		fromAudio: run.force_audio === 1,
+		completedChunks: row.count,
+		transcribedMs: Math.round(row.duration),
+		attemptCount: run.attempt_count,
+		maxAttempts: 3,
+		...run.next_attempt_at !== null ? { nextAttemptAt: run.next_attempt_at } : {}
+	};
+}
+function claimSealingCapture(owner, now) {
+	return runSqliteWriteTransaction((db) => {
+		const row = db.prepare(`SELECT d.id FROM discussion_captures d LEFT JOIN discussion_processing p ON p.discussion_id=d.id
+      WHERE d.status IN ('stopping','sealing') AND (p.next_attempt_at IS NULL OR p.next_attempt_at<=?)
+      AND (p.lease_until IS NULL OR p.lease_until<=?) ORDER BY d.updated_at, d.id LIMIT 1`).get(now, Date.now());
+		if (!row) return null;
+		const capture = getDiscussionCapture(row.id);
+		ensureProcessingRun(capture, true);
+		db.prepare("UPDATE discussion_processing SET lease_owner=?, lease_until=? WHERE discussion_id=?").run(owner, Date.now() + LEASE_MS, row.id);
+		return capture;
+	});
+}
+function renewSealingLease(id, owner) {
+	return getSqliteDatabase().prepare(`UPDATE discussion_processing SET lease_until=? WHERE discussion_id=? AND lease_owner=? AND lease_until>?`).run(Date.now() + LEASE_MS, id, owner, Date.now()).changes === 1;
+}
+function releaseSealingLease(id, owner) {
+	getSqliteDatabase().prepare("UPDATE discussion_processing SET lease_owner=NULL,lease_until=NULL WHERE discussion_id=? AND lease_owner=?").run(id, owner);
+}
+function assertProcessingRun(run, owner, signal) {
+	signal.throwIfAborted();
+	const current = getDiscussionCapture(run.discussion_id);
+	if (!current || current.status !== "sealing" || current.audioDeletedAt || current.audioSha256 !== (run.audio_sha256 ?? void 0) || current.transcriptRevision !== run.base_transcript_revision || getProcessingRun(current.id)?.run_id !== run.run_id || !renewSealingLease(current.id, owner)) throw new Error("Transcription processing lease or source revision changed");
+}
+function readCheckpoint(runId, start, end) {
+	const row = getSqliteDatabase().prepare("SELECT result_json FROM discussion_transcription_checkpoints WHERE run_id=? AND started_at_ms=? AND ended_at_ms=?").get(runId, start, end);
+	return row ? JSON.parse(row.result_json) : void 0;
+}
+function saveCheckpoint(runId, start, end, result) {
+	getSqliteDatabase().prepare(`INSERT INTO discussion_transcription_checkpoints (run_id,started_at_ms,ended_at_ms,result_json,created_at) VALUES (?,?,?,?,?)`).run(runId, start, end, JSON.stringify(result), Date.now());
+}
+function isTransientProcessingError(error, depth = 0) {
+	if (depth > 3) return false;
+	const item = error;
+	const status = item?.status ?? item?.statusCode;
+	if (status !== void 0) return [
+		408,
+		425,
+		429
+	].includes(status) || status >= 500;
+	const text = error instanceof Error ? `${error.name} ${error.message}` : String(error);
+	if (/not configured|no model configured|no api key|invalid.*key|unauthorized|forbidden|authentication|unsupported|invalid.*(audio|time range)|no text|audio.*missing|checksum mismatch|transcript.*missing|ENOENT|lease|revision changed/i.test(text)) return false;
+	if (item?.reasonCode === "not_configured" || item?.reasonCode === "unsupported_format") return false;
+	if (item?.reasonCode === "timeout" || item?.reasonCode === "provider_error") return true;
+	if (/timeout|timed out|rate.?limit|temporar|unavailable|fetch failed|network|connection error|ECONN|ETIMEDOUT|EAI_AGAIN|socket|overload|internal server|server error|try again|invalid discussion organization|invalid evidence|truncated|\b(408|429|5\d\d)\b|SyntaxError/i.test(text)) return true;
+	return item?.cause !== void 0 && item.cause !== error ? isTransientProcessingError(item.cause, depth + 1) : false;
+}
+/** Persist bounded retries instead of sleeping inside a worker and blocking other recordings. */
+function failOrRetryProcessing(capture, stage, error) {
+	return runSqliteWriteTransaction((db) => {
+		const current = getDiscussionCapture(capture.id);
+		if (!current || current.status !== (stage === "organization" ? "organizing" : "sealing")) return null;
+		const run = ensureProcessingRun(current);
+		const attempts = (run.retry_stage === stage ? run.attempt_count : 0) + 1;
+		const retry = attempts < 3 && isTransientProcessingError(error);
+		const next = retry ? Date.now() + 5e3 * 4 ** (attempts - 1) : null;
+		db.prepare("UPDATE discussion_processing SET retry_stage=?,attempt_count=?,next_attempt_at=? WHERE discussion_id=?").run(stage, attempts, next, capture.id);
+		return updateDiscussionCapture(capture.id, {
+			status: retry ? current.status : "needs_attention",
+			failureStage: stage,
+			failureCode: retry ? "processing_retry_scheduled" : `${stage}_failed`,
+			failureMessage: (error instanceof Error ? error.message : String(error)).slice(0, 1e3)
+		}, [current.status]);
+	});
+}
+/** Race the signal as well as passing it downstream, so an uncooperative provider cannot hold the worker. */
+async function withProcessingDeadline(work, parent, timeoutMs) {
+	const timeout = new AbortController();
+	const timer = setTimeout(() => timeout.abort(/* @__PURE__ */ new Error("Processing request timed out")), timeoutMs);
+	timer.unref();
+	const signal = AbortSignal.any([parent, timeout.signal]);
+	let abort;
+	try {
+		signal.throwIfAborted();
+		const aborted = new Promise((_resolve, reject) => {
+			abort = () => reject(signal.reason);
+			signal.addEventListener("abort", abort, { once: true });
+		});
+		return await Promise.race([work(signal), aborted]);
+	} finally {
+		clearTimeout(timer);
+		if (abort) signal.removeEventListener("abort", abort);
+	}
+}
+//#endregion
+export { PROCESSING_MAX_ATTEMPTS, assertProcessingRun, claimSealingCapture, createProcessingRun, ensureProcessingRun, failOrRetryProcessing, getProcessingRun, isTransientProcessingError, processingProgress, readCheckpoint, releaseSealingLease, renewSealingLease, resetProcessingRetry, saveCheckpoint, withProcessingDeadline };

package/dist/src/discussions/recording.js

@@ -1,9 +1,10 @@
 import { getSqliteDatabase, init_transaction, runSqliteWriteTransaction } from "../storage/sqlite/transaction.js";
-import { DISCUSSION_MAX_DURATION_MS } from "../../packages/gateway-contract/src/discussions.js";
+import { DISCUSSION_MAX_SAVED_DURATION_MS } from "../../packages/gateway-contract/src/discussions.js";
 import { init_src } from "../../packages/gateway-contract/src/index.js";
 import { resolveNoteMediaDir } from "../notes/paths.js";
 import { DiscussionServiceError } from "./errors.js";
 import { getDiscussionCapture, updateDiscussionCapture } from "./repository.js";
+import { pcmEpoch, probeMediaEpoch } from "./media-timeline.js";
 import { decodeWavToMonoFloat32 } from "../voice/audio/wav.js";
 import { forEachNormalizedAudioSegment } from "../voice/audio/normalize.js";
 import { join } from "node:path";
@@ -71,6 +72,20 @@ async function saveRecordingChunk(capture, sequence, sha256, body) {
 }
 function validateRecordingManifest(capture, input) {
 	if (input.containerMode !== void 0 && (input.containerMode !== "independent_wav" || input.mimeType !== "audio/wav")) throw invalid("Unsupported recording container");
+	if (input.events !== void 0 && (!Array.isArray(input.events) || input.events.length > 1e3 || input.events.some((event) => !event || !Number.isSafeInteger(event.recordedAt) || event.recordedAt < 0 || !Number.isSafeInteger(event.savedMs) || event.savedMs < 0 || event.savedMs > 7205e3 || ![
+		"start",
+		"resume",
+		"interrupted",
+		"seal"
+	].includes(event.kind)))) throw invalid("Invalid recording events");
+	if (input.epochs !== void 0) {
+		if (input.containerMode || !Array.isArray(input.epochs) || input.epochs.length < 2 || input.epochs.length > 100 || input.epochs.some((epoch, index) => !epoch || !Number.isSafeInteger(epoch.firstChunk) || (index === 0 ? epoch.firstChunk !== 0 : epoch.firstChunk <= input.epochs[index - 1].firstChunk) || epoch.firstChunk >= input.chunkCount || !Number.isSafeInteger(epoch.startedAt) || epoch.startedAt < 0 || epoch.previousEndedAt !== void 0 && (!Number.isSafeInteger(epoch.previousEndedAt) || epoch.previousEndedAt < 0) || typeof epoch.mimeType !== "string" || ![
+			"audio/webm",
+			"audio/mp4",
+			"audio/ogg",
+			"audio/wav"
+		].includes(epoch.mimeType.split(";")[0]))) throw invalid("Invalid recording epochs");
+	}
 	const mimeType = input.mimeType.split(";")[0];
 	if (![
 		"audio/wav",
@@ -89,48 +104,52 @@ async function completeRecording(capture, input, notes, assertLease, signal) {
 	const target = join(directory(capture), `assembled-${randomUUID()}`);
 	const file = await open(target, "w");
 	const hash = createHash("sha256");
+	let epochs;
 	try {
 		try {
-			if (input.containerMode === "independent_wav") {
-				const samples = chunks.reduce((total, chunk) => total + (chunk.bytes - 44) / 2, 0);
-				if (!Number.isSafeInteger(samples) || samples <= 0 || samples > 16e3 * 72e5 / 1e3) throw invalid("Invalid PCM recording duration");
-				const header = recordingWavHeader(samples);
-				hash.update(header);
-				await file.writeFile(header);
-			}
-			for (const chunk of chunks) {
-				const chunkHash = createHash("sha256");
-				let bytes = 0;
-				try {
-					if (input.containerMode === "independent_wav") {
-						signal.throwIfAborted();
-						const buffers = [];
+			if (input.epochs) epochs = await assembleEpochs(capture, input, notes, file, signal, assertLease);
+			else {
+				if (input.containerMode === "independent_wav") {
+					const samples = chunks.reduce((total, chunk) => total + (chunk.bytes - 44) / 2, 0);
+					if (!Number.isSafeInteger(samples) || samples <= 0 || samples > 16e3 * 7205e3 / 1e3) throw invalid("Invalid PCM recording duration");
+					const header = recordingWavHeader(samples);
+					hash.update(header);
+					await file.writeFile(header);
+				}
+				for (const chunk of chunks) {
+					const chunkHash = createHash("sha256");
+					let bytes = 0;
+					try {
+						if (input.containerMode === "independent_wav") {
+							signal.throwIfAborted();
+							const buffers = [];
+							for await (const buffer of createReadStream(join(directory(capture), String(chunk.sequence)))) {
+								signal.throwIfAborted();
+								bytes += buffer.length;
+								if (bytes > 8388608 || bytes > chunk.bytes) throw invalid("Stored WAV chunk is corrupt");
+								buffers.push(buffer);
+							}
+							const data = Buffer.concat(buffers, bytes);
+							if (data.length !== chunk.bytes || data.length <= 44 || data.length > 8388608 || data.length % 2 !== 0 || !data.subarray(0, 44).equals(recordingWavHeader((data.length - 44) / 2)) || createHash("sha256").update(data).digest("hex") !== chunk.sha256) throw invalid("Stored WAV chunk is corrupt");
+							hash.update(data.subarray(44));
+							await file.writeFile(data.subarray(44));
+							continue;
+						}
 						for await (const buffer of createReadStream(join(directory(capture), String(chunk.sequence)))) {
 							signal.throwIfAborted();
+							hash.update(buffer);
+							chunkHash.update(buffer);
 							bytes += buffer.length;
-							if (bytes > 8388608 || bytes > chunk.bytes) throw invalid("Stored WAV chunk is corrupt");
-							buffers.push(buffer);
+							await file.writeFile(buffer);
 						}
-						const data = Buffer.concat(buffers, bytes);
-						if (data.length !== chunk.bytes || data.length <= 44 || data.length > 8388608 || data.length % 2 !== 0 || !data.subarray(0, 44).equals(recordingWavHeader((data.length - 44) / 2)) || createHash("sha256").update(data).digest("hex") !== chunk.sha256) throw invalid("Stored WAV chunk is corrupt");
-						hash.update(data.subarray(44));
-						await file.writeFile(data.subarray(44));
-						continue;
-					}
-					for await (const buffer of createReadStream(join(directory(capture), String(chunk.sequence)))) {
-						signal.throwIfAborted();
-						hash.update(buffer);
-						chunkHash.update(buffer);
-						bytes += buffer.length;
-						await file.writeFile(buffer);
-					}
-					if (bytes !== chunk.bytes || chunkHash.digest("hex") !== chunk.sha256) throw invalid("Stored recording chunk is corrupt");
-				} catch (error) {
-					if (!signal.aborted && (error instanceof DiscussionServiceError || error.code === "ENOENT")) {
-						assertLease();
-						getSqliteDatabase().prepare("DELETE FROM discussion_recording_chunks WHERE discussion_id=? AND sequence=?").run(capture.id, chunk.sequence);
+						if (bytes !== chunk.bytes || chunkHash.digest("hex") !== chunk.sha256) throw invalid("Stored recording chunk is corrupt");
+					} catch (error) {
+						if (!signal.aborted && (error instanceof DiscussionServiceError || error.code === "ENOENT")) {
+							assertLease();
+							getSqliteDatabase().prepare("DELETE FROM discussion_recording_chunks WHERE discussion_id=? AND sequence=?").run(capture.id, chunk.sequence);
+						}
+						throw error;
 					}
-					throw error;
 				}
 			}
 			await file.sync();
@@ -141,7 +160,7 @@ async function completeRecording(capture, input, notes, assertLease, signal) {
 		await forEachNormalizedAudioSegment({
 			filePath: target,
 			segmentSeconds: 30,
-			maxDurationSeconds: DISCUSSION_MAX_DURATION_MS / 1e3,
+			maxDurationSeconds: DISCUSSION_MAX_SAVED_DURATION_MS / 1e3,
 			signal: AbortSignal.any([signal, AbortSignal.timeout(18e4)])
 		}, async (buffer) => {
 			durationMs += decodeWavToMonoFloat32(buffer).durationSeconds * 1e3;
@@ -150,11 +169,37 @@ async function completeRecording(capture, input, notes, assertLease, signal) {
 		const latest = getDiscussionCapture(capture.id);
 		if (!latest || latest.status === "cancelled" || latest.audioDeletedAt) throw new DiscussionServiceError("conflict", "Recording was deleted or cancelled");
 		assertLease();
-		const audioSha256 = hash.digest("hex");
+		const audioSha256 = input.epochs ? await hashFile(target, signal) : hash.digest("hex");
+		const outputMime = input.epochs ? "audio/wav" : input.mimeType;
+		const timeline = {
+			primary: input.epochs || input.containerMode === "independent_wav" || outputMime.includes("wav") ? "pcm" : "encoded",
+			epochs: epochs ?? [outputMime.includes("wav") ? pcmEpoch(durationMs) : await probeMediaEpoch(target, durationMs, 0, signal)]
+		};
+		if (input.events?.length) {
+			const events = await notes.addAttachment(capture.noteId, {
+				name: `recording-events-${capture.id}.json`,
+				buffer: Buffer.from(JSON.stringify({
+					version: 1,
+					discussionId: capture.id,
+					events: input.events
+				})),
+				mimeType: "application/json",
+				retainWithoutReference: true
+			}, `meeting-events:${capture.id}`);
+			if (!events) throw new Error("Discussion note is missing");
+			const saved = await notes.getAttachmentPath(capture.noteId, events.id);
+			if (!saved) throw new Error("Saved recording events are missing");
+			const durable = await open(saved.filePath, "r");
+			try {
+				await durable.sync();
+			} finally {
+				await durable.close();
+			}
+		}
 		const attachment = await notes.addAttachment(capture.noteId, {
-			name: input.fileName.trim().slice(0, 200) || "meeting.webm",
+			name: input.epochs ? "meeting-resumed.wav" : input.fileName.trim().slice(0, 200) || "meeting.webm",
 			buffer: { filePath: target },
-			mimeType: input.mimeType,
+			mimeType: outputMime,
 			duration: Math.round(durationMs / 1e3),
 			retainWithoutReference: true
 		}, `meeting-recording:${capture.id}`);
@@ -175,13 +220,14 @@ async function completeRecording(capture, input, notes, assertLease, signal) {
 		}
 		const updated = runSqliteWriteTransaction(() => {
 			assertLease();
+			getSqliteDatabase().prepare("INSERT OR REPLACE INTO discussion_media_timeline (discussion_id,audio_sha256,timeline_json) VALUES (?,?,?)").run(capture.id, audioSha256, JSON.stringify(timeline));
 			return updateDiscussionCapture(capture.id, {
 				status: "stopping",
 				audioAttachmentId: attachment.id,
-				mimeType: input.mimeType,
+				mimeType: outputMime,
 				audioSha256,
 				durationMs: Math.round(durationMs),
-				audioSizeBytes: chunks.reduce((sum, chunk) => sum + chunk.bytes, 0)
+				audioSizeBytes: attachment.size
 			}, [
 				"recording",
 				"stopping",
@@ -195,6 +241,120 @@ async function completeRecording(capture, input, notes, assertLease, signal) {
 		await rm(target, { force: true });
 	}
 }
+async function hashFile(path, signal) {
+	const hash = createHash("sha256");
+	for await (const buffer of createReadStream(path)) {
+		signal.throwIfAborted();
+		hash.update(buffer);
+	}
+	return hash.digest("hex");
+}
+/** Independent recorder containers stay immutable; only decoded PCM is joined for playback/STT. */
+async function assembleEpochs(capture, input, notes, output, signal, assertLease) {
+	const epochs = [];
+	const chunks = listRecordingChunks(capture.id);
+	const sources = [];
+	let samples = 0;
+	await output.writeFile(recordingWavHeader(0));
+	for (const [index, epoch] of input.epochs.entries()) {
+		const path = join(directory(capture), `epoch-${randomUUID()}`);
+		const source = await open(path, "wx");
+		try {
+			try {
+				const end = input.epochs[index + 1]?.firstChunk ?? chunks.length;
+				for (const chunk of chunks.slice(epoch.firstChunk, end)) try {
+					let bytes = 0;
+					const hash = createHash("sha256");
+					for await (const buffer of createReadStream(join(directory(capture), String(chunk.sequence)))) {
+						signal.throwIfAborted();
+						bytes += buffer.length;
+						hash.update(buffer);
+						await source.writeFile(buffer);
+					}
+					if (bytes !== chunk.bytes || hash.digest("hex") !== chunk.sha256) throw invalid("Stored recording chunk is corrupt");
+				} catch (error) {
+					if (!signal.aborted && (error instanceof DiscussionServiceError || error.code === "ENOENT")) {
+						assertLease();
+						getSqliteDatabase().prepare("DELETE FROM discussion_recording_chunks WHERE discussion_id=? AND sequence=?").run(capture.id, chunk.sequence);
+					}
+					throw error;
+				}
+				await source.sync();
+			} finally {
+				await source.close();
+			}
+			let epochSamples = 0;
+			await forEachNormalizedAudioSegment({
+				filePath: path,
+				segmentSeconds: 30,
+				maxDurationSeconds: DISCUSSION_MAX_SAVED_DURATION_MS / 1e3,
+				signal: AbortSignal.any([signal, AbortSignal.timeout(18e4)])
+			}, async (buffer) => {
+				const audio = decodeWavToMonoFloat32(buffer);
+				const pcm = Buffer.alloc(audio.samples.length * 2);
+				for (let i = 0; i < audio.samples.length; i++) pcm.writeInt16LE(Math.max(-32768, Math.min(32767, Math.round(audio.samples[i] * 32768))), i * 2);
+				samples += audio.samples.length;
+				epochSamples += audio.samples.length;
+				if (samples > 16e3 * 7205e3 / 1e3) throw invalid("Recording exceeds duration limit");
+				await output.writeFile(pcm);
+			});
+			if (!epochSamples) throw invalid("Recording epoch has no decodable audio");
+			const epochDuration = epochSamples / 16;
+			epochs.push(epoch.mimeType.includes("wav") ? pcmEpoch(epochDuration, (samples - epochSamples) / 16) : await probeMediaEpoch(path, epochDuration, (samples - epochSamples) / 16, signal));
+			assertLease();
+			signal.throwIfAborted();
+			const sha256 = await hashFile(path, signal);
+			const extension = epoch.mimeType.includes("mp4") ? "m4a" : epoch.mimeType.includes("ogg") ? "ogg" : epoch.mimeType.includes("wav") ? "wav" : "webm";
+			const attachment = await notes.addAttachment(capture.noteId, {
+				name: `recording-part-${capture.id}-${index + 1}.${extension}`,
+				buffer: { filePath: path },
+				mimeType: epoch.mimeType,
+				retainWithoutReference: true
+			}, `meeting-source:${capture.id}:${index}:${sha256}`);
+			if (!attachment) throw new Error("Discussion note is missing");
+			const stored = await notes.getAttachmentPath(capture.noteId, attachment.id);
+			if (!stored) throw new Error("Saved recording source is missing");
+			const durable = await open(stored.filePath, "r");
+			try {
+				await durable.sync();
+			} finally {
+				await durable.close();
+			}
+			sources.push({
+				...epoch,
+				attachmentId: attachment.id,
+				sha256,
+				durationMs: epochSamples / 16
+			});
+		} finally {
+			await rm(path, { force: true });
+		}
+	}
+	await output.write(recordingWavHeader(samples), 0, 44, 0);
+	assertLease();
+	signal.throwIfAborted();
+	const manifestAttachment = await notes.addAttachment(capture.noteId, {
+		name: `recording-sources-${capture.id}.json`,
+		buffer: Buffer.from(JSON.stringify({
+			version: 1,
+			discussionId: capture.id,
+			noteId: capture.noteId,
+			sources
+		})),
+		mimeType: "application/json",
+		retainWithoutReference: true
+	}, `meeting-sources:${capture.id}`);
+	if (!manifestAttachment) throw new Error("Discussion note is missing");
+	const manifestFile = await notes.getAttachmentPath(capture.noteId, manifestAttachment.id);
+	if (!manifestFile) throw new Error("Saved recording manifest is missing");
+	const durable = await open(manifestFile.filePath, "r");
+	try {
+		await durable.sync();
+	} finally {
+		await durable.close();
+	}
+	return epochs;
+}
 function recordingWavHeader(samples) {
 	const header = Buffer.alloc(44);
 	header.write("RIFF");

package/dist/src/discussions/recordingJobs.js

@@ -27,6 +27,8 @@ function submitRecordingJob(discussionId, input) {
 		mimeType: input.mimeType,
 		fileName: input.fileName,
 		lastSequence: input.lastSequence,
+		...input.events ? { events: input.events } : {},
+		...input.epochs ? { epochs: input.epochs } : {},
 		...input.containerMode ? { containerMode: input.containerMode } : {}
 	});
 	return runSqliteWriteTransaction((db) => {

package/dist/src/discussions/repository.js

@@ -170,7 +170,8 @@ function claimNextDiscussionCapture(owner, now = Date.now(), leaseMs = 5 * 6e4)
 	return runSqliteWriteTransaction((db) => {
 		const row = db.prepare(`SELECT * FROM discussion_captures
       WHERE status='organizing' AND (work_lease_owner IS NULL OR work_lease_expires_at <= ?)
-      ORDER BY updated_at ASC LIMIT 1`).get(now);
+      AND NOT EXISTS (SELECT 1 FROM discussion_processing p WHERE p.discussion_id=discussion_captures.id AND p.next_attempt_at>?)
+      ORDER BY updated_at ASC LIMIT 1`).get(now, now);
 		if (!row) return null;
 		return db.prepare(`UPDATE discussion_captures SET work_lease_owner=?, work_lease_expires_at=?, updated_at=?
       WHERE id=? AND status='organizing' AND (work_lease_owner IS NULL OR work_lease_expires_at <= ?)`).run(owner, now + leaseMs, now, row.id, now).changes ? getDiscussionCapture(row.id) : null;
@@ -226,7 +227,8 @@ function completeDiscussionTranscriptSegment(discussionId, sequence, owner, text
       raw_text=?, display_text=?, provider=?, language=?, confidence=?, audio_blob=NULL,
       lease_owner=NULL, lease_expires_at=NULL, next_attempt_at=NULL, last_error=NULL,
       revision=revision+1, updated_at=? WHERE discussion_id=? AND sequence=?
-      AND status='transcribing' AND lease_owner=?`).run(text, text, provider, language ?? null, confidence ?? null, now, discussionId, sequence, owner).changes;
+      AND status='transcribing' AND lease_owner=?
+      AND EXISTS (SELECT 1 FROM discussion_captures d WHERE d.id=discussion_id AND d.status IN ('recording','stopping'))`).run(text, text, provider, language ?? null, confidence ?? null, now, discussionId, sequence, owner).changes;
 		if (changed) db.prepare("UPDATE discussion_captures SET transcript_revision=transcript_revision+1, updated_at=? WHERE id=?").run(now, discussionId);
 		return changed;
 	}) ? getDiscussionTranscriptSegment(discussionId, sequence) : null;

package/dist/src/discussions/review.d.ts

@@ -0,0 +1,8 @@
+import type { DiscussionAnnotation, DiscussionAnnotationInput, DiscussionEvidence, DiscussionResolvedAnnotation } from '@xopcai/gateway-contract';
+import type { NotesService } from '../notes/service.js';
+import { type RecordingTimeline } from './media-timeline.js';
+export declare function listAnnotations(id: string): DiscussionAnnotation[];
+export declare function putAnnotation(id: string, value: DiscussionAnnotationInput): DiscussionAnnotation;
+export declare function recordingTimeline(id: string, notes: NotesService): Promise<RecordingTimeline | undefined>;
+export declare function evidenceFor(id: string, revision: number, ids: number[], notes: NotesService): Promise<DiscussionEvidence>;
+export declare function resolvedAnnotations(id: string, notes: NotesService): Promise<DiscussionResolvedAnnotation[]>;

package/dist/src/discussions/review.js

@@ -0,0 +1,183 @@
+import { getSqliteDatabase, init_transaction, runSqliteWriteTransaction } from "../storage/sqlite/transaction.js";
+import { DiscussionServiceError } from "./errors.js";
+import { getDiscussionCapture, listDiscussionTranscriptSegments } from "./repository.js";
+import { readTranscriptRevision, saveTranscriptRevision } from "./revisions.js";
+import { pcmEpoch, playbackRanges, pointToPcm, probeMediaEpoch } from "./media-timeline.js";
+import { z } from "zod";
+//#region src/discussions/review.ts
+init_transaction();
+const anchorSchema = z.object({
+	type: z.enum(["time", "transcript"]),
+	capturedAt: z.number().int().nonnegative(),
+	epoch: z.number().int().min(0).max(100).optional(),
+	coordinate: z.enum(["encoded", "pcm"]).optional(),
+	offsetMs: z.number().min(0).max(8e6).optional(),
+	positionMs: z.number().min(0).max(8e6).optional(),
+	transcriptRevision: z.number().int().nonnegative().optional(),
+	segmentIds: z.array(z.number().int().nonnegative()).min(1).max(100).optional()
+}).strict().refine((anchor) => anchor.type === "transcript" ? anchor.transcriptRevision !== void 0 && !!anchor.segmentIds?.length && anchor.offsetMs === void 0 && anchor.positionMs === void 0 : anchor.transcriptRevision === void 0 && anchor.segmentIds === void 0 && !(anchor.offsetMs !== void 0 && anchor.positionMs !== void 0) && (anchor.offsetMs === void 0 || anchor.epoch !== void 0));
+const inputSchema = z.object({
+	id: z.string().regex(/^[a-zA-Z0-9_-]{1,100}$/),
+	kind: z.enum([
+		"highlight",
+		"question",
+		"note"
+	]),
+	text: z.string().max(4e3),
+	anchor: anchorSchema,
+	expectedRevision: z.number().int().nonnegative(),
+	deleted: z.boolean().optional()
+});
+const map = (row) => ({
+	id: row.id,
+	kind: row.kind,
+	text: row.text,
+	anchor: JSON.parse(row.anchor_json),
+	revision: row.revision,
+	deleted: !!row.deleted,
+	createdAt: row.created_at,
+	updatedAt: row.updated_at
+});
+const requireCapture = (id) => {
+	const capture = getDiscussionCapture(id);
+	if (!capture) throw new DiscussionServiceError("not_found", "Discussion not found");
+	return capture;
+};
+function listAnnotations(id) {
+	requireCapture(id);
+	return getSqliteDatabase().prepare("SELECT * FROM discussion_annotations WHERE discussion_id=? ORDER BY created_at,id").all(id).map(map).sort((a, b) => a.anchor.capturedAt - b.anchor.capturedAt || a.id.localeCompare(b.id));
+}
+function putAnnotation(id, value) {
+	const parsed = inputSchema.safeParse(value);
+	if (!parsed.success) throw new DiscussionServiceError("invalid_input", "Invalid annotation");
+	const input = parsed.data;
+	return runSqliteWriteTransaction((db) => {
+		const capture = requireCapture(id);
+		if (input.anchor.type === "transcript") {
+			if (input.anchor.transcriptRevision === capture.transcriptRevision) saveTranscriptRevision(id);
+			const segments = readTranscriptRevision(id, input.anchor.transcriptRevision);
+			if (!segments || input.anchor.segmentIds.some((sequence) => !segments.some((segment) => segment.sequence === sequence && segment.status === "confirmed"))) throw new DiscussionServiceError("conflict", "Transcript evidence is no longer available");
+		}
+		const row = db.prepare("SELECT * FROM discussion_annotations WHERE discussion_id=? AND id=?").get(id, input.id);
+		const current = row ? map(row) : void 0;
+		const anchor = JSON.stringify(input.anchor);
+		if (current && current.kind === input.kind && current.text === input.text && current.deleted === !!input.deleted && JSON.stringify(current.anchor) === anchor) return current;
+		if ((current?.revision ?? 0) !== input.expectedRevision) throw new DiscussionServiceError("conflict", "Annotation changed; reload before saving");
+		if (current && JSON.stringify(current.anchor) !== anchor) {
+			const previous = current.anchor;
+			if (!(previous.type === "time" && previous.offsetMs === void 0 && previous.positionMs === void 0 && input.anchor.type === "time" && previous.capturedAt === input.anchor.capturedAt && previous.epoch === input.anchor.epoch && previous.coordinate === input.anchor.coordinate)) throw new DiscussionServiceError("conflict", "Original annotation anchor is immutable");
+		}
+		if (!current && Number(db.prepare("SELECT COUNT(*) n FROM discussion_annotations WHERE discussion_id=?").get(id).n) >= 1e3) throw new DiscussionServiceError("invalid_input", "Annotation limit reached");
+		const now = Date.now();
+		const revision = (current?.revision ?? 0) + 1;
+		db.prepare(`INSERT INTO discussion_annotations(discussion_id,id,kind,text,anchor_json,revision,deleted,created_at,updated_at)
+      VALUES (?,?,?,?,?,?,?,?,?) ON CONFLICT(discussion_id,id) DO UPDATE SET kind=excluded.kind,text=excluded.text,anchor_json=excluded.anchor_json,revision=excluded.revision,deleted=excluded.deleted,updated_at=excluded.updated_at`).run(id, input.id, input.kind, input.text, anchor, revision, input.deleted ? 1 : 0, current?.createdAt ?? now, now);
+		return {
+			id: input.id,
+			kind: input.kind,
+			text: input.text,
+			anchor: input.anchor,
+			revision,
+			deleted: !!input.deleted,
+			createdAt: current?.createdAt ?? now,
+			updatedAt: now
+		};
+	});
+}
+const timingAttempts = /* @__PURE__ */ new Map();
+const timingInFlight = /* @__PURE__ */ new Map();
+async function recordingTimeline(id, notes) {
+	const capture = requireCapture(id);
+	if (!capture.audioAttachmentId || capture.audioDeletedAt || !capture.durationMs) return;
+	const key = `${id}:${capture.audioSha256}`;
+	if (timingInFlight.has(key)) return timingInFlight.get(key);
+	const cached = getSqliteDatabase().prepare("SELECT timeline_json FROM discussion_media_timeline WHERE discussion_id=? AND audio_sha256=?").get(id, capture.audioSha256 ?? "");
+	let previous;
+	try {
+		previous = cached ? JSON.parse(cached.timeline_json) : void 0;
+	} catch {}
+	if (previous && Array.isArray(previous.epochs) && (previous.primary === "pcm" || previous.epochs.every((epoch) => epoch.verified))) return previous;
+	if (capture.mimeType?.includes("wav")) return {
+		primary: "pcm",
+		epochs: [pcmEpoch(capture.durationMs)]
+	};
+	if (previous && Date.now() - (timingAttempts.get(key) ?? 0) < 3e4) return previous;
+	timingAttempts.set(key, Date.now());
+	if (timingAttempts.size > 256) timingAttempts.delete(timingAttempts.keys().next().value);
+	const pending = (async () => {
+		const attachment = await notes.getAttachmentPath(capture.noteId, capture.audioAttachmentId);
+		if (!attachment) return;
+		const timeline = {
+			primary: "encoded",
+			epochs: [await probeMediaEpoch(attachment.filePath, capture.durationMs, 0, AbortSignal.timeout(35e3))]
+		};
+		if (getDiscussionCapture(id)?.audioSha256 === capture.audioSha256) getSqliteDatabase().prepare("INSERT OR REPLACE INTO discussion_media_timeline(discussion_id,audio_sha256,timeline_json) VALUES(?,?,?)").run(id, capture.audioSha256 ?? "", JSON.stringify(timeline));
+		return timeline;
+	})().finally(() => timingInFlight.delete(key));
+	timingInFlight.set(key, pending);
+	return pending;
+}
+async function evidenceFor(id, revision, ids, notes) {
+	const capture = requireCapture(id);
+	if (!Number.isSafeInteger(revision) || revision < 0 || !ids.length || ids.length > 100 || ids.some((id) => !Number.isSafeInteger(id) || id < 0)) throw new DiscussionServiceError("invalid_input", "Invalid evidence reference");
+	if (capture.transcriptRevision === revision) saveTranscriptRevision(id);
+	const source = readTranscriptRevision(id, revision);
+	if (!source || ids.some((id) => !source.some((segment) => segment.sequence === id && segment.status === "confirmed"))) throw new DiscussionServiceError("not_found", "Referenced transcript revision or segment is unavailable");
+	const attachment = capture.audioAttachmentId && !capture.audioDeletedAt ? await notes.getAttachmentPath(capture.noteId, capture.audioAttachmentId) : null;
+	const timeline = attachment ? await recordingTimeline(id, notes) : void 0;
+	return {
+		transcriptRevision: revision,
+		stale: revision !== getDiscussionCapture(id)?.transcriptRevision,
+		audioAvailable: !!attachment,
+		timingVerified: !!timeline && (timeline.primary === "pcm" || timeline.epochs.every((epoch) => epoch.verified)),
+		segments: source.filter((segment) => ids.includes(segment.sequence)).map((segment) => ({
+			sequence: segment.sequence,
+			startedAtMs: segment.startedAtMs,
+			endedAtMs: segment.endedAtMs,
+			text: segment.displayText ?? segment.rawText ?? "",
+			speakerLabel: segment.speakerLabel,
+			playback: timeline ? playbackRanges(timeline, segment.startedAtMs, segment.endedAtMs) : []
+		}))
+	};
+}
+async function resolvedAnnotations(id, notes) {
+	const capture = requireCapture(id);
+	const annotations = listAnnotations(id);
+	const timeline = await recordingTimeline(id, notes);
+	const current = listDiscussionTranscriptSegments(id).filter((segment) => segment.status === "confirmed");
+	return Promise.all(annotations.map(async (annotation) => {
+		const anchor = annotation.anchor;
+		if (annotation.deleted) return {
+			annotation,
+			state: "unavailable",
+			playback: []
+		};
+		if (anchor.type === "transcript") {
+			const evidence = await evidenceFor(id, anchor.transcriptRevision, anchor.segmentIds, notes).catch(() => void 0);
+			return {
+				annotation,
+				state: evidence ? "located" : "unavailable",
+				evidence,
+				playback: evidence?.segments.flatMap((segment) => segment.playback) ?? []
+			};
+		}
+		const epoch = timeline?.epochs[anchor.epoch ?? 0];
+		const position = anchor.positionMs ?? (epoch && anchor.offsetMs !== void 0 ? anchor.coordinate === "pcm" ? anchor.offsetMs < epoch.durationMs ? epoch.baseMs + anchor.offsetMs : void 0 : pointToPcm(epoch, anchor.offsetMs) : void 0);
+		if (!(!capture.audioDeletedAt && !!capture.audioAttachmentId && position !== void 0 && position >= 0 && position < (capture.durationMs ?? 0))) return {
+			annotation,
+			state: !capture.audioAttachmentId && !capture.audioDeletedAt ? "pending" : "unavailable",
+			playback: []
+		};
+		const refs = current.filter((segment) => segment.startedAtMs <= position && segment.endedAtMs > position).map((segment) => segment.sequence);
+		const evidence = refs.length ? await evidenceFor(id, capture.transcriptRevision, refs, notes) : void 0;
+		return {
+			annotation,
+			state: "located",
+			positionMs: position,
+			playback: timeline ? playbackRanges(timeline, Math.max(0, position - 2e3), Math.min(capture.durationMs, position + 8e3)) : [],
+			evidence
+		};
+	}));
+}
+//#endregion
+export { evidenceFor, listAnnotations, putAnnotation, recordingTimeline, resolvedAnnotations };