emdash 0.39.1 → 0.40.1

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

@@ -2,6 +2,8 @@ import type { Kysely } from "kysely";
 
 import type { Database } from "../../database/types.js";
 import { validateIdentifier } from "../../database/validate.js";
+import { BlockTypeRegistry } from "../../schema/block-type-registry.js";
+import type { BlockType } from "../../schema/block-types.js";
 import { buildCanonicalSha256Fingerprint } from "./projection-fingerprint.js";
 import type { MediaUsageExtractionField, MediaUsageExtractionSubField } from "./types.js";
 import { CONTENT_SOURCE_SCHEMA_VERSION } from "./types.js";
@@ -20,6 +22,18 @@ export async function buildContentMediaUsageFieldFingerprint(
 		.map((field) => ({
 			slug: field.slug,
 			type: field.type,
+			...(field.type === "blocks"
+				? {
+						blockTypes: (field.blockTypes ?? []).map((type) => ({
+							slug: type.slug,
+							currentVersion: type.currentVersion,
+							versions: type.versions.map((version) => ({
+								version: version.version,
+								fingerprint: version.fingerprint,
+							})),
+						})),
+					}
+				: {}),
 			...(field.type === "repeater"
 				? {
 						subFields: (field.validation?.subFields ?? [])
@@ -41,7 +55,10 @@ export async function buildContentMediaUsageFieldFingerprint(
 export class MediaUsageFieldDiscoveryError extends Error {
 	constructor(
 		message: string,
-		public code: "INVALID_REPEATER_VALIDATION",
+		public code:
+			| "INVALID_REPEATER_VALIDATION"
+			| "INVALID_BLOCK_VALIDATION"
+			| "UNSUPPORTED_BLOCK_DEFINITION",
 	) {
 		super(message);
 		this.name = "MediaUsageFieldDiscoveryError";
@@ -76,6 +93,9 @@ export async function loadContentMediaUsageFields(
 
 	const extractionFields: ContentMediaUsageField[] = [];
 	const rowBySlug = new Map<string, FieldDiscoveryRow>();
+	const allBlockTypes = rows.some((row) => row.type === "blocks")
+		? await new BlockTypeRegistry(db).listBlockTypes()
+		: [];
 
 	for (const row of rows) {
 		rowBySlug.set(row.slug, row);
@@ -96,6 +116,13 @@ export async function loadContentMediaUsageFields(
 				});
 			}
 		}
+
+		if (row.type === "blocks") {
+			validateIdentifier(row.slug, "media usage field slug");
+			const configured = parseBlockTypeSlugs(row.validation);
+			const blockTypes = resolveMediaBlockTypes(allBlockTypes, configured);
+			extractionFields.push({ slug: row.slug, type: "blocks", blockTypes });
+		}
 	}
 
 	extractionFields.sort((a, b) => a.slug.localeCompare(b.slug));
@@ -110,10 +137,47 @@ export async function loadContentMediaUsageFields(
 	};
 }
 
+function parseBlockTypeSlugs(rawValidation: string | null): string[] {
+	const validation = parseValidation(rawValidation, "block");
+	if (!isRecord(validation)) {
+		throw new MediaUsageFieldDiscoveryError(
+			"Blocks field validation must be an object before media usage can be discovered",
+			"INVALID_BLOCK_VALIDATION",
+		);
+	}
+	const allowed = Array.isArray(validation.allowedTypes) ? validation.allowedTypes : [];
+	const retired = Array.isArray(validation.retiredTypes) ? validation.retiredTypes : [];
+	const values = [...allowed, ...retired];
+	if (values.some((value) => typeof value !== "string")) {
+		throw new MediaUsageFieldDiscoveryError(
+			"Blocks field type lists must contain strings before media usage can be discovered",
+			"INVALID_BLOCK_VALIDATION",
+		);
+	}
+	return [...new Set(values)];
+}
+
+function resolveMediaBlockTypes(
+	types: readonly BlockType[],
+	slugs: readonly string[],
+): BlockType[] {
+	const bySlug = new Map(types.map((type) => [type.slug, type]));
+	return slugs.map((slug) => {
+		const type = bySlug.get(slug);
+		if (!type || type.versions.some((version) => version.unsupportedTypes?.length)) {
+			throw new MediaUsageFieldDiscoveryError(
+				`Block type "${slug}" cannot be resolved for media usage`,
+				"UNSUPPORTED_BLOCK_DEFINITION",
+			);
+		}
+		return type;
+	});
+}
+
 function normalizeRepeaterImageSubFields(
 	rawValidation: string | null,
 ): MediaUsageExtractionSubField[] {
-	const validation = parseValidation(rawValidation);
+	const validation = parseValidation(rawValidation, "repeater");
 	if (!isRecord(validation) || !Array.isArray(validation.subFields)) return [];
 
 	const subFields: MediaUsageExtractionSubField[] = [];
@@ -127,14 +191,14 @@ function normalizeRepeaterImageSubFields(
 	return subFields.toSorted((a, b) => a.slug.localeCompare(b.slug));
 }
 
-function parseValidation(rawValidation: string | null): unknown {
+function parseValidation(rawValidation: string | null, kind: "block" | "repeater"): unknown {
 	if (!rawValidation) return null;
 	try {
 		return JSON.parse(rawValidation);
 	} catch {
 		throw new MediaUsageFieldDiscoveryError(
-			"Repeater field validation must be valid JSON before media usage can be discovered",
-			"INVALID_REPEATER_VALIDATION",
+			`${kind === "block" ? "Blocks" : "Repeater"} field validation must be valid JSON before media usage can be discovered`,
+			kind === "block" ? "INVALID_BLOCK_VALIDATION" : "INVALID_REPEATER_VALIDATION",
 		);
 	}
 }

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

@@ -1,6 +1,5 @@
 import { sql, type Kysely } from "kysely";
 
-import { tableExists } from "../../database/dialect-helpers.js";
 import {
 	type MediaUsageExistingSourceProjection,
 	MediaUsageRepository,
@@ -15,19 +14,29 @@ import {
 	type ContentMediaUsageFieldDiscovery,
 } from "./content-fields.js";
 import {
-	CONTENT_SOURCE_SCHEMA_VERSION,
 	loadContentMediaUsageSnapshots,
 	loadContentMediaUsageSnapshotsBatch,
 	type ContentMediaUsageSnapshot,
 	type LoadContentMediaUsageSnapshotsResult,
 } from "./content-snapshots.js";
+import {
+	CONTENT_MEDIA_USAGE_ADAPTER_ID,
+	CONTENT_MEDIA_USAGE_COLLECTION_SCOPE,
+	markContentMediaUsageCollectionStale,
+	markContentMediaUsageCollectionStaleSafely,
+} from "./schema-invalidation.js";
 import {
 	buildContentMediaUsageSourceKey,
 	MEDIA_USAGE_CONTENT_SOURCE_VARIANTS,
 } from "./source-key.js";
 
-export const CONTENT_MEDIA_USAGE_ADAPTER_ID = "content-media";
-export const CONTENT_MEDIA_USAGE_COLLECTION_SCOPE = "collection";
+export {
+	CONTENT_MEDIA_USAGE_ADAPTER_ID,
+	CONTENT_MEDIA_USAGE_COLLECTION_SCOPE,
+	invalidateContentMediaUsageSchemaChange,
+	markContentMediaUsageCollectionStale,
+	markContentMediaUsageCollectionStaleSafely,
+} from "./schema-invalidation.js";
 
 const CONTENT_USAGE_LOCKS_KEY = Symbol.for("emdash.mediaUsage.contentLocks");
 const CONTENT_USAGE_COLLECTION_LOCKS_KEY = Symbol.for("emdash.mediaUsage.collectionLocks");
@@ -814,54 +823,6 @@ export async function refreshContentMediaUsageAfterWrite(
 	}
 }
 
-export async function markContentMediaUsageCollectionStale(
-	db: Kysely<Database>,
-	collectionSlug: string,
-	lastErrorCode: string,
-): Promise<void> {
-	validateIdentifier(collectionSlug, "collection slug");
-	const repo = new MediaUsageRepository(db);
-	const identity = {
-		adapterId: CONTENT_MEDIA_USAGE_ADAPTER_ID,
-		scopeType: CONTENT_MEDIA_USAGE_COLLECTION_SCOPE,
-		scopeKey: collectionSlug,
-	};
-	const existing = await repo.findIndexStatus(identity);
-	await repo.upsertIndexStatus({
-		...identity,
-		status: "stale",
-		schemaVersion: existing?.schemaVersion ?? CONTENT_SOURCE_SCHEMA_VERSION,
-		startedAt: existing?.startedAt ?? null,
-		completedAt: existing?.completedAt ?? null,
-		cursor: existing?.cursor ?? null,
-		indexedSourceCount: existing?.indexedSourceCount ?? 0,
-		failedSourceCount: existing?.failedSourceCount ?? 0,
-		lastErrorCode,
-	});
-}
-
-export async function invalidateContentMediaUsageSchemaChange(
-	db: Kysely<Database>,
-	collectionSlug: string,
-): Promise<boolean> {
-	validateIdentifier(collectionSlug, "collection slug");
-	if (!(await tableExists(db, "_emdash_media_usage_activation"))) return false;
-	const activation = await db
-		.selectFrom("_emdash_media_usage_activation")
-		.select("state")
-		.where("task_key", "=", "incremental_capture")
-		.executeTakeFirst();
-	if (activation?.state !== "active") return false;
-
-	const invalidated = await new MediaUsageRepository(db).invalidateIndexStatusForSchemaChange(
-		collectionSlug,
-	);
-	if (!invalidated) {
-		throw new Error(`Cannot invalidate media usage coverage for collection ${collectionSlug}`);
-	}
-	return true;
-}
-
 export async function findNonTranslatableSiblingContentIds(
 	db: Kysely<Database>,
 	collectionSlug: string,
@@ -971,20 +932,6 @@ async function deleteCanonicalContentSourcesIfAbsent(
 	return { ...ZERO_RESULT, deletedSourceCount };
 }
 
-export async function markContentMediaUsageCollectionStaleSafely(
-	db: Kysely<Database>,
-	collectionSlug: string,
-	lastErrorCode: ContentMediaUsageRefreshErrorCode,
-): Promise<boolean> {
-	try {
-		await markContentMediaUsageCollectionStale(db, collectionSlug, lastErrorCode);
-		return true;
-	} catch (error) {
-		console.error(`[media-usage] Failed to mark ${collectionSlug} stale:`, error);
-		return false;
-	}
-}
-
 async function withContentUsageLock<T>(
 	collectionSlug: string,
 	contentId: string,

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

@@ -24,6 +24,7 @@ import {
 	type ContentMediaUsageSnapshot,
 	loadContentMediaUsageSnapshots,
 } from "./content-snapshots.js";
+import { MediaUsageBlockResolutionError } from "./extractor.js";
 import {
 	buildContentMediaUsageSourceKey,
 	MEDIA_USAGE_CONTENT_SOURCE_VARIANTS,
@@ -40,6 +41,8 @@ export const CONTENT_MEDIA_USAGE_REPAIR_ERROR = {
 	CONTENT_USAGE_REPAIR_ERROR: "CONTENT_USAGE_REPAIR_ERROR",
 	CONTENT_USAGE_REPAIR_CONFLICT: "CONTENT_USAGE_REPAIR_CONFLICT",
 	INVALID_REPEATER_VALIDATION: "INVALID_REPEATER_VALIDATION",
+	INVALID_BLOCK_VALIDATION: "INVALID_BLOCK_VALIDATION",
+	UNSUPPORTED_BLOCK_DEFINITION: "UNSUPPORTED_BLOCK_DEFINITION",
 } as const;
 
 export type ContentMediaUsageRepairErrorCode =
@@ -381,14 +384,19 @@ async function repairContentMediaUsageCollectionUnlocked(
 			execution,
 		});
 	} catch (error) {
-		if (!(error instanceof MediaUsageFieldDiscoveryError)) {
+		if (
+			!(error instanceof MediaUsageFieldDiscoveryError) &&
+			!(error instanceof MediaUsageBlockResolutionError)
+		) {
 			console.error(`[media-usage] Failed to repair collection ${collectionSlug}:`, error);
 		}
 		const completedAt = new Date().toISOString();
 		const lastErrorCode =
 			error instanceof MediaUsageFieldDiscoveryError
 				? error.code
-				: CONTENT_MEDIA_USAGE_REPAIR_ERROR.CONTENT_USAGE_REPAIR_ERROR;
+				: error instanceof MediaUsageBlockResolutionError
+					? CONTENT_MEDIA_USAGE_REPAIR_ERROR.UNSUPPORTED_BLOCK_DEFINITION
+					: CONTENT_MEDIA_USAGE_REPAIR_ERROR.CONTENT_USAGE_REPAIR_ERROR;
 		return finalizeRepairStatus(db, repo, {
 			...scope,
 			runToken,

package/src/media/usage/extractor.ts

@@ -59,6 +59,11 @@ export function extractMediaUsageOccurrences({
 
 		if (field.type === "portableText") {
 			extractPortableTextOccurrences(occurrences, seen, field.slug, value);
+			continue;
+		}
+
+		if (field.type === "blocks") {
+			extractBlockOccurrences(occurrences, seen, field, value);
 		}
 	}
 
@@ -71,6 +76,7 @@ function extractRepeaterOccurrences(
 	fieldSlug: string,
 	value: unknown,
 	subFields: readonly MediaUsageExtractionSubField[] | undefined,
+	pathPrefix = fieldSlug,
 ): void {
 	if (!Array.isArray(value) || !Array.isArray(subFields)) return;
 
@@ -84,7 +90,7 @@ function extractRepeaterOccurrences(
 				occurrences,
 				seen,
 				fieldSlug,
-				`${fieldSlug}[${itemIndex}].${subField.slug}`,
+				`${pathPrefix}[${itemIndex}].${subField.slug}`,
 				item[subField.slug],
 			);
 		}
@@ -121,6 +127,7 @@ function extractPortableTextOccurrences(
 	seen: Set<string>,
 	fieldSlug: string,
 	value: unknown,
+	pathPrefix = fieldSlug,
 ): void {
 	if (!Array.isArray(value)) return;
 
@@ -132,7 +139,7 @@ function extractPortableTextOccurrences(
 				occurrences,
 				seen,
 				fieldSlug,
-				`${fieldSlug}[${blockIndex}]`,
+				`${pathPrefix}[${blockIndex}]`,
 				block.asset,
 			);
 			continue;
@@ -146,7 +153,7 @@ function extractPortableTextOccurrences(
 					occurrences,
 					seen,
 					fieldSlug,
-					`${fieldSlug}[${blockIndex}].images[${imageIndex}]`,
+					`${pathPrefix}[${blockIndex}].images[${imageIndex}]`,
 					image.asset,
 				);
 			}
@@ -154,6 +161,70 @@ function extractPortableTextOccurrences(
 	}
 }
 
+export class MediaUsageBlockResolutionError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "MediaUsageBlockResolutionError";
+	}
+}
+
+function extractBlockOccurrences(
+	occurrences: ExtractedMediaUsageOccurrence[],
+	seen: Set<string>,
+	field: ExtractMediaUsageOccurrencesInput["fields"][number],
+	value: unknown,
+): void {
+	if (!Array.isArray(value)) return;
+	const types = new Map((field.blockTypes ?? []).map((type) => [type.slug, type]));
+	for (const [index, block] of value.entries()) {
+		if (!isRecord(block)) continue;
+		if (
+			typeof block._type !== "string" ||
+			typeof block._version !== "number" ||
+			typeof block._key !== "string" ||
+			block._key.length === 0
+		) {
+			throw new MediaUsageBlockResolutionError(
+				`Block at ${field.slug}[${index}] has invalid identity metadata`,
+			);
+		}
+		const type = types.get(block._type);
+		const version = type?.versions.find((candidate) => candidate.version === block._version);
+		if (!type || !version || version.unsupportedTypes?.length) {
+			throw new MediaUsageBlockResolutionError(
+				`Block at ${field.slug}[${index}] has no retained definition`,
+			);
+		}
+		const pathPrefix = `${field.slug}.${block._key}`;
+		for (const nestedField of version.fields) {
+			const nestedValue = block[nestedField.slug];
+			const nestedPath = `${pathPrefix}.${nestedField.slug}`;
+			if (nestedField.type === "image") {
+				addImageOccurrences(occurrences, seen, field.slug, nestedPath, nestedValue);
+			} else if (nestedField.type === "file") {
+				addOccurrence(occurrences, seen, {
+					fieldSlug: field.slug,
+					fieldPath: nestedPath,
+					referenceType: "file_field",
+					value: nestedValue,
+					fallbackKind: null,
+				});
+			} else if (nestedField.type === "portableText") {
+				extractPortableTextOccurrences(occurrences, seen, field.slug, nestedValue, nestedPath);
+			} else if (nestedField.type === "repeater") {
+				extractRepeaterOccurrences(
+					occurrences,
+					seen,
+					field.slug,
+					nestedValue,
+					nestedField.validation?.subFields,
+					nestedPath,
+				);
+			}
+		}
+	}
+}
+
 function addPortableTextAssetOccurrence(
 	occurrences: ExtractedMediaUsageOccurrence[],
 	seen: Set<string>,

package/src/media/usage/projection-fingerprint.ts

@@ -86,6 +86,20 @@ function normalizeExtractionFields(
 ): Record<string, unknown>[] {
 	return fields
 		.map((field) => {
+			if (field.type === "blocks") {
+				return {
+					slug: field.slug,
+					type: field.type,
+					blockTypes: (field.blockTypes ?? []).map((type) => ({
+						slug: type.slug,
+						currentVersion: type.currentVersion,
+						versions: type.versions.map((version) => ({
+							version: version.version,
+							fingerprint: version.fingerprint,
+						})),
+					})),
+				};
+			}
 			if (field.type !== "repeater") return { slug: field.slug, type: field.type };
 			return {
 				slug: field.slug,

package/src/media/usage/schema-invalidation.ts

@@ -0,0 +1,72 @@
+import type { Kysely } from "kysely";
+
+import { tableExists } from "../../database/dialect-helpers.js";
+import { MediaUsageRepository } from "../../database/repositories/media-usage.js";
+import type { Database } from "../../database/types.js";
+import { validateIdentifier } from "../../database/validate.js";
+import { CONTENT_SOURCE_SCHEMA_VERSION } from "./types.js";
+
+export const CONTENT_MEDIA_USAGE_ADAPTER_ID = "content-media";
+export const CONTENT_MEDIA_USAGE_COLLECTION_SCOPE = "collection";
+
+export async function markContentMediaUsageCollectionStale(
+	db: Kysely<Database>,
+	collectionSlug: string,
+	lastErrorCode: string,
+): Promise<void> {
+	validateIdentifier(collectionSlug, "collection slug");
+	const repo = new MediaUsageRepository(db);
+	const identity = {
+		adapterId: CONTENT_MEDIA_USAGE_ADAPTER_ID,
+		scopeType: CONTENT_MEDIA_USAGE_COLLECTION_SCOPE,
+		scopeKey: collectionSlug,
+	};
+	const existing = await repo.findIndexStatus(identity);
+	await repo.upsertIndexStatus({
+		...identity,
+		status: "stale",
+		schemaVersion: existing?.schemaVersion ?? CONTENT_SOURCE_SCHEMA_VERSION,
+		startedAt: existing?.startedAt ?? null,
+		completedAt: existing?.completedAt ?? null,
+		cursor: existing?.cursor ?? null,
+		indexedSourceCount: existing?.indexedSourceCount ?? 0,
+		failedSourceCount: existing?.failedSourceCount ?? 0,
+		lastErrorCode,
+	});
+}
+
+export async function invalidateContentMediaUsageSchemaChange(
+	db: Kysely<Database>,
+	collectionSlug: string,
+): Promise<boolean> {
+	validateIdentifier(collectionSlug, "collection slug");
+	if (!(await tableExists(db, "_emdash_media_usage_activation"))) return false;
+	const activation = await db
+		.selectFrom("_emdash_media_usage_activation")
+		.select("state")
+		.where("task_key", "=", "incremental_capture")
+		.executeTakeFirst();
+	if (activation?.state !== "active") return false;
+
+	const invalidated = await new MediaUsageRepository(db).invalidateIndexStatusForSchemaChange(
+		collectionSlug,
+	);
+	if (!invalidated) {
+		throw new Error(`Cannot invalidate media usage coverage for collection ${collectionSlug}`);
+	}
+	return true;
+}
+
+export async function markContentMediaUsageCollectionStaleSafely(
+	db: Kysely<Database>,
+	collectionSlug: string,
+	lastErrorCode: string,
+): Promise<boolean> {
+	try {
+		await markContentMediaUsageCollectionStale(db, collectionSlug, lastErrorCode);
+		return true;
+	} catch (error) {
+		console.error(`[media-usage] Failed to mark ${collectionSlug} stale:`, error);
+		return false;
+	}
+}

package/src/media/usage/site-settings.ts

@@ -0,0 +1,52 @@
+/**
+ * Media references held by site settings.
+ *
+ * Usage reads parse these from the stored `site:*` options on every read, so
+ * a change through any writer of those options shows up on the next read.
+ */
+
+import { settingMediaIds, type PortableSettingName } from "../../transfer/format/settings.js";
+
+export const MEDIA_USAGE_SITE_SETTINGS = ["logo", "favicon", "seo.defaultOgImage"] as const;
+
+export type MediaUsageSiteSetting = (typeof MEDIA_USAGE_SITE_SETTINGS)[number];
+
+/**
+ * One setting per option, which holds while each option has a single path in
+ * `SETTING_MEDIA_REFERENCE_PATHS`. A second path needs a setting of its own.
+ */
+const SITE_SETTING_OPTIONS = [
+	["site:logo", "logo"],
+	["site:favicon", "favicon"],
+	["site:seo", "seo.defaultOgImage"],
+] as const satisfies readonly (readonly [PortableSettingName, MediaUsageSiteSetting])[];
+
+export const MEDIA_USAGE_SITE_SETTING_OPTIONS = SITE_SETTING_OPTIONS.map(([option]) => option);
+
+/**
+ * Group the site settings that select each media item, in settings order.
+ *
+ * @param options Raw JSON option values keyed by option name.
+ */
+export function groupSiteSettingMediaUsage(
+	options: ReadonlyMap<string, string | null>,
+): Map<string, MediaUsageSiteSetting[]> {
+	const usage = new Map<string, MediaUsageSiteSetting[]>();
+	for (const [option, setting] of SITE_SETTING_OPTIONS) {
+		for (const mediaId of settingMediaIds(option, parseOption(options.get(option)))) {
+			const settings = usage.get(mediaId);
+			if (settings) settings.push(setting);
+			else usage.set(mediaId, [setting]);
+		}
+	}
+	return usage;
+}
+
+function parseOption(value: string | null | undefined): unknown {
+	if (value == null) return undefined;
+	try {
+		return JSON.parse(value);
+	} catch {
+		return undefined;
+	}
+}

package/src/media/usage/types.ts

@@ -1,3 +1,4 @@
+import type { BlockType } from "../../schema/block-types.js";
 import type { FieldType } from "../../schema/types.js";
 
 export const CONTENT_SOURCE_SCHEMA_VERSION = 2;
@@ -28,6 +29,7 @@ export interface MediaUsageExtractionField {
 	slug: string;
 	type: FieldType;
 	validation?: MediaUsageExtractionValidation | null;
+	blockTypes?: readonly BlockType[];
 }
 
 export interface ExtractMediaUsageOccurrencesInput {

package/src/object-cache/index.ts

@@ -25,6 +25,8 @@
  * fork them (same pattern as `request-context.ts`).
  */
 
+import { AsyncLocalStorage } from "node:async_hooks";
+
 import { after } from "../after.js";
 import { getRequestContext } from "../request-context.js";
 import { decode, encode } from "./codec.js";
@@ -147,6 +149,7 @@ const EPOCH_KEY = Symbol.for("emdash:object-cache:epochs");
 const PENDING_KEY = Symbol.for("emdash:object-cache:pending-bumps");
 const LAST_CONTENT_WRITE_KEY = Symbol.for("emdash:object-cache:last-content-write");
 const PENDING_CONTENT_WRITE_KEY = Symbol.for("emdash:object-cache:pending-content-write");
+const WRITE_SCOPE_KEY = Symbol.for("emdash:object-cache:write-scope");
 const g = globalThis as Record<symbol, unknown>;
 
 const holder: BackendHolder =
@@ -220,6 +223,23 @@ const contentWritePersist: { pending: boolean } =
 		g[PENDING_CONTENT_WRITE_KEY] = s;
 		return s;
 	})();
+
+/** Backend writes held by {@link coalesceObjectCacheWrites} until its work ends. */
+interface WriteScope {
+	/** Each write persists the latest local value when it runs, so one per key suffices. */
+	held: Map<string, () => void>;
+	closed: boolean;
+}
+
+const writeScopes: AsyncLocalStorage<WriteScope> =
+	// eslint-disable-next-line typescript/no-unsafe-type-assertion -- globalThis singleton pattern (see request-context.ts)
+	(g[WRITE_SCOPE_KEY] as AsyncLocalStorage<WriteScope> | undefined) ??
+	(() => {
+		const als = new AsyncLocalStorage<WriteScope>();
+		g[WRITE_SCOPE_KEY] = als;
+		return als;
+	})();
+
 /**
  * Resolve (once per isolate) the configured object-cache backend.
  *
@@ -573,6 +593,10 @@ function stampLastContentWrite(): void {
 	lastContentWrite.promise = undefined;
 	lastContentWrite.promiseAt = undefined;
 
+	scheduleBackendWrite("last-content-write", persistLastContentWrite);
+}
+
+function persistLastContentWrite(): void {
 	if (contentWritePersist.pending) return;
 	contentWritePersist.pending = true;
 	after(async () => {
@@ -653,8 +677,10 @@ export async function getLastContentWriteAt(): Promise<number> {
  *
  * Sync and non-blocking: the local epoch is stamped immediately (so the
  * writing isolate is instantly consistent) and the backend write is deferred
- * via `after`. Other isolates pick up the new epoch within their `revalidate`
- * window. No-ops when the cache is disabled.
+ * via `after`, or held until the work ends inside
+ * {@link coalesceObjectCacheWrites}. Other isolates pick up the new epoch
+ * within their `revalidate` window after that write. No-ops when the cache is
+ * disabled.
  *
  * Content namespaces (`content:*`) also stamp {@link getLastContentWriteAt}.
  */
@@ -671,8 +697,12 @@ export function invalidateObjectCache(namespace: string): void {
 		stampLastContentWrite();
 	}
 
-	// Coalesce repeated bumps of the same namespace within a tick (e.g. a bulk
-	// publish loop) into a single backend write that persists the latest epoch.
+	scheduleBackendWrite(`epoch:${namespace}`, () => persistEpoch(namespace, stamp));
+}
+
+function persistEpoch(namespace: string, stamp: number): void {
+	// Coalesce repeated bumps of the same namespace within a tick into a single
+	// backend write that persists the latest epoch.
 	if (pendingBumps.has(namespace)) return;
 	pendingBumps.add(namespace);
 	after(async () => {
@@ -689,6 +719,41 @@ export function invalidateObjectCache(namespace: string): void {
 		}
 	});
 }
+
+function scheduleBackendWrite(key: string, write: () => void): void {
+	const scope = writeScopes.getStore();
+	if (scope && !scope.closed) {
+		scope.held.set(key, write);
+		return;
+	}
+	write();
+}
+
+/**
+ * Run a bulk write, such as applying a seed, with its backend epoch writes held
+ * until it settles. Invalidations inside `fn` still stamp the local epochs
+ * immediately; the backend then receives one write per namespace, carrying the
+ * latest epoch, whether `fn` resolves or throws. Without this, every entry
+ * rewrites the same few keys, and KV accepts about one write per second per key.
+ *
+ * Other isolates see none of these invalidations until `fn` ends, so don't wrap
+ * work that purges edge-cached pages part-way through: a page rebuilt after
+ * such a purge would still read the old epoch. If the invocation is killed
+ * before `fn` settles, the held writes are lost with it, and other isolates
+ * keep their cached values until those expire.
+ */
+export async function coalesceObjectCacheWrites<T>(fn: () => Promise<T>): Promise<T> {
+	const scope: WriteScope = { held: new Map(), closed: false };
+	try {
+		return await writeScopes.run(scope, fn);
+	} finally {
+		// Deferred work started inside `fn` can still invalidate after this point;
+		// it sees the closed scope and writes through.
+		scope.closed = true;
+		for (const write of scope.held.values()) write();
+	}
+}
+
 /**
  * Fixed namespaces for data shared across collections. Content reads fold the
  * `BYLINES` and `TAXONOMIES` epochs into their keys (via {@link cachedQuery})

package/src/plugin-test-runtime.ts

@@ -15,3 +15,4 @@ export { getI18nConfig, setI18nConfig } from "./i18n/config.js";
 export { RedirectRepository } from "./database/repositories/redirect.js";
 export { BylineRepository } from "./database/repositories/byline.js";
 export { TaxonomyRepository } from "./database/repositories/taxonomy.js";
+export { saveTaxonomyStructure } from "./database/repositories/taxonomy-def.js";