emdash 0.33.0 → 0.35.0

package/src/database/repositories/media-usage.ts

@@ -1,17 +1,19 @@
 import {
 	sql,
 	type ExpressionBuilder,
-	type Insertable,
 	type Kysely,
+	type RawBuilder,
 	type Selectable,
 	type Transaction,
 	type Updateable,
 } from "kysely";
 import { ulid } from "ulidx";
 
+import { isMediaUsageProjectionFingerprint } from "../../media/usage/projection-fingerprint.js";
 import type { MediaUsageContentSourceVariant } from "../../media/usage/source-key.js";
 import type { MediaKind, MediaUsageReferenceType } from "../../media/usage/types.js";
 import { chunks, SQL_BATCH_SIZE } from "../../utils/chunks.js";
+import { isPostgres } from "../dialect-helpers.js";
 import { withTransaction } from "../transaction.js";
 import type {
 	Database,
@@ -24,18 +26,35 @@ import { decodeCursor, encodeCursor, InvalidCursorError, type FindManyResult } f
 
 type DatabaseExecutor = Kysely<Database> | Transaction<Database>;
 type MediaUsageSourceNullableStringColumn =
+	| "collection_id"
 	| "source_fingerprint"
 	| "source_updated_at"
 	| "revision_id"
 	| "updated_at"
 	| "last_attempted_at"
 	| "last_error_code";
-
 const OCCURRENCE_BIND_COLUMNS = 13;
+export const MEDIA_USAGE_GENERATION_WRITE_LEASE_MS = 60 * 60 * 1000;
 const OCCURRENCE_INSERT_BATCH_SIZE = Math.max(
 	1,
 	Math.floor(SQL_BATCH_SIZE / OCCURRENCE_BIND_COLUMNS),
 );
+
+function cleanupDeleteBatchSize(cleanupLease: MediaUsageCleanupLease | undefined): number {
+	return cleanupLease ? SQL_BATCH_SIZE - 3 : SQL_BATCH_SIZE;
+}
+
+function canIssueCleanupStatement(canIssueStatement: (() => boolean) | undefined): boolean {
+	return canIssueStatement?.() ?? true;
+}
+
+function cleanupDurationSeconds(value: number): number {
+	if (!Number.isSafeInteger(value) || value < 0) {
+		throw new Error("Media usage cleanup duration must be a non-negative whole number of seconds");
+	}
+	return value;
+}
+
 const CONTENT_SOURCE_ELIGIBILITY = sql<boolean>`(
 	s.source_variant = 'draft_overlay'
 	OR (
@@ -49,14 +68,37 @@ const CONTENT_SOURCE_ELIGIBILITY = sql<boolean>`(
 					AND overlay.collection_slug = s.collection_slug
 					AND overlay.content_id = s.content_id
 					AND overlay.source_variant = 'draft_overlay'
+					AND ${contentSourceMatchesActiveCollection("overlay", "s.collection_id")}
 			)
 		)
 	)
 )`;
 
+type ContentSourceAlias = "deleted_source" | "overlay" | "s" | "state";
+type CurrentCollectionIdReference = "collection.id" | "page.collection_id" | "s.collection_id";
+
+function contentSourceMatchesActiveCollection(
+	source: ContentSourceAlias,
+	currentCollectionId: CurrentCollectionIdReference,
+): RawBuilder<boolean> {
+	return sql<boolean>`(
+		NOT EXISTS (
+			SELECT 1
+			FROM _emdash_media_usage_activation AS activation
+			WHERE activation.task_key = 'incremental_capture'
+				AND activation.state = 'active'
+		)
+		OR (
+			${sql.ref(`${source}.collection_id`)} = ${sql.ref(currentCollectionId)}
+			AND ${sql.ref(`${source}.identity_version`)} = 1
+		)
+	)`;
+}
+
 export interface MediaUsageSourceInput {
 	sourceKey: string;
 	sourceType: string;
+	collectionId?: string | null;
 	collectionSlug?: string | null;
 	contentId?: string | null;
 	sourceVariant: MediaUsageContentSourceVariant;
@@ -72,6 +114,7 @@ export interface MediaUsageSourceInput {
 	sourceUpdatedAt?: string | null;
 	sourceVersion?: number | null;
 	sourceFingerprint?: string | null;
+	identityVersion?: number | null;
 	sourceCompleteness?: MediaUsageSourceCompleteness;
 	lastAttemptedAt?: string | null;
 	lastErrorCode?: string | null;
@@ -92,6 +135,7 @@ export interface MediaUsageOccurrenceInput {
 export interface MediaUsageSource {
 	sourceKey: string;
 	sourceType: string;
+	collectionId: string | null;
 	collectionSlug: string | null;
 	contentId: string | null;
 	sourceVariant: string;
@@ -108,6 +152,7 @@ export interface MediaUsageSource {
 	sourceUpdatedAt: string | null;
 	sourceVersion: number | null;
 	sourceFingerprint: string | null;
+	identityVersion: number | null;
 	sourceCompleteness: string;
 	lastAttemptedAt: string | null;
 	lastErrorCode: string | null;
@@ -118,6 +163,7 @@ export interface MediaUsageSource {
 
 export interface MediaUsageGuardedReplaceResult {
 	replaced: boolean;
+	unchanged: boolean;
 	/** Populated only when a guarded replacement did not win the current source row. */
 	source: MediaUsageSource | null;
 }
@@ -137,6 +183,59 @@ export interface MediaUsageGuardedAttemptResult {
 	source: MediaUsageSource | null;
 }
 
+export interface MediaUsageSourceGenerationDeletionMeasurement {
+	occurrenceCount: number;
+	occurrenceBytes: number;
+	exceedsOccurrenceLimit: boolean;
+}
+
+export interface MediaUsageCleanupCursor {
+	createdAt: string;
+	id: string;
+}
+
+export interface MediaUsageCleanupClaim {
+	leaseToken: string;
+	cursor: MediaUsageCleanupCursor | null;
+	claimedAt: string;
+	scanBeforeAt: string;
+	consecutiveFailures: number;
+}
+
+export interface MediaUsageCleanupCandidate {
+	id: string;
+	sourceKey: string;
+	generation: string;
+	createdAt: string;
+	currentGeneration: string | null;
+	indexedAt: string | null;
+	writeLeaseExpiresAt: string | null;
+}
+
+export interface MediaUsageCleanupLease {
+	leaseToken: string;
+}
+
+export interface MediaUsageCleanupDeleteOptions {
+	candidateIds?: readonly string[];
+	cleanupLease?: MediaUsageCleanupLease;
+	canIssueStatement?: () => boolean;
+}
+
+export interface MediaUsageCleanupCompletion {
+	leaseToken: string;
+	nextCursor: MediaUsageCleanupCursor | null;
+	sweepComplete: boolean;
+	candidateCount: number;
+	deletedOrphans: number;
+	deletedStale: number;
+	deletedAbandoned: number;
+	deletedWriteLeases: number;
+	backlogLowerBound: number;
+	scanHasMore: boolean;
+	durationMs: number;
+}
+
 export interface MediaUsageIndexStatusRepairInput extends MediaUsageIndexStatusIdentity {
 	runToken: string;
 	schemaVersion?: number;
@@ -155,6 +254,30 @@ export interface MediaUsageIndexStatusFinalizeInput extends MediaUsageIndexStatu
 	updatedAt?: string;
 }
 
+export interface MediaUsageIndexStatusEpochRepairInput extends MediaUsageIndexStatusIdentity {
+	collectionId: string;
+	runToken: string;
+	schemaVersion: number;
+}
+
+export interface MediaUsageIndexStatusEpochRepairRun {
+	changeEpoch: number | string;
+	startedAt: string;
+}
+
+export interface MediaUsageIndexStatusEpochFinalizeInput extends MediaUsageIndexStatusEpochRepairInput {
+	startingEpoch: number | string;
+	status: Exclude<MediaUsageIndexStatusValue, "never" | "running" | "stale">;
+	indexedSourceCount: number;
+	failedSourceCount: number;
+	lastErrorCode: string | null;
+}
+
+export interface MediaUsageIncrementalStatusIdentity {
+	collectionId: string;
+	collectionSlug: string;
+}
+
 export interface MediaUsageGuardedIndexStatusResult {
 	finalized: boolean;
 	status: MediaUsageIndexStatus | null;
@@ -214,6 +337,7 @@ export interface MediaUsageCollectionIndexStatusScope {
 	collectionSlug: string;
 	status: string | null;
 	schemaVersion: number | null;
+	reconciliationRequired: boolean;
 }
 
 export interface MediaUsageEntrySource {
@@ -231,6 +355,7 @@ export interface MediaUsageEntryGroup {
 interface MediaUsageSourceRow {
 	source_key: string;
 	source_type: string;
+	collection_id: string | null;
 	collection_slug: string | null;
 	content_id: string | null;
 	source_variant: string;
@@ -247,6 +372,7 @@ interface MediaUsageSourceRow {
 	source_updated_at: string | null;
 	source_version: number | null;
 	source_fingerprint: string | null;
+	identity_version: number | null;
 	source_completeness: string;
 	last_attempted_at: string | null;
 	last_error_code: string | null;
@@ -279,6 +405,7 @@ export interface MediaUsageRecord {
 interface JoinedUsageRow {
 	source_key: string;
 	source_type: string;
+	collection_id: string | null;
 	collection_slug: string | null;
 	content_id: string | null;
 	source_variant: string;
@@ -295,6 +422,7 @@ interface JoinedUsageRow {
 	source_updated_at: string | null;
 	source_version: number | null;
 	source_fingerprint: string | null;
+	identity_version: number | null;
 	source_completeness: string;
 	last_attempted_at: string | null;
 	last_error_code: string | null;
@@ -329,12 +457,26 @@ export class MediaUsageRepository {
 		occurrences: readonly MediaUsageOccurrenceInput[],
 	): Promise<MediaUsageSource> {
 		const generation = ulid();
-		const now = new Date().toISOString();
 
-		await withTransaction(this.db, async (trx) => {
-			await this.insertOccurrences(trx, source.sourceKey, generation, occurrences, now);
-			await this.upsertSource(trx, source, generation, now);
-		});
+		const admitted = await this.withGenerationWriteLease(
+			source,
+			generation,
+			async (leaseToken, now) => {
+				await withTransaction(this.db, async (trx) => {
+					if (!(await this.lockCanonicalSourceCollection(trx, source))) {
+						throw new Error(`Media usage collection is no longer current for ${source.sourceKey}`);
+					}
+					await this.insertOccurrences(trx, source.sourceKey, generation, occurrences, now);
+					const promoted = await this.upsertSource(trx, source, generation, now, leaseToken);
+					if (!promoted) {
+						throw new Error(`Media usage generation lease expired for ${source.sourceKey}`);
+					}
+				});
+			},
+		);
+		if (!admitted) {
+			throw new Error(`Media usage collection is no longer current for ${source.sourceKey}`);
+		}
 
 		const replaced = await this.findSource(source.sourceKey);
 		if (!replaced) {
@@ -347,22 +489,36 @@ export class MediaUsageRepository {
 		occurrences: readonly MediaUsageOccurrenceInput[],
 		expectedCurrentGeneration: string | null,
 	): Promise<MediaUsageGuardedReplaceResult> {
+		if (
+			expectedCurrentGeneration !== null &&
+			(await this.projectionMatchesCurrentGeneration(source, expectedCurrentGeneration))
+		) {
+			return { replaced: false, unchanged: true, source: null };
+		}
 		const generation = ulid();
-		const now = new Date().toISOString();
-		const row = this.buildSourceRow(source, generation, now);
 		let replaced = false;
 
-		await withTransaction(this.db, async (trx) => {
-			await this.insertOccurrences(trx, source.sourceKey, generation, occurrences, now);
-			if (expectedCurrentGeneration === null) {
-				replaced = await this.insertSourceIfAbsent(trx, row);
-				return;
-			}
-			replaced = await this.updateSourceIfGeneration(trx, row, expectedCurrentGeneration);
+		await this.withGenerationWriteLease(source, generation, async (leaseToken, now) => {
+			const row = this.buildSourceRow(source, generation, now);
+			await withTransaction(this.db, async (trx) => {
+				if (!(await this.lockCanonicalSourceCollection(trx, source))) return;
+				await this.insertOccurrences(trx, source.sourceKey, generation, occurrences, now);
+				if (expectedCurrentGeneration === null) {
+					replaced = await this.insertSourceIfAbsent(trx, row, leaseToken);
+					return;
+				}
+				replaced = await this.updateSourceIfGeneration(
+					trx,
+					row,
+					expectedCurrentGeneration,
+					leaseToken,
+				);
+			});
 		});
 
 		return {
 			replaced,
+			unchanged: false,
 			source: replaced ? null : await this.findSource(source.sourceKey),
 		};
 	}
@@ -397,41 +553,99 @@ export class MediaUsageRepository {
 		return sources;
 	}
 
+	async measureSourceGenerationDeletion(
+		sourceKey: string,
+		generation: string,
+		maxOccurrences: number,
+	): Promise<MediaUsageSourceGenerationDeletionMeasurement> {
+		if (!Number.isSafeInteger(maxOccurrences) || maxOccurrences < 0) {
+			throw new Error("Media usage deletion measurement requires a non-negative row limit");
+		}
+		const payload = sql<string>`
+			COALESCE(field_slug, '') || COALESCE(field_path, '') ||
+			COALESCE(reference_type, '') || COALESCE(media_id, '') ||
+			COALESCE(provider, '') || COALESCE(provider_asset_id, '') ||
+			COALESCE(media_kind, '') || COALESCE(mime_type, '')
+		`;
+		const occurrenceBytes = isPostgres(this.db)
+			? sql<number>`octet_length(${payload})`
+			: sql<number>`length(CAST(${payload} AS BLOB))`;
+		const rows = await this.db
+			.selectFrom("_emdash_media_usage")
+			.select(occurrenceBytes.as("occurrence_bytes"))
+			.where("source_key", "=", sourceKey)
+			.where("generation", "=", generation)
+			.limit(maxOccurrences + 1)
+			.execute();
+
+		return {
+			occurrenceCount: rows.length,
+			occurrenceBytes: rows.reduce((total, row) => total + Number(row.occurrence_bytes), 0),
+			exceedsOccurrenceLimit: rows.length > maxOccurrences,
+		};
+	}
+
 	async replaceSourceIfMatching(
 		source: MediaUsageSourceInput,
 		occurrences: readonly MediaUsageOccurrenceInput[],
 		expectedSource: MediaUsageSource | null,
 	): Promise<MediaUsageGuardedReplaceResult> {
+		if (
+			expectedSource !== null &&
+			(await this.projectionMatchesExpectedSource(source, expectedSource))
+		) {
+			return { replaced: false, unchanged: true, source: null };
+		}
 		const generation = ulid();
-		const now = new Date().toISOString();
-		const row = this.buildSourceRow(source, generation, now);
 		let replaced = false;
 
-		await withTransaction(this.db, async (trx) => {
-			await this.insertOccurrences(trx, source.sourceKey, generation, occurrences, now);
-			if (expectedSource === null) {
-				replaced = await this.insertSourceIfAbsent(trx, row);
-				return;
-			}
-			replaced = await this.updateSourceIfMatching(trx, row, expectedSource);
+		await this.withGenerationWriteLease(source, generation, async (leaseToken, now) => {
+			const row = this.buildSourceRow(source, generation, now);
+			await withTransaction(this.db, async (trx) => {
+				if (!(await this.lockCanonicalSourceCollection(trx, source))) return;
+				await this.insertOccurrences(trx, source.sourceKey, generation, occurrences, now);
+				if (expectedSource === null) {
+					replaced = await this.insertSourceIfAbsent(trx, row, leaseToken);
+					return;
+				}
+				replaced = await this.updateSourceIfMatching(trx, row, expectedSource, leaseToken);
+			});
 		});
 
 		return {
 			replaced,
+			unchanged: false,
 			source: replaced ? null : await this.findSource(source.sourceKey),
 		};
 	}
 
 	async markSourceAttempted(source: MediaUsageSourceInput): Promise<MediaUsageSource> {
-		const now = new Date().toISOString();
-		const row = this.buildAttemptedSourceRow(source, now);
-		const updates = this.attemptedSourceUpdateSet(source, row);
+		if (source.collectionId !== undefined && source.collectionId !== null) {
+			const expectedSource = await this.findSource(source.sourceKey);
+			const result = await this.markSourceAttemptedIfMatching(source, expectedSource);
+			if (!result.attempted) {
+				throw new Error(`Canonical media usage source ${source.sourceKey} is no longer current`);
+			}
+			const attempted = await this.findSource(source.sourceKey);
+			if (!attempted) {
+				throw new Error(`Media usage source ${source.sourceKey} was not persisted`);
+			}
+			return attempted;
+		}
 
-		await this.db
-			.insertInto("_emdash_media_usage_sources")
-			.values(row)
-			.onConflict((oc) => oc.column("source_key").doUpdateSet(updates))
-			.execute();
+		const generation = ulid();
+		await this.withGenerationWriteLease(source, generation, async (leaseToken, now) => {
+			const row = this.buildAttemptedSourceRow(source, generation, now);
+			const updates = this.attemptedSourceUpdateSet(source, row);
+			const result = await this.db
+				.insertInto("_emdash_media_usage_sources")
+				.values(row)
+				.onConflict((oc) => oc.column("source_key").doUpdateSet(updates))
+				.executeTakeFirst();
+			if ((result.numInsertedOrUpdatedRows ?? 0n) <= 0n) {
+				throw new Error(`Media usage generation lease expired for ${source.sourceKey}`);
+			}
+		});
 
 		const attempted = await this.findSource(source.sourceKey);
 		if (!attempted) {
@@ -444,14 +658,28 @@ export class MediaUsageRepository {
 		source: MediaUsageSourceInput,
 		expectedSource: MediaUsageSource | null,
 	): Promise<MediaUsageGuardedAttemptResult> {
-		const now = new Date().toISOString();
-		const row = this.buildAttemptedSourceRow(source, now);
+		const generation = ulid();
 		let attempted = false;
 
 		if (expectedSource === null) {
-			attempted = await this.insertSourceIfAbsent(this.db, row);
+			await this.withGenerationWriteLease(source, generation, async (leaseToken, now) => {
+				const row = this.buildAttemptedSourceRow(source, generation, now);
+				await withTransaction(this.db, async (trx) => {
+					if (!(await this.lockCanonicalSourceCollection(trx, source))) return;
+					attempted = await this.persistSourceIfWriteLease(
+						trx,
+						row,
+						leaseToken,
+						sql`ON CONFLICT (source_key) DO NOTHING`,
+					);
+				});
+			});
 		} else {
-			attempted = await this.updateAttemptedSourceIfMatching(this.db, source, row, expectedSource);
+			const row = this.buildAttemptedSourceRow(source, generation, new Date().toISOString());
+			await withTransaction(this.db, async (trx) => {
+				if (!(await this.lockCanonicalSourceCollection(trx, source))) return;
+				attempted = await this.updateAttemptedSourceIfMatching(trx, source, row, expectedSource);
+			});
 		}
 
 		return {
@@ -482,6 +710,7 @@ export class MediaUsageRepository {
 								.whereRef("deleted_source.collection_slug", "=", "s.collection_slug")
 								.whereRef("deleted_source.content_id", "=", "s.content_id")
 								.where("deleted_source.source_variant", "in", ["columns", "draft_overlay"])
+								.where(contentSourceMatchesActiveCollection("deleted_source", "collection.id"))
 								.where("deleted_source.content_deleted_at", "is not", null),
 						),
 					),
@@ -519,6 +748,7 @@ export class MediaUsageRepository {
 				"collection.slug as collection_slug",
 				"status.status as status",
 				"status.schema_version as schema_version",
+				"status.reconciliation_required as reconciliation_required",
 			])
 			.orderBy("collection.slug", "asc")
 			.execute();
@@ -527,6 +757,8 @@ export class MediaUsageRepository {
 			collectionSlug: row.collection_slug,
 			status: row.status,
 			schemaVersion: row.schema_version === null ? null : Number(row.schema_version),
+			reconciliationRequired:
+				row.reconciliation_required !== null && Number(row.reconciliation_required) !== 0,
 		}));
 	}
 
@@ -541,7 +773,11 @@ export class MediaUsageRepository {
 			throw new InvalidCursorError(options.cursor ?? "");
 		}
 		let matchedGroups = this.currentContentMediaUsageBaseQuery()
-			.select(["s.collection_slug as collection_slug", "s.content_id as content_id"])
+			.select([
+				"collection.id as collection_id",
+				"s.collection_slug as collection_slug",
+				"s.content_id as content_id",
+			])
 			.where("u.media_id", "=", mediaId)
 			.distinct();
 		if (cursor) {
@@ -574,7 +810,7 @@ export class MediaUsageRepository {
 				db
 					.selectFrom("page_groups as page")
 					.crossJoin("_emdash_media_usage_sources as state")
-					.select(["page.collection_slug", "page.content_id"])
+					.select(["page.collection_id", "page.collection_slug", "page.content_id"])
 					.select((eb) =>
 						eb.fn.max<string | null>("state.content_deleted_at").as("entry_deleted_at"),
 					)
@@ -582,13 +818,15 @@ export class MediaUsageRepository {
 					.whereRef("page.content_id", "=", "state.content_id")
 					.where("state.source_type", "=", "content")
 					.where("state.source_variant", "in", ["columns", "draft_overlay"])
-					.groupBy(["page.collection_slug", "page.content_id"]),
+					.where(contentSourceMatchesActiveCollection("state", "page.collection_id"))
+					.groupBy(["page.collection_id", "page.collection_slug", "page.content_id"]),
 			)
 			.selectFrom("entry_state as page")
 			.crossJoin("_emdash_media_usage_sources as s")
 			.crossJoin("_emdash_media_usage as u")
 			.whereRef("page.collection_slug", "=", "s.collection_slug")
 			.whereRef("page.content_id", "=", "s.content_id")
+			.where(contentSourceMatchesActiveCollection("s", "page.collection_id"))
 			.whereRef("s.source_key", "=", "u.source_key")
 			.whereRef("s.current_generation", "=", "u.generation")
 			.select(currentUsageSelect)
@@ -692,6 +930,7 @@ export class MediaUsageRepository {
 	): Promise<MediaUsageGuardedDeleteResult> {
 		let deleted = false;
 		await withTransaction(this.db, async (trx) => {
+			await this.lockCleanupBeforeSourceDelete(trx);
 			const result = await trx
 				.deleteFrom("_emdash_media_usage_sources")
 				.where("source_key", "=", sourceKey)
@@ -714,10 +953,14 @@ export class MediaUsageRepository {
 	): Promise<MediaUsageGuardedDeleteResult> {
 		let deleted = false;
 		await withTransaction(this.db, async (trx) => {
+			await this.lockCleanupBeforeSourceDelete(trx);
 			const result = await trx
 				.deleteFrom("_emdash_media_usage_sources")
 				.where("source_key", "=", sourceKey)
 				.where(this.sourceMatchExpression(expectedSource))
+				.where(
+					this.currentCollectionExists(expectedSource.collectionId, expectedSource.collectionSlug),
+				)
 				.executeTakeFirst();
 			deleted = Number(result.numDeletedRows ?? 0) > 0;
 			if (!deleted) return;
@@ -744,10 +987,14 @@ export class MediaUsageRepository {
 		const tableName = `ec_${collectionSlug}`;
 		let deleted = false;
 		await withTransaction(this.db, async (trx) => {
+			await this.lockCleanupBeforeSourceDelete(trx);
 			const result = await trx
 				.deleteFrom("_emdash_media_usage_sources")
 				.where("source_key", "=", sourceKey)
 				.where(this.sourceMatchExpression(expectedSource))
+				.where(
+					this.currentCollectionExists(expectedSource.collectionId, expectedSource.collectionSlug),
+				)
 				.where(
 					sql<boolean>`NOT EXISTS (SELECT 1 FROM ${sql.ref(tableName)} WHERE id = ${contentId})`,
 				)
@@ -803,136 +1050,360 @@ export class MediaUsageRepository {
 		return deleted;
 	}
 
-	async findCollectionContentSources(collectionSlug: string): Promise<MediaUsageSource[]> {
-		const rows = await this.db
+	async findCollectionContentSources(
+		collectionSlug: string,
+		collectionId?: string,
+	): Promise<MediaUsageSource[]> {
+		let query = this.db
 			.selectFrom("_emdash_media_usage_sources")
 			.selectAll()
 			.where("source_type", "=", "content")
 			.where("collection_slug", "=", collectionSlug)
-			.orderBy("source_key", "asc")
-			.execute();
+			.orderBy("source_key", "asc");
+		if (collectionId !== undefined) query = query.where("collection_id", "=", collectionId);
+		const rows = await query.execute();
 		return rows.map((row) => rowToSource(row));
 	}
 
-	async deleteOrphanOccurrencesOlderThan(cutoff: string, limit: number): Promise<number> {
+	async claimMediaUsageCleanup(input: {
+		leaseToken: string;
+		leaseDurationSeconds: number;
+		nextEligibleDelaySeconds: number;
+		sweepSafetyWindowSeconds: number;
+	}): Promise<MediaUsageCleanupClaim | null> {
+		const leaseDurationSeconds = cleanupDurationSeconds(input.leaseDurationSeconds);
+		const nextEligibleDelaySeconds = cleanupDurationSeconds(input.nextEligibleDelaySeconds);
+		const sweepSafetyWindowSeconds = cleanupDurationSeconds(input.sweepSafetyWindowSeconds);
+		const claimedAt = this.cleanupTimestampOffset(0);
+		const leaseExpiresAt = this.cleanupTimestampOffset(leaseDurationSeconds);
+		const nextEligibleAt = this.cleanupTimestampOffset(nextEligibleDelaySeconds);
+		const sweepBeforeAt = this.cleanupTimestampOffset(-sweepSafetyWindowSeconds);
+		const row = await this.db
+			.updateTable("_emdash_media_usage_cleanup")
+			.set({
+				lease_token: input.leaseToken,
+				lease_expires_at: leaseExpiresAt,
+				next_eligible_at: nextEligibleAt,
+				last_started_at: claimedAt,
+				updated_at: claimedAt,
+				scan_before_at: sql<string>`CASE
+					WHEN scan_before_at IS NULL THEN ${sweepBeforeAt}
+					ELSE scan_before_at
+				END`,
+			})
+			.where("task_key", "=", "projection_gc")
+			.where(this.cleanupTimestampIsDue("next_eligible_at"))
+			.where((eb) =>
+				eb.or([eb("lease_token", "is", null), this.cleanupTimestampIsDue("lease_expires_at")]),
+			)
+			.returning([
+				"cursor_created_at",
+				"cursor_id",
+				"last_started_at",
+				"scan_before_at",
+				"consecutive_failures",
+			])
+			.executeTakeFirst();
+		if (!row) return null;
+		if (!row.last_started_at || !row.scan_before_at) {
+			throw new Error("Media usage cleanup claim did not persist its database timestamps");
+		}
+		return {
+			leaseToken: input.leaseToken,
+			cursor:
+				row.cursor_created_at && row.cursor_id
+					? { createdAt: row.cursor_created_at, id: row.cursor_id }
+					: null,
+			claimedAt: row.last_started_at,
+			scanBeforeAt: row.scan_before_at,
+			consecutiveFailures: row.consecutive_failures,
+		};
+	}
+
+	async findMediaUsageCleanupCandidates(input: {
+		cutoff: string;
+		cursor: MediaUsageCleanupCursor | null;
+		limit: number;
+		cleanupLease?: MediaUsageCleanupLease;
+	}): Promise<MediaUsageCleanupCandidate[]> {
+		let query = this.db
+			.selectFrom("_emdash_media_usage as u")
+			.leftJoin("_emdash_media_usage_sources as s", "s.source_key", "u.source_key")
+			.leftJoin("_emdash_media_usage_generation_writes as writer", (join) =>
+				join
+					.onRef("writer.source_key", "=", "u.source_key")
+					.onRef("writer.generation", "=", "u.generation"),
+			)
+			.select([
+				"u.id as id",
+				"u.source_key as source_key",
+				"u.generation as generation",
+				"u.created_at as created_at",
+				"s.current_generation as current_generation",
+				"s.indexed_at as indexed_at",
+				"writer.expires_at as write_lease_expires_at",
+			])
+			.where("u.created_at", "<", input.cutoff)
+			.orderBy("u.created_at", "asc")
+			.orderBy("u.id", "asc")
+			.limit(Math.max(0, Math.floor(input.limit)));
+		if (input.cleanupLease) {
+			query = query.where(this.activeCleanupLeaseExpression(input.cleanupLease));
+		}
+
+		if (input.cursor) {
+			query = query.where((eb) =>
+				eb.or([
+					eb("u.created_at", ">", input.cursor!.createdAt),
+					eb.and([
+						eb("u.created_at", "=", input.cursor!.createdAt),
+						eb("u.id", ">", input.cursor!.id),
+					]),
+				]),
+			);
+		}
+
+		const rows = await query.execute();
+		return rows.map((row) => ({
+			id: row.id,
+			sourceKey: row.source_key,
+			generation: row.generation,
+			createdAt: row.created_at,
+			currentGeneration: row.current_generation,
+			indexedAt: row.indexed_at,
+			writeLeaseExpiresAt: row.write_lease_expires_at,
+		}));
+	}
+
+	async completeMediaUsageCleanup(input: MediaUsageCleanupCompletion): Promise<boolean> {
+		const updates = {
+			lease_token: null,
+			lease_expires_at: null,
+			cursor_created_at: input.sweepComplete ? null : (input.nextCursor?.createdAt ?? null),
+			cursor_id: input.sweepComplete ? null : (input.nextCursor?.id ?? null),
+			...(input.sweepComplete ? { scan_before_at: null } : {}),
+			consecutive_failures: 0,
+			last_completed_at: this.cleanupTimestampOffset(0),
+			last_candidate_count: input.candidateCount,
+			last_deleted_orphans: input.deletedOrphans,
+			last_deleted_stale: input.deletedStale,
+			last_deleted_abandoned: input.deletedAbandoned,
+			last_deleted_write_leases: input.deletedWriteLeases,
+			last_backlog_lower_bound: input.backlogLowerBound,
+			last_scan_has_more: input.scanHasMore ? 1 : 0,
+			last_duration_ms: input.durationMs,
+			last_error_code: null,
+			updated_at: this.cleanupTimestampOffset(0),
+		};
+		const result = await this.db
+			.updateTable("_emdash_media_usage_cleanup")
+			.set(updates)
+			.where("task_key", "=", "projection_gc")
+			.where("lease_token", "=", input.leaseToken)
+			.where(this.cleanupLeaseExpiryIsInFuture("_emdash_media_usage_cleanup.lease_expires_at"))
+			.executeTakeFirst();
+		return Number(result.numUpdatedRows ?? 0) > 0;
+	}
+
+	async failMediaUsageCleanup(input: {
+		leaseToken: string;
+		retryDelaySeconds: number;
+		consecutiveFailures: number;
+		durationMs: number;
+		errorCode: string;
+	}): Promise<boolean> {
+		const retryDelaySeconds = cleanupDurationSeconds(input.retryDelaySeconds);
+		const result = await this.db
+			.updateTable("_emdash_media_usage_cleanup")
+			.set({
+				lease_token: null,
+				lease_expires_at: null,
+				next_eligible_at: this.cleanupTimestampOffset(retryDelaySeconds),
+				consecutive_failures: input.consecutiveFailures,
+				last_completed_at: this.cleanupTimestampOffset(0),
+				last_duration_ms: input.durationMs,
+				last_error_code: input.errorCode,
+				updated_at: this.cleanupTimestampOffset(0),
+			})
+			.where("task_key", "=", "projection_gc")
+			.where("lease_token", "=", input.leaseToken)
+			.where(this.cleanupLeaseExpiryIsInFuture("_emdash_media_usage_cleanup.lease_expires_at"))
+			.executeTakeFirst();
+		return Number(result.numUpdatedRows ?? 0) > 0;
+	}
+
+	async deleteOrphanOccurrencesOlderThan(
+		cutoff: string,
+		limit: number,
+		options: MediaUsageCleanupDeleteOptions = {},
+	): Promise<number> {
 		const batchLimit = Math.floor(limit);
 		if (batchLimit <= 0) return 0;
+		if (options.candidateIds) {
+			return this.deleteOrphanCandidateIds(
+				options.candidateIds.slice(0, batchLimit),
+				cutoff,
+				options.cleanupLease,
+				options.canIssueStatement,
+			);
+		}
+		if (!canIssueCleanupStatement(options.canIssueStatement)) return 0;
 
-		const rows = await this.db
+		let query = this.db
 			.selectFrom("_emdash_media_usage as u")
 			.leftJoin("_emdash_media_usage_sources as s", (join) =>
 				join.onRef("s.source_key", "=", "u.source_key"),
 			)
+			.leftJoin("_emdash_media_usage_generation_writes as writer", (join) =>
+				join
+					.onRef("writer.source_key", "=", "u.source_key")
+					.onRef("writer.generation", "=", "u.generation"),
+			)
 			.select("u.id")
 			.where("s.source_key", "is", null)
 			.where("u.created_at", "<", cutoff)
+			.where(this.noActiveGenerationWriteExpression("u"))
 			.orderBy("u.created_at", "asc")
 			.orderBy("u.id", "asc")
-			.limit(batchLimit)
-			.execute();
+			.limit(batchLimit);
+		if (options.cleanupLease) {
+			query = query.where(this.activeCleanupLeaseExpression(options.cleanupLease));
+		}
+		const rows = await query.execute();
 
-		let deleted = 0;
-		for (const idBatch of chunks(
+		return this.deleteOrphanCandidateIds(
 			rows.map((row) => row.id),
-			SQL_BATCH_SIZE,
-		)) {
-			const result = await this.db
-				.deleteFrom("_emdash_media_usage")
-				.where("id", "in", idBatch)
-				.where("created_at", "<", cutoff)
-				.where(
-					sql<boolean>`NOT EXISTS (SELECT 1 FROM _emdash_media_usage_sources s WHERE s.source_key = _emdash_media_usage.source_key)`,
-				)
-				.executeTakeFirst();
-			deleted += Number(result.numDeletedRows ?? 0);
-		}
-		return deleted;
+			cutoff,
+			options.cleanupLease,
+			options.canIssueStatement,
+		);
 	}
 
-	async deleteStaleGenerationsOlderThan(cutoff: string, limit: number): Promise<number> {
+	async deleteStaleGenerationsOlderThan(
+		cutoff: string,
+		limit: number,
+		options: MediaUsageCleanupDeleteOptions = {},
+	): Promise<number> {
 		const batchLimit = Math.floor(limit);
 		if (batchLimit <= 0) return 0;
+		if (options.candidateIds) {
+			return this.deleteStaleCandidateIds(
+				options.candidateIds.slice(0, batchLimit),
+				cutoff,
+				options.cleanupLease,
+				options.canIssueStatement,
+			);
+		}
+		if (!canIssueCleanupStatement(options.canIssueStatement)) return 0;
 
-		const rows = await this.db
+		let query = this.db
 			.selectFrom("_emdash_media_usage as u")
 			.innerJoin("_emdash_media_usage_sources as s", (join) =>
 				join.onRef("s.source_key", "=", "u.source_key"),
 			)
+			.leftJoin("_emdash_media_usage_generation_writes as writer", (join) =>
+				join
+					.onRef("writer.source_key", "=", "u.source_key")
+					.onRef("writer.generation", "=", "u.generation"),
+			)
 			.select("u.id")
 			.where("u.created_at", "<", cutoff)
 			.whereRef("u.generation", "!=", "s.current_generation")
 			.whereRef("u.created_at", "<", "s.indexed_at")
+			.where(this.noActiveGenerationWriteExpression("u"))
 			.orderBy("u.created_at", "asc")
 			.orderBy("u.id", "asc")
-			.limit(batchLimit)
-			.execute();
-
-		const ids = rows.map((row) => row.id);
-		if (ids.length === 0) return 0;
-
-		let deleted = 0;
-		for (const idBatch of chunks(ids, SQL_BATCH_SIZE)) {
-			const result = await this.db
-				.deleteFrom("_emdash_media_usage")
-				.where("id", "in", idBatch)
-				.where("created_at", "<", cutoff)
-				.where((eb) =>
-					eb.exists(
-						eb
-							.selectFrom("_emdash_media_usage_sources as s")
-							.select("s.source_key")
-							.whereRef("s.source_key", "=", "_emdash_media_usage.source_key")
-							.whereRef("s.current_generation", "!=", "_emdash_media_usage.generation")
-							.whereRef("_emdash_media_usage.created_at", "<", "s.indexed_at"),
-					),
-				)
-				.executeTakeFirst();
-			deleted += Number(result.numDeletedRows ?? 0);
+			.limit(batchLimit);
+		if (options.cleanupLease) {
+			query = query.where(this.activeCleanupLeaseExpression(options.cleanupLease));
 		}
-		return deleted;
+		const rows = await query.execute();
+
+		return this.deleteStaleCandidateIds(
+			rows.map((row) => row.id),
+			cutoff,
+			options.cleanupLease,
+			options.canIssueStatement,
+		);
 	}
 
-	async deleteAbandonedGenerationsOlderThan(cutoff: string, limit: number): Promise<number> {
+	async deleteAbandonedGenerationsOlderThan(
+		cutoff: string,
+		limit: number,
+		options: MediaUsageCleanupDeleteOptions = {},
+	): Promise<number> {
 		const batchLimit = Math.floor(limit);
 		if (batchLimit <= 0) return 0;
+		if (options.candidateIds) {
+			return this.deleteAbandonedCandidateIds(
+				options.candidateIds.slice(0, batchLimit),
+				cutoff,
+				options.cleanupLease,
+				options.canIssueStatement,
+			);
+		}
+		if (!canIssueCleanupStatement(options.canIssueStatement)) return 0;
 
-		const rows = await this.db
+		let query = this.db
 			.selectFrom("_emdash_media_usage as u")
 			.innerJoin("_emdash_media_usage_sources as s", (join) =>
 				join.onRef("s.source_key", "=", "u.source_key"),
 			)
+			.leftJoin("_emdash_media_usage_generation_writes as writer", (join) =>
+				join
+					.onRef("writer.source_key", "=", "u.source_key")
+					.onRef("writer.generation", "=", "u.generation"),
+			)
 			.select("u.id")
 			.where("u.created_at", "<", cutoff)
 			.whereRef("u.generation", "!=", "s.current_generation")
 			.whereRef("u.created_at", ">=", "s.indexed_at")
+			.where(this.noActiveGenerationWriteExpression("u"))
 			.orderBy("u.created_at", "asc")
 			.orderBy("u.id", "asc")
-			.limit(batchLimit)
-			.execute();
+			.limit(batchLimit);
+		if (options.cleanupLease) {
+			query = query.where(this.activeCleanupLeaseExpression(options.cleanupLease));
+		}
+		const rows = await query.execute();
 
-		let deleted = 0;
-		for (const idBatch of chunks(
+		return this.deleteAbandonedCandidateIds(
 			rows.map((row) => row.id),
-			SQL_BATCH_SIZE,
-		)) {
-			const result = await this.db
-				.deleteFrom("_emdash_media_usage")
-				.where("id", "in", idBatch)
-				.where("created_at", "<", cutoff)
-				.where((eb) =>
-					eb.exists(
-						eb
-							.selectFrom("_emdash_media_usage_sources as s")
-							.select("s.source_key")
-							.whereRef("s.source_key", "=", "_emdash_media_usage.source_key")
-							.whereRef("s.current_generation", "!=", "_emdash_media_usage.generation")
-							.whereRef("_emdash_media_usage.created_at", ">=", "s.indexed_at"),
-					),
-				)
-				.executeTakeFirst();
-			deleted += Number(result.numDeletedRows ?? 0);
-		}
-		return deleted;
+			cutoff,
+			options.cleanupLease,
+			options.canIssueStatement,
+		);
+	}
+
+	async deleteExpiredGenerationWriteLeases(
+		limit: number,
+		cleanupLease?: MediaUsageCleanupLease,
+		canIssueStatement?: () => boolean,
+	): Promise<number> {
+		const batchLimit = Math.floor(limit);
+		if (batchLimit <= 0 || !canIssueCleanupStatement(canIssueStatement)) return 0;
+		let query = this.db
+			.selectFrom("_emdash_media_usage_generation_writes")
+			.select("lease_token")
+			.where(this.generationWriteLeaseHasExpired("expires_at"))
+			.orderBy("expires_at", "asc")
+			.orderBy("lease_token", "asc")
+			.limit(batchLimit);
+		if (cleanupLease) query = query.where(this.activeCleanupLeaseExpression(cleanupLease));
+		const rows = await query.execute();
+		if (rows.length === 0 || !canIssueCleanupStatement(canIssueStatement)) return 0;
+		let deleteQuery = this.db
+			.deleteFrom("_emdash_media_usage_generation_writes")
+			.where(
+				"lease_token",
+				"in",
+				rows.map((row) => row.lease_token),
+			)
+			.where(this.generationWriteLeaseHasExpired("expires_at"));
+		if (cleanupLease)
+			deleteQuery = deleteQuery.where(this.activeCleanupLeaseExpression(cleanupLease));
+		const result = await deleteQuery.executeTakeFirst();
+		return Number(result.numDeletedRows ?? 0);
 	}
 
 	async upsertIndexStatus(input: MediaUsageIndexStatusInput): Promise<MediaUsageIndexStatus> {
@@ -979,6 +1450,43 @@ export class MediaUsageRepository {
 		return status;
 	}
 
+	async invalidateIndexStatusForSchemaChange(collectionSlug: string): Promise<boolean> {
+		const result = await this.db
+			.updateTable("_emdash_media_usage_index_status as status")
+			.set({
+				change_epoch: sql<number>`change_epoch + 1`,
+				status: "stale",
+				completed_at: null,
+				cursor: null,
+				last_error_code: "CONTENT_USAGE_STALE",
+				reconciliation_required: 1,
+				updated_at: this.sortableUtcTimestamp(),
+			})
+			.where("status.adapter_id", "=", "content-media")
+			.where("status.scope_type", "=", "collection")
+			.where("status.scope_key", "=", collectionSlug)
+			.where("status.capture_state", "=", "active")
+			.where((eb) =>
+				eb.exists(
+					eb
+						.selectFrom("_emdash_collections as collection")
+						.select("collection.id")
+						.whereRef("collection.id", "=", "status.collection_id")
+						.whereRef("collection.slug", "=", "status.scope_key"),
+				),
+			)
+			.where(
+				sql<boolean>`EXISTS (
+					SELECT 1
+					FROM _emdash_media_usage_activation AS activation
+					WHERE activation.task_key = 'incremental_capture'
+						AND activation.state = 'active'
+				)`,
+			)
+			.executeTakeFirst();
+		return Number(result.numUpdatedRows ?? 0) === 1;
+	}
+
 	async beginIndexStatusRepair(
 		input: MediaUsageIndexStatusRepairInput,
 	): Promise<MediaUsageIndexStatus> {
@@ -1029,6 +1537,247 @@ export class MediaUsageRepository {
 		};
 	}
 
+	async beginIndexStatusRepairAtCurrentEpoch(
+		input: MediaUsageIndexStatusEpochRepairInput,
+	): Promise<MediaUsageIndexStatusEpochRepairRun | null> {
+		const now = this.sortableUtcTimestamp();
+		const row = await this.db
+			.updateTable("_emdash_media_usage_index_status")
+			.set({
+				status: "running",
+				schema_version: input.schemaVersion,
+				started_at: now,
+				completed_at: null,
+				cursor: input.runToken,
+				indexed_source_count: 0,
+				failed_source_count: 0,
+				last_error_code: null,
+				reconciliation_required: 1,
+				updated_at: now,
+			})
+			.where("adapter_id", "=", input.adapterId)
+			.where("scope_type", "=", input.scopeType)
+			.where("scope_key", "=", input.scopeKey)
+			.where("collection_id", "=", input.collectionId)
+			.where("capture_state", "=", "active")
+			.where(
+				sql<boolean>`EXISTS (
+					SELECT 1
+					FROM _emdash_collections AS collection
+					WHERE collection.id = ${input.collectionId}
+						AND collection.slug = ${input.scopeKey}
+				)`,
+			)
+			.where(
+				sql<boolean>`EXISTS (
+					SELECT 1
+					FROM _emdash_media_usage_activation AS activation
+					WHERE activation.task_key = 'incremental_capture'
+						AND activation.state = 'active'
+				)`,
+			)
+			.returning(["change_epoch", "started_at"])
+			.executeTakeFirst();
+		if (!row?.started_at) return null;
+		return { changeEpoch: row.change_epoch, startedAt: row.started_at };
+	}
+
+	async finalizeIndexStatusRepairAtEpoch(
+		input: MediaUsageIndexStatusEpochFinalizeInput,
+	): Promise<MediaUsageGuardedIndexStatusResult> {
+		const now = this.sortableUtcTimestamp();
+		const updates = {
+			status: input.status,
+			schema_version: input.schemaVersion,
+			completed_at: now,
+			cursor: null,
+			indexed_source_count: input.indexedSourceCount,
+			failed_source_count: input.failedSourceCount,
+			last_error_code: input.lastErrorCode,
+			reconciliation_required: input.status === "complete" ? 0 : 1,
+			updated_at: now,
+		};
+
+		let query = this.db
+			.updateTable("_emdash_media_usage_index_status")
+			.set(updates)
+			.where("adapter_id", "=", input.adapterId)
+			.where("scope_type", "=", input.scopeType)
+			.where("scope_key", "=", input.scopeKey)
+			.where("collection_id", "=", input.collectionId)
+			.where("status", "=", "running")
+			.where("cursor", "=", input.runToken)
+			.where("change_epoch", "=", input.startingEpoch)
+			.where(
+				sql<boolean>`EXISTS (
+					SELECT 1
+					FROM _emdash_collections AS collection
+					WHERE collection.id = ${input.collectionId}
+						AND collection.slug = ${input.scopeKey}
+				)`,
+			);
+		if (input.status === "complete") {
+			query = query.where(
+				sql<boolean>`NOT EXISTS (
+					SELECT 1
+					FROM _emdash_media_usage_work AS work
+					WHERE work.collection_id = ${input.collectionId}
+				)`,
+			);
+		}
+		const result = await query.executeTakeFirst();
+		const finalized = Number(result.numUpdatedRows ?? 0) > 0;
+
+		if (!finalized) {
+			await this.db
+				.updateTable("_emdash_media_usage_index_status")
+				.set({
+					status: "stale",
+					completed_at: null,
+					cursor: null,
+					last_error_code: "CONTENT_USAGE_REPAIR_CONFLICT",
+					reconciliation_required: 1,
+					updated_at: this.sortableUtcTimestamp(),
+				})
+				.where("adapter_id", "=", input.adapterId)
+				.where("scope_type", "=", input.scopeType)
+				.where("scope_key", "=", input.scopeKey)
+				.where("collection_id", "=", input.collectionId)
+				.where("status", "=", "running")
+				.where("cursor", "=", input.runToken)
+				.execute();
+		}
+
+		return {
+			finalized,
+			status: await this.findIndexStatusForCollection(input, input.collectionId),
+		};
+	}
+
+	async recordIncrementalSuccess(input: MediaUsageIncrementalStatusIdentity): Promise<boolean> {
+		const observed = await this.db
+			.selectFrom("_emdash_media_usage_index_status")
+			.select("change_epoch")
+			.where("adapter_id", "=", "content-media")
+			.where("scope_type", "=", "collection")
+			.where("scope_key", "=", input.collectionSlug)
+			.where("collection_id", "=", input.collectionId)
+			.where("capture_state", "=", "active")
+			.where(
+				sql<boolean>`EXISTS (
+					SELECT 1
+					FROM _emdash_collections AS collection
+					WHERE collection.id = ${input.collectionId}
+						AND collection.slug = ${input.collectionSlug}
+				)`,
+			)
+			.executeTakeFirst();
+		if (!observed) return false;
+
+		const canComplete = sql<boolean>`(
+			reconciliation_required = 0
+			AND status IN ('complete', 'stale', 'partial')
+			AND NOT EXISTS (
+				SELECT 1
+				FROM _emdash_media_usage_work AS work
+				WHERE work.collection_id = ${input.collectionId}
+			)
+		)`;
+		const now = this.sortableUtcTimestamp();
+		const result = await this.db
+			.updateTable("_emdash_media_usage_index_status")
+			.set({
+				status: sql<string>`CASE WHEN ${canComplete} THEN 'complete' ELSE status END`,
+				completed_at: sql<
+					string | null
+				>`CASE WHEN ${canComplete} THEN ${now} ELSE completed_at END`,
+				last_error_code: sql<
+					string | null
+				>`CASE WHEN ${canComplete} THEN NULL ELSE last_error_code END`,
+				last_incremental_success_at: now,
+				updated_at: now,
+			})
+			.where("adapter_id", "=", "content-media")
+			.where("scope_type", "=", "collection")
+			.where("scope_key", "=", input.collectionSlug)
+			.where("collection_id", "=", input.collectionId)
+			.where("change_epoch", "=", observed.change_epoch)
+			.where("capture_state", "=", "active")
+			.where(
+				sql<boolean>`EXISTS (
+					SELECT 1
+					FROM _emdash_collections AS collection
+					WHERE collection.id = ${input.collectionId}
+						AND collection.slug = ${input.collectionSlug}
+				)`,
+			)
+			.executeTakeFirst();
+		return Number(result.numUpdatedRows ?? 0) > 0;
+	}
+
+	async recordIncrementalFailure(
+		input: MediaUsageIncrementalStatusIdentity & {
+			contentId: string;
+			workVersion: number | string;
+			errorCode: string;
+		},
+	): Promise<boolean> {
+		const now = this.sortableUtcTimestamp();
+		const automaticRunOwnsCoverage = sql<boolean>`EXISTS (
+			SELECT 1
+			FROM _emdash_media_usage_reconciliations AS reconciliation
+			WHERE reconciliation.collection_id = ${input.collectionId}
+				AND reconciliation.run_token = cursor
+		)`;
+		const result = await this.db
+			.updateTable("_emdash_media_usage_index_status")
+			.set({
+				status: sql<string>`CASE
+					WHEN ${automaticRunOwnsCoverage} THEN status
+					WHEN reconciliation_required = 0 THEN 'partial'
+					WHEN status = 'running' THEN 'stale'
+					ELSE status
+				END`,
+				completed_at: sql<string | null>`CASE
+					WHEN ${automaticRunOwnsCoverage} THEN completed_at
+					WHEN reconciliation_required = 0 OR status = 'running' THEN NULL
+					ELSE completed_at
+				END`,
+				cursor: sql<string | null>`CASE
+					WHEN ${automaticRunOwnsCoverage} THEN cursor
+					WHEN status = 'running' THEN NULL
+					ELSE cursor
+				END`,
+				last_error_code: input.errorCode,
+				updated_at: now,
+			})
+			.where("adapter_id", "=", "content-media")
+			.where("scope_type", "=", "collection")
+			.where("scope_key", "=", input.collectionSlug)
+			.where("collection_id", "=", input.collectionId)
+			.where(
+				sql<boolean>`EXISTS (
+					SELECT 1
+					FROM _emdash_media_usage_work AS work
+					WHERE work.collection_id = ${input.collectionId}
+						AND work.content_id = ${input.contentId}
+						AND work.work_version = ${input.workVersion}
+						AND work.state = 'failed'
+						AND work.last_error_code = ${input.errorCode}
+				)`,
+			)
+			.where(
+				sql<boolean>`EXISTS (
+					SELECT 1
+					FROM _emdash_collections AS collection
+					WHERE collection.id = ${input.collectionId}
+						AND collection.slug = ${input.collectionSlug}
+				)`,
+			)
+			.executeTakeFirst();
+		return Number(result.numUpdatedRows ?? 0) > 0;
+	}
+
 	async findIndexStatus(
 		identity: MediaUsageIndexStatusIdentity,
 	): Promise<MediaUsageIndexStatus | null> {
@@ -1043,16 +1792,41 @@ export class MediaUsageRepository {
 		return row ? rowToIndexStatus(row) : null;
 	}
 
-	async deleteIndexStatus(identity: MediaUsageIndexStatusIdentity): Promise<number> {
-		const result = await this.db
-			.deleteFrom("_emdash_media_usage_index_status")
+	private async findIndexStatusForCollection(
+		identity: MediaUsageIndexStatusIdentity,
+		collectionId: string,
+	): Promise<MediaUsageIndexStatus | null> {
+		const row = await this.db
+			.selectFrom("_emdash_media_usage_index_status")
+			.selectAll()
 			.where("adapter_id", "=", identity.adapterId)
 			.where("scope_type", "=", identity.scopeType)
 			.where("scope_key", "=", identity.scopeKey)
+			.where("collection_id", "=", collectionId)
 			.executeTakeFirst();
+		return row ? rowToIndexStatus(row) : null;
+	}
+
+	async deleteIndexStatus(
+		identity: MediaUsageIndexStatusIdentity,
+		collectionId?: string,
+	): Promise<number> {
+		let query = this.db
+			.deleteFrom("_emdash_media_usage_index_status")
+			.where("adapter_id", "=", identity.adapterId)
+			.where("scope_type", "=", identity.scopeType)
+			.where("scope_key", "=", identity.scopeKey);
+		if (collectionId !== undefined) query = query.where("collection_id", "=", collectionId);
+		const result = await query.executeTakeFirst();
 		return Number(result.numDeletedRows ?? 0);
 	}
 
+	private sortableUtcTimestamp(): RawBuilder<string> {
+		return isPostgres(this.db)
+			? sql<string>`to_char(clock_timestamp() AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"')`
+			: sql<string>`strftime('%Y-%m-%dT%H:%M:%fZ', 'now')`;
+	}
+
 	private async findCurrentUsagePage(
 		applyFilter: (
 			query: ReturnType<MediaUsageRepository["currentUsageBaseQuery"]>,
@@ -1103,14 +1877,253 @@ export class MediaUsageRepository {
 			.where("s.collection_slug", "is not", null)
 			.where("s.content_id", "is not", null)
 			.where("s.source_variant", "in", ["columns", "draft_overlay"])
+			.where(contentSourceMatchesActiveCollection("s", "collection.id"))
 			.where(CONTENT_SOURCE_ELIGIBILITY);
 	}
 
+	private async deleteOrphanCandidateIds(
+		ids: readonly string[],
+		cutoff: string,
+		cleanupLease?: MediaUsageCleanupLease,
+		canIssueStatement?: () => boolean,
+	): Promise<number> {
+		let deleted = 0;
+		for (const idBatch of chunks([...ids], cleanupDeleteBatchSize(cleanupLease))) {
+			if (!canIssueCleanupStatement(canIssueStatement)) break;
+			if (cleanupLease) {
+				await this.markOrphanCandidatesForCleanup(idBatch, cutoff, cleanupLease);
+				if (!canIssueCleanupStatement(canIssueStatement)) break;
+			}
+			let query = this.db
+				.deleteFrom("_emdash_media_usage")
+				.where("id", "in", idBatch)
+				.where("created_at", "<", cutoff)
+				.where(
+					sql<boolean>`NOT EXISTS (SELECT 1 FROM _emdash_media_usage_sources source WHERE source.source_key = _emdash_media_usage.source_key)`,
+				)
+				.where(this.noActiveGenerationWriteExpression());
+			if (cleanupLease) {
+				query = query
+					.where("cleanup_lease_token", "=", cleanupLease.leaseToken)
+					.where(this.activeCleanupLeaseExpression(cleanupLease));
+			}
+			const result = await query.executeTakeFirst();
+			deleted += Number(result.numDeletedRows ?? 0);
+		}
+		return deleted;
+	}
+
+	private async deleteStaleCandidateIds(
+		ids: readonly string[],
+		cutoff: string,
+		cleanupLease?: MediaUsageCleanupLease,
+		canIssueStatement?: () => boolean,
+	): Promise<number> {
+		let deleted = 0;
+		for (const idBatch of chunks([...ids], cleanupDeleteBatchSize(cleanupLease))) {
+			if (!canIssueCleanupStatement(canIssueStatement)) break;
+			if (cleanupLease) {
+				await this.markStaleCandidatesForCleanup(idBatch, cutoff, cleanupLease);
+				if (!canIssueCleanupStatement(canIssueStatement)) break;
+			}
+			let query = this.db
+				.deleteFrom("_emdash_media_usage")
+				.where("id", "in", idBatch)
+				.where("created_at", "<", cutoff)
+				.where((eb) =>
+					eb.exists(
+						eb
+							.selectFrom("_emdash_media_usage_sources as source")
+							.select("source.source_key")
+							.whereRef("source.source_key", "=", "_emdash_media_usage.source_key")
+							.whereRef("source.current_generation", "!=", "_emdash_media_usage.generation")
+							.whereRef("_emdash_media_usage.created_at", "<", "source.indexed_at"),
+					),
+				)
+				.where(this.noActiveGenerationWriteExpression());
+			if (cleanupLease) {
+				query = query
+					.where("cleanup_lease_token", "=", cleanupLease.leaseToken)
+					.where(this.activeCleanupLeaseExpression(cleanupLease));
+			}
+			const result = await query.executeTakeFirst();
+			deleted += Number(result.numDeletedRows ?? 0);
+		}
+		return deleted;
+	}
+
+	private async deleteAbandonedCandidateIds(
+		ids: readonly string[],
+		cutoff: string,
+		cleanupLease?: MediaUsageCleanupLease,
+		canIssueStatement?: () => boolean,
+	): Promise<number> {
+		let deleted = 0;
+		for (const idBatch of chunks([...ids], cleanupDeleteBatchSize(cleanupLease))) {
+			if (!canIssueCleanupStatement(canIssueStatement)) break;
+			if (cleanupLease) {
+				await this.markAbandonedCandidatesForCleanup(idBatch, cutoff, cleanupLease);
+				if (!canIssueCleanupStatement(canIssueStatement)) break;
+			}
+			let query = this.db
+				.deleteFrom("_emdash_media_usage")
+				.where("id", "in", idBatch)
+				.where("created_at", "<", cutoff)
+				.where((eb) =>
+					eb.exists(
+						eb
+							.selectFrom("_emdash_media_usage_sources as source")
+							.select("source.source_key")
+							.whereRef("source.source_key", "=", "_emdash_media_usage.source_key")
+							.whereRef("source.current_generation", "!=", "_emdash_media_usage.generation")
+							.whereRef("_emdash_media_usage.created_at", ">=", "source.indexed_at"),
+					),
+				)
+				.where(this.noActiveGenerationWriteExpression());
+			if (cleanupLease) {
+				query = query
+					.where("cleanup_lease_token", "=", cleanupLease.leaseToken)
+					.where(this.activeCleanupLeaseExpression(cleanupLease));
+			}
+			const result = await query.executeTakeFirst();
+			deleted += Number(result.numDeletedRows ?? 0);
+		}
+		return deleted;
+	}
+
+	private async markOrphanCandidatesForCleanup(
+		ids: readonly string[],
+		cutoff: string,
+		cleanupLease: MediaUsageCleanupLease,
+	): Promise<void> {
+		await this.db
+			.updateTable("_emdash_media_usage")
+			.set({ cleanup_lease_token: cleanupLease.leaseToken })
+			.where("id", "in", ids)
+			.where("created_at", "<", cutoff)
+			.where(
+				sql<boolean>`NOT EXISTS (SELECT 1 FROM _emdash_media_usage_sources source WHERE source.source_key = _emdash_media_usage.source_key)`,
+			)
+			.where(this.noActiveGenerationWriteExpression())
+			.where(this.activeCleanupLeaseExpression(cleanupLease))
+			.execute();
+	}
+
+	private async markStaleCandidatesForCleanup(
+		ids: readonly string[],
+		cutoff: string,
+		cleanupLease: MediaUsageCleanupLease,
+	): Promise<void> {
+		await this.db
+			.updateTable("_emdash_media_usage")
+			.set({ cleanup_lease_token: cleanupLease.leaseToken })
+			.where("id", "in", ids)
+			.where("created_at", "<", cutoff)
+			.where((eb) =>
+				eb.exists(
+					eb
+						.selectFrom("_emdash_media_usage_sources as source")
+						.select("source.source_key")
+						.whereRef("source.source_key", "=", "_emdash_media_usage.source_key")
+						.whereRef("source.current_generation", "!=", "_emdash_media_usage.generation")
+						.whereRef("_emdash_media_usage.created_at", "<", "source.indexed_at"),
+				),
+			)
+			.where(this.noActiveGenerationWriteExpression())
+			.where(this.activeCleanupLeaseExpression(cleanupLease))
+			.execute();
+	}
+
+	private async markAbandonedCandidatesForCleanup(
+		ids: readonly string[],
+		cutoff: string,
+		cleanupLease: MediaUsageCleanupLease,
+	): Promise<void> {
+		await this.db
+			.updateTable("_emdash_media_usage")
+			.set({ cleanup_lease_token: cleanupLease.leaseToken })
+			.where("id", "in", ids)
+			.where("created_at", "<", cutoff)
+			.where((eb) =>
+				eb.exists(
+					eb
+						.selectFrom("_emdash_media_usage_sources as source")
+						.select("source.source_key")
+						.whereRef("source.source_key", "=", "_emdash_media_usage.source_key")
+						.whereRef("source.current_generation", "!=", "_emdash_media_usage.generation")
+						.whereRef("_emdash_media_usage.created_at", ">=", "source.indexed_at"),
+				),
+			)
+			.where(this.noActiveGenerationWriteExpression())
+			.where(this.activeCleanupLeaseExpression(cleanupLease))
+			.execute();
+	}
+
+	private noActiveGenerationWriteExpression(usageTable = "_emdash_media_usage") {
+		const sourceKey = sql.ref(`${usageTable}.source_key`);
+		const generation = sql.ref(`${usageTable}.generation`);
+		return sql<boolean>`NOT EXISTS (
+				SELECT 1
+				FROM _emdash_media_usage_generation_writes AS writer
+				WHERE writer.source_key = ${sourceKey}
+					AND writer.generation = ${generation}
+					AND ${this.generationWriteLeaseExpiryIsInFuture("writer.expires_at")}
+			)`;
+	}
+
+	private activeCleanupLeaseExpression(cleanupLease: MediaUsageCleanupLease) {
+		const rowLock = isPostgres(this.db) ? sql` FOR UPDATE` : sql``;
+		return sql<boolean>`EXISTS (
+				SELECT 1
+				FROM _emdash_media_usage_cleanup AS cleanup
+				WHERE cleanup.task_key = 'projection_gc'
+					AND cleanup.lease_token = ${cleanupLease.leaseToken}
+					AND ${this.cleanupLeaseExpiryIsInFuture("cleanup.lease_expires_at")}
+				${rowLock}
+			)`;
+	}
+
+	private cleanupLeaseExpiryIsInFuture(column: string) {
+		const leaseExpiresAt = sql.ref(column);
+		return isPostgres(this.db)
+			? sql<boolean>`${leaseExpiresAt}::timestamptz > clock_timestamp()`
+			: sql<boolean>`${leaseExpiresAt} > strftime('%Y-%m-%dT%H:%M:%fZ', 'now')`;
+	}
+
+	private cleanupTimestampIsDue(column: string) {
+		const timestamp = sql.ref(column);
+		return isPostgres(this.db)
+			? sql<boolean>`${timestamp}::timestamptz <= clock_timestamp()`
+			: sql<boolean>`${timestamp} <= strftime('%Y-%m-%dT%H:%M:%fZ', 'now')`;
+	}
+
+	private cleanupTimestampOffset(offsetSeconds: number): RawBuilder<string> {
+		if (isPostgres(this.db)) {
+			return sql<string>`to_char(
+				(clock_timestamp() AT TIME ZONE 'UTC') + (${offsetSeconds} * INTERVAL '1 second'),
+				'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"'
+			)`;
+		}
+		return sql<string>`strftime(
+			'%Y-%m-%dT%H:%M:%fZ',
+			'now',
+			${`${offsetSeconds >= 0 ? "+" : ""}${offsetSeconds} seconds`}
+		)`;
+	}
+
+	private generationWriteLeaseHasExpired(column: string) {
+		const leaseExpiresAt = sql.ref(column);
+		return isPostgres(this.db)
+			? sql<boolean>`${leaseExpiresAt}::timestamptz <= clock_timestamp()`
+			: sql<boolean>`${leaseExpiresAt} <= strftime('%Y-%m-%dT%H:%M:%fZ', 'now')`;
+	}
+
 	private async deleteSourceKeys(sourceKeys: readonly string[]): Promise<number> {
 		const uniqueSourceKeys = [...new Set(sourceKeys)];
 		if (uniqueSourceKeys.length === 0) return 0;
 
 		return withTransaction(this.db, async (trx) => {
+			await this.lockCleanupBeforeSourceDelete(trx);
 			let deleted = 0;
 			for (const sourceKeyBatch of chunks(uniqueSourceKeys, SQL_BATCH_SIZE)) {
 				const result = await trx
@@ -1119,6 +2132,11 @@ export class MediaUsageRepository {
 					.executeTakeFirst();
 				deleted += Number(result.numDeletedRows ?? 0);
 
+				await trx
+					.updateTable("_emdash_media_usage")
+					.set({ cleanup_lease_token: null })
+					.where("source_key", "in", sourceKeyBatch)
+					.execute();
 				await trx
 					.deleteFrom("_emdash_media_usage")
 					.where("source_key", "in", sourceKeyBatch)
@@ -1133,8 +2151,12 @@ export class MediaUsageRepository {
 		sourceKey: string,
 		generation: string,
 	): Promise<void> {
-		// Guarded source deletes remove only the generation that won the source CAS;
-		// unmatched generations become invisible orphans reclaimed by age-gated cleanup.
+		await db
+			.updateTable("_emdash_media_usage")
+			.set({ cleanup_lease_token: null })
+			.where("source_key", "=", sourceKey)
+			.where("generation", "=", generation)
+			.execute();
 		await db
 			.deleteFrom("_emdash_media_usage")
 			.where("source_key", "=", sourceKey)
@@ -1142,6 +2164,16 @@ export class MediaUsageRepository {
 			.execute();
 	}
 
+	private async lockCleanupBeforeSourceDelete(db: DatabaseExecutor): Promise<void> {
+		if (!isPostgres(this.db)) return;
+		await sql`
+			SELECT 1
+			FROM _emdash_media_usage_cleanup
+			WHERE task_key = 'projection_gc'
+			FOR SHARE
+		`.execute(db);
+	}
+
 	private async insertOccurrences(
 		db: DatabaseExecutor,
 		sourceKey: string,
@@ -1172,43 +2204,252 @@ export class MediaUsageRepository {
 		}
 	}
 
+	private async lockCanonicalSourceCollection(
+		db: DatabaseExecutor,
+		source: MediaUsageSourceInput,
+	): Promise<boolean> {
+		if (source.collectionId === undefined || source.collectionId === null) return true;
+		if (!source.collectionSlug) return false;
+		if (!isPostgres(this.db)) return true;
+		const collection = await db
+			.selectFrom("_emdash_collections")
+			.select("id")
+			.where("id", "=", source.collectionId)
+			.where("slug", "=", source.collectionSlug)
+			.forKeyShare()
+			.executeTakeFirst();
+		return collection !== undefined;
+	}
+
 	private async upsertSource(
 		db: DatabaseExecutor,
 		source: MediaUsageSourceInput,
 		generation: string,
 		now: string,
-	): Promise<void> {
+		leaseToken: string,
+	): Promise<boolean> {
 		const row = this.buildSourceRow(source, generation, now);
-
-		await db
-			.insertInto("_emdash_media_usage_sources")
-			.values(row)
-			.onConflict((oc) => oc.column("source_key").doUpdateSet(this.sourceUpdateSet(row)))
-			.execute();
+		return this.persistSourceIfWriteLease(
+			db,
+			row,
+			leaseToken,
+			sql`
+				ON CONFLICT (source_key) DO UPDATE SET
+					source_type = excluded.source_type,
+					collection_id = excluded.collection_id,
+					collection_slug = excluded.collection_slug,
+					content_id = excluded.content_id,
+					source_variant = excluded.source_variant,
+					locale = excluded.locale,
+					translation_group = excluded.translation_group,
+					content_slug = excluded.content_slug,
+					content_title = excluded.content_title,
+					content_status = excluded.content_status,
+					content_scheduled_at = excluded.content_scheduled_at,
+					content_deleted_at = excluded.content_deleted_at,
+					revision_id = excluded.revision_id,
+					current_generation = excluded.current_generation,
+					schema_version = excluded.schema_version,
+					source_updated_at = excluded.source_updated_at,
+					source_version = excluded.source_version,
+					source_fingerprint = excluded.source_fingerprint,
+					identity_version = excluded.identity_version,
+					source_completeness = excluded.source_completeness,
+					last_attempted_at = excluded.last_attempted_at,
+					last_error_code = excluded.last_error_code,
+					indexed_at = excluded.indexed_at,
+					updated_at = excluded.updated_at
+			`,
+		);
 	}
 
 	private async insertSourceIfAbsent(
 		db: DatabaseExecutor,
-		row: Insertable<MediaUsageSourceTable>,
+		row: ReturnType<MediaUsageRepository["buildSourceRow"]>,
+		leaseToken: string,
 	): Promise<boolean> {
-		const result = await db
-			.insertInto("_emdash_media_usage_sources")
-			.values(row)
-			.onConflict((oc) => oc.column("source_key").doNothing())
-			.executeTakeFirst();
-		return (result.numInsertedOrUpdatedRows ?? 0n) > 0n;
+		return this.persistSourceIfWriteLease(
+			db,
+			row,
+			leaseToken,
+			sql`ON CONFLICT (source_key) DO NOTHING`,
+		);
+	}
+
+	private async persistSourceIfWriteLease(
+		db: DatabaseExecutor,
+		row:
+			| ReturnType<MediaUsageRepository["buildSourceRow"]>
+			| ReturnType<MediaUsageRepository["buildAttemptedSourceRow"]>,
+		leaseToken: string,
+		conflict: RawBuilder<unknown>,
+	): Promise<boolean> {
+		const result = await sql`
+			INSERT INTO _emdash_media_usage_sources (
+				source_key,
+				source_type,
+				collection_id,
+				collection_slug,
+				content_id,
+				source_variant,
+				locale,
+				translation_group,
+				content_slug,
+				content_title,
+				content_status,
+				content_scheduled_at,
+				content_deleted_at,
+				revision_id,
+				current_generation,
+				schema_version,
+				source_updated_at,
+				source_version,
+				source_fingerprint,
+				identity_version,
+				source_completeness,
+				last_attempted_at,
+				last_error_code,
+				indexed_at,
+				updated_at
+			)
+			SELECT
+				${row.source_key},
+				${row.source_type},
+				${row.collection_id},
+				${row.collection_slug},
+				${row.content_id},
+				${row.source_variant},
+				${row.locale},
+				${row.translation_group},
+				${row.content_slug},
+				${row.content_title},
+				${row.content_status},
+				${row.content_scheduled_at},
+				${row.content_deleted_at},
+				${row.revision_id},
+				${row.current_generation},
+				${row.schema_version},
+				${row.source_updated_at},
+				${row.source_version},
+				${row.source_fingerprint},
+				${row.identity_version},
+				${row.source_completeness},
+				${row.last_attempted_at},
+				${row.last_error_code},
+				${row.indexed_at},
+				${row.updated_at}
+			WHERE EXISTS (
+				SELECT 1
+				FROM _emdash_media_usage_generation_writes
+				WHERE source_key = ${row.source_key}
+					AND generation = ${row.current_generation}
+					AND lease_token = ${leaseToken}
+					AND ${this.generationWriteLeaseExpiryIsInFuture("expires_at")}
+			)
+			AND ${this.currentCollectionExists(row.collection_id, row.collection_slug)}
+			AND ${this.currentCanonicalContentExists(row)}
+			${conflict}
+		`.execute(db);
+		return Number(result.numAffectedRows ?? 0) > 0;
+	}
+
+	private generationWriteLeaseExpression(
+		row: ReturnType<MediaUsageRepository["buildSourceRow"]>,
+		leaseToken: string,
+	) {
+		return (eb: ExpressionBuilder<Database, "_emdash_media_usage_sources">) =>
+			eb.exists(
+				eb
+					.selectFrom("_emdash_media_usage_generation_writes")
+					.select("source_key")
+					.where("source_key", "=", row.source_key)
+					.where("generation", "=", row.current_generation)
+					.where("lease_token", "=", leaseToken)
+					.where(
+						this.generationWriteLeaseExpiryIsInFuture(
+							"_emdash_media_usage_generation_writes.expires_at",
+						),
+					),
+			);
+	}
+
+	private generationWriteLeaseExpiryIsInFuture(column: string) {
+		const leaseExpiresAt = sql.ref(column);
+		return isPostgres(this.db)
+			? sql<boolean>`${leaseExpiresAt}::timestamptz > clock_timestamp()`
+			: sql<boolean>`${leaseExpiresAt} > strftime('%Y-%m-%dT%H:%M:%fZ', 'now')`;
+	}
+
+	private async withGenerationWriteLease(
+		source: Pick<MediaUsageSourceInput, "sourceKey" | "collectionId" | "collectionSlug">,
+		generation: string,
+		write: (leaseToken: string, startedAt: string) => Promise<void>,
+	): Promise<boolean> {
+		const leaseToken = ulid();
+		const lease = await sql<{ created_at: string }>`
+			INSERT INTO _emdash_media_usage_generation_writes (
+				source_key, generation, lease_token, expires_at, created_at
+			)
+			SELECT
+				${source.sourceKey},
+				${generation},
+				${leaseToken},
+				${this.generationWriteLeaseTimestampOffset(MEDIA_USAGE_GENERATION_WRITE_LEASE_MS / 1000)},
+				${this.generationWriteLeaseTimestampOffset(0)}
+			WHERE ${this.currentCollectionExists(
+				source.collectionId ?? null,
+				source.collectionSlug ?? null,
+			)}
+			RETURNING created_at
+		`.execute(this.db);
+		const owner = lease.rows[0];
+		if (!owner) return false;
+
+		try {
+			await write(leaseToken, owner.created_at);
+			return true;
+		} finally {
+			try {
+				await this.db
+					.deleteFrom("_emdash_media_usage_generation_writes")
+					.where("source_key", "=", source.sourceKey)
+					.where("generation", "=", generation)
+					.where("lease_token", "=", leaseToken)
+					.execute();
+			} catch (error) {
+				console.error("[media-usage] Failed to release generation write lease:", error);
+			}
+		}
+	}
+
+	private generationWriteLeaseTimestampOffset(offsetSeconds: number): RawBuilder<string> {
+		if (isPostgres(this.db)) {
+			return sql<string>`to_char(
+				(clock_timestamp() AT TIME ZONE 'UTC') + (${offsetSeconds} * INTERVAL '1 second'),
+				'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"'
+			)`;
+		}
+		return sql<string>`strftime(
+			'%Y-%m-%dT%H:%M:%fZ',
+			'now',
+			${`${offsetSeconds >= 0 ? "+" : ""}${offsetSeconds} seconds`}
+		)`;
 	}
 
 	private async updateSourceIfGeneration(
 		db: DatabaseExecutor,
 		row: ReturnType<MediaUsageRepository["buildSourceRow"]>,
 		expectedCurrentGeneration: string,
+		leaseToken: string,
 	): Promise<boolean> {
 		const result = await db
 			.updateTable("_emdash_media_usage_sources")
 			.set(this.sourceUpdateSet(row))
 			.where("source_key", "=", row.source_key)
 			.where("current_generation", "=", expectedCurrentGeneration)
+			.where(this.generationWriteLeaseExpression(row, leaseToken))
+			.where(this.currentCollectionExists(row.collection_id, row.collection_slug))
+			.where(this.currentCanonicalContentExists(row))
 			.executeTakeFirst();
 		return Number(result.numUpdatedRows ?? 0) > 0;
 	}
@@ -1217,12 +2458,16 @@ export class MediaUsageRepository {
 		db: DatabaseExecutor,
 		row: ReturnType<MediaUsageRepository["buildSourceRow"]>,
 		expectedSource: MediaUsageSource,
+		leaseToken: string,
 	): Promise<boolean> {
 		const result = await db
 			.updateTable("_emdash_media_usage_sources")
 			.set(this.sourceUpdateSet(row))
 			.where("source_key", "=", row.source_key)
 			.where(this.sourceMatchExpression(expectedSource))
+			.where(this.generationWriteLeaseExpression(row, leaseToken))
+			.where(this.currentCollectionExists(row.collection_id, row.collection_slug))
+			.where(this.currentCanonicalContentExists(row))
 			.executeTakeFirst();
 		return Number(result.numUpdatedRows ?? 0) > 0;
 	}
@@ -1238,6 +2483,8 @@ export class MediaUsageRepository {
 			.set(this.attemptedSourceUpdateSet(source, row))
 			.where("source_key", "=", row.source_key)
 			.where(this.sourceMatchExpression(expectedSource))
+			.where(this.currentCollectionExists(row.collection_id, row.collection_slug))
+			.where(this.currentCanonicalContentExists(row))
 			.executeTakeFirst();
 		return Number(result.numUpdatedRows ?? 0) > 0;
 	}
@@ -1247,16 +2494,64 @@ export class MediaUsageRepository {
 			eb.and([
 				eb("current_generation", "=", expectedSource.currentGeneration),
 				eb("source_completeness", "=", expectedSource.sourceCompleteness),
+				this.nullableStringExpression(eb, "collection_id", expectedSource.collectionId),
 				this.nullableStringExpression(eb, "updated_at", expectedSource.updatedAt),
 				this.nullableStringExpression(eb, "source_fingerprint", expectedSource.sourceFingerprint),
 				this.nullableStringExpression(eb, "source_updated_at", expectedSource.sourceUpdatedAt),
 				this.nullableNumberExpression(eb, "source_version", expectedSource.sourceVersion),
+				this.nullableNumberExpression(eb, "identity_version", expectedSource.identityVersion),
 				this.nullableStringExpression(eb, "revision_id", expectedSource.revisionId),
 				this.nullableStringExpression(eb, "last_attempted_at", expectedSource.lastAttemptedAt),
 				this.nullableStringExpression(eb, "last_error_code", expectedSource.lastErrorCode),
 			]);
 	}
 
+	private async projectionMatchesCurrentGeneration(
+		source: MediaUsageSourceInput,
+		expectedCurrentGeneration: string,
+	): Promise<boolean> {
+		const fingerprint = source.sourceFingerprint;
+		if (!isMediaUsageProjectionFingerprint(fingerprint)) return false;
+		const row = await this.db
+			.selectFrom("_emdash_media_usage_sources")
+			.select("source_key")
+			.where("source_key", "=", source.sourceKey)
+			.where("current_generation", "=", expectedCurrentGeneration)
+			.where("source_fingerprint", "=", fingerprint!)
+			.where("source_completeness", "=", source.sourceCompleteness ?? "complete")
+			.where("last_error_code", "is", null)
+			.where(
+				this.currentCollectionExists(source.collectionId ?? null, source.collectionSlug ?? null),
+			)
+			.executeTakeFirst();
+		return row !== undefined;
+	}
+
+	async projectionMatchesExpectedSource(
+		source: MediaUsageSourceInput,
+		expectedSource: MediaUsageSource,
+	): Promise<boolean> {
+		const fingerprint = source.sourceFingerprint;
+		if (
+			!isMediaUsageProjectionFingerprint(fingerprint) ||
+			expectedSource.sourceFingerprint !== fingerprint ||
+			expectedSource.sourceCompleteness !== (source.sourceCompleteness ?? "complete") ||
+			expectedSource.lastErrorCode !== null
+		) {
+			return false;
+		}
+		const row = await this.db
+			.selectFrom("_emdash_media_usage_sources")
+			.select("source_key")
+			.where("source_key", "=", source.sourceKey)
+			.where(this.sourceMatchExpression(expectedSource))
+			.where(
+				this.currentCollectionExists(source.collectionId ?? null, source.collectionSlug ?? null),
+			)
+			.executeTakeFirst();
+		return row !== undefined;
+	}
+
 	private nullableStringExpression(
 		eb: ExpressionBuilder<Database, "_emdash_media_usage_sources">,
 		column: MediaUsageSourceNullableStringColumn,
@@ -1265,9 +2560,63 @@ export class MediaUsageRepository {
 		return value === null ? eb(column, "is", null) : eb(column, "=", value);
 	}
 
+	private currentCollectionExists(
+		collectionId: string | null,
+		collectionSlug: string | null,
+	): RawBuilder<boolean> {
+		if (collectionId === null) return sql<boolean>`1 = 1`;
+		return sql<boolean>`EXISTS (
+			SELECT 1
+			FROM _emdash_collections
+			WHERE id = ${collectionId}
+				AND slug = ${collectionSlug}
+		)`;
+	}
+
+	private currentCanonicalContentExists(
+		row:
+			| ReturnType<MediaUsageRepository["buildSourceRow"]>
+			| ReturnType<MediaUsageRepository["buildAttemptedSourceRow"]>,
+	): RawBuilder<boolean> {
+		if (row.collection_id === null || row.identity_version !== 1 || row.source_type !== "content") {
+			return sql<boolean>`1 = 1`;
+		}
+		if (
+			!row.collection_slug ||
+			!row.content_id ||
+			row.source_version === null ||
+			row.source_updated_at === null
+		) {
+			return sql<boolean>`1 = 0`;
+		}
+		validateIdentifier(row.collection_slug, "collection slug");
+		const tableName = `ec_${row.collection_slug}`;
+		validateIdentifier(tableName, "content table");
+		const revisionColumn =
+			row.source_variant === "columns"
+				? "live_revision_id"
+				: row.source_variant === "draft_overlay"
+					? "draft_revision_id"
+					: null;
+		if (!revisionColumn) return sql<boolean>`1 = 0`;
+		const revision = sql.ref(`content.${revisionColumn}`);
+		const revisionMatches =
+			row.revision_id === null
+				? sql<boolean>`${revision} IS NULL`
+				: sql<boolean>`${revision} = ${row.revision_id}`;
+		return sql<boolean>`EXISTS (
+			SELECT 1
+			FROM ${sql.ref(tableName)} AS content
+			WHERE content.id = ${row.content_id}
+				AND content.version = ${row.source_version}
+				AND content.updated_at = ${row.source_updated_at}
+				AND ${revisionMatches}
+		)`;
+	}
+
 	private nullableNumberExpression(
 		eb: ExpressionBuilder<Database, "_emdash_media_usage_sources">,
-		column: "source_version",
+		column: "source_version" | "identity_version",
 		value: number | null,
 	) {
 		return value === null ? eb(column, "is", null) : eb(column, "=", value);
@@ -1287,6 +2636,7 @@ export class MediaUsageRepository {
 		return {
 			source_key: source.sourceKey,
 			source_type: source.sourceType,
+			collection_id: source.collectionId ?? null,
 			collection_slug: source.collectionSlug ?? null,
 			content_id: source.contentId ?? null,
 			source_variant: source.sourceVariant,
@@ -1303,6 +2653,7 @@ export class MediaUsageRepository {
 			source_updated_at: source.sourceUpdatedAt ?? null,
 			source_version: source.sourceVersion ?? null,
 			source_fingerprint: source.sourceFingerprint ?? null,
+			identity_version: source.identityVersion ?? null,
 			// Complete means this source was fully refreshed for the extractor's current
 			// schema/version coverage, not that every possible reference shape is known.
 			source_completeness: source.sourceCompleteness ?? "complete",
@@ -1313,10 +2664,11 @@ export class MediaUsageRepository {
 		};
 	}
 
-	private buildAttemptedSourceRow(source: MediaUsageSourceInput, now: string) {
+	private buildAttemptedSourceRow(source: MediaUsageSourceInput, generation: string, now: string) {
 		return {
 			source_key: source.sourceKey,
 			source_type: source.sourceType,
+			collection_id: source.collectionId ?? null,
 			collection_slug: source.collectionSlug ?? null,
 			content_id: source.contentId ?? null,
 			source_variant: source.sourceVariant,
@@ -1328,11 +2680,12 @@ export class MediaUsageRepository {
 			content_scheduled_at: source.contentScheduledAt ?? null,
 			content_deleted_at: source.contentDeletedAt ?? null,
 			revision_id: source.revisionId ?? null,
-			current_generation: ulid(),
+			current_generation: generation,
 			schema_version: source.schemaVersion ?? 1,
 			source_updated_at: source.sourceUpdatedAt ?? null,
 			source_version: source.sourceVersion ?? null,
 			source_fingerprint: source.sourceFingerprint ?? null,
+			identity_version: source.identityVersion ?? null,
 			source_completeness:
 				source.sourceCompleteness ?? (source.lastErrorCode ? "failed" : "unknown"),
 			last_attempted_at: source.lastAttemptedAt ?? now,
@@ -1356,6 +2709,7 @@ export class MediaUsageRepository {
 		};
 
 		if (source.collectionSlug !== undefined) updates.collection_slug = row.collection_slug;
+		if (source.collectionId !== undefined) updates.collection_id = row.collection_id;
 		if (source.contentId !== undefined) updates.content_id = row.content_id;
 		if (source.locale !== undefined) updates.locale = row.locale;
 		if (source.translationGroup !== undefined) updates.translation_group = row.translation_group;
@@ -1373,6 +2727,7 @@ export class MediaUsageRepository {
 		if (source.sourceFingerprint !== undefined) {
 			updates.source_fingerprint = row.source_fingerprint;
 		}
+		if (source.identityVersion !== undefined) updates.identity_version = row.identity_version;
 
 		return updates;
 	}
@@ -1382,6 +2737,7 @@ export class MediaUsageRepository {
 	): Updateable<MediaUsageSourceTable> {
 		return {
 			source_type: row.source_type,
+			collection_id: row.collection_id,
 			collection_slug: row.collection_slug,
 			content_id: row.content_id,
 			source_variant: row.source_variant,
@@ -1398,6 +2754,7 @@ export class MediaUsageRepository {
 			source_updated_at: row.source_updated_at,
 			source_version: row.source_version,
 			source_fingerprint: row.source_fingerprint,
+			identity_version: row.identity_version,
 			source_completeness: row.source_completeness,
 			last_attempted_at: row.last_attempted_at,
 			last_error_code: row.last_error_code,
@@ -1410,6 +2767,7 @@ export class MediaUsageRepository {
 const currentUsageSelect = [
 	"s.source_key as source_key",
 	"s.source_type as source_type",
+	"s.collection_id as collection_id",
 	"s.collection_slug as collection_slug",
 	"s.content_id as content_id",
 	"s.source_variant as source_variant",
@@ -1426,6 +2784,7 @@ const currentUsageSelect = [
 	"s.source_updated_at as source_updated_at",
 	"s.source_version as source_version",
 	"s.source_fingerprint as source_fingerprint",
+	"s.identity_version as identity_version",
 	"s.source_completeness as source_completeness",
 	"s.last_attempted_at as last_attempted_at",
 	"s.last_error_code as last_error_code",
@@ -1482,6 +2841,7 @@ function rowToSource(row: MediaUsageSourceRow): MediaUsageSource {
 	return {
 		sourceKey: row.source_key,
 		sourceType: row.source_type,
+		collectionId: row.collection_id,
 		collectionSlug: row.collection_slug,
 		contentId: row.content_id,
 		sourceVariant: row.source_variant,
@@ -1498,6 +2858,7 @@ function rowToSource(row: MediaUsageSourceRow): MediaUsageSource {
 		sourceUpdatedAt: row.source_updated_at,
 		sourceVersion: row.source_version === null ? null : Number(row.source_version),
 		sourceFingerprint: row.source_fingerprint,
+		identityVersion: row.identity_version === null ? null : Number(row.identity_version),
 		sourceCompleteness: row.source_completeness,
 		lastAttemptedAt: row.last_attempted_at,
 		lastErrorCode: row.last_error_code,
@@ -1530,6 +2891,7 @@ function rowToUsageRecord(row: JoinedUsageRow): MediaUsageRecord {
 		source: rowToSource({
 			source_key: row.source_key,
 			source_type: row.source_type,
+			collection_id: row.collection_id,
 			collection_slug: row.collection_slug,
 			content_id: row.content_id,
 			source_variant: row.source_variant,
@@ -1546,6 +2908,7 @@ function rowToUsageRecord(row: JoinedUsageRow): MediaUsageRecord {
 			source_updated_at: row.source_updated_at,
 			source_version: row.source_version,
 			source_fingerprint: row.source_fingerprint,
+			identity_version: row.identity_version,
 			source_completeness: row.source_completeness,
 			last_attempted_at: row.last_attempted_at,
 			last_error_code: row.last_error_code,
@@ -1567,6 +2930,7 @@ function rowToUsageRecord(row: JoinedUsageRow): MediaUsageRecord {
 			media_kind: row.media_kind,
 			mime_type: row.mime_type,
 			created_at: row.occurrence_created_at,
+			cleanup_lease_token: null,
 		}),
 	};
 }