@speclip/pi-talking-head 0.1.2 → 0.1.4

package/src/continuity.ts

@@ -0,0 +1,355 @@
+import { createHash } from "node:crypto";
+import type {
+	ArollJumpCut,
+	ArollSegment,
+	BrollContinuityBridge,
+	BrollContinuityPlan,
+	BrollContinuityPlanReceipt,
+	BrollNeed,
+} from "./contracts.ts";
+import { timelineDuration } from "./transcript.ts";
+
+export interface PlanBrollContinuityInput {
+	aroll: ArollSegment[];
+	needs: BrollNeed[];
+	shortGapMs?: number;
+	cutCoverBeforeMs?: number;
+	cutCoverAfterMs?: number;
+}
+
+export interface BrollOutputWindow {
+	id: string;
+	outputStartMs: number;
+	outputEndMs: number;
+}
+
+export interface ShortArollFlashGap {
+	fromBrollId: string;
+	toBrollId: string;
+	startMs: number;
+	endMs: number;
+	durationMs: number;
+}
+
+export interface OverlappingBrollWindows {
+	underBrollId: string;
+	overBrollId: string;
+}
+
+function boundedMilliseconds(value: number | undefined, fallback: number, name: string, maximum: number): number {
+	const selected = value ?? fallback;
+	if (!Number.isInteger(selected) || selected < 0 || selected > maximum) {
+		throw new Error(`${name} must be an integer within 0-${maximum}`);
+	}
+	return selected;
+}
+
+export function findShortArollFlashGaps(
+	windows: BrollOutputWindow[],
+	shortGapMs = 500,
+): ShortArollFlashGap[] {
+	const threshold = boundedMilliseconds(shortGapMs, 500, "shortGapMs", 2_000);
+	const sorted = [...windows].sort((left, right) => (
+		left.outputStartMs - right.outputStartMs
+		|| left.outputEndMs - right.outputEndMs
+		|| (left.id < right.id ? -1 : left.id > right.id ? 1 : 0)
+	));
+	const gaps: ShortArollFlashGap[] = [];
+	let frontier = sorted[0];
+	let coveredUntilMs = frontier?.outputEndMs ?? 0;
+	for (let index = 1; index < sorted.length; index += 1) {
+		const next = sorted[index]!;
+		if (next.outputStartMs <= coveredUntilMs) {
+			if (next.outputEndMs > coveredUntilMs) {
+				frontier = next;
+				coveredUntilMs = next.outputEndMs;
+			}
+			continue;
+		}
+		const durationMs = next.outputStartMs - coveredUntilMs;
+		if (durationMs > threshold) {
+			frontier = next;
+			coveredUntilMs = next.outputEndMs;
+			continue;
+		}
+		gaps.push({
+			fromBrollId: frontier!.id,
+			toBrollId: next.id,
+			startMs: coveredUntilMs,
+			endMs: next.outputStartMs,
+			durationMs,
+		});
+		frontier = next;
+		coveredUntilMs = next.outputEndMs;
+	}
+	return gaps;
+}
+
+export function findOverlappingBrollWindows(windows: BrollOutputWindow[]): OverlappingBrollWindows[] {
+	const sorted = [...windows].sort((left, right) => (
+		left.outputStartMs - right.outputStartMs
+		|| right.outputEndMs - left.outputEndMs
+		|| (left.id < right.id ? -1 : left.id > right.id ? 1 : 0)
+	));
+	const overlaps: OverlappingBrollWindows[] = [];
+	let frontier = sorted[0];
+	for (let index = 1; index < sorted.length; index += 1) {
+		const next = sorted[index]!;
+		if (frontier && next.outputStartMs < frontier.outputEndMs) {
+			overlaps.push({ underBrollId: frontier.id, overBrollId: next.id });
+			if (next.outputEndMs > frontier.outputEndMs) frontier = next;
+			continue;
+		}
+		frontier = next;
+	}
+	return overlaps;
+}
+
+function validateSegments(aroll: ArollSegment[]): void {
+	if (aroll.length === 0 || aroll.length > 1_000) throw new Error("A-roll must contain 1-1000 segments");
+	const ids = new Set<string>();
+	for (const segment of aroll) {
+		if (ids.has(segment.id)) throw new Error(`Duplicate A-roll segment ID: ${segment.id}`);
+		ids.add(segment.id);
+		if (!Number.isFinite(segment.sourceStartMs) || !Number.isFinite(segment.sourceEndMs)
+			|| segment.sourceStartMs < 0 || segment.sourceEndMs <= segment.sourceStartMs) {
+			throw new Error(`Invalid A-roll segment range: ${segment.id}`);
+		}
+	}
+}
+
+function validateNeeds(needs: BrollNeed[], outputDurationMs: number): void {
+	if (needs.length > 500) throw new Error("B-roll plan must contain at most 500 needs");
+	const ids = new Set<string>();
+	for (const need of needs) {
+		if (ids.has(need.id)) throw new Error(`Duplicate B-roll need ID: ${need.id}`);
+		ids.add(need.id);
+		if (!Number.isFinite(need.outputStartMs) || !Number.isFinite(need.outputEndMs)
+			|| need.outputStartMs < 0 || need.outputEndMs <= need.outputStartMs
+			|| need.outputEndMs > outputDurationMs) {
+			throw new Error(`Invalid B-roll need output range: ${need.id}`);
+		}
+	}
+	const overlap = findOverlappingBrollWindows(needs)[0];
+	if (overlap) throw new Error(`B-roll needs ${overlap.underBrollId} and ${overlap.overBrollId} overlap; z-order is not supported`);
+}
+
+function bridgeShortGaps(needs: BrollNeed[], shortGapMs: number): {
+	needs: BrollNeed[];
+	bridges: BrollContinuityBridge[];
+} {
+	const sorted = structuredClone(needs).sort((left, right) => (
+		left.outputStartMs - right.outputStartMs
+		|| left.outputEndMs - right.outputEndMs
+		|| (left.id < right.id ? -1 : left.id > right.id ? 1 : 0)
+	));
+	const bridges: BrollContinuityBridge[] = [];
+	let frontier = sorted[0];
+	let coveredUntilMs = frontier?.outputEndMs ?? 0;
+	for (let index = 1; index < sorted.length; index += 1) {
+		const next = sorted[index]!;
+		if (next.outputStartMs <= coveredUntilMs) {
+			if (next.outputEndMs > coveredUntilMs) {
+				frontier = next;
+				coveredUntilMs = next.outputEndMs;
+			}
+			continue;
+		}
+		const durationMs = next.outputStartMs - coveredUntilMs;
+		if (durationMs > shortGapMs) {
+			frontier = next;
+			coveredUntilMs = next.outputEndMs;
+			continue;
+		}
+		bridges.push({
+			fromNeedId: frontier!.id,
+			toNeedId: next.id,
+			gapStartMs: coveredUntilMs,
+			gapEndMs: next.outputStartMs,
+			durationMs,
+			strategy: "extend-previous-broll",
+		});
+		frontier!.outputEndMs = next.outputStartMs;
+		frontier = next;
+		coveredUntilMs = next.outputEndMs;
+	}
+	return { needs: sorted, bridges };
+}
+
+function coverageForRange(needs: BrollOutputWindow[], startMs: number, endMs: number): {
+	covered: boolean;
+	needIds: string[];
+} {
+	const overlapping = needs.filter((need) => need.outputEndMs > startMs && need.outputStartMs < endMs).sort((left, right) => (
+		left.outputStartMs - right.outputStartMs
+		|| left.outputEndMs - right.outputEndMs
+		|| (left.id < right.id ? -1 : left.id > right.id ? 1 : 0)
+	));
+	let cursor = startMs;
+	const needIds: string[] = [];
+	for (const need of overlapping) {
+		if (need.outputStartMs > cursor) return { covered: false, needIds };
+		needIds.push(need.id);
+		cursor = Math.max(cursor, need.outputEndMs);
+		if (cursor >= endMs) return { covered: true, needIds };
+	}
+	return { covered: false, needIds };
+}
+
+export function analyzeArollJumpCuts(
+	aroll: ArollSegment[],
+	needs: BrollOutputWindow[],
+	outputDurationMs: number,
+	cutCoverBeforeMs: number,
+	cutCoverAfterMs: number,
+): ArollJumpCut[] {
+	const jumpCuts: ArollJumpCut[] = [];
+	let outputTimeMs = 0;
+	for (let index = 0; index < aroll.length - 1; index += 1) {
+		const current = aroll[index]!;
+		const next = aroll[index + 1]!;
+		outputTimeMs += current.sourceEndMs - current.sourceStartMs;
+		const sourceDeltaMs = next.sourceStartMs - current.sourceEndMs;
+		if (sourceDeltaMs === 0) continue;
+		const suggestedOutputStartMs = Math.max(0, outputTimeMs - cutCoverBeforeMs);
+		const suggestedOutputEndMs = Math.min(outputDurationMs, outputTimeMs + cutCoverAfterMs);
+		const coverage = coverageForRange(needs, suggestedOutputStartMs, suggestedOutputEndMs);
+		jumpCuts.push({
+			fromSegmentId: current.id,
+			toSegmentId: next.id,
+			outputTimeMs,
+			sourceDeltaMs,
+			suggestedOutputStartMs,
+			suggestedOutputEndMs,
+			coveredByNeedIds: coverage.needIds,
+			status: coverage.covered ? "covered" : "needs-broll",
+		});
+	}
+	return jumpCuts;
+}
+
+export function planBrollContinuity(input: PlanBrollContinuityInput): BrollContinuityPlan {
+	validateSegments(input.aroll);
+	const outputDurationMs = timelineDuration(input.aroll);
+	validateNeeds(input.needs, outputDurationMs);
+	const shortGapMs = boundedMilliseconds(input.shortGapMs, 500, "shortGapMs", 2_000);
+	const cutCoverBeforeMs = boundedMilliseconds(input.cutCoverBeforeMs, 250, "cutCoverBeforeMs", 2_000);
+	const cutCoverAfterMs = boundedMilliseconds(input.cutCoverAfterMs, 500, "cutCoverAfterMs", 2_000);
+	if (cutCoverBeforeMs === 0 && cutCoverAfterMs === 0) {
+		throw new Error("cutCoverBeforeMs and cutCoverAfterMs cannot both be zero");
+	}
+	const bridged = bridgeShortGaps(input.needs, shortGapMs);
+	return {
+		outputDurationMs,
+		shortGapMs,
+		cutCoverBeforeMs,
+		cutCoverAfterMs,
+		needs: bridged.needs,
+		bridges: bridged.bridges,
+		jumpCuts: analyzeArollJumpCuts(
+			input.aroll,
+			bridged.needs,
+			outputDurationMs,
+			cutCoverBeforeMs,
+			cutCoverAfterMs,
+		),
+	};
+}
+
+function planReceiptPayload(receipt: Omit<BrollContinuityPlanReceipt, "planSha256">): string {
+	return canonicalJson(receipt);
+}
+
+function canonicalJson(value: unknown): string {
+	if (value === null || typeof value !== "object") {
+		const serialized = JSON.stringify(value);
+		if (serialized === undefined) throw new Error("Cannot canonicalize an undefined value");
+		return serialized;
+	}
+	if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+	const object = value as Record<string, unknown>;
+	return `{${Object.keys(object).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(object[key])}`).join(",")}}`;
+}
+
+function sha256(value: string): string {
+	return createHash("sha256").update(value).digest("hex");
+}
+
+function arollSha256(aroll: ArollSegment[]): string {
+	return sha256(canonicalJson(aroll));
+}
+
+function plannedRanges(needs: BrollNeed[]): BrollContinuityPlanReceipt["needs"] {
+	return needs.map((need) => ({
+		id: need.id,
+		outputStartMs: need.outputStartMs,
+		outputEndMs: need.outputEndMs,
+	}));
+}
+
+export function createBrollContinuityPlanReceipt(
+	projectId: string,
+	revision: number,
+	aroll: ArollSegment[],
+	plan: BrollContinuityPlan,
+): BrollContinuityPlanReceipt {
+	const payload: Omit<BrollContinuityPlanReceipt, "planSha256"> = {
+		schemaVersion: 1,
+		projectId,
+		revision,
+		arollSha256: arollSha256(aroll),
+		shortGapMs: plan.shortGapMs,
+		cutCoverBeforeMs: plan.cutCoverBeforeMs,
+		cutCoverAfterMs: plan.cutCoverAfterMs,
+		needs: plannedRanges(plan.needs),
+		jumpCuts: structuredClone(plan.jumpCuts),
+	};
+	return { ...payload, planSha256: sha256(planReceiptPayload(payload)) };
+}
+
+export function verifyBrollContinuityPlanReceipt(
+	projectId: string,
+	revision: number,
+	aroll: ArollSegment[],
+	placements: BrollOutputWindow[],
+	receipt: BrollContinuityPlanReceipt,
+): void {
+	if (receipt.schemaVersion !== 1 || receipt.projectId !== projectId || receipt.revision !== revision) {
+		throw new Error("B-roll continuity receipt does not match the current project revision");
+	}
+	if (receipt.arollSha256 !== arollSha256(aroll)) {
+		throw new Error("B-roll continuity receipt does not match the planned A-roll");
+	}
+	const { planSha256, ...payload } = receipt;
+	if (planSha256 !== sha256(planReceiptPayload(payload))) {
+		throw new Error("B-roll continuity receipt hash is invalid");
+	}
+	const dummyNeeds: BrollNeed[] = receipt.needs.map((need) => ({
+		...need,
+		speechText: "continuity receipt",
+		purpose: "mask-cut",
+		searchTerms: ["continuity"],
+		reason: "continuity receipt verification",
+	}));
+	const recomputed = planBrollContinuity({
+		aroll,
+		needs: dummyNeeds,
+		shortGapMs: receipt.shortGapMs,
+		cutCoverBeforeMs: receipt.cutCoverBeforeMs,
+		cutCoverAfterMs: receipt.cutCoverAfterMs,
+	});
+	if (canonicalJson(plannedRanges(recomputed.needs)) !== canonicalJson(receipt.needs)
+		|| canonicalJson(recomputed.jumpCuts) !== canonicalJson(receipt.jumpCuts)) {
+		throw new Error("B-roll continuity receipt does not match the recomputed plan");
+	}
+	const actualRanges = [...placements].sort((left, right) => (
+		left.outputStartMs - right.outputStartMs || left.outputEndMs - right.outputEndMs
+	)).map((placement) => ({
+		id: placement.id,
+		outputStartMs: placement.outputStartMs,
+		outputEndMs: placement.outputEndMs,
+	}));
+	if (canonicalJson(actualRanges) !== canonicalJson(receipt.needs)) {
+		throw new Error("B-roll placements do not match the planned ranges");
+	}
+}

package/src/contracts.ts

@@ -95,13 +95,118 @@ 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 BrollContinuityBridge {
+	fromNeedId: string;
+	toNeedId: string;
+	gapStartMs: number;
+	gapEndMs: number;
+	durationMs: number;
+	strategy: "extend-previous-broll";
+}
+
+export interface ArollJumpCut {
+	fromSegmentId: string;
+	toSegmentId: string;
+	outputTimeMs: number;
+	sourceDeltaMs: number;
+	suggestedOutputStartMs: number;
+	suggestedOutputEndMs: number;
+	coveredByNeedIds: string[];
+	status: "covered" | "needs-broll";
+}
+
+export interface BrollContinuityPlan {
+	outputDurationMs: number;
+	shortGapMs: number;
+	cutCoverBeforeMs: number;
+	cutCoverAfterMs: number;
+	needs: BrollNeed[];
+	bridges: BrollContinuityBridge[];
+	jumpCuts: ArollJumpCut[];
+}
+
+export interface BrollContinuityPlanReceipt {
+	schemaVersion: 1;
+	projectId: string;
+	revision: number;
+	arollSha256: string;
+	shortGapMs: number;
+	cutCoverBeforeMs: number;
+	cutCoverAfterMs: number;
+	needs: Array<{ id: string; outputStartMs: number; outputEndMs: number }>;
+	jumpCuts: ArollJumpCut[];
+	planSha256: string;
+}
 
 export interface TranscriptAnalysis {
 	schemaVersion: 2;
@@ -147,6 +252,8 @@ export interface TalkingHeadSnapshot {
 	policy: TalkingHeadPolicy;
 	aroll: ArollSegment[];
 	broll: BrollPlacement[];
+	continuityPlanReceipt?: BrollContinuityPlanReceipt;
+	jumpCuts?: ArollJumpCut[];
 	outputDurationMs: number;
 }
 

package/src/project.ts

@@ -5,6 +5,7 @@ import type {
 	ArollSegment,
 	BrollPlacement,
 	BrollPlacementInput,
+	BrollContinuityPlanReceipt,
 	FillerCandidate,
 	PauseCandidate,
 	RepetitionCandidate,
@@ -16,6 +17,13 @@ import type {
 	TranscriptWord,
 	WordTranscript,
 } from "./contracts.ts";
+import { verifyBrollPlacementSelection } from "./broll.ts";
+import {
+	analyzeArollJumpCuts,
+	findOverlappingBrollWindows,
+	findShortArollFlashGaps,
+	verifyBrollContinuityPlanReceipt,
+} from "./continuity.ts";
 import { analyzeTranscript, DEFAULT_POLICY, timelineDuration } from "./transcript.ts";
 import { resolveExistingWorkspaceFile, resolveWorkspacePath, snapshotFile, workspaceRelativePath } from "./workspace.ts";
 
@@ -33,6 +41,7 @@ export interface ApplyTimelineInput {
 	expectedRevision: number;
 	aroll: ArollSegment[];
 	broll: BrollPlacementInput[];
+	continuityPlanReceipt?: BrollContinuityPlanReceipt;
 }
 
 function assertProjectId(projectId: string): void {
@@ -77,7 +86,11 @@ async function validateTimeline(
 	cwd: string,
 	aroll: ArollSegment[],
 	broll: BrollPlacementInput[],
-): Promise<{ outputDurationMs: number; broll: BrollPlacement[] }> {
+	projectId: string,
+	revision: number,
+	continuityPlanReceipt: BrollContinuityPlanReceipt | undefined,
+	signal?: AbortSignal,
+): Promise<{ outputDurationMs: number; broll: BrollPlacement[]; jumpCuts: ReturnType<typeof analyzeArollJumpCuts> }> {
 	if (aroll.length === 0 || aroll.length > 1_000) throw new Error("A-roll must contain 1-1000 segments");
 	uniqueIds(aroll, "A-roll segment");
 	for (const segment of aroll) {
@@ -89,7 +102,6 @@ async function validateTimeline(
 	const outputDurationMs = timelineDuration(aroll);
 	if (broll.length > 500) throw new Error("B-roll must contain at most 500 placements");
 	uniqueIds(broll, "B-roll placement");
-	const normalizedBroll: BrollPlacement[] = [];
 	for (const placement of broll) {
 		if (!Number.isFinite(placement.outputStartMs) || !Number.isFinite(placement.outputEndMs)
 			|| placement.outputStartMs < 0 || placement.outputEndMs <= placement.outputStartMs) {
@@ -98,11 +110,30 @@ 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 overlap = findOverlappingBrollWindows(broll)[0];
+	if (overlap) {
+		throw new Error(`B-roll placements ${overlap.underBrollId} and ${overlap.overBrollId} overlap; ambiguous z-order is not supported`);
+	}
+	const flashGap = findShortArollFlashGaps(broll, 500)[0];
+	if (flashGap) {
+		throw new Error(`B-roll placements ${flashGap.fromBrollId} and ${flashGap.toBrollId} leave a brief ${flashGap.durationMs}ms A-roll flash; run talking_head_broll_plan and reselect the bridged window`);
+	}
+	if (broll.length > 0 && !continuityPlanReceipt) {
+		throw new Error("B-roll continuityPlanReceipt is required; run talking_head_broll_plan first");
+	}
+	if (continuityPlanReceipt) {
+		verifyBrollContinuityPlanReceipt(projectId, revision, aroll, broll, continuityPlanReceipt);
+	}
+	const normalizedBroll: BrollPlacement[] = [];
+	for (const placement of broll) {
+		signal?.throwIfAborted();
+		const asset = await verifyBrollPlacementSelection(cwd, placement, signal);
 		normalizedBroll.push({
 			...structuredClone(placement),
 			assetPath: asset.path,
@@ -110,7 +141,13 @@ async function validateTimeline(
 			assetSha256: asset.sha256,
 		});
 	}
-	return { outputDurationMs, broll: normalizedBroll };
+	return {
+		outputDurationMs,
+		broll: normalizedBroll,
+		jumpCuts: continuityPlanReceipt
+			? structuredClone(continuityPlanReceipt.jumpCuts)
+			: analyzeArollJumpCuts(aroll, broll, outputDurationMs, 250, 500),
+	};
 }
 
 function summary(analysis: TranscriptAnalysis) {
@@ -177,6 +214,7 @@ export async function createTalkingHeadProject(cwd: string, input: CreateTalking
 		policy,
 		aroll: analysis.segments,
 		broll: [],
+		jumpCuts: analyzeArollJumpCuts(analysis.segments, [], analysis.outputDurationMs, 250, 500),
 		outputDurationMs: analysis.outputDurationMs,
 	};
 	try {
@@ -233,7 +271,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 {
@@ -244,7 +282,15 @@ 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,
+			input.projectId,
+			input.expectedRevision,
+			input.continuityPlanReceipt,
+			signal,
+		);
 		const revision = project.currentRevision + 1;
 		const now = new Date().toISOString();
 		const snapshot: TalkingHeadSnapshot = {
@@ -256,6 +302,10 @@ export async function applyTimeline(cwd: string, input: ApplyTimelineInput): Pro
 			policy: current.policy,
 			aroll: structuredClone(input.aroll),
 			broll: validated.broll,
+			jumpCuts: validated.jumpCuts,
+			...(input.continuityPlanReceipt === undefined
+				? {}
+				: { continuityPlanReceipt: structuredClone(input.continuityPlanReceipt) }),
 			outputDurationMs: validated.outputDurationMs,
 		};
 		await writeJson(join(directory, "snapshots", `${revision}.json`), snapshot, true);

package/src/workspace.ts

@@ -39,6 +39,17 @@ export async function resolveExistingWorkspaceFile(cwd: string, inputPath: strin
 	return canonical;
 }
 
+export async function resolveExistingWorkspaceDirectory(cwd: string, inputPath: string): Promise<string> {
+	const root = await workspaceRoot(cwd);
+	const lexical = resolve(root, inputPath);
+	if (!isWithin(root, lexical)) throw new Error(`Path is outside the workspace: ${inputPath}`);
+	if ((await lstat(lexical)).isSymbolicLink()) throw new Error(`Unsafe workspace-directory symlink: ${inputPath}`);
+	const canonical = await realpath(lexical);
+	if (!isWithin(root, canonical)) throw new Error(`Path resolves outside the workspace: ${inputPath}`);
+	if (!(await stat(canonical)).isDirectory()) throw new Error(`Path is not a directory: ${inputPath}`);
+	return canonical;
+}
+
 export async function resolveWorkspacePath(cwd: string, inputPath: string): Promise<string> {
 	const root = await workspaceRoot(cwd);
 	const lexical = resolve(root, inputPath);
@@ -55,17 +66,20 @@ export async function workspaceRelativePath(cwd: string, absolutePath: string):
 	return relative(root, absolutePath).split(sep).join("/");
 }
 
-async function sha256File(path: string): Promise<string> {
+async function sha256File(path: string, signal?: AbortSignal): Promise<string> {
+	signal?.throwIfAborted();
 	const hash = createHash("sha256");
-	for await (const chunk of createReadStream(path)) hash.update(chunk);
+	for await (const chunk of createReadStream(path, signal === undefined ? {} : { signal })) hash.update(chunk);
+	signal?.throwIfAborted();
 	return hash.digest("hex");
 }
 
-export async function snapshotFile(cwd: string, inputPath: string): Promise<FileRef> {
+export async function snapshotFile(cwd: string, inputPath: string, signal?: AbortSignal): Promise<FileRef> {
+	signal?.throwIfAborted();
 	const absolute = await resolveExistingWorkspaceFile(cwd, inputPath);
 	return {
 		path: await workspaceRelativePath(cwd, absolute),
 		bytes: (await stat(absolute)).size,
-		sha256: await sha256File(absolute),
+		sha256: await sha256File(absolute, signal),
 	};
 }