emdash 0.28.0 → 0.29.0

package/src/emdash-runtime.ts

@@ -22,7 +22,11 @@ import { getAuthMode } from "./auth/mode.js";
 import { getTrustedProxyHeaders } from "./auth/trusted-proxy.js";
 import { isSqlite } from "./database/dialect-helpers.js";
 import { kyselyLogOption } from "./database/instrumentation.js";
-import { MIGRATION_RACE_WAIT_MS, runMigrations } from "./database/migrations/runner.js";
+import {
+	ConcurrentMigrationTimeoutError,
+	MIGRATION_RACE_WAIT_MS,
+	runMigrations,
+} from "./database/migrations/runner.js";
 import { RevisionRepository } from "./database/repositories/revision.js";
 import type {
 	ContentItem as ContentItemInternal,
@@ -385,18 +389,42 @@ const DB_HOLDER_KEY = Symbol.for("emdash:db-cache");
 interface DbHolder {
 	cache: Map<string, Kysely<Database>>;
 	lock: InitLock;
+	/**
+	 * Recent migration failures, keyed like `cache`. A failed migration is
+	 * near-certain to fail again immediately (schema conflict, broken
+	 * migration), and without this every request in a warm isolate would
+	 * re-attempt it — on Workers with Postgres that stampedes the database
+	 * through the migration advisory lock (#1744). Entries expire after
+	 * DB_INIT_FAILURE_BACKOFF_MS; a successful init clears them.
+	 */
+	failures: Map<string, { at: number; message: string }>;
 }
 const globalSymbolStore = globalThis as Record<symbol, unknown>;
 function getDbHolder(): DbHolder {
 	// eslint-disable-next-line typescript/no-unsafe-type-assertion -- globalThis symbol slot, written only below
 	let holder = globalSymbolStore[DB_HOLDER_KEY] as DbHolder | undefined;
 	if (!holder) {
-		holder = { cache: new Map<string, Kysely<Database>>(), lock: createInitLock() };
+		holder = {
+			cache: new Map<string, Kysely<Database>>(),
+			lock: createInitLock(),
+			failures: new Map(),
+		};
 		globalSymbolStore[DB_HOLDER_KEY] = holder;
 	}
+	// A holder created by an older copy of this module (dev-server HMR keeps
+	// globalThis across reloads) may predate the failures map.
+	holder.failures ??= new Map();
 	return holder;
 }
 
+/**
+ * After a database init fails (migrations threw), skip re-attempting for
+ * this long. Cold isolates still get one attempt each, so a transient
+ * failure heals on its own; a persistently failing migration is retried at
+ * most once per backoff window per isolate instead of on every request.
+ */
+const DB_INIT_FAILURE_BACKOFF_MS = 30_000;
+
 /**
  * Auto-seed runs at most once per isolate per database. Its lock + "done" set
  * live on globalThis (same bundler-duplication reasoning as the db cache) so a
@@ -1623,14 +1651,52 @@ export class EmDashRuntime {
 		// owner's init still completes and populates the cache. Net: a stale
 		// lock is reclaimed after a deadline.
 		const holder = getDbHolder();
+
+		const throwIfBackingOff = () => {
+			const failure = holder.failures.get(cacheKey);
+			if (!failure) return;
+			if (Date.now() - failure.at < DB_INIT_FAILURE_BACKOFF_MS) {
+				throw new Error(
+					`Database initialization is backing off after a recent migration failure: ${failure.message}`,
+				);
+			}
+			// Expired — drop it so the map only ever holds active backoffs.
+			holder.failures.delete(cacheKey);
+		};
+		throwIfBackingOff();
+
 		return initWithLock(
 			holder.lock,
 			() => holder.cache.get(cacheKey),
 			async (isCurrentClaim) => {
+				// Re-check under the lock: a request that entered the wait loop
+				// before the failure was recorded must not immediately re-run
+				// the failing migration when the lock frees up.
+				throwIfBackingOff();
+
 				const dialect = deps.createDialect(dbConfig.config);
 				const db = new Kysely<Database>({ dialect, log: kyselyLogOption() });
 
-				await runMigrations(db);
+				try {
+					await runMigrations(db);
+				} catch (error) {
+					// Timing out behind another instance's in-flight migrations
+					// is not a failure of OUR migration — the holder may just be
+					// slow. Don't back off for it: the next request waits again
+					// and init recovers the moment the holder finishes.
+					if (!(error instanceof ConcurrentMigrationTimeoutError)) {
+						holder.failures.set(cacheKey, {
+							at: Date.now(),
+							message: error instanceof Error ? error.message : String(error),
+						});
+					}
+					// Every attempt builds a fresh dialect/pool; close it or each
+					// failed init leaks its connection(s) (#1744 observed these
+					// piling up as idle Postgres connections).
+					await db.destroy().catch(() => {});
+					throw error;
+				}
+				holder.failures.delete(cacheKey);
 
 				// Note: legacy installs may carry a stray `emdash:manifest_cache`
 				// row in the options table from versions that persisted a JSON
@@ -2520,7 +2586,7 @@ export class EmDashRuntime {
 					...r.data,
 					item: { ...item, data: mergedData, liveData },
 				},
-			} as T;
+			};
 		} catch (error) {
 			// Non-fatal — fall back to the unhydrated response. Log so the
 			// failure isn't completely silent (the response will look stale
@@ -2540,6 +2606,7 @@ export class EmDashRuntime {
 			bylines?: Array<{ bylineId: string; roleLabel?: string | null }>;
 			locale?: string;
 			translationOf?: string;
+			taxonomies?: Record<string, string[]>;
 		},
 	) {
 		// Run beforeSave hooks (trusted plugins)
@@ -2604,6 +2671,7 @@ export class EmDashRuntime {
 				canonical?: string | null;
 				noIndex?: boolean;
 			};
+			taxonomies?: Record<string, string[]>;
 			publishedAt?: string | null;
 			locale?: string;
 			/** Skip revision creation (used by autosave) */

package/src/index.ts

@@ -247,6 +247,10 @@ export type {
 	MediaAccess,
 	HttpAccess,
 	LogAccess,
+	TaxonomyAccess,
+	TaxonomyDefInfo,
+	TaxonomyTermInfo,
+	TaxonomyReadOptions,
 	PluginHooks,
 	HookConfig,
 	HookName,
@@ -404,8 +408,8 @@ export type {
 } from "./settings/types.js";
 
 // SEO
-export { getSeoMeta, getContentSeo } from "./seo/index.js";
-export type { SeoMeta, SeoMetaOptions } from "./seo/index.js";
+export { getSeoMeta, getContentSeo, getHreflangAlternates } from "./seo/index.js";
+export type { SeoMeta, SeoMetaOptions, HreflangAlternate, HreflangOptions } from "./seo/index.js";
 
 // Public page contribution types
 export type {

package/src/loader.ts

@@ -14,7 +14,7 @@
 import type { LiveLoader } from "astro/loaders";
 import { Kysely, type RawBuilder, sql, type Dialect } from "kysely";
 
-import { currentTimestampValue, isPostgres } from "./database/dialect-helpers.js";
+import { buildStatusCondition, isPostgres } from "./database/dialect-helpers.js";
 import { kyselyLogOption } from "./database/instrumentation.js";
 import { decodeCursor, encodeCursor } from "./database/repositories/types.js";
 import { validateIdentifier } from "./database/validate.js";
@@ -515,36 +515,6 @@ export type SortDirection = "asc" | "desc";
  */
 export type OrderBySpec = Record<string, SortDirection>;
 
-/**
- * Build WHERE clause for status filtering.
- * When filtering for 'published' status, also include scheduled content
- * whose scheduled_at time has passed (treating it as effectively published).
- */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any -- accepts any Kysely instance
-function buildStatusCondition(
-	db: Kysely<any>,
-	status: string,
-	tablePrefix?: string,
-): ReturnType<typeof sql> {
-	const statusField = tablePrefix ? `${tablePrefix}.status` : "status";
-	const scheduledAtField = tablePrefix ? `${tablePrefix}.scheduled_at` : "scheduled_at";
-
-	if (status === "published") {
-		// Include both published content AND scheduled content past its publish time.
-		// scheduled_at is stored as text (ISO 8601). On Postgres, we must cast it
-		// to timestamptz for the comparison with CURRENT_TIMESTAMP to work.
-		const scheduledAtExpr = isPostgres(db)
-			? sql`${sql.ref(scheduledAtField)}::timestamptz`
-			: sql.ref(scheduledAtField);
-		const nowExpr = isPostgres(db)
-			? currentTimestampValue(db)
-			: sql`strftime('%Y-%m-%dT%H:%M:%fZ', 'now')`;
-		return sql`(${sql.ref(statusField)} = 'published' OR (${sql.ref(statusField)} = 'scheduled' AND ${scheduledAtExpr} <= ${nowExpr}))`;
-	}
-
-	return sql`${sql.ref(statusField)} = ${status}`;
-}
-
 /**
  * Resolved primary sort field and direction (used for cursor pagination).
  */

package/src/mcp/server.ts

@@ -660,6 +660,12 @@ export function createMcpServer(): McpServer {
 					.describe(
 						"Bylines to credit. Each entry references an existing byline by id (see byline_list / byline_create) with an optional roleLabel. The first entry becomes the primary byline.",
 					),
+				taxonomies: z
+					.record(z.string(), z.array(z.string()))
+					.optional()
+					.describe(
+						"Taxonomy term assignments as { taxonomyName: [termSlug, ...] }. Term slugs are resolved in the entry's locale. Call taxonomy_list to see available taxonomies and taxonomy_list_terms to look up slugs. Missing keys leave that taxonomy unchanged.",
+					),
 			}),
 			annotations: { destructiveHint: false },
 		},
@@ -685,7 +691,7 @@ export function createMcpServer(): McpServer {
 			// Publishing requires publish permission — create as draft then publish
 			if (args.status === "published") {
 				const user = { id: userId, role: getExtra(extra).userRole };
-				if (!hasPermission(user, "content:publish_own" as Permission)) {
+				if (!hasPermission(user, "content:publish_own")) {
 					throw new EmDashAuthError(
 						"Insufficient permissions: publishing requires content:publish_own",
 						"INSUFFICIENT_PERMISSIONS",
@@ -698,6 +704,7 @@ export function createMcpServer(): McpServer {
 					locale: args.locale,
 					translationOf: args.translationOf,
 					bylines: args.bylines,
+					taxonomies: args.taxonomies,
 				});
 				if (!result.success) return unwrap(result);
 				const itemId = extractContentId(result.data);
@@ -715,6 +722,7 @@ export function createMcpServer(): McpServer {
 					locale: args.locale,
 					translationOf: args.translationOf,
 					bylines: args.bylines,
+					taxonomies: args.taxonomies,
 				}),
 			);
 		},
@@ -771,6 +779,12 @@ export function createMcpServer(): McpServer {
 					.describe(
 						"Replace the byline list for this item. The first entry becomes the primary byline. Pass an empty array to clear all bylines.",
 					),
+				taxonomies: z
+					.record(z.string(), z.array(z.string()))
+					.optional()
+					.describe(
+						"Replace taxonomy term assignments as { taxonomyName: [termSlug, ...] }. Term slugs are resolved in the entry's locale. Only named taxonomies are touched; other taxonomies are left unchanged. Pass an empty array to clear a taxonomy.",
+					),
 				publishedAt: z.iso
 					.datetime({ offset: true, message: "must be an ISO 8601 datetime" })
 					.nullish()
@@ -805,7 +819,7 @@ export function createMcpServer(): McpServer {
 			// route. Status-driven publishes are gated separately below.
 			if (args.publishedAt !== undefined) {
 				const user = { id: userId, role: userRole };
-				if (!hasPermission(user, "content:publish_any" as Permission)) {
+				if (!hasPermission(user, "content:publish_any")) {
 					throw new EmDashAuthError(
 						"Setting publishedAt requires content:publish_any permission",
 						"INSUFFICIENT_PERMISSIONS",
@@ -823,6 +837,7 @@ export function createMcpServer(): McpServer {
 					args.slug ||
 					args.seo !== undefined ||
 					args.bylines !== undefined ||
+					args.taxonomies !== undefined ||
 					args.publishedAt !== undefined
 				) {
 					const updateResult = await emdash.handleContentUpdate(args.collection, resolvedId, {
@@ -832,6 +847,7 @@ export function createMcpServer(): McpServer {
 						locale: args.locale,
 						seo: args.seo,
 						bylines: args.bylines,
+						taxonomies: args.taxonomies,
 						publishedAt: args.publishedAt,
 						_rev: args._rev,
 					});
@@ -847,6 +863,7 @@ export function createMcpServer(): McpServer {
 					args.slug ||
 					args.seo !== undefined ||
 					args.bylines !== undefined ||
+					args.taxonomies !== undefined ||
 					args.publishedAt !== undefined
 				) {
 					const updateResult = await emdash.handleContentUpdate(args.collection, resolvedId, {
@@ -856,6 +873,7 @@ export function createMcpServer(): McpServer {
 						locale: args.locale,
 						seo: args.seo,
 						bylines: args.bylines,
+						taxonomies: args.taxonomies,
 						publishedAt: args.publishedAt,
 						_rev: args._rev,
 					});
@@ -872,6 +890,7 @@ export function createMcpServer(): McpServer {
 					locale: args.locale,
 					seo: args.seo,
 					bylines: args.bylines,
+					taxonomies: args.taxonomies,
 					publishedAt: args.publishedAt,
 					_rev: args._rev,
 				}),
@@ -1008,7 +1027,7 @@ export function createMcpServer(): McpServer {
 			// regardless of ownership (mirrors the REST PUT route's publishedAt gate).
 			if (args.publishedAt !== undefined) {
 				const user = { id: userId, role: userRole };
-				if (!hasPermission(user, "content:publish_any" as Permission)) {
+				if (!hasPermission(user, "content:publish_any")) {
 					throw new EmDashAuthError(
 						"Setting publishedAt requires content:publish_any permission",
 						"INSUFFICIENT_PERMISSIONS",
@@ -1932,6 +1951,12 @@ export function createMcpServer(): McpServer {
 					.optional()
 					.describe("Filter results by locale (omit to search all locales)"),
 				limit: z.number().int().min(1).max(50).optional().describe("Max results (default 20)"),
+				cursor: z
+					.string()
+					.min(1)
+					.max(2048)
+					.optional()
+					.describe("Pagination cursor from a previous response"),
 			}),
 			annotations: { readOnlyHint: true },
 		},
@@ -1944,6 +1969,7 @@ export function createMcpServer(): McpServer {
 					collections: args.collections,
 					locale: args.locale,
 					limit: args.limit,
+					cursor: args.cursor,
 				});
 				return jsonResult(results);
 			} catch (error) {

package/src/media/usage/content-repair.ts

@@ -20,6 +20,7 @@ import {
 } from "./content-refresh.js";
 import {
 	CONTENT_SOURCE_SCHEMA_VERSION,
+	type ContentMediaUsageSnapshot,
 	loadContentMediaUsageSnapshots,
 } from "./content-snapshots.js";
 import {
@@ -65,11 +66,48 @@ export interface ContentMediaUsageRepairCollectionResult {
 	completedAt: string | null;
 }
 
+export interface ContentMediaUsageRepairAllResult {
+	status: ContentMediaUsageRepairStatus;
+	collections: ContentMediaUsageRepairCollectionResult[];
+	indexedSourceCount: number;
+	failedSourceCount: number;
+	skippedSourceCount: number;
+	deletedSourceCount: number;
+}
+
 export interface ContentMediaUsageCollectionScan {
 	collectionSlug: string;
 	contentIds: string[];
 }
 
+interface ContentMediaUsageCollectionRecord {
+	id: string;
+	slug: string;
+}
+
+interface ContentMediaUsageInitialCollectionResult {
+	collection: ContentMediaUsageCollectionRecord;
+	result: ContentMediaUsageRepairCollectionResult;
+}
+
+export async function repairContentMediaUsageAll(
+	db: Kysely<Database>,
+): Promise<ContentMediaUsageRepairAllResult> {
+	const collections = await loadContentMediaUsageCollectionRecords(db);
+	const results: ContentMediaUsageInitialCollectionResult[] = [];
+
+	for (const collection of collections) {
+		results.push({
+			collection,
+			result: await repairContentMediaUsageCollectionSafely(db, collection.slug),
+		});
+	}
+
+	return aggregateContentMediaUsageRepairAll(
+		await filterExistingContentMediaUsageCollectionResults(db, results),
+	);
+}
+
 export async function scanContentMediaUsageCollection(
 	db: Kysely<Database>,
 	collectionSlug: string,
@@ -105,6 +143,116 @@ export async function repairContentMediaUsageCollection(
 	);
 }
 
+async function loadContentMediaUsageCollectionRecords(
+	db: Kysely<Database>,
+): Promise<ContentMediaUsageCollectionRecord[]> {
+	return db
+		.selectFrom("_emdash_collections")
+		.select(["id", "slug"])
+		.orderBy("slug", "asc")
+		.execute();
+}
+
+async function repairContentMediaUsageCollectionSafely(
+	db: Kysely<Database>,
+	collectionSlug: string,
+): Promise<ContentMediaUsageRepairCollectionResult> {
+	try {
+		return await repairContentMediaUsageCollection(db, { collectionSlug });
+	} catch (error) {
+		console.error(`[media-usage] Failed to repair collection ${collectionSlug}:`, error);
+		const now = new Date().toISOString();
+		return {
+			scope: contentMediaUsageCollectionScope(collectionSlug),
+			status: "failed",
+			indexedSourceCount: 0,
+			failedSourceCount: 0,
+			skippedSourceCount: 0,
+			deletedSourceCount: 0,
+			lastErrorCode: CONTENT_MEDIA_USAGE_REPAIR_ERROR.CONTENT_USAGE_REPAIR_ERROR,
+			startedAt: now,
+			completedAt: now,
+		};
+	}
+}
+
+async function filterExistingContentMediaUsageCollectionResults(
+	db: Kysely<Database>,
+	results: readonly ContentMediaUsageInitialCollectionResult[],
+): Promise<ContentMediaUsageRepairCollectionResult[]> {
+	const currentCollections = await loadContentMediaUsageCollectionRecordsSafely(db);
+	const currentIdsBySlug = new Map(
+		currentCollections.map((collection) => [collection.slug, collection.id]),
+	);
+	const includedResults: ContentMediaUsageRepairCollectionResult[] = [];
+	const excludedResults: ContentMediaUsageRepairCollectionResult[] = [];
+
+	for (const { collection, result } of results) {
+		if (currentIdsBySlug.get(collection.slug) === collection.id) {
+			includedResults.push(result);
+		} else {
+			excludedResults.push(result);
+		}
+	}
+
+	if (excludedResults.length > 0) {
+		const repo = new MediaUsageRepository(db);
+		for (const result of excludedResults) {
+			await repo.deleteIndexStatus(result.scope);
+		}
+	}
+
+	return includedResults;
+}
+
+async function loadContentMediaUsageCollectionRecordsSafely(
+	db: Kysely<Database>,
+): Promise<ContentMediaUsageCollectionRecord[]> {
+	try {
+		return await loadContentMediaUsageCollectionRecords(db);
+	} catch {
+		// Retry once before failing; returning unpruned results can over-report deleted collections.
+	}
+
+	try {
+		return await loadContentMediaUsageCollectionRecords(db);
+	} catch (error) {
+		console.error("[media-usage] Failed to reconcile all-content repair collections:", error);
+		throw error;
+	}
+}
+
+function aggregateContentMediaUsageRepairAll(
+	collections: readonly ContentMediaUsageRepairCollectionResult[],
+): ContentMediaUsageRepairAllResult {
+	return {
+		status: determineRepairAllStatus(collections),
+		collections: [...collections],
+		indexedSourceCount: sumCollectionRepairCount(collections, "indexedSourceCount"),
+		failedSourceCount: sumCollectionRepairCount(collections, "failedSourceCount"),
+		skippedSourceCount: sumCollectionRepairCount(collections, "skippedSourceCount"),
+		deletedSourceCount: sumCollectionRepairCount(collections, "deletedSourceCount"),
+	};
+}
+
+function determineRepairAllStatus(
+	collections: readonly ContentMediaUsageRepairCollectionResult[],
+): ContentMediaUsageRepairStatus {
+	if (collections.length === 0) return "complete";
+	if (collections.every((collection) => collection.status === "complete")) return "complete";
+	if (collections.some((collection) => collection.status === "stale")) return "stale";
+	if (collections.some((collection) => collection.status === "partial")) return "partial";
+	if (collections.every((collection) => collection.status === "failed")) return "failed";
+	return "partial";
+}
+
+function sumCollectionRepairCount(
+	collections: readonly ContentMediaUsageRepairCollectionResult[],
+	key: "indexedSourceCount" | "failedSourceCount" | "skippedSourceCount" | "deletedSourceCount",
+): number {
+	return collections.reduce((sum, collection) => sum + collection[key], 0);
+}
+
 async function repairContentMediaUsageCollectionUnlocked(
 	db: Kysely<Database>,
 	collectionSlug: string,
@@ -147,6 +295,7 @@ async function repairContentMediaUsageCollectionUnlocked(
 					skippedSourceCount: 0,
 					deletedSourceCount: 0,
 					lastErrorCode: CONTENT_MEDIA_USAGE_REPAIR_ERROR.COLLECTION_NOT_FOUND,
+					missingContentIds: new Set(),
 				},
 				status: "failed",
 				startedAt,
@@ -155,16 +304,14 @@ async function repairContentMediaUsageCollectionUnlocked(
 		}
 		const counts = await repairScannedContentSources(db, repo, scan);
 		const finalScan = await scanContentMediaUsageCollection(db, collectionSlug);
-		const scannedContentCount = finalScan?.contentIds.length ?? scan.contentIds.length;
 		if (!finalScan) {
 			counts.failedSourceCount++;
 			counts.lastErrorCode = CONTENT_MEDIA_USAGE_REPAIR_ERROR.COLLECTION_NOT_FOUND;
-		} else if (!sameContentIds(scan.contentIds, finalScan.contentIds)) {
-			counts.skippedSourceCount++;
-			counts.lastErrorCode = CONTENT_MEDIA_USAGE_REPAIR_ERROR.CONTENT_USAGE_REPAIR_CONFLICT;
+		} else if (!sameContentIds(repairedContentIds(scan.contentIds, counts), finalScan.contentIds)) {
+			markRepairConflict(counts);
 		}
 		const completedAt = new Date().toISOString();
-		const status = determineRepairStatus(counts, scannedContentCount);
+		const status = determineRepairStatus(counts);
 		return await finalizeRepairStatus(repo, {
 			...scope,
 			runToken,
@@ -191,6 +338,7 @@ async function repairContentMediaUsageCollectionUnlocked(
 				skippedSourceCount: 0,
 				deletedSourceCount: 0,
 				lastErrorCode,
+				missingContentIds: new Set(),
 			},
 			status: "failed",
 			startedAt,
@@ -205,6 +353,7 @@ interface RepairCounts {
 	skippedSourceCount: number;
 	deletedSourceCount: number;
 	lastErrorCode: ContentMediaUsageRepairErrorCode | null;
+	missingContentIds: Set<string>;
 }
 
 async function repairScannedContentSources(
@@ -218,6 +367,7 @@ async function repairScannedContentSources(
 		skippedSourceCount: 0,
 		deletedSourceCount: 0,
 		lastErrorCode: null,
+		missingContentIds: new Set(),
 	};
 
 	const fieldDiscovery = await loadContentMediaUsageFields(db, scan.collectionSlug);
@@ -256,7 +406,16 @@ async function repairContentSource(
 		fieldDiscovery,
 	);
 	if (!snapshotsResult.success) {
+		if (snapshotsResult.error === CONTENT_MEDIA_USAGE_REPAIR_ERROR.CONTENT_NOT_FOUND) {
+			markRepairConflict(counts);
+			counts.missingContentIds.add(contentId);
+			return;
+		}
 		counts.lastErrorCode = snapshotsResult.error;
+		if (snapshotsResult.snapshots) {
+			// Partial snapshot failures keep absent variants in place; the attempted source is marked below.
+			await repairSnapshotSources(repo, snapshotsResult.snapshots, observedSources, counts);
+		}
 		if (snapshotsResult.source) {
 			const result = await repo.markSourceAttemptedIfMatching(
 				{
@@ -269,8 +428,7 @@ async function repairContentSource(
 			if (result.attempted) {
 				counts.failedSourceCount++;
 			} else {
-				counts.skippedSourceCount++;
-				counts.lastErrorCode = CONTENT_MEDIA_USAGE_REPAIR_ERROR.CONTENT_USAGE_REPAIR_CONFLICT;
+				markRepairConflict(counts);
 			}
 			return;
 		}
@@ -279,8 +437,29 @@ async function repairContentSource(
 		return;
 	}
 
+	const expectedSourceKeys = await repairSnapshotSources(
+		repo,
+		snapshotsResult.snapshots,
+		observedSources,
+		counts,
+	);
+
+	for (const sourceKey of sourceKeys) {
+		if (expectedSourceKeys.has(sourceKey)) continue;
+		const observedSource = observedSources.get(sourceKey);
+		if (!observedSource) continue;
+		await deleteObservedSource(repo, sourceKey, observedSource, counts);
+	}
+}
+
+async function repairSnapshotSources(
+	repo: MediaUsageRepository,
+	snapshots: readonly ContentMediaUsageSnapshot[],
+	observedSources: Map<string, MediaUsageSource>,
+	counts: RepairCounts,
+): Promise<Set<string>> {
 	const expectedSourceKeys = new Set<string>();
-	for (const snapshot of snapshotsResult.snapshots) {
+	for (const snapshot of snapshots) {
 		expectedSourceKeys.add(snapshot.source.sourceKey);
 		const result = await repo.replaceSourceIfMatching(
 			snapshot.source,
@@ -290,17 +469,15 @@ async function repairContentSource(
 		if (result.replaced) {
 			counts.indexedSourceCount++;
 		} else {
-			counts.skippedSourceCount++;
-			counts.lastErrorCode = CONTENT_MEDIA_USAGE_REPAIR_ERROR.CONTENT_USAGE_REPAIR_CONFLICT;
+			markRepairConflict(counts);
 		}
 	}
+	return expectedSourceKeys;
+}
 
-	for (const sourceKey of sourceKeys) {
-		if (expectedSourceKeys.has(sourceKey)) continue;
-		const observedSource = observedSources.get(sourceKey);
-		if (!observedSource) continue;
-		await deleteObservedSource(repo, sourceKey, observedSource, counts);
-	}
+function markRepairConflict(counts: RepairCounts): void {
+	counts.skippedSourceCount++;
+	counts.lastErrorCode ??= CONTENT_MEDIA_USAGE_REPAIR_ERROR.CONTENT_USAGE_REPAIR_CONFLICT;
 }
 
 async function reconcileOrphanedContentSources(
@@ -370,8 +547,7 @@ async function deleteObservedSourceIfContentAbsent(
 	}
 	if (result.contentPresent) return;
 	if (result.source) {
-		counts.skippedSourceCount++;
-		counts.lastErrorCode = CONTENT_MEDIA_USAGE_REPAIR_ERROR.CONTENT_USAGE_REPAIR_CONFLICT;
+		markRepairConflict(counts);
 	}
 }
 
@@ -387,8 +563,7 @@ async function deleteObservedSource(
 		return;
 	}
 	if (result.source) {
-		counts.skippedSourceCount++;
-		counts.lastErrorCode = CONTENT_MEDIA_USAGE_REPAIR_ERROR.CONTENT_USAGE_REPAIR_CONFLICT;
+		markRepairConflict(counts);
 	}
 }
 
@@ -439,11 +614,12 @@ async function finalizeRepairStatus(
 
 function determineRepairStatus(
 	counts: RepairCounts,
-	scannedContentCount: number,
 ): Exclude<ContentMediaUsageRepairStatus, "stale"> {
 	if (counts.failedSourceCount === 0 && counts.skippedSourceCount === 0) return "complete";
 	const trustedProgress = counts.indexedSourceCount + counts.deletedSourceCount;
-	if (trustedProgress === 0 && scannedContentCount > 0) return "failed";
+	if (counts.failedSourceCount > 0 && trustedProgress === 0) {
+		return "failed";
+	}
 	return "partial";
 }
 
@@ -477,6 +653,14 @@ function sameContentIds(left: readonly string[], right: readonly string[]): bool
 	return left.every((id) => rightIds.has(id));
 }
 
+function repairedContentIds(
+	contentIds: readonly string[],
+	counts: Pick<RepairCounts, "missingContentIds">,
+): string[] {
+	if (counts.missingContentIds.size === 0) return [...contentIds];
+	return contentIds.filter((contentId) => !counts.missingContentIds.has(contentId));
+}
+
 function contentMediaUsageCollectionScope(collectionSlug: string): ContentMediaUsageRepairScope {
 	return {
 		adapterId: CONTENT_MEDIA_USAGE_ADAPTER_ID,