Skip to content

armgit / Cap

Public Imported from GitHub
0

Open source Loom alternative. Beautiful, shareable screen recordings.

51.7 KB
Raw Blame
import type { User, Video } from "@cap/web-domain";
import { Effect, Option } from "effect";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import type {
	DesktopRecordingAttempt,
	DesktopRecordingJob,
} from "@/lib/desktop-recording-jobs";
import type { DesktopRecordingSourceCheckpoint } from "@/lib/desktop-recording-source-checkpoint";
import type { RecordingVerification } from "@/lib/desktop-recording-verification";
import { MediaProcessingBudgetError } from "@/lib/media-processing-budget";
import sourceCommitTimings from "../fixtures/source-commit-timings.json";

const mocks = vi.hoisted(() => ({
	state: vi.fn(),
	claim: vi.fn(),
	ensure: vi.fn(),
	persist: vi.fn(),
	heartbeat: vi.fn(),
	waitCapacity: vi.fn(),
	blocked: vi.fn(),
	retry: vi.fn(),
	attach: vi.fn(),
	defer: vi.fn(),
	commitSource: vi.fn(),
	checkpoint: vi.fn(),
	saveCheckpoint: vi.fn(),
	sourceUrls: vi.fn(),
	preverifiedRunUrls: vi.fn(async (): Promise<string[]> => []),
	observe: vi.fn(),
	sleep: vi.fn(),
	env: vi.fn(),
	transcribe: vi.fn(),
	fetch: vi.fn(),
	put: vi.fn(),
	databaseRows: vi.fn(),
	reserveBudget: vi.fn(),
	storage: vi.fn(),
	multipartCreate: vi.fn(),
	// Plain calls stand in for a step's last try; retry tests lower the attempt.
	stepMetadata: vi.fn(() => ({ stepId: "step_test", attempt: 4 })),
}));
vi.mock("@/lib/media-processing-budget", () => ({
	reserveMediaProcessingBudget: mocks.reserveBudget,
	MediaProcessingBudgetError: class extends Error {
		constructor(readonly scope: "recording") {
			super(scope);
		}
	},
}));
vi.mock("@cap/database", () => ({
	db: () => ({
		select: () => ({
			from: () => ({
				where: mocks.databaseRows,
			}),
		}),
	}),
}));
vi.mock("@cap/database/schema", () => ({ users: {}, videos: {} }));
vi.mock("drizzle-orm", () => ({ and: vi.fn(), eq: vi.fn() }));
vi.mock("@cap/env", () => ({ serverEnv: mocks.env }));
vi.mock("workflow", () => ({
	sleep: mocks.sleep,
	getStepMetadata: () => mocks.stepMetadata(),
}));
vi.mock("@/lib/desktop-recording-jobs", () => ({
	getProcessingState: mocks.state,
	claimProcessingAttempt: mocks.claim,
	ensureSegmentProcessingJob: mocks.ensure,
	persistCommittedSource: mocks.persist,
	initializeSourceCommitCheckpoint: mocks.checkpoint,
	persistSourceCommitCheckpoint: mocks.saveCheckpoint,
	heartbeatAttempt: mocks.heartbeat,
	waitForDesktopRecordingCapacity: mocks.waitCapacity,
	markSourceBlocked: mocks.blocked,
	scheduleRetry: mocks.retry,
	attachRemoteJob: mocks.attach,
	deferWithoutMediaServer: mocks.defer,
}));
vi.mock("@/lib/desktop-recording-source", () => ({
	advanceDesktopRecordingSourceCommit: mocks.commitSource,
	buildDesktopRecordingSourceUrls: mocks.sourceUrls,
	buildPreverifiedRunUrls: mocks.preverifiedRunUrls,
	getDesktopRecordingOutputKey: (
		owner: string,
		video: string,
		generation: string,
		attempt: string,
	) => `${owner}/${video}/.recording/outputs/${generation}/${attempt}.mp4`,
}));
vi.mock("@/lib/desktop-recording-job-status", () => ({
	observeDesktopRecordingJob: mocks.observe,
}));
vi.mock("@/lib/ai-generation-entitlement", () => ({
	isAiGenerationEnabledForUser: () => false,
}));
vi.mock("@/lib/google-drive-storage-quota-cache", () => ({
	invalidateGoogleDriveStorageQuotaCache: vi.fn(),
}));
vi.mock("@/lib/transcribe", () => ({ transcribeVideo: mocks.transcribe }));
vi.mock("@/lib/video-storage", () => ({ decodeStorageVideo: () => ({}) }));
vi.mock("@/lib/workflow-runtime", async () => ({
	runWorkflowPromise: (await import("effect")).Effect.runPromise,
}));
vi.mock("@cap/web-backend/src/Storage/index", async () => {
	const { Effect } = await import("effect");
	return {
		Storage: {
			getAccessForVideo: () => Effect.sync(mocks.storage),
		},
	};
});

import {
	acquireAndStartDesktopRecordingAttempt,
	commitAndStartDesktopRecordingAttempt,
	commitDesktopRecordingAttempt,
	finalizeDesktopRecordingWorkflow,
	pollDesktopRecordingAttempt,
	startDesktopRecordingJob,
} from "@/workflows/finalize-desktop-recording";

const videoId = "video" as Video.VideoId;
const userId = "user" as User.UserId;
const now = new Date("2026-09-02T12:00:00Z");
const source = {
	version: 1 as const,
	kind: "segments" as const,
	manifestSha256: "a".repeat(64),
	inventorySha256: "b".repeat(64),
	inventoryKey: "user/video/.recording/sources/generation/inventory.json",
	requiredAudio: true,
};
const fixture: DesktopRecordingAttempt = {
	videoId,
	ownerId: userId,
	generation: "generation",
	state: "processing",
	attemptId: "attempt",
	attemptCount: 1,
	manifestSha256: source.manifestSha256,
	leaseExpiresAt: new Date(now.getTime() + 5 * 60_000),
	nextRetryAt: now,
	workflowRunId: "run",
	remoteJobId: null,
	source,
	verification: null,
	output: null,
	errorCode: null,
	errorMessage: null,
	createdAt: now,
	updatedAt: now,
};
let current: DesktopRecordingJob | null;

function storageAccess(provider: string, customBucket = false) {
	return [
		{
			provider,
			getInternalSignedObjectUrl: (key: string) =>
				Effect.succeed(`https://storage.test/${key}`),
			getInternalPresignedPutUrl: mocks.put,
			multipart: { create: mocks.multipartCreate },
		},
		customBucket ? Option.some({ id: "bucket" }) : Option.none(),
	];
}

function withCurrent(update: Partial<DesktopRecordingJob>) {
	if (!current) throw new Error("Fixture job disappeared");
	current = { ...current, ...update };
}

beforeEach(() => {
	mocks.stepMetadata.mockReturnValue({ stepId: "step_test", attempt: 4 });
	mocks.preverifiedRunUrls.mockResolvedValue([]);
	mocks.reserveBudget.mockResolvedValue(100_000_000);
	mocks.storage.mockImplementation(() => storageAccess("test"));
	mocks.multipartCreate.mockImplementation(() =>
		Effect.succeed({ UploadId: "upload" }),
	);
	mocks.databaseRows.mockResolvedValue([
		{ id: "video", ownerId: "user", source: { type: "desktopSegments" } },
	]);
	vi.useFakeTimers({ toFake: ["Date"] });
	vi.setSystemTime(now);
	current = { ...fixture };
	mocks.state.mockImplementation(async () => (current ? { ...current } : null));
	mocks.ensure.mockImplementation(async () => ({
		job: current,
		created: false,
	}));
	mocks.claim.mockImplementation(async () => {
		if (!current) return null;
		withCurrent({
			state: current.source ? "processing" : "committing",
			attemptId: `attempt-${current.attemptCount + 1}`,
			attemptCount: current.attemptCount + 1,
			leaseExpiresAt: new Date(Date.now() + 5 * 60_000),
			updatedAt: new Date(),
			remoteJobId: null,
		});
		return current;
	});
	mocks.persist.mockImplementation(async (_attempt, savedSource) => {
		withCurrent({ source: savedSource, state: "processing" });
		return true;
	});
	mocks.waitCapacity.mockResolvedValue(true);
	mocks.heartbeat.mockImplementation(async () => {
		withCurrent({ leaseExpiresAt: new Date(Date.now() + 5 * 60_000) });
		return true;
	});
	mocks.retry.mockImplementation(
		async ({ nextRetryAt }: { nextRetryAt?: Date }) => {
			withCurrent({
				state: "retry",
				leaseExpiresAt: null,
				nextRetryAt: nextRetryAt ?? new Date(Date.now() + 15_000),
			});
			return true;
		},
	);
	mocks.blocked.mockImplementation(async () => {
		withCurrent({ state: "source-blocked", leaseExpiresAt: null });
		return true;
	});
	mocks.attach.mockImplementation(async ({ remoteJobId }) => {
		withCurrent({ remoteJobId });
		return true;
	});

	mocks.defer.mockImplementation(async () => {
		withCurrent({ state: "queued", leaseExpiresAt: null });
		return true;
	});
	mocks.commitSource.mockResolvedValue({ source });
	mocks.checkpoint.mockImplementation(
		async () =>
			current?.output ?? {
				kind: "desktop-recording-source-commit",
				version: 1,
				generation: fixture.generation,
				snapshotId: "snapshot",
				revision: 0,
				phase: "plan",
				cursor: 0,
				planRoots: [],
				receiptRoots: [],
			},
	);
	mocks.saveCheckpoint.mockImplementation(async (_fence, checkpoint) => {
		withCurrent({ output: checkpoint });
		return true;
	});
	mocks.sourceUrls.mockResolvedValue({
		videoInitUrl: "https://source.test/init.mp4",
		videoSegmentUrls: ["https://source.test/segment.m4s"],
		sourceObjects: [
			{
				url: "https://source.test/init.mp4",
				objectIdentity: '"init"',
				size: 100,
			},
			{
				url: "https://source.test/segment.m4s",
				objectIdentity: '"segment"',
				size: 1000,
			},
		],
		manifestSha256: source.manifestSha256,
		inventorySha256: source.inventorySha256,
	});
	mocks.observe.mockImplementation(async () => {
		withCurrent({ state: "verified" });
		return { status: "terminal", delivered: true };
	});
	mocks.sleep.mockImplementation(async (delay: number | Date) =>
		vi.setSystemTime(
			delay instanceof Date ? delay : new Date(Date.now() + delay),
		),
	);
	mocks.env.mockReturnValue({
		MEDIA_SERVER_URL: "https://media.test",
		MEDIA_SERVER_WEBHOOK_SECRET: "secret",
		ASSEMBLY_API_KEY: "assembly-test",
		WEB_URL: "https://cap.test",
	});
	mocks.transcribe.mockResolvedValue({ success: true });
	mocks.put.mockImplementation((key: string) =>
		Effect.succeed(`https://storage.test/${key}`),
	);
	mocks.fetch.mockResolvedValue(Response.json({ jobId: "remote-job" }));
	vi.stubGlobal("fetch", mocks.fetch);
});

describe("durable post-publication transcription enqueue", () => {
	it.each(["returned failure", "thrown failure"])(
		"retries %s without creating another media attempt",
		async (failure) => {
			withCurrent({ leaseExpiresAt: null });
			if (failure === "returned failure")
				mocks.transcribe.mockResolvedValueOnce({
					success: false,
					message: "Queue unavailable",
				});
			else
				mocks.transcribe.mockRejectedValueOnce(new Error("Queue unavailable"));
			const result = await finalizeDesktopRecordingWorkflow({
				videoId,
				userId,
				generation: fixture.generation,
			});
			expect(result).toMatchObject({ success: true, jobId: "remote-job" });
			expect(mocks.transcribe).toHaveBeenCalledTimes(2);
			expect(mocks.fetch).toHaveBeenCalledOnce();
			expect(mocks.claim).toHaveBeenCalledOnce();
			expect(mocks.retry).not.toHaveBeenCalled();
			expect(current?.state).toBe("verified");
			expect(mocks.sleep.mock.calls).toEqual([[15_000], [15_000]]);
		},
	);

	it("resumes failed enqueue from an already verified recording without remuxing", async () => {
		withCurrent({ state: "verified" });
		mocks.transcribe.mockResolvedValueOnce({
			success: false,
			message: "Temporary queue error",
		});
		expect(
			await finalizeDesktopRecordingWorkflow({
				videoId,
				userId,
				generation: fixture.generation,
			}),
		).toEqual({ success: true });
		expect(mocks.transcribe).toHaveBeenCalledTimes(2);
		expect(mocks.fetch).not.toHaveBeenCalled();
		expect(mocks.claim).not.toHaveBeenCalled();
	});

	it("finishes after repeated transcription queue failures", async () => {
		withCurrent({ state: "verified" });
		mocks.transcribe.mockResolvedValue({
			success: false,
			message: "Queue unavailable",
		});
		mocks.sleep.mockImplementation(async () => {
			if (mocks.transcribe.mock.calls.length >= 12) {
				throw new Error("Transcription retry limit exceeded");
			}
		});

		await expect(
			finalizeDesktopRecordingWorkflow({
				videoId,
				userId,
				generation: fixture.generation,
			}),
		).resolves.toEqual({ success: true });
		expect(mocks.transcribe).toHaveBeenCalledTimes(12);
		expect(mocks.fetch).not.toHaveBeenCalled();
		expect(mocks.claim).not.toHaveBeenCalled();
	});

	it.each(["unconfigured", "deleted"])(
		"skips %s transcription without retrying forever",
		async (reason) => {
			withCurrent({ state: "verified" });
			if (reason === "unconfigured") mocks.env.mockReturnValue({});
			else mocks.databaseRows.mockResolvedValue([]);
			expect(
				await finalizeDesktopRecordingWorkflow({
					videoId,
					userId,
					generation: fixture.generation,
				}),
			).toEqual({ success: true });
			expect(mocks.transcribe).not.toHaveBeenCalled();
			expect(mocks.sleep).not.toHaveBeenCalled();
		},
	);
});

afterEach(() => {
	vi.useRealTimers();
	vi.unstubAllGlobals();
});

function pollingInput() {
	return {
		videoId,
		generation: fixture.generation,
		attemptId: fixture.attemptId,
		jobId: "remote-job",
		deadline: new Date(now.getTime() + 2 * 60 * 60_000),
	};
}

describe("short durable processing polls", () => {
	it("keeps an unchanged stage alive from durable heartbeats while every status lookup misses", async () => {
		withCurrent({ remoteJobId: "owning-replica" });
		mocks.observe.mockResolvedValue({
			status: "unavailable",
			delivered: false,
		});
		for (let minute = 1; minute <= 10; minute++) {
			vi.setSystemTime(new Date(now.getTime() + minute * 60_000));
			withCurrent({ leaseExpiresAt: new Date(Date.now() + 5 * 60_000) });
			expect(await pollDesktopRecordingAttempt(pollingInput())).toBe("waiting");
		}
		expect(mocks.observe).toHaveBeenLastCalledWith(
			expect.objectContaining({ jobId: "owning-replica" }),
		);
		expect(mocks.retry).not.toHaveBeenCalled();
		expect(mocks.heartbeat).not.toHaveBeenCalled();
	});

	it("does not renew an owned worker from a status probe", async () => {
		mocks.observe.mockResolvedValue({
			status: "active",
			delivered: false,
			workerProtocol: 1,
		});
		expect(await pollDesktopRecordingAttempt(pollingInput())).toBe("waiting");
		expect(mocks.heartbeat).not.toHaveBeenCalled();
		vi.setSystemTime(new Date(now.getTime() + 5 * 60_000));
		expect(await pollDesktopRecordingAttempt(pollingInput())).toBe("retry");
		expect(mocks.heartbeat).not.toHaveBeenCalled();
	});

	it.each(["processing-timeout", "worker-lease-expired"])(
		"does not reuse a rich attempt's stale retry date after %s",
		async (errorCode) => {
			withCurrent({ leaseExpiresAt: new Date(now.getTime() - 1) });
			mocks.observe.mockResolvedValue({
				status: "unavailable",
				delivered: false,
			});
			const input = {
				...fixture,
				...pollingInput(),
				nextRetryAt: new Date(now.getTime() - 60_000),
				...(errorCode === "processing-timeout" ? { deadline: now } : {}),
			};
			expect(await pollDesktopRecordingAttempt(input)).toBe("retry");
			expect(current?.nextRetryAt).toEqual(new Date(now.getTime() + 15_000));
			expect(mocks.retry.mock.calls[0]?.[0]).not.toHaveProperty("nextRetryAt");
			expect(mocks.retry.mock.calls[0]?.[0]).toMatchObject({
				videoId,
				generation: fixture.generation,
				attemptId: fixture.attemptId,
				errorCode,
			});
		},
	);

	it("does not treat a delivered terminal webhook as durable success until publication is committed", async () => {
		mocks.observe.mockResolvedValue({ status: "terminal", delivered: true });
		expect(await pollDesktopRecordingAttempt(pollingInput())).toBe("waiting");
		expect(mocks.sleep).not.toHaveBeenCalled();
		expect(mocks.heartbeat).not.toHaveBeenCalled();
	});

	it("returns success only from the current durable verified state", async () => {
		withCurrent({ state: "verified" });
		expect(await pollDesktopRecordingAttempt(pollingInput())).toBe("verified");
		expect(mocks.observe).not.toHaveBeenCalled();
	});

	it("does not extend a lease when the remote worker is missing", async () => {
		mocks.observe.mockResolvedValue({
			status: "unavailable",
			delivered: false,
		});
		expect(await pollDesktopRecordingAttempt(pollingInput())).toBe("waiting");
		expect(mocks.heartbeat).not.toHaveBeenCalled();
		vi.setSystemTime(new Date(now.getTime() + 6 * 60_000));
		expect(await pollDesktopRecordingAttempt(pollingInput())).toBe("retry");
		expect(current?.source).toEqual(source);
		expect(mocks.retry).toHaveBeenCalledWith(
			expect.objectContaining({
				errorCode: "worker-lease-expired",
				generation: "generation",
				attemptId: "attempt",
			}),
		);
	});

	it("renews only a positively observed matching active attempt", async () => {
		mocks.observe.mockResolvedValue({ status: "active", delivered: false });
		expect(await pollDesktopRecordingAttempt(pollingInput())).toBe("waiting");
		expect(mocks.heartbeat).toHaveBeenCalledWith({
			videoId,
			generation: "generation",
			attemptId: "attempt",
		});
		expect(mocks.observe).toHaveBeenCalledWith(
			expect.objectContaining({
				inventorySha256: source.inventorySha256,
				generation: "generation",
				attemptId: "attempt",
			}),
		);
	});

	it("ignores an older workflow after another attempt takes over", async () => {
		withCurrent({ attemptId: "new-attempt" });
		expect(await pollDesktopRecordingAttempt(pollingInput())).toBe(
			"superseded",
		);
		expect(mocks.observe).not.toHaveBeenCalled();
		expect(mocks.retry).not.toHaveBeenCalled();
	});
});

describe("bounded source commitment steps", () => {
	beforeEach(() => {
		withCurrent({ source: null, state: "committing" });
	});

	function advanceCheckpoint(
		_video: unknown,
		checkpoint: DesktopRecordingSourceCheckpoint,
	) {
		return { checkpoint: { ...checkpoint, revision: checkpoint.revision + 1 } };
	}

	it.each(sourceCommitTimings)(
		"replays the $name production timings without repeating or skipping a page",
		async ({ pageDurationsMs, expectedBatchedSteps, terminalResult }) => {
			const revisions: number[] = [];
			mocks.commitSource.mockImplementation(async (_video, checkpoint) => {
				const duration = pageDurationsMs[checkpoint.revision];
				if (duration === undefined) throw new Error("Unexpected source page");
				vi.setSystemTime(Date.now() + duration);
				revisions.push(checkpoint.revision);
				if (checkpoint.revision + 1 < pageDurationsMs.length)
					return advanceCheckpoint(_video, checkpoint);
				if (terminalResult === "source-blocked")
					throw Object.assign(new Error("Manifest is incomplete"), {
						code: "source-incomplete",
					});
				return { source };
			});
			let batches = 0;
			let result: Awaited<ReturnType<typeof commitDesktopRecordingAttempt>>;
			do {
				if (++batches > pageDurationsMs.length)
					throw new Error("Source preparation did not terminate");
				result = await commitDesktopRecordingAttempt(fixture);
			} while (result === "progress");
			expect(result).toBe(terminalResult);
			expect(batches).toBe(expectedBatchedSteps);
			expect(revisions).toEqual(pageDurationsMs.map((_, index) => index));
			expect(mocks.saveCheckpoint).toHaveBeenCalledTimes(
				pageDurationsMs.length - 1,
			);
			expect(mocks.persist).toHaveBeenCalledTimes(
				terminalResult === "ready" ? 1 : 0,
			);
		},
	);

	it("persists every page before advancing and commits only once after a lost step response", async () => {
		const revisions: number[] = [];
		mocks.commitSource.mockImplementation(async (_video, checkpoint) => {
			expect(current?.output).toEqual(
				checkpoint.revision === 0 ? null : checkpoint,
			);
			revisions.push(checkpoint.revision);
			return checkpoint.revision === 4
				? { source }
				: advanceCheckpoint(_video, checkpoint);
		});
		expect(await commitDesktopRecordingAttempt(fixture)).toBe("ready");
		expect(revisions).toEqual([0, 1, 2, 3, 4]);
		expect(mocks.saveCheckpoint).toHaveBeenCalledTimes(4);
		expect(await commitDesktopRecordingAttempt(fixture)).toBe("ready");
		expect(mocks.commitSource).toHaveBeenCalledTimes(5);
		expect(mocks.persist).toHaveBeenCalledOnce();
		expect(mocks.fetch).not.toHaveBeenCalled();
	});

	it.each([
		[0, 128],
		[-1, 128],
		[1_000, 45],
		[14_999, 4],
		[15_000, 3],
		[44_999, 2],
		[45_000, 1],
		[180_000, 1],
	])("yields after bounded work with %i ms pages", async (duration, pages) => {
		mocks.commitSource.mockImplementation(async (_video, checkpoint) => {
			vi.setSystemTime(Date.now() + duration);
			return advanceCheckpoint(_video, checkpoint);
		});
		expect(await commitDesktopRecordingAttempt(fixture)).toBe("progress");
		expect(mocks.commitSource).toHaveBeenCalledTimes(pages);
		expect(mocks.saveCheckpoint).toHaveBeenCalledTimes(pages);
		expect(current?.output).toMatchObject({ revision: pages });
		expect(mocks.persist).not.toHaveBeenCalled();
	});

	it("logs the timing of every commit page without storage keys", async () => {
		let clock = 0;
		const now = vi.spyOn(performance, "now").mockImplementation(() => clock);
		mocks.commitSource.mockImplementation(
			async (_video, checkpoint, _verification, onProgress) => {
				clock += 5;
				await onProgress();
				clock += 100;
				if (checkpoint.revision === 1) return { source };
				return {
					checkpoint: {
						...checkpoint,
						phase: "copy",
						revision: checkpoint.revision + 1,
					},
				};
			},
		);
		mocks.heartbeat.mockImplementation(async () => {
			clock += 7;
			return true;
		});
		mocks.saveCheckpoint.mockImplementation(async (_attempt, checkpoint) => {
			clock += 20;
			withCurrent({ output: checkpoint });
			return true;
		});
		mocks.persist.mockImplementation(async (_attempt, savedSource) => {
			clock += 30;
			withCurrent({ source: savedSource, state: "processing" });
			return true;
		});
		const info = vi.spyOn(console, "info").mockImplementation(() => {});
		try {
			expect(await commitDesktopRecordingAttempt(fixture)).toBe("ready");
			const events = info.mock.calls
				.map(([line]) => JSON.parse(String(line)))
				.filter((event) => event.event === "desktop_source_commit_advance");
			expect(events).toEqual([
				{
					event: "desktop_source_commit_advance",
					videoId: "video",
					attemptId: "attempt",
					phase: "plan",
					next: "copy",
					outcome: "progress",
					loadMs: 0,
					heartbeatMs: 7,
					advanceMs: 112,
					persistMs: 20,
				},
				{
					event: "desktop_source_commit_advance",
					videoId: "video",
					attemptId: "attempt",
					phase: "copy",
					next: "committed",
					outcome: "ready",
					loadMs: 0,
					heartbeatMs: 7,
					advanceMs: 112,
					persistMs: 30,
				},
			]);
			expect(JSON.stringify(events)).not.toContain(source.inventoryKey);
		} finally {
			info.mockRestore();
			now.mockRestore();
		}
	});

	it("dispatches in the same step when the commit finishes inside its batch budget", async () => {
		withCurrent({ source: null });
		mocks.commitSource.mockResolvedValue({ source });
		await expect(
			commitAndStartDesktopRecordingAttempt(fixture),
		).resolves.toEqual({
			committed: "ready",
			dispatched: true,
			started: "remote-job",
		});
		expect(mocks.persist).toHaveBeenCalledOnce();
		expect(mocks.fetch).toHaveBeenCalledOnce();
	});

	it("returns the accepted job without committing or dispatching again when the combined step is retried", async () => {
		withCurrent({ source: null });
		mocks.commitSource.mockResolvedValue({ source });
		mocks.attach.mockImplementation(
			async ({ remoteJobId }: { remoteJobId: string }) => {
				withCurrent({ remoteJobId });
				return true;
			},
		);
		await expect(
			commitAndStartDesktopRecordingAttempt(fixture),
		).resolves.toEqual({
			committed: "ready",
			dispatched: true,
			started: "remote-job",
		});
		await expect(
			commitAndStartDesktopRecordingAttempt(fixture),
		).resolves.toEqual({
			committed: "ready",
			dispatched: true,
			started: "remote-job",
		});
		expect(mocks.commitSource).toHaveBeenCalledOnce();
		expect(mocks.persist).toHaveBeenCalledOnce();
		expect(mocks.fetch).toHaveBeenCalledOnce();
		expect(mocks.sourceUrls).toHaveBeenCalledOnce();
	});

	it("leaves dispatch to its own step after a slow commit", async () => {
		withCurrent({ source: null });
		mocks.commitSource.mockImplementation(async () => {
			vi.setSystemTime(Date.now() + 45_000);
			return { source };
		});
		await expect(
			commitAndStartDesktopRecordingAttempt(fixture),
		).resolves.toEqual({ committed: "ready" });
		expect(mocks.fetch).not.toHaveBeenCalled();
	});

	it("does not dispatch while the source commit is still in progress", async () => {
		withCurrent({ source: null });
		mocks.commitSource.mockImplementation(async (_video, checkpoint) => {
			vi.setSystemTime(Date.now() + 45_000);
			return advanceCheckpoint(_video, checkpoint);
		});
		await expect(
			commitAndStartDesktopRecordingAttempt(fixture),
		).resolves.toEqual({ committed: "progress" });
		expect(mocks.fetch).not.toHaveBeenCalled();
	});

	it("includes checkpoint persistence latency in the batch budget", async () => {
		mocks.commitSource.mockImplementation(advanceCheckpoint);
		mocks.saveCheckpoint.mockImplementation(async (_attempt, checkpoint) => {
			withCurrent({ output: checkpoint });
			vi.setSystemTime(Date.now() + 45_000);
			return true;
		});
		expect(await commitDesktopRecordingAttempt(fixture)).toBe("progress");
		expect(mocks.commitSource).toHaveBeenCalledOnce();
		expect(current?.output).toMatchObject({ revision: 1 });
	});

	it("resumes from the last saved page when a later storage operation fails", async () => {
		mocks.commitSource
			.mockImplementationOnce(advanceCheckpoint)
			.mockImplementationOnce(advanceCheckpoint)
			.mockRejectedValueOnce(new Error("Storage unavailable"));
		expect(await commitDesktopRecordingAttempt(fixture)).toBe("progress");
		expect(current?.output).toMatchObject({ revision: 2 });
		expect(mocks.blocked).not.toHaveBeenCalled();
		expect(await commitDesktopRecordingAttempt(fixture)).toBe("ready");
		expect(
			mocks.commitSource.mock.calls.map((call) => call[1].revision),
		).toEqual([0, 1, 2, 2]);
		expect(mocks.persist).toHaveBeenCalledOnce();
	});

	it("preserves a fresh durable retry budget after each saved page", async () => {
		const failedRevisions = new Set<number>();
		mocks.commitSource.mockImplementation(async (_video, checkpoint) => {
			if (
				checkpoint.revision > 0 &&
				!failedRevisions.has(checkpoint.revision)
			) {
				failedRevisions.add(checkpoint.revision);
				throw new Error("Intermittent storage failure");
			}
			return checkpoint.revision === 5
				? { source }
				: advanceCheckpoint(_video, checkpoint);
		});
		for (let revision = 1; revision <= 5; revision++) {
			expect(await commitDesktopRecordingAttempt(fixture)).toBe("progress");
			expect(current?.output).toMatchObject({ revision });
		}
		expect(await commitDesktopRecordingAttempt(fixture)).toBe("ready");
		expect(mocks.saveCheckpoint).toHaveBeenCalledTimes(5);
		expect(mocks.retry).not.toHaveBeenCalled();
	});

	it("throws persistent failures when the new batch cannot make progress", async () => {
		mocks.commitSource.mockImplementationOnce(advanceCheckpoint);
		mocks.commitSource.mockRejectedValue(new Error("Storage unavailable"));
		expect(await commitDesktopRecordingAttempt(fixture)).toBe("progress");
		await expect(commitDesktopRecordingAttempt(fixture)).rejects.toThrow(
			"Storage unavailable",
		);
		expect(current?.output).toMatchObject({ revision: 1 });
		expect(mocks.commitSource).toHaveBeenCalledTimes(3);
	});

	it.each([false, true])(
		"reconciles a failed checkpoint response with database commit=%s",
		async (committed) => {
			mocks.commitSource.mockImplementationOnce(advanceCheckpoint);
			mocks.saveCheckpoint.mockImplementationOnce(
				async (_attempt, checkpoint) => {
					if (committed) withCurrent({ output: checkpoint });
					throw new Error("Database response lost");
				},
			);
			await expect(commitDesktopRecordingAttempt(fixture)).rejects.toThrow(
				"Database response lost",
			);
			expect(mocks.commitSource).toHaveBeenCalledOnce();
			expect(await commitDesktopRecordingAttempt(fixture)).toBe("ready");
			expect(mocks.commitSource.mock.calls[1]?.[1]).toMatchObject({
				revision: committed ? 1 : 0,
			});
		},
	);

	it("stops immediately when checkpoint persistence loses its ownership fence", async () => {
		mocks.commitSource.mockImplementation(advanceCheckpoint);
		mocks.saveCheckpoint.mockResolvedValueOnce(false);
		expect(await commitDesktopRecordingAttempt(fixture)).toBe("superseded");
		expect(mocks.commitSource).toHaveBeenCalledOnce();
		expect(mocks.persist).not.toHaveBeenCalled();
	});

	it.each(["deleted", "replaced", "lease-expired"])(
		"stops between pages when the job is %s",
		async (change) => {
			mocks.commitSource.mockImplementationOnce(advanceCheckpoint);
			mocks.saveCheckpoint.mockImplementationOnce(
				async (_attempt, checkpoint) => {
					withCurrent({ output: checkpoint });
					if (change === "deleted") current = null;
					else if (change === "replaced")
						withCurrent({ attemptId: "replacement" });
					else mocks.checkpoint.mockResolvedValueOnce(null);
					return true;
				},
			);
			expect(await commitDesktopRecordingAttempt(fixture)).toBe("superseded");
			expect(mocks.commitSource).toHaveBeenCalledOnce();
			expect(mocks.persist).not.toHaveBeenCalled();
		},
	);

	it("refreshes the video and late verification before the next page", async () => {
		const verification: RecordingVerification = {
			version: 1,
			artifact: { kind: "segments", manifestSha256: source.manifestSha256 },
			requiredAudio: true,
		};
		const updatedVideo = { id: "video", storageIntegrationId: "updated" };
		mocks.commitSource.mockImplementationOnce(async (_video, checkpoint) => {
			withCurrent({ verification });
			mocks.databaseRows.mockResolvedValueOnce([updatedVideo]);
			return advanceCheckpoint(_video, checkpoint);
		});
		expect(await commitDesktopRecordingAttempt(fixture)).toBe("ready");
		expect(mocks.commitSource.mock.calls[0]?.[2]).toBeUndefined();
		expect(mocks.commitSource.mock.calls[1]?.slice(0, 3)).toEqual([
			updatedVideo,
			expect.objectContaining({ revision: 1 }),
			verification,
		]);
	});

	it("keeps heartbeat ownership checks on later pages", async () => {
		mocks.commitSource
			.mockImplementationOnce(advanceCheckpoint)
			.mockImplementationOnce(
				async (_video, _checkpoint, _verification, pulse) => {
					await pulse();
					return { source };
				},
			);
		mocks.heartbeat.mockResolvedValueOnce(false);
		expect(await commitDesktopRecordingAttempt(fixture)).toBe("progress");
		expect(current?.output).toMatchObject({ revision: 1 });
		expect(mocks.persist).not.toHaveBeenCalled();
		mocks.checkpoint.mockResolvedValueOnce(null);
		expect(await commitDesktopRecordingAttempt(fixture)).toBe("superseded");
		expect(mocks.commitSource).toHaveBeenCalledTimes(2);
	});

	it.each([
		"source-incomplete",
		"source-missing",
		"source-changed",
		"source-invalid",
	])("preserves %s rejection after earlier pages were saved", async (code) => {
		mocks.commitSource
			.mockImplementationOnce(advanceCheckpoint)
			.mockRejectedValueOnce(Object.assign(new Error(code), { code }));
		expect(await commitDesktopRecordingAttempt(fixture)).toBe("source-blocked");
		expect(mocks.blocked).toHaveBeenCalledWith(
			expect.objectContaining({ errorCode: code }),
		);
		expect(mocks.persist).not.toHaveBeenCalled();
		expect(mocks.fetch).not.toHaveBeenCalled();
	});
});

describe("source commitment and media request compatibility", () => {
	it("checkpoints each source page before processing", async () => {
		withCurrent({ source: null, state: "committing", leaseExpiresAt: null });
		mocks.commitSource.mockImplementationOnce(async (_video, checkpoint) => ({
			checkpoint: { ...checkpoint, revision: 1, phase: "copy" },
		}));
		const result = await finalizeDesktopRecordingWorkflow({
			videoId,
			userId,
			generation: fixture.generation,
		});
		expect(result.success).toBe(true);
		expect(mocks.commitSource).toHaveBeenCalledTimes(2);
		expect(mocks.saveCheckpoint).toHaveBeenCalledOnce();
		expect(mocks.persist).toHaveBeenCalledOnce();
		expect(mocks.commitSource.mock.calls[1]?.[1]).toMatchObject({
			revision: 1,
			phase: "copy",
		});
	});

	it.each(["source-missing", "source-changed", "source-invalid"])(
		"keeps %s classification when committed inventory cannot be read",
		async (code) => {
			withCurrent({ leaseExpiresAt: null });
			mocks.sourceUrls.mockRejectedValue(
				Object.assign(new Error("Committed source cannot be read"), { code }),
			);
			expect(
				await finalizeDesktopRecordingWorkflow({
					videoId,
					userId,
					generation: fixture.generation,
				}),
			).toMatchObject({ success: false, reason: "source-blocked" });
			expect(mocks.blocked).toHaveBeenCalledWith(
				expect.objectContaining({ errorCode: code }),
			);
			expect(mocks.retry).not.toHaveBeenCalled();
			expect(mocks.fetch).not.toHaveBeenCalled();
		},
	);

	it("does not start media processing before durable source commitment", async () => {
		withCurrent({ source: null });
		await expect(startDesktopRecordingJob(fixture)).rejects.toThrow(
			"superseded",
		);
		expect(mocks.fetch).not.toHaveBeenCalled();
	});

	it("waits for capacity using the same attempt instead of exhausting processing retries", async () => {
		withCurrent({ state: "retry", leaseExpiresAt: null, attemptCount: 4 });
		for (let index = 0; index < 8; index++)
			mocks.fetch.mockResolvedValueOnce(
				Response.json(
					{ code: "SERVER_BUSY" },
					{ status: 503, headers: { "Retry-After": "60" } },
				),
			);
		await expect(
			finalizeDesktopRecordingWorkflow({
				videoId,
				userId,
				generation: fixture.generation,
			}),
		).resolves.toMatchObject({ success: true });
		expect(current?.attemptCount).toBe(5);
		expect(mocks.fetch).toHaveBeenCalledTimes(9);
		expect(mocks.waitCapacity).toHaveBeenCalledWith(
			expect.objectContaining({ retryAfterMs: expect.any(Number) }),
		);
		expect(
			mocks.sleep.mock.calls.filter(
				([delay]) => typeof delay === "number" && delay >= 60_000,
			),
		).toHaveLength(8);
		const attempts = mocks.reserveBudget.mock.calls.map(
			([input]) => input.attemptId,
		);
		expect(new Set(attempts).size).toBe(1);
		expect(mocks.retry).not.toHaveBeenCalled();
		expect(mocks.blocked).not.toHaveBeenCalled();
	});

	it("respects a persisted capacity wait when a dispatch step is replayed", async () => {
		withCurrent({
			output: { kind: "desktop-recording-capacity-wait" },
			nextRetryAt: new Date(Date.now() + 60_000),
		});
		await expect(startDesktopRecordingJob(fixture)).resolves.toMatchObject({
			status: "capacity",
		});
		expect(mocks.fetch).not.toHaveBeenCalled();
		expect(mocks.sourceUrls).not.toHaveBeenCalled();
	});

	it("does not treat an ambiguous dispatch failure as a capacity refusal", async () => {
		mocks.fetch.mockResolvedValueOnce(
			Response.json({ code: "UPSTREAM_FAILURE" }, { status: 503 }),
		);
		await expect(startDesktopRecordingJob(fixture)).resolves.toBeUndefined();
		expect(mocks.heartbeat).not.toHaveBeenCalled();
	});

	it("blocks an exhausted transfer budget before dispatching media work", async () => {
		const error = new MediaProcessingBudgetError("recording");
		mocks.reserveBudget.mockRejectedValueOnce(error);
		await expect(startDesktopRecordingJob(fixture)).rejects.toBe(error);
		expect(mocks.blocked).toHaveBeenCalledWith(
			expect.objectContaining({ errorCode: "processing-budget-exhausted" }),
		);
		expect(mocks.fetch).not.toHaveBeenCalled();
		expect(mocks.put).not.toHaveBeenCalled();
	});

	it("preserves incomplete originals without calling the media server", async () => {
		withCurrent({ source: null, state: "committing" });
		mocks.commitSource.mockRejectedValue(
			Object.assign(new Error("Manifest is incomplete"), {
				code: "source-incomplete",
			}),
		);
		expect(await commitDesktopRecordingAttempt(fixture)).toBe("source-blocked");
		expect(mocks.persist).not.toHaveBeenCalled();
		expect(mocks.fetch).not.toHaveBeenCalled();
	});

	it("sends immutable inventory identities without estimated legacy duration", async () => {
		await startDesktopRecordingJob(fixture);
		const body = JSON.parse(mocks.fetch.mock.calls[0]?.[1]?.body ?? "{}");
		expect(body).toMatchObject({
			generation: "generation",
			attemptId: "attempt",
			inventorySha256: source.inventorySha256,
			manifestSha256: source.manifestSha256,
			outputKey: "user/video/.recording/outputs/generation/attempt.mp4",
			outputUpload: { type: "put", ifNoneMatch: "*" },
		});
		expect(body).not.toHaveProperty("expectedDuration");
		expect(body.thumbnailPresignedUrl).toContain(
			"/generation/attempt/screenshot.jpg",
		);
	});

	function withSourceBytes(size: number) {
		mocks.sourceUrls.mockResolvedValue({
			videoInitUrl: "https://source.test/init.mp4",
			videoSegmentUrls: ["https://source.test/segment.m4s"],
			sourceObjects: [
				{
					url: "https://source.test/segment.m4s",
					objectIdentity: '"segment"',
					size,
				},
			],
		});
	}

	it("passes runs decoded during the recording to the media server only when there are any", async () => {
		await startDesktopRecordingJob(fixture);
		const plain = JSON.parse(String(mocks.fetch.mock.calls[0]?.[1]?.body));
		expect(plain).not.toHaveProperty("preverifiedRunUrls");
		mocks.fetch.mockClear();
		withCurrent({ remoteJobId: null });
		mocks.preverifiedRunUrls.mockResolvedValue([
			"https://storage.test/run-1.json",
		]);
		await startDesktopRecordingJob(fixture);
		expect(
			JSON.parse(String(mocks.fetch.mock.calls[0]?.[1]?.body))
				.preverifiedRunUrls,
		).toEqual(["https://storage.test/run-1.json"]);
	});

	it("uploads a small Cap storage output with one PUT instead of multipart", async () => {
		mocks.storage.mockImplementation(() => storageAccess("s3"));
		withSourceBytes(64 * 1024 * 1024);
		await startDesktopRecordingJob(fixture);
		const body = JSON.parse(mocks.fetch.mock.calls[0]?.[1]?.body ?? "{}");
		expect(body.outputUpload).toEqual({
			type: "put",
			url: "https://storage.test/user/video/.recording/outputs/generation/attempt.mp4",
			ifNoneMatch: "*",
		});
		expect(mocks.multipartCreate).not.toHaveBeenCalled();
	});

	it("keeps multipart output uploads for recordings larger than one part", async () => {
		mocks.storage.mockImplementation(() => storageAccess("s3"));
		withSourceBytes(64 * 1024 * 1024 + 1);
		await startDesktopRecordingJob(fixture);
		const body = JSON.parse(mocks.fetch.mock.calls[0]?.[1]?.body ?? "{}");
		expect(body.outputUpload).toMatchObject({
			type: "multipart",
			uploadId: "upload",
			partSize: 64 * 1024 * 1024,
			signPartUrl:
				"https://cap.test/api/webhooks/media-server/multipart/sign-part",
		});
		expect(mocks.multipartCreate).toHaveBeenCalledOnce();
	});

	it("keeps multipart output uploads for small recordings in a custom bucket", async () => {
		mocks.storage.mockImplementation(() => storageAccess("s3", true));
		withSourceBytes(1024);
		await startDesktopRecordingJob(fixture);
		const body = JSON.parse(mocks.fetch.mock.calls[0]?.[1]?.body ?? "{}");
		expect(body.outputUpload).toMatchObject({ type: "multipart" });
		expect(mocks.multipartCreate).toHaveBeenCalledOnce();
	});

	it("reuses a recorded remote job after a step replay instead of submitting another mux", async () => {
		withCurrent({ remoteJobId: "existing-worker" });
		expect(await startDesktopRecordingJob(fixture)).toBe("existing-worker");
		expect(mocks.fetch).not.toHaveBeenCalled();
	});

	it("verifies a legacy MP4 from its immutable snapshot without inventing a capture duration", async () => {
		withCurrent({
			source: {
				...source,
				kind: "mp4",
				manifestSha256: undefined,
				mp4: { fileSize: 1000, objectIdentity: '"original"' },
			},
		});
		mocks.sourceUrls.mockResolvedValue({
			videoUrl: "https://source.test/recording.mp4",
			sourceObjects: [
				{
					url: "https://source.test/recording.mp4",
					size: 1000,
					objectIdentity: '"snapshot"',
				},
			],
			sourceObjectIdentity: '"snapshot"',
			outputKey: "user/video/.recording/sources/generation/mp4/0.mp4",
		});
		await startDesktopRecordingJob(fixture);
		expect(mocks.fetch.mock.calls[0]?.[0]).toBe(
			"https://media.test/video/verify-recording",
		);
		const body = JSON.parse(mocks.fetch.mock.calls[0]?.[1]?.body ?? "{}");
		expect(body).toMatchObject({
			originalObjectIdentity: '"original"',
			sourceObjectIdentity: '"snapshot"',
			fileSize: 1000,
		});
		expect(body).not.toHaveProperty("duration");
	});

	it("retains explicit modern MP4 duration and audio requirements", async () => {
		withCurrent({
			source: {
				...source,
				kind: "mp4",
				manifestSha256: undefined,
				mp4: { fileSize: 1000, objectIdentity: '"original"' },
			},
			verification: {
				version: 1,
				artifact: {
					kind: "mp4",
					fileSize: 1000,
					duration: 91.6,
					objectIdentity: '"original"',
				},
				requiredAudio: true,
			},
		});
		mocks.sourceUrls.mockResolvedValue({
			videoUrl: "https://source.test/recording.mp4",
			sourceObjects: [
				{
					url: "https://source.test/recording.mp4",
					size: 1000,
					objectIdentity: '"snapshot"',
				},
			],
			sourceObjectIdentity: '"snapshot"',
			outputKey: "user/video/.recording/sources/generation/mp4/0.mp4",
		});
		await startDesktopRecordingJob(fixture);
		const body = JSON.parse(mocks.fetch.mock.calls[0]?.[1]?.body ?? "{}");
		expect(body).toMatchObject({ duration: 91.6, requiredAudio: true });
	});
});

describe("first attempt step", () => {
	// Claims the way the database does: a live attempt named for its number is handed back to its caller.
	function claimByName() {
		mocks.claim.mockImplementation(
			async ({
				attemptIdFor,
			}: {
				attemptIdFor?: (attemptCount: number) => string;
			}) => {
				if (!current) return null;
				if (
					attemptIdFor &&
					current.attemptId === attemptIdFor(current.attemptCount) &&
					current.leaseExpiresAt &&
					current.leaseExpiresAt > new Date()
				)
					return current;
				const attemptCount = current.attemptCount + 1;
				withCurrent({
					state: current.source ? "processing" : "committing",
					attemptId: attemptIdFor?.(attemptCount) ?? `attempt-${attemptCount}`,
					attemptCount,
					leaseExpiresAt: new Date(Date.now() + 5 * 60_000),
					remoteJobId: null,
				});
				return current;
			},
		);
	}

	it("claims, commits and dispatches the first attempt in one step", async () => {
		claimByName();
		withCurrent({
			state: "committing",
			source: null,
			leaseExpiresAt: null,
			attemptId: null,
		});
		const result = await acquireAndStartDesktopRecordingAttempt({
			videoId,
			userId,
			generation: fixture.generation,
		});
		expect(result).toMatchObject({
			status: "attempt",
			attempt: {
				attemptId: expect.stringMatching(
					/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/,
				),
			},
			started: { committed: "ready", dispatched: true, started: "remote-job" },
		});
		expect(mocks.fetch).toHaveBeenCalledOnce();
	});

	it("rethrows an early failure so the step retry resumes the same attempt", async () => {
		claimByName();
		withCurrent({ state: "committing", source: null, leaseExpiresAt: null });
		mocks.stepMetadata.mockReturnValue({ stepId: "step_retry", attempt: 1 });
		mocks.commitSource.mockRejectedValueOnce(new Error("storage blip"));
		await expect(
			acquireAndStartDesktopRecordingAttempt({
				videoId,
				userId,
				generation: fixture.generation,
			}),
		).rejects.toThrow("storage blip");
		const claimed = current?.attemptId;
		mocks.stepMetadata.mockReturnValue({ stepId: "step_retry", attempt: 2 });
		expect(
			await acquireAndStartDesktopRecordingAttempt({
				videoId,
				userId,
				generation: fixture.generation,
			}),
		).toMatchObject({
			status: "attempt",
			attempt: { attemptId: claimed, attemptCount: 2 },
			started: { committed: "ready", dispatched: true, started: "remote-job" },
		});
		expect(mocks.fetch).toHaveBeenCalledOnce();
	});

	it("keeps resuming a replacement claimed after its earlier attempt's lease expired", async () => {
		claimByName();
		withCurrent({ state: "committing", source: null, leaseExpiresAt: null });
		mocks.stepMetadata.mockReturnValue({ stepId: "step_slow", attempt: 1 });
		mocks.commitSource.mockRejectedValueOnce(new Error("storage blip"));
		await expect(
			acquireAndStartDesktopRecordingAttempt({
				videoId,
				userId,
				generation: fixture.generation,
			}),
		).rejects.toThrow("storage blip");
		const first = current?.attemptId;
		vi.setSystemTime(new Date(Date.now() + 6 * 60_000));
		mocks.stepMetadata.mockReturnValue({ stepId: "step_slow", attempt: 2 });
		mocks.commitSource.mockRejectedValueOnce(new Error("storage blip again"));
		await expect(
			acquireAndStartDesktopRecordingAttempt({
				videoId,
				userId,
				generation: fixture.generation,
			}),
		).rejects.toThrow("storage blip again");
		const replacement = current?.attemptId;
		expect(replacement).not.toBe(first);
		mocks.stepMetadata.mockReturnValue({ stepId: "step_slow", attempt: 3 });
		expect(
			await acquireAndStartDesktopRecordingAttempt({
				videoId,
				userId,
				generation: fixture.generation,
			}),
		).toMatchObject({
			status: "attempt",
			attempt: { attemptId: replacement },
			started: { committed: "ready", dispatched: true },
		});
	});

	it("leaves another workflow's live attempt alone", async () => {
		withCurrent({
			attemptId: "someone-else",
			leaseExpiresAt: new Date(Date.now() + 60_000),
		});
		expect(
			await acquireAndStartDesktopRecordingAttempt({
				videoId,
				userId,
				generation: fixture.generation,
			}),
		).toEqual({ status: "already-processing" });
		expect(mocks.claim).not.toHaveBeenCalled();
	});

	it("returns a failure after the last try as data for the workflow to retry", async () => {
		withCurrent({ state: "committing", source: null, leaseExpiresAt: null });
		mocks.commitSource.mockRejectedValueOnce(
			new Error("provider copy unavailable"),
		);
		expect(
			await acquireAndStartDesktopRecordingAttempt({
				videoId,
				userId,
				generation: fixture.generation,
			}),
		).toMatchObject({
			status: "attempt",
			failure: { message: "provider copy unavailable", code: null },
		});
	});

	it("blocks a missing source inside the step like the commit step does", async () => {
		withCurrent({ state: "committing", source: null, leaseExpiresAt: null });
		mocks.commitSource.mockRejectedValueOnce(
			Object.assign(new Error("fragment missing"), { code: "source-missing" }),
		);
		expect(
			await acquireAndStartDesktopRecordingAttempt({
				videoId,
				userId,
				generation: fixture.generation,
			}),
		).toMatchObject({
			status: "attempt",
			started: { committed: "source-blocked" },
		});
		expect(mocks.blocked).toHaveBeenCalledWith(
			expect.objectContaining({ errorCode: "source-missing" }),
		);
	});
});

describe("workflow retry lifetime", () => {
	it("finishes normally when publication commits during a failing poll", async () => {
		withCurrent({ state: "queued", leaseExpiresAt: null });
		mocks.observe.mockImplementationOnce(async () => {
			withCurrent({ state: "verified", leaseExpiresAt: null });
			throw new Error("Response lost after publication");
		});
		expect(
			await finalizeDesktopRecordingWorkflow({
				videoId,
				userId,
				generation: fixture.generation,
			}),
		).toMatchObject({ success: true });
		expect(mocks.retry).not.toHaveBeenCalled();
		expect(mocks.claim).toHaveBeenCalledOnce();
		expect(mocks.transcribe).toHaveBeenCalledOnce();
	});

	it("waits for an uncertain dispatch without reserving the unacknowledged worker", async () => {
		mocks.fetch.mockResolvedValue(
			Response.json({ jobId: "unclaimed-worker", recordingWorkerVersion: 1 }),
		);
		expect(await startDesktopRecordingJob(fixture)).toBeUndefined();
		expect(mocks.attach).not.toHaveBeenCalled();
		expect(mocks.retry).not.toHaveBeenCalled();
		const input = { ...pollingInput(), jobId: undefined };
		expect(await pollDesktopRecordingAttempt(input)).toBe("waiting");
		expect(mocks.observe).not.toHaveBeenCalled();
		withCurrent({ remoteJobId: "actual-owner" });
		expect(await pollDesktopRecordingAttempt(input)).toBe("verified");
		expect(mocks.observe).toHaveBeenCalledWith(
			expect.objectContaining({ jobId: "actual-owner" }),
		);
		expect(mocks.fetch).toHaveBeenCalledOnce();
	});

	it("uses the durable winning replica instead of a dispatch response", async () => {
		mocks.fetch.mockImplementation(async () => {
			withCurrent({ remoteJobId: "winner" });
			return Response.json({ jobId: "loser", recordingWorkerVersion: 1 });
		});
		expect(await startDesktopRecordingJob(fixture)).toBe("winner");
		expect(mocks.attach).not.toHaveBeenCalled();
	});

	it("reconciles a committed ownership claim after the dispatch ACK is lost", async () => {
		mocks.fetch.mockImplementation(async () => {
			withCurrent({ remoteJobId: "winner" });
			throw new Error("Response lost after acceptance");
		});
		expect(await startDesktopRecordingJob(fixture)).toBe("winner");
		expect(await startDesktopRecordingJob(fixture)).toBe("winner");
		expect(mocks.fetch).toHaveBeenCalledOnce();
		expect(mocks.attach).not.toHaveBeenCalled();
		expect(mocks.retry).not.toHaveBeenCalled();
	});

	it("waits for the existing lease to expire if dispatch was never accepted", async () => {
		mocks.fetch.mockRejectedValue(new Error("offline"));
		expect(await startDesktopRecordingJob(fixture)).toBeUndefined();
		const input = { ...pollingInput(), jobId: undefined };
		expect(await pollDesktopRecordingAttempt(input)).toBe("waiting");
		expect(mocks.retry).not.toHaveBeenCalled();
		vi.setSystemTime(new Date(now.getTime() + 5 * 60_000));
		expect(await pollDesktopRecordingAttempt(input)).toBe("retry");
		expect(current?.source).toEqual(source);
		expect(mocks.fetch).toHaveBeenCalledOnce();
	});

	it("resumes the same live attempt after a polling exception", async () => {
		withCurrent({ state: "queued", leaseExpiresAt: null });
		mocks.observe.mockRejectedValueOnce(new Error("Transient polling failure"));
		expect(
			await finalizeDesktopRecordingWorkflow({
				videoId,
				userId,
				generation: fixture.generation,
			}),
		).toEqual({ success: true, jobId: "remote-job" });
		expect(mocks.claim).toHaveBeenCalledOnce();
		expect(mocks.fetch).toHaveBeenCalledOnce();
		expect(mocks.retry).not.toHaveBeenCalled();
	});

	it("waits for fresh backoff after a source commit failure with a rich stale attempt", async () => {
		withCurrent({
			state: "committing",
			source: null,
			leaseExpiresAt: null,
			nextRetryAt: new Date(now.getTime() - 60_000),
		});
		mocks.commitSource.mockRejectedValueOnce(
			new Error("provider copy unavailable"),
		);
		expect(
			await finalizeDesktopRecordingWorkflow({
				videoId,
				userId,
				generation: fixture.generation,
			}),
		).toEqual({ success: true, jobId: "remote-job" });
		expect(mocks.retry).toHaveBeenCalledWith({
			videoId,
			generation: fixture.generation,
			attemptId: "attempt-2",
			errorCode: "processing-interrupted",
			errorMessage: "provider copy unavailable",
		});
		expect(mocks.sleep.mock.calls[0]).toEqual([
			new Date(now.getTime() + 15_000),
		]);
		expect(mocks.claim.mock.calls[1]?.[0].now).toEqual(
			new Date(now.getTime() + 15_000),
		);
		expect(mocks.fetch).toHaveBeenCalledOnce();
	});

	it("waits durably between failed attempts and continues past the old eight-attempt cutoff", async () => {
		withCurrent({
			state: "committing",
			source: null,
			leaseExpiresAt: null,
			attemptId: null,
			attemptCount: 0,
		});
		let submitted = 0;
		mocks.fetch.mockImplementation(async () => {
			if (++submitted <= 9) throw new Error("worker restarting");
			return Response.json({ jobId: "recovered-worker" });
		});
		const result = await finalizeDesktopRecordingWorkflow({
			videoId,
			userId,
			generation: "generation",
		});
		expect(result).toEqual({ success: true, jobId: "recovered-worker" });
		expect(mocks.retry).toHaveBeenCalledTimes(9);
		expect(mocks.commitSource).toHaveBeenCalledOnce();
		expect(
			mocks.sleep.mock.calls.some(([delay]) => delay instanceof Date),
		).toBe(true);
		expect(mocks.sleep.mock.calls.some(([delay]) => delay === 15_000)).toBe(
			true,
		);
	});

	it.each([
		["uses the generation it was started with", "generation", 0],
		["looks the job up when started without a generation", undefined, 1],
	])("%s", async (_name, generation, lookups) => {
		withCurrent({
			state: "queued",
			leaseExpiresAt: null,
			attemptId: null,
			attemptCount: 0,
		});
		mocks.env.mockReturnValue({ WEB_URL: "https://self-hosted.test" });
		const result = await finalizeDesktopRecordingWorkflow({
			videoId,
			userId,
			generation,
		});
		expect(result).toEqual({
			success: false,
			reason: "media-server-unconfigured",
		});
		expect(mocks.ensure).toHaveBeenCalledTimes(lookups);
		expect(mocks.defer).toHaveBeenCalledOnce();
	});

	it("reports a missing media server from the dispatch step without dispatching", async () => {
		mocks.env.mockReturnValue({ WEB_URL: "https://self-hosted.test" });
		await expect(startDesktopRecordingJob(fixture)).resolves.toEqual({
			status: "media-server-unconfigured",
		});
		expect(mocks.defer).toHaveBeenCalledOnce();
		expect(mocks.fetch).not.toHaveBeenCalled();
		expect(mocks.sourceUrls).not.toHaveBeenCalled();
	});

	it("preserves the self-hosted playback fallback without issuing a verified cleanup receipt", async () => {
		withCurrent({
			state: "queued",
			leaseExpiresAt: null,
			attemptId: null,
			attemptCount: 0,
		});
		mocks.env.mockReturnValue({ WEB_URL: "https://self-hosted.test" });
		const result = await finalizeDesktopRecordingWorkflow({
			videoId,
			userId,
			generation: "generation",
		});
		expect(result).toEqual({
			success: false,
			reason: "media-server-unconfigured",
		});
		expect(current?.source).toEqual(source);
		expect(current?.state).not.toBe("verified");
		expect(mocks.fetch).not.toHaveBeenCalled();
	});
});