@speclip/pi-talking-head 0.1.1 → 0.1.3

package/src/broll.ts

@@ -0,0 +1,406 @@
+import { opendir, readFile, stat } from "node:fs/promises";
+import { basename, dirname, extname, join, relative, sep } from "node:path";
+import type {
+	BrollAssetCandidate,
+	BrollAssetMatch,
+	BrollNeed,
+	BrollPlacementInput,
+	BrollSelectionReceipt,
+	BrollWindowSelection,
+	FileRef,
+} from "./contracts.ts";
+import { resolveExistingWorkspaceDirectory, resolveExistingWorkspaceFile, snapshotFile, workspaceRoot } from "./workspace.ts";
+
+const VIDEO_EXTENSIONS = new Set([".mp4", ".mov", ".m4v", ".webm", ".mkv", ".avi"]);
+
+export interface RankBrollAssetsInput {
+	need: BrollNeed;
+	assetPaths: string[];
+	maxCandidates?: number;
+	candidateOffset?: number;
+	completeInventory?: boolean;
+}
+
+export interface MatchWorkspaceBrollAssetsInput {
+	assetDirectory: string;
+	recursive?: boolean;
+	maxFiles?: number;
+	maxEntries?: number;
+	maxDepth?: number;
+	maxCandidates?: number;
+	candidateOffset?: number;
+	need: BrollNeed;
+	signal?: AbortSignal;
+}
+
+export type WorkspaceBrollAssetMatch = BrollAssetMatch & {
+	assetDirectory: string;
+	scannedFileCount: number;
+	scannedEntryCount: number;
+	truncated: boolean;
+};
+
+export interface SelectBrollWindowInput {
+	need: BrollNeed;
+	assetPath: string;
+	manifestPath: string;
+	selectedStartMs: number;
+	evidenceTimestampsMs: number[];
+	fit: "cover" | "contain";
+	signal?: AbortSignal;
+}
+
+interface ContactSheetManifest {
+	schemaVersion: number;
+	source?: { path?: string; bytes?: number; sha256?: string };
+	range?: { startSeconds?: number; endSeconds?: number };
+	artifacts?: Array<{ timestampsSeconds?: number[]; sourceSha256?: string }>;
+}
+
+function normalized(value: string): string {
+	return value.normalize("NFKC").toLowerCase().replace(/[\p{P}\p{S}\s]+/gu, "");
+}
+
+function normalizedTerms(terms: string[]): string[] {
+	const unique = new Set<string>();
+	for (const term of terms) {
+		const value = normalized(term);
+		if (value) unique.add(value);
+	}
+	if (unique.size === 0) throw new Error("B-roll searchTerms must contain at least one meaningful term");
+	return [...unique];
+}
+
+function candidateFor(assetPath: string, terms: string[]): BrollAssetCandidate {
+	const fileName = basename(assetPath);
+	const normalizedName = normalized(fileName.replace(/\.[^.]+$/u, ""));
+	const normalizedDirectory = normalized(dirname(assetPath));
+	const matchedTerms: string[] = [];
+	let score = 0;
+	for (const term of terms) {
+		if (normalizedName.includes(term)) {
+			matchedTerms.push(term);
+			score += 4;
+		} else if (normalizedDirectory.includes(term)) {
+			matchedTerms.push(term);
+			score += 2;
+		}
+	}
+	const highThreshold = Math.min(2, terms.length);
+	return {
+		assetPath,
+		fileName,
+		matchedTerms,
+		score,
+		confidence: matchedTerms.length >= highThreshold ? "high" : matchedTerms.length > 0 ? "medium" : "low",
+	};
+}
+
+function validateNeed(need: BrollNeed): void {
+	if (!Number.isFinite(need.outputStartMs) || !Number.isFinite(need.outputEndMs)
+		|| need.outputStartMs < 0 || need.outputEndMs <= need.outputStartMs) {
+		throw new Error("B-roll need must contain a valid output range");
+	}
+}
+
+export function rankBrollAssets(input: RankBrollAssetsInput): BrollAssetMatch {
+	validateNeed(input.need);
+	if (input.assetPaths.length === 0) throw new Error("No candidate B-roll video assets were found");
+	const terms = normalizedTerms(input.need.searchTerms);
+	const maxCandidates = input.maxCandidates ?? 5;
+	if (!Number.isInteger(maxCandidates) || maxCandidates < 1 || maxCandidates > 20) {
+		throw new Error("maxCandidates must be within 1-20");
+	}
+	const ranked = [...new Set(input.assetPaths)].map((assetPath) => candidateFor(assetPath, terms)).sort((left, right) => (
+		right.score - left.score || (left.assetPath < right.assetPath ? -1 : left.assetPath > right.assetPath ? 1 : 0)
+	));
+	const candidateOffset = input.candidateOffset ?? 0;
+	if (!Number.isInteger(candidateOffset) || candidateOffset < 0 || candidateOffset >= ranked.length) {
+		throw new Error(`candidateOffset must be within 0-${ranked.length - 1}`);
+	}
+	const top = ranked[0];
+	const second = ranked[1];
+	const direct = (input.completeInventory ?? true) && candidateOffset === 0
+		&& top?.confidence === "high" && (second === undefined || top.score > second.score);
+	if (direct) {
+		return {
+			requiredDurationMs: input.need.outputEndMs - input.need.outputStartMs,
+			totalCandidates: ranked.length,
+			candidateOffset: 0,
+			nextCandidateOffset: null,
+			selectionMode: "filename-direct",
+			shortlist: [top],
+			nextStep: {
+				action: "inspect-selected-asset",
+				reason: "One filename is the unique high-confidence match; inspect only this asset to choose the source window.",
+			},
+		};
+	}
+	const hasLexicalMatch = ranked.some((candidate) => candidate.confidence !== "low");
+	const shortlist = ranked.slice(candidateOffset, candidateOffset + maxCandidates);
+	const nextCandidateOffset = (input.completeInventory ?? true) && candidateOffset + shortlist.length < ranked.length
+		? candidateOffset + shortlist.length
+		: null;
+	const shared = {
+		requiredDurationMs: input.need.outputEndMs - input.need.outputStartMs,
+		totalCandidates: ranked.length,
+		candidateOffset,
+		nextCandidateOffset,
+		shortlist,
+	};
+	if (hasLexicalMatch) return {
+		...shared,
+		selectionMode: "filename-shortlist",
+		nextStep: {
+			action: "inspect-shortlist",
+			reason: "Filename evidence is ambiguous; visually inspect only the bounded shortlist.",
+		},
+	};
+	return {
+		...shared,
+		selectionMode: "visual-fallback",
+		nextStep: {
+			action: "visual-fallback",
+			reason: "Filenames provide no useful evidence; use low-cost visual screening on the bounded shortlist.",
+		},
+	};
+}
+
+interface ScanState {
+	paths: string[];
+	visitedEntries: number;
+	truncated: boolean;
+}
+
+interface ScanLimits {
+	recursive: boolean;
+	maxFiles: number;
+	maxEntries: number;
+	maxDepth: number;
+	signal?: AbortSignal;
+}
+
+function codePointCompare(left: string, right: string): number {
+	return left < right ? -1 : left > right ? 1 : 0;
+}
+
+async function collectVideoPaths(directory: string, depth: number, limits: ScanLimits, state: ScanState): Promise<void> {
+	limits.signal?.throwIfAborted();
+	const entries = [];
+	const handle = await opendir(directory);
+	for await (const entry of handle) {
+		limits.signal?.throwIfAborted();
+		if (state.visitedEntries >= limits.maxEntries) {
+			state.truncated = true;
+			break;
+		}
+		state.visitedEntries += 1;
+		entries.push(entry);
+	}
+	entries.sort((left, right) => codePointCompare(left.name, right.name));
+	for (const entry of entries) {
+		limits.signal?.throwIfAborted();
+		if (state.paths.length > limits.maxFiles) {
+			state.truncated = true;
+			return;
+		}
+		if (entry.isSymbolicLink()) continue;
+		const absolute = join(directory, entry.name);
+		if (entry.isDirectory()) {
+			if (limits.recursive) {
+				if (depth >= limits.maxDepth) state.truncated = true;
+				else await collectVideoPaths(absolute, depth + 1, limits, state);
+			}
+			continue;
+		}
+		if (entry.isFile() && VIDEO_EXTENSIONS.has(extname(entry.name).toLowerCase())) state.paths.push(absolute);
+	}
+}
+
+export async function matchWorkspaceBrollAssets(
+	cwd: string,
+	input: MatchWorkspaceBrollAssetsInput,
+): Promise<WorkspaceBrollAssetMatch> {
+	const maxFiles = input.maxFiles ?? 1_000;
+	if (!Number.isInteger(maxFiles) || maxFiles < 1 || maxFiles > 5_000) {
+		throw new Error("maxFiles must be within 1-5000");
+	}
+	const maxEntries = input.maxEntries ?? 20_000;
+	if (!Number.isInteger(maxEntries) || maxEntries < 1 || maxEntries > 100_000) {
+		throw new Error("maxEntries must be within 1-100000");
+	}
+	const maxDepth = input.maxDepth ?? 12;
+	if (!Number.isInteger(maxDepth) || maxDepth < 0 || maxDepth > 50) {
+		throw new Error("maxDepth must be within 0-50");
+	}
+	const directory = await resolveExistingWorkspaceDirectory(cwd, input.assetDirectory);
+	const state: ScanState = { paths: [], visitedEntries: 0, truncated: false };
+	await collectVideoPaths(directory, 0, {
+		recursive: input.recursive ?? true,
+		maxFiles,
+		maxEntries,
+		maxDepth,
+		...(input.signal === undefined ? {} : { signal: input.signal }),
+	}, state);
+	const truncated = state.truncated || state.paths.length > maxFiles;
+	if (truncated && (input.candidateOffset ?? 0) !== 0) {
+		throw new Error("candidateOffset cannot be reused after a truncated scan; narrow the asset directory and rescan");
+	}
+	const included = state.paths.slice(0, maxFiles);
+	const root = await workspaceRoot(cwd);
+	const toWorkspacePath = (path: string) => relative(root, path).split(sep).join("/");
+	const assetPaths = included.map(toWorkspacePath);
+	return {
+		assetDirectory: toWorkspacePath(directory),
+		scannedFileCount: included.length,
+		scannedEntryCount: state.visitedEntries,
+		truncated,
+		...rankBrollAssets({
+			need: input.need,
+			assetPaths,
+			...(input.maxCandidates === undefined ? {} : { maxCandidates: input.maxCandidates }),
+			...(input.candidateOffset === undefined ? {} : { candidateOffset: input.candidateOffset }),
+			completeInventory: !truncated,
+		}),
+	};
+}
+
+function parseContactSheetManifest(payload: string, manifestPath: string): ContactSheetManifest {
+	try {
+		return JSON.parse(payload) as ContactSheetManifest;
+	} catch (error) {
+		throw new Error(`Invalid contact-sheet manifest ${manifestPath}: ${(error as Error).message}`);
+	}
+}
+
+interface SelectionWindow {
+	assetStartMs: number;
+	outputStartMs: number;
+	outputEndMs: number;
+}
+
+function validateManifestSelection(
+	asset: FileRef,
+	manifest: FileRef,
+	payload: ContactSheetManifest,
+	window: SelectionWindow,
+	receipt: BrollSelectionReceipt,
+): void {
+	if (payload.schemaVersion !== 2 || !payload.source || !payload.range || !Array.isArray(payload.artifacts)) {
+		throw new Error("Contact-sheet manifest must use pi-media schemaVersion 2");
+	}
+	if (receipt.assetSha256 !== asset.sha256 || receipt.assetBytes !== asset.bytes) {
+		throw new Error("B-roll selection receipt does not match the current asset");
+	}
+	if (receipt.manifestPath !== manifest.path || receipt.manifestSha256 !== manifest.sha256) {
+		throw new Error("B-roll selection receipt does not match the current contact-sheet manifest");
+	}
+	if (payload.source.path !== asset.path || payload.source.sha256 !== asset.sha256 || payload.source.bytes !== asset.bytes) {
+		throw new Error("Contact-sheet manifest source does not match the selected B-roll asset");
+	}
+	const requiredDurationMs = window.outputEndMs - window.outputStartMs;
+	const selectedEndMs = window.assetStartMs + requiredDurationMs;
+	if (receipt.selectedEndMs !== selectedEndMs) {
+		throw new Error("B-roll selection receipt duration does not match the output placement");
+	}
+	const rangeStartMs = Number(payload.range.startSeconds) * 1_000;
+	const rangeEndMs = Number(payload.range.endSeconds) * 1_000;
+	if (!Number.isFinite(rangeStartMs) || !Number.isFinite(rangeEndMs)
+		|| window.assetStartMs < rangeStartMs || selectedEndMs > rangeEndMs) {
+		throw new Error("Selected B-roll source window is outside the analyzed contact-sheet range");
+	}
+	const availableTimestamps = new Set<number>();
+	for (const artifact of payload.artifacts) {
+		if (artifact.sourceSha256 !== asset.sha256 || !Array.isArray(artifact.timestampsSeconds)) {
+			throw new Error("Contact-sheet artifact provenance does not match the selected B-roll asset");
+		}
+		for (const timestamp of artifact.timestampsSeconds) {
+			if (Number.isFinite(timestamp)) availableTimestamps.add(Math.round(timestamp * 1_000));
+		}
+	}
+	if (!availableTimestamps.has(window.assetStartMs)) {
+		throw new Error("Selected B-roll source window must start on a manifest timestamp");
+	}
+	const evidenceTimestampsMs = [...new Set(receipt.evidenceTimestampsMs)];
+	const minimumEvidence = requiredDurationMs >= 1_000 ? 2 : 1;
+	if (evidenceTimestampsMs.length < minimumEvidence || !evidenceTimestampsMs.includes(window.assetStartMs)
+		|| evidenceTimestampsMs.some((timestamp) => (
+			!Number.isFinite(timestamp)
+			|| !availableTimestamps.has(timestamp)
+			|| timestamp < window.assetStartMs
+			|| timestamp > selectedEndMs
+		))) {
+		throw new Error(`B-roll selection requires ${minimumEvidence} or more manifest-backed evidence timestamps, including its source start`);
+	}
+	const tailThresholdMs = selectedEndMs - Math.max(500, requiredDurationMs * 0.25);
+	if (Math.max(...evidenceTimestampsMs) < tailThresholdMs) {
+		throw new Error("B-roll selection evidence must cover the end of the source window");
+	}
+}
+
+async function readVerifiedManifest(
+	cwd: string,
+	manifestPath: string,
+	signal?: AbortSignal,
+): Promise<{ manifest: FileRef; payload: ContactSheetManifest }> {
+	signal?.throwIfAborted();
+	const manifestAbsolute = await resolveExistingWorkspaceFile(cwd, manifestPath);
+	if ((await stat(manifestAbsolute)).size > 5 * 1024 * 1024) throw new Error("Contact-sheet manifest exceeds the 5MB limit");
+	const manifest = await snapshotFile(cwd, manifestPath, signal);
+	const payload = parseContactSheetManifest(
+		await readFile(manifestAbsolute, signal === undefined ? "utf8" : { encoding: "utf8", signal }),
+		manifest.path,
+	);
+	return { manifest, payload };
+}
+
+export async function verifyBrollPlacementSelection(
+	cwd: string,
+	placement: BrollPlacementInput,
+	signal?: AbortSignal,
+): Promise<FileRef> {
+	if (!Number.isFinite(placement.assetStartMs) || placement.assetStartMs < 0) {
+		throw new Error(`B-roll assetStartMs is required and must be valid: ${placement.id}`);
+	}
+	if (!placement.selectionReceipt) {
+		throw new Error(`B-roll selectionReceipt is required: ${placement.id}`);
+	}
+	const asset = await snapshotFile(cwd, placement.assetPath, signal);
+	const { manifest, payload } = await readVerifiedManifest(cwd, placement.selectionReceipt.manifestPath, signal);
+	validateManifestSelection(asset, manifest, payload, placement, placement.selectionReceipt);
+	return asset;
+}
+
+export async function selectBrollWindow(cwd: string, input: SelectBrollWindowInput): Promise<BrollWindowSelection> {
+	validateNeed(input.need);
+	input.signal?.throwIfAborted();
+	if (!Number.isFinite(input.selectedStartMs) || input.selectedStartMs < 0) {
+		throw new Error("selectedStartMs must be a finite non-negative timestamp");
+	}
+	const requiredDurationMs = input.need.outputEndMs - input.need.outputStartMs;
+	const selectedEndMs = input.selectedStartMs + requiredDurationMs;
+	const evidenceTimestampsMs = [...new Set(input.evidenceTimestampsMs)];
+	const asset = await snapshotFile(cwd, input.assetPath, input.signal);
+	const { manifest, payload } = await readVerifiedManifest(cwd, input.manifestPath, input.signal);
+	const placement: BrollPlacementInput = {
+			id: input.need.id,
+			assetPath: asset.path,
+			outputStartMs: input.need.outputStartMs,
+			outputEndMs: input.need.outputEndMs,
+			assetStartMs: input.selectedStartMs,
+			fit: input.fit,
+			audio: "keep-primary",
+			query: input.need.searchTerms.join(" "),
+			reason: input.need.reason,
+			selectionReceipt: {
+				assetBytes: asset.bytes,
+				assetSha256: asset.sha256,
+				manifestPath: manifest.path,
+				manifestSha256: manifest.sha256,
+				selectedEndMs,
+				evidenceTimestampsMs,
+			},
+	};
+	validateManifestSelection(asset, manifest, payload, placement, placement.selectionReceipt);
+	return { placement };
+}

package/src/contracts.ts

@@ -28,6 +28,57 @@ export interface PauseCandidate {
 	classification: PauseClassification;
 	beforeText: string;
 	afterText: string;
+	boundary: "within-sentence" | "between-sentences";
+	context: {
+		before: string;
+		after: string;
+	};
+	adjacentFillerIds: string[];
+	recommendation: EditorialRecommendation;
+	reasons: string[];
+}
+
+export type EditorialRecommendation = "cut" | "review" | "keep";
+export type DeliveryCue = "neutral" | "hesitation" | "emphasis" | "question";
+
+export interface SentenceAnalysis {
+	sentenceIndex: number;
+	sentenceId: number;
+	beginMs: number;
+	endMs: number;
+	text: string;
+	wordStartIndex: number;
+	wordEndIndex: number;
+	deliveryCues: DeliveryCue[];
+	confidence: "low";
+	evidence: string[];
+}
+
+export interface FillerCandidate {
+	id: string;
+	wordIndex: number;
+	sentenceIndex: number;
+	text: string;
+	startMs: number;
+	endMs: number;
+	kind: "hesitation" | "discourse";
+	matchConfidence: "exact" | "contextual";
+	recommendation: "review";
+	contextText: string;
+	reasons: string[];
+}
+
+export interface RepetitionCandidate {
+	id: string;
+	sentenceIndex: number;
+	text: string;
+	firstWordIndex: number;
+	secondWordIndex: number;
+	startMs: number;
+	endMs: number;
+	recommendation: "review";
+	contextText: string;
+	reasons: string[];
 }
 
 export interface ArollSegment {
@@ -44,16 +95,83 @@ export interface BrollPlacement {
 	outputStartMs: number;
 	outputEndMs: number;
 	assetStartMs?: number;
+	selectionReceipt?: BrollSelectionReceipt;
 	fit: "cover" | "contain";
 	audio: "keep-primary";
 	query?: string;
 	reason?: string;
 }
 
-export type BrollPlacementInput = Omit<BrollPlacement, "assetBytes" | "assetSha256">;
+export interface BrollSelectionReceipt {
+	assetBytes: number;
+	assetSha256: string;
+	manifestPath: string;
+	manifestSha256: string;
+	selectedEndMs: number;
+	evidenceTimestampsMs: number[];
+}
+
+export type BrollPlacementInput = Omit<
+	BrollPlacement,
+	"assetBytes" | "assetSha256" | "assetStartMs" | "selectionReceipt"
+> & {
+	assetStartMs: number;
+	selectionReceipt: BrollSelectionReceipt;
+};
+
+export type BrollPurpose = "demonstrate" | "explain" | "evidence" | "establish" | "transition" | "mask-cut";
+
+export interface BrollNeed {
+	id: string;
+	outputStartMs: number;
+	outputEndMs: number;
+	speechText: string;
+	purpose: BrollPurpose;
+	searchTerms: string[];
+	reason: string;
+}
+
+export interface BrollAssetCandidate {
+	assetPath: string;
+	fileName: string;
+	matchedTerms: string[];
+	score: number;
+	confidence: "high" | "medium" | "low";
+}
+
+interface BrollAssetMatchBase {
+	requiredDurationMs: number;
+	totalCandidates: number;
+	candidateOffset: number;
+	nextCandidateOffset: number | null;
+	shortlist: BrollAssetCandidate[];
+}
+
+export type BrollAssetMatch =
+	| BrollAssetMatchBase & {
+		selectionMode: "filename-direct";
+		nextStep: { action: "inspect-selected-asset"; reason: string };
+	}
+	| BrollAssetMatchBase & {
+		selectionMode: "filename-shortlist";
+		nextStep: { action: "inspect-shortlist"; reason: string };
+	}
+	| BrollAssetMatchBase & {
+		selectionMode: "visual-fallback";
+		nextStep: { action: "visual-fallback"; reason: string };
+	};
+
+export interface BrollWindowSelection {
+	placement: BrollPlacementInput;
+}
 
 export interface TranscriptAnalysis {
+	schemaVersion: 2;
+	text: string;
 	words: TranscriptWord[];
+	sentences: SentenceAnalysis[];
+	fillers: FillerCandidate[];
+	repetitions: RepetitionCandidate[];
 	candidates: PauseCandidate[];
 	segments: ArollSegment[];
 	outputDurationMs: number;

package/src/project.ts

@@ -5,12 +5,18 @@ import type {
 	ArollSegment,
 	BrollPlacement,
 	BrollPlacementInput,
+	FillerCandidate,
+	PauseCandidate,
+	RepetitionCandidate,
+	SentenceAnalysis,
 	TalkingHeadPolicy,
 	TalkingHeadProject,
 	TalkingHeadSnapshot,
 	TranscriptAnalysis,
+	TranscriptWord,
 	WordTranscript,
 } from "./contracts.ts";
+import { verifyBrollPlacementSelection } from "./broll.ts";
 import { analyzeTranscript, DEFAULT_POLICY, timelineDuration } from "./transcript.ts";
 import { resolveExistingWorkspaceFile, resolveWorkspacePath, snapshotFile, workspaceRelativePath } from "./workspace.ts";
 
@@ -72,6 +78,7 @@ async function validateTimeline(
 	cwd: string,
 	aroll: ArollSegment[],
 	broll: BrollPlacementInput[],
+	signal?: AbortSignal,
 ): Promise<{ outputDurationMs: number; broll: BrollPlacement[] }> {
 	if (aroll.length === 0 || aroll.length > 1_000) throw new Error("A-roll must contain 1-1000 segments");
 	uniqueIds(aroll, "A-roll segment");
@@ -86,6 +93,7 @@ async function validateTimeline(
 	uniqueIds(broll, "B-roll placement");
 	const normalizedBroll: BrollPlacement[] = [];
 	for (const placement of broll) {
+		signal?.throwIfAborted();
 		if (!Number.isFinite(placement.outputStartMs) || !Number.isFinite(placement.outputEndMs)
 			|| placement.outputStartMs < 0 || placement.outputEndMs <= placement.outputStartMs) {
 			throw new Error(`Invalid B-roll output range: ${placement.id}`);
@@ -93,11 +101,12 @@ async function validateTimeline(
 		if (placement.outputEndMs > outputDurationMs) {
 			throw new Error(`B-roll placement ${placement.id} exceeds output duration ${outputDurationMs}ms`);
 		}
-		if (placement.assetStartMs !== undefined && (!Number.isFinite(placement.assetStartMs) || placement.assetStartMs < 0)) {
-			throw new Error(`Invalid B-roll asset start: ${placement.id}`);
+		if (!Number.isFinite(placement.assetStartMs) || placement.assetStartMs < 0) {
+			throw new Error(`B-roll assetStartMs is required and must be valid: ${placement.id}`);
 		}
+		if (!placement.selectionReceipt) throw new Error(`B-roll selectionReceipt is required: ${placement.id}`);
 		if (placement.audio !== "keep-primary") throw new Error("B-roll audio must keep the primary A-roll audio");
-		const asset = await snapshotFile(cwd, placement.assetPath);
+		const asset = await verifyBrollPlacementSelection(cwd, placement, signal);
 		normalizedBroll.push({
 			...structuredClone(placement),
 			assetPath: asset.path,
@@ -111,10 +120,15 @@ async function validateTimeline(
 function summary(analysis: TranscriptAnalysis) {
 	return {
 		wordCount: analysis.words.length,
+		sentenceCount: analysis.sentences.length,
+		fillerCount: analysis.fillers.length,
+		repetitionCount: analysis.repetitions.length,
 		pauseCount: analysis.candidates.length,
 		safePauses: analysis.candidates.filter((candidate) => candidate.classification === "safe").length,
 		reviewPauses: analysis.candidates.filter((candidate) => candidate.classification === "review").length,
 		unsafePauses: analysis.candidates.filter((candidate) => candidate.classification === "unsafe").length,
+		automaticCutPauses: analysis.candidates.filter((candidate) => candidate.recommendation === "cut").length,
+		editorialReviewPauses: analysis.candidates.filter((candidate) => candidate.recommendation === "review").length,
 		defaultSegmentCount: analysis.segments.length,
 		defaultOutputDurationMs: analysis.outputDurationMs,
 	};
@@ -223,7 +237,7 @@ async function acquireLock(directory: string): Promise<() => Promise<void>> {
 	return async () => { await unlink(lockPath).catch(() => undefined); };
 }
 
-export async function applyTimeline(cwd: string, input: ApplyTimelineInput): Promise<TalkingHeadSnapshot> {
+export async function applyTimeline(cwd: string, input: ApplyTimelineInput, signal?: AbortSignal): Promise<TalkingHeadSnapshot> {
 	const directory = await projectDirectory(cwd, input.projectId);
 	const release = await acquireLock(directory);
 	try {
@@ -234,7 +248,7 @@ export async function applyTimeline(cwd: string, input: ApplyTimelineInput): Pro
 		await assertProjectSourcesUnchanged(cwd, project);
 		await assertSnapshotAssetsUnchanged(cwd, current);
 		assertWordSafeSegments(input.aroll, await getAnalysis(cwd, project));
-		const validated = await validateTimeline(cwd, input.aroll, input.broll);
+		const validated = await validateTimeline(cwd, input.aroll, input.broll, signal);
 		const revision = project.currentRevision + 1;
 		const now = new Date().toISOString();
 		const snapshot: TalkingHeadSnapshot = {
@@ -261,7 +275,60 @@ export async function applyTimeline(cwd: string, input: ApplyTimelineInput): Pro
 
 export async function getAnalysis(cwd: string, project: TalkingHeadProject): Promise<TranscriptAnalysis> {
 	const absolute = await resolveExistingWorkspaceFile(cwd, project.analysisPath);
-	return await readJson<TranscriptAnalysis>(absolute, `talking-head analysis ${project.projectId}`);
+	const persisted = await readJson<{
+		schemaVersion?: number;
+		text?: string;
+		words: TranscriptWord[];
+		sentences?: SentenceAnalysis[];
+		fillers?: FillerCandidate[];
+		repetitions?: RepetitionCandidate[];
+		candidates: Array<Partial<PauseCandidate> & Pick<PauseCandidate, "id" | "startMs" | "endMs" | "durationMs" | "classification" | "beforeText" | "afterText">>;
+		segments: ArollSegment[];
+		outputDurationMs: number;
+	}>(absolute, `talking-head analysis ${project.projectId}`);
+	if (!Array.isArray(persisted.words) || !Array.isArray(persisted.candidates)
+		|| !Array.isArray(persisted.segments) || !Number.isFinite(persisted.outputDurationMs)) {
+		throw new Error(`Invalid talking-head analysis: ${project.projectId}`);
+	}
+	const completeV2 = persisted.schemaVersion === 2
+		&& typeof persisted.text === "string"
+		&& Array.isArray(persisted.sentences)
+		&& Array.isArray(persisted.fillers)
+		&& Array.isArray(persisted.repetitions);
+	if (!completeV2) {
+		const currentTranscript = await snapshotFile(cwd, project.transcript.path);
+		if (currentTranscript.sha256 !== project.transcript.sha256 || currentTranscript.bytes !== project.transcript.bytes) {
+			throw new Error(`Transcript changed before legacy analysis migration: ${project.transcript.path}`);
+		}
+		const transcriptAbsolute = await resolveExistingWorkspaceFile(cwd, project.transcript.path);
+		const transcriptPayload = await readJson<WordTranscript>(transcriptAbsolute, "word transcript");
+		const { snapshot } = await getTalkingHeadProject(cwd, project.projectId);
+		return analyzeTranscript(transcriptPayload, snapshot.policy);
+	}
+	return {
+		schemaVersion: 2,
+		text: persisted.text ?? "",
+		words: persisted.words,
+		sentences: persisted.sentences ?? [],
+		fillers: persisted.fillers ?? [],
+		repetitions: persisted.repetitions ?? [],
+		candidates: persisted.candidates.map((candidate) => ({
+			id: candidate.id,
+			startMs: candidate.startMs,
+			endMs: candidate.endMs,
+			durationMs: candidate.durationMs,
+			classification: candidate.classification,
+			beforeText: candidate.beforeText,
+			afterText: candidate.afterText,
+			boundary: candidate.boundary ?? "within-sentence",
+			context: candidate.context ?? { before: candidate.beforeText, after: candidate.afterText },
+			adjacentFillerIds: candidate.adjacentFillerIds ?? [],
+			recommendation: candidate.recommendation ?? "review",
+			reasons: candidate.reasons ?? ["Legacy pause analysis requires editorial review before cutting."],
+		})),
+		segments: persisted.segments,
+		outputDurationMs: persisted.outputDurationMs,
+	};
 }
 
 export async function assertProjectSourcesUnchanged(cwd: string, project: TalkingHeadProject): Promise<void> {