emdash 0.36.0 → 0.37.0

package/src/mcp/server.ts

@@ -21,8 +21,10 @@ import {
 	contentBylineInputSchema,
 	contentSeoInput,
 	createCollectionBody,
+	createTaxonomyDefBody,
 	updateCollectionBody,
 	updateFieldBody,
+	updateTaxonomyDefBody,
 } from "#api/schemas.js";
 
 import type { MediaUsageRepairRequest } from "../api/schemas/media-usage.js";
@@ -37,8 +39,34 @@ import { decodeBase64, encodeBase64 } from "../utils/base64.js";
 const COLLECTION_SLUG_PATTERN = /^[a-z][a-z0-9_]*$/;
 /** http(s) scheme matcher used by `settings_update` URL validation. */
 const HTTP_SCHEME_PATTERN = /^https?:\/\//i;
+/**
+ * Shared wording for the `_rev` parameter on write tools. Agents only see the
+ * tool schema, so the retry protocol is stated here.
+ */
+const REV_PARAM_DESCRIPTION =
+	"Revision token proving you have read the current item. Call content_get " +
+	"first and pass back the _rev it returns. If this call fails with CONFLICT " +
+	"the item changed in the meantime: call content_get again and retry with " +
+	"the new token.";
+
+/**
+ * Replaces Zod's "expected string, received undefined" for a caller that never
+ * read the schema, so the message says where the token comes from.
+ */
+const REV_MISSING_ERROR =
+	"_rev is required: call content_get for this item and pass back the _rev it returns.";
+
 const TAXONOMY_CURSOR_VERSION = 2;
 const MAX_TAXONOMY_CURSOR_LENGTH = 2048;
+const contentDateTimeInputSchema = z.iso
+	.datetime({ offset: true, message: "must be an ISO 8601 datetime" })
+	.or(
+		z.iso.datetime({
+			offset: true,
+			precision: -1,
+			message: "must be an ISO 8601 datetime",
+		}),
+	);
 
 // ---------------------------------------------------------------------------
 // Shared schemas — kept in sync with `api/schemas/settings.ts` (which the
@@ -150,6 +178,12 @@ const schemaUpdateCollectionToolSchema = z.object({
 	commentsAutoApproveUsers: updateCollectionBody.shape.commentsAutoApproveUsers.describe(
 		"Whether comments from authenticated users are automatically approved",
 	),
+	titleField: updateCollectionBody.shape.titleField.describe(
+		"Field slug to use as the Title column in admin lists; pass null to fall back to the default",
+	),
+	dateField: updateCollectionBody.shape.dateField.describe(
+		"Datetime field slug to use as the Date column in admin lists; pass null to fall back to the default",
+	),
 });
 
 const schemaUpdateFieldToolSchema = z.object({
@@ -617,6 +651,13 @@ function extractContentId(data: unknown): string | undefined {
 	return typeof item?.id === "string" ? item.id : undefined;
 }
 
+/** Extract the `_rev` token from a content handler response. */
+function extractContentRev(data: unknown): string | undefined {
+	if (!data || typeof data !== "object") return undefined;
+	const rev = (data as Record<string, unknown>)._rev;
+	return typeof rev === "string" ? rev : undefined;
+}
+
 // ---------------------------------------------------------------------------
 // Server factory
 // ---------------------------------------------------------------------------
@@ -827,8 +868,9 @@ export function createMcpServer(
 			title: "Get Content",
 			description:
 				"Get a single content item by its ID or slug. Returns the full content data " +
-				"including all field values, metadata, and a _rev token for optimistic " +
-				"concurrency (pass _rev back when updating to detect conflicts).",
+				"including all field values, metadata, and a _rev token. content_update, " +
+				"content_publish, content_unpublish and content_discard_draft require that " +
+				"token, so read the item here before calling them.",
 			inputSchema: z.object({
 				collection: z.string().describe("Collection slug (e.g. 'posts', 'pages')"),
 				id: z.string().describe("Content item ID (ULID) or slug"),
@@ -995,9 +1037,12 @@ export function createMcpServer(
 				"in the 'data' object — unspecified fields are left unchanged. Rich text " +
 				"(portableText) fields accept a Markdown string (recommended, converted " +
 				"automatically); use a Portable Text JSON array only for complex content " +
-				"Markdown can't express (custom blocks, embeds). Pass the " +
-				"_rev token from content_get to enable optimistic concurrency checking " +
-				"(the update fails if the item was modified since you read it). " +
+				"Markdown can't express (custom blocks, embeds). Requires the _rev " +
+				"token from content_get, so read the item before updating it: the " +
+				"update fails if the item changed since that read. When status is not " +
+				"set, a change to a published item is staged as a draft, so the " +
+				"response shows the new values while the live version keeps the old " +
+				"ones until content_publish. " +
 				"`seo` and `bylines` are persisted alongside the field updates in a " +
 				"single transaction. `publishedAt` requires the content:publish_any " +
 				"permission and is useful for migrations or correcting historical dates.",
@@ -1043,16 +1088,12 @@ export function createMcpServer(
 					.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" })
+				publishedAt: contentDateTimeInputSchema
 					.nullish()
 					.describe(
 						"Override the publication timestamp (ISO 8601). Requires content:publish_any permission. Pass null to clear. Useful for content migrations.",
 					),
-				_rev: z
-					.string()
-					.optional()
-					.describe("Revision token from content_get for conflict detection"),
+				_rev: z.string({ error: REV_MISSING_ERROR }).describe(REV_PARAM_DESCRIPTION),
 			}),
 		},
 		async (args, extra) => {
@@ -1090,6 +1131,7 @@ export function createMcpServer(
 			// Status transitions route through dedicated handlers for proper revision management
 			if (args.status === "published") {
 				requireOwnership(extra, ownerId, "content:publish_own", "content:publish_any");
+				let rev: string | undefined = args._rev;
 				if (
 					args.data ||
 					args.slug ||
@@ -1110,12 +1152,16 @@ export function createMcpServer(
 						_rev: args._rev,
 					});
 					if (!updateResult.success) return unwrap(updateResult);
+					rev = extractContentRev(updateResult.data);
 				}
-				return unwrap(await emdash.handleContentPublish(args.collection, resolvedId));
+				return unwrap(
+					await emdash.handleContentPublish(args.collection, resolvedId, { _rev: rev }),
+				);
 			}
 
 			if (args.status === "draft") {
 				requireOwnership(extra, ownerId, "content:publish_own", "content:publish_any");
+				let rev: string | undefined = args._rev;
 				if (
 					args.data ||
 					args.slug ||
@@ -1136,8 +1182,11 @@ export function createMcpServer(
 						_rev: args._rev,
 					});
 					if (!updateResult.success) return unwrap(updateResult);
+					rev = extractContentRev(updateResult.data);
 				}
-				return unwrap(await emdash.handleContentUnpublish(args.collection, resolvedId));
+				return unwrap(
+					await emdash.handleContentUnpublish(args.collection, resolvedId, { _rev: rev }),
+				);
 			}
 
 			return unwrap(
@@ -1260,8 +1309,8 @@ export function createMcpServer(
 			inputSchema: z.object({
 				collection: z.string().describe("Collection slug"),
 				id: z.string().describe("Content item ID or slug"),
-				publishedAt: z.iso
-					.datetime({ offset: true, message: "must be an ISO 8601 datetime" })
+				_rev: z.string({ error: REV_MISSING_ERROR }).describe(REV_PARAM_DESCRIPTION),
+				publishedAt: contentDateTimeInputSchema
 					.optional()
 					.describe(
 						"Override publication timestamp (ISO 8601). Requires content:publish_any permission. Useful when importing content with original publish dates.",
@@ -1297,6 +1346,7 @@ export function createMcpServer(
 			return unwrap(
 				await emdash.handleContentPublish(args.collection, resolvedId, {
 					publishedAt: args.publishedAt,
+					_rev: args._rev,
 				}),
 			);
 		},
@@ -1308,10 +1358,11 @@ export function createMcpServer(
 			title: "Unpublish Content",
 			description:
 				"Unpublish a content item, reverting it to draft status. It will no " +
-				"longer be visible on the live site but its content is preserved.",
+				"longer be visible on the live site, but its content and publication date are preserved.",
 			inputSchema: z.object({
 				collection: z.string().describe("Collection slug"),
 				id: z.string().describe("Content item ID or slug"),
+				_rev: z.string({ error: REV_MISSING_ERROR }).describe(REV_PARAM_DESCRIPTION),
 			}),
 		},
 		async (args, extra) => {
@@ -1332,7 +1383,9 @@ export function createMcpServer(
 			);
 
 			const resolvedId = extractContentId(existing.data) ?? args.id;
-			return unwrap(await ec.handleContentUnpublish(args.collection, resolvedId));
+			return unwrap(
+				await ec.handleContentUnpublish(args.collection, resolvedId, { _rev: args._rev }),
+			);
 		},
 	);
 
@@ -1440,6 +1493,7 @@ export function createMcpServer(
 			inputSchema: z.object({
 				collection: z.string().describe("Collection slug"),
 				id: z.string().describe("Content item ID or slug"),
+				_rev: z.string({ error: REV_MISSING_ERROR }).describe(REV_PARAM_DESCRIPTION),
 			}),
 			annotations: { destructiveHint: true },
 		},
@@ -1461,7 +1515,9 @@ export function createMcpServer(
 			);
 
 			const resolvedId = extractContentId(existing.data) ?? args.id;
-			return unwrap(await ec.handleContentDiscardDraft(args.collection, resolvedId));
+			return unwrap(
+				await ec.handleContentDiscardDraft(args.collection, resolvedId, { _rev: args._rev }),
+			);
 		},
 	);
 
@@ -1969,7 +2025,7 @@ export function createMcpServer(
 							.describe("Target collection slug for reference fields"),
 						rows: z.number().optional().describe("Number of rows for textarea"),
 					})
-					.passthrough()
+					.loose()
 					.optional()
 					.describe("Widget configuration"),
 				searchable: z
@@ -2168,7 +2224,6 @@ export function createMcpServer(
 					.optional()
 					.describe("Base64-encoded file contents. Provide exactly one of base64 / url."),
 				url: z
-					.string()
 					.url()
 					.optional()
 					.describe(
@@ -2423,6 +2478,158 @@ export function createMcpServer(
 		},
 	);
 
+	server.registerTool(
+		"taxonomy_get",
+		{
+			title: "Get Taxonomy Definition",
+			description:
+				"Get a single taxonomy definition by name. Taxonomy definitions describe " +
+				"a classification system (e.g. categories or tags), which collections " +
+				"it applies to, and whether it is hierarchical. Pass `locale` to resolve " +
+				"a specific translation; otherwise the lowest matching locale is returned.",
+			inputSchema: z.object({
+				name: z.string().describe("Taxonomy name (e.g. 'categories', 'tags')"),
+				locale: z.string().optional().describe("Locale to resolve the definition for"),
+			}),
+			annotations: { readOnlyHint: true },
+		},
+		async (args, extra) => {
+			requireScope(extra, "content:read");
+			const ec = getEmDash(extra);
+			try {
+				const { handleTaxonomyGet } = await import("../api/handlers/taxonomies.js");
+				return unwrap(await handleTaxonomyGet(ec.db, args.name, { locale: args.locale }));
+			} catch (error) {
+				return respondHandlerError(error, "TAXONOMY_GET_ERROR");
+			}
+		},
+	);
+
+	server.registerTool(
+		"taxonomy_create",
+		{
+			title: "Create Taxonomy Definition",
+			description:
+				"Create a new taxonomy definition. Definitions are per-locale; pass " +
+				"`locale` when the same taxonomy name exists in multiple translations. " +
+				"`collections` names which content types the taxonomy applies to. " +
+				"If `translationOf` is set, the new definition joins the source's " +
+				"translation group and inherits `hierarchical` and `collections` from " +
+				"the source when those fields are omitted.",
+			inputSchema: z.object({
+				name: createTaxonomyDefBody.shape.name.describe(
+					"Taxonomy name (lowercase letters, numbers, underscores)",
+				),
+				label: createTaxonomyDefBody.shape.label.describe("Display name"),
+				labelSingular: createTaxonomyDefBody.shape.labelSingular.describe(
+					"Singular form of the display name",
+				),
+				hierarchical: createTaxonomyDefBody.shape.hierarchical.describe(
+					"Whether the taxonomy supports parent/child terms (defaults to false, or inherited from translationOf)",
+				),
+				collections: createTaxonomyDefBody.shape.collections.describe(
+					"Collection slugs this taxonomy applies to (defaults to [], or inherited from translationOf)",
+				),
+				locale: z.string().optional().describe("Locale for this definition (e.g. 'fr-fr')"),
+				translationOf: z
+					.string()
+					.optional()
+					.describe("Existing taxonomy definition id to create this locale variant from"),
+			}),
+		},
+		async (args, extra) => {
+			requireScope(extra, "taxonomies:manage");
+			requireRole(extra, Role.EDITOR);
+			const ec = getEmDash(extra);
+			try {
+				const { handleTaxonomyCreate } = await import("../api/handlers/taxonomies.js");
+				return unwrap(
+					await handleTaxonomyCreate(ec.db, {
+						name: args.name,
+						label: args.label,
+						labelSingular: args.labelSingular,
+						hierarchical: args.hierarchical,
+						collections: args.collections,
+						locale: args.locale,
+						translationOf: args.translationOf,
+					}),
+				);
+			} catch (error) {
+				return respondHandlerError(error, "TAXONOMY_CREATE_ERROR");
+			}
+		},
+	);
+
+	server.registerTool(
+		"taxonomy_update",
+		{
+			title: "Update Taxonomy Definition",
+			description:
+				"Update an existing taxonomy definition. The taxonomy `name` cannot be " +
+				"changed. Pass `locale` to update a specific translation; otherwise the " +
+				"lowest matching locale is updated. Any field may be omitted to leave it " +
+				"unchanged.",
+			inputSchema: z.object({
+				name: z.string().describe("Taxonomy name to update"),
+				label: updateTaxonomyDefBody.shape.label.describe("New display name"),
+				labelSingular: updateTaxonomyDefBody.shape.labelSingular.describe(
+					"New singular display name; pass null to clear",
+				),
+				hierarchical: updateTaxonomyDefBody.shape.hierarchical.describe(
+					"Whether the taxonomy supports parent/child terms",
+				),
+				collections: updateTaxonomyDefBody.shape.collections.describe(
+					"Collection slugs this taxonomy applies to",
+				),
+				locale: z.string().optional().describe("Locale of the definition to update"),
+			}),
+		},
+		async (args, extra) => {
+			requireScope(extra, "taxonomies:manage");
+			requireRole(extra, Role.EDITOR);
+			const ec = getEmDash(extra);
+			try {
+				const { handleTaxonomyUpdate } = await import("../api/handlers/taxonomies.js");
+				return unwrap(
+					await handleTaxonomyUpdate(ec.db, args.name, {
+						label: args.label,
+						labelSingular: args.labelSingular,
+						hierarchical: args.hierarchical,
+						collections: args.collections,
+						locale: args.locale,
+					}),
+				);
+			} catch (error) {
+				return respondHandlerError(error, "TAXONOMY_UPDATE_ERROR");
+			}
+		},
+	);
+
+	server.registerTool(
+		"taxonomy_delete",
+		{
+			title: "Delete Taxonomy Definition",
+			description:
+				"Delete a taxonomy definition and all of its terms in every locale, " +
+				"along with any content assignments those terms hold. This cannot be undone.",
+			inputSchema: z.object({
+				name: z.string().describe("Taxonomy name to delete"),
+			}),
+			annotations: { destructiveHint: true },
+		},
+		async (args, extra) => {
+			requireScope(extra, "taxonomies:manage");
+			requireRole(extra, Role.EDITOR);
+			const ec = getEmDash(extra);
+			try {
+				const { handleTaxonomyDelete } = await import("../api/handlers/taxonomies.js");
+				return unwrap(await handleTaxonomyDelete(ec.db, args.name));
+			} catch (error) {
+				return respondHandlerError(error, "TAXONOMY_DELETE_ERROR");
+			}
+		},
+	);
+
 	server.registerTool(
 		"taxonomy_list_terms",
 		{
@@ -3026,10 +3233,7 @@ export function createMcpServer(
 					.describe("Favicon media reference ({ mediaId, alt? })"),
 				url: z
 					.union([
-						z
-							.string()
-							.url()
-							.refine((u) => HTTP_SCHEME_PATTERN.test(u), "URL must use http or https"),
+						z.url().refine((u) => HTTP_SCHEME_PATTERN.test(u), "URL must use http or https"),
 						z.literal(""),
 					])
 					.optional()

package/src/media/image-endpoint.ts

@@ -50,9 +50,12 @@ export interface ImageTransformOptions {
 	quality?: number;
 }
 
-/** Long-lived immutable cache -- transform output is deterministic per key+params. */
+/** Long-lived cache for content-addressed image URLs. */
 export const IMMUTABLE_IMAGE_CACHE = "public, max-age=31536000, immutable";
 
+/** Cache policy for media keys that Replace original may overwrite. */
+export const MUTABLE_MEDIA_CACHE_CONTROL = "public, max-age=0, must-revalidate";
+
 /**
  * Raster types safe to render inline. Anything else (SVG, PDF, ...) is served
  * as an attachment so it can't execute as an active document. Mirrors the
@@ -77,7 +80,7 @@ const SAFE_INLINE_IMAGE_TYPES = new Set([
 export function originalMediaHeaders(contentType: string): Record<string, string> {
 	return {
 		"Content-Type": contentType,
-		"Cache-Control": IMMUTABLE_IMAGE_CACHE,
+		"Cache-Control": MUTABLE_MEDIA_CACHE_CONTROL,
 		"X-Content-Type-Options": "nosniff",
 		"Content-Security-Policy":
 			"sandbox; default-src 'none'; img-src 'self'; style-src 'unsafe-inline'",

package/src/media/normalize.ts

@@ -15,6 +15,16 @@ import type { MediaProvider, MediaProviderItem, MediaValue } from "./types.js";
 export const INTERNAL_MEDIA_PREFIX = "/_emdash/api/media/file/";
 const URL_PATTERN = /^https?:\/\//;
 
+export function normalizeLegacyExternalMediaValue(value: MediaValue): MediaValue {
+	if (value.provider !== "external-url") return value;
+	const src = value.src ?? value.previewUrl;
+	return {
+		...value,
+		provider: "external",
+		...(src === undefined ? {} : { src }),
+	};
+}
+
 /**
  * Normalize a media field value into a consistent MediaValue shape.
  *
@@ -41,16 +51,17 @@ export async function normalizeMediaValue(
 	// Must have at least an id to be a valid media value
 	if (!("id" in value) && !("src" in value)) return null;
 
-	const provider = (typeof value.provider === "string" ? value.provider : undefined) || "local";
-	const id = typeof value.id === "string" ? value.id : "";
+	const parsed = normalizeLegacyExternalMediaValue(recordToMediaValue(value));
+	const provider = parsed.provider || "local";
+	const id = parsed.id;
 
 	// External URLs — return as-is, no server-side dimension detection
 	if (provider === "external") {
-		return recordToMediaValue(value);
+		return parsed;
 	}
 
 	// Build the base value from the input
-	const result: MediaValue = { ...recordToMediaValue(value), provider };
+	const result: MediaValue = { ...parsed, provider };
 
 	// For local media, strip `src` — it's derived at display time from storageKey
 	if (provider === "local") {

package/src/media/usage/cleanup.ts

@@ -81,14 +81,15 @@ export async function cleanupMediaUsage(db: Kysely<Database>): Promise<MediaUsag
 			);
 		}
 
-		if (canIssueStatement()) {
-			const cutoff = claim.scanBeforeAt;
-			const candidates = await repo.findMediaUsageCleanupCandidates({
-				cutoff,
-				cursor: claim.cursor,
-				limit: MEDIA_USAGE_CLEANUP_CANDIDATE_LIMIT,
-				cleanupLease: cleanupLease(leaseToken),
-			});
+		const cutoff = claim.scanBeforeAt;
+		const candidates = await repo.findMediaUsageCleanupCandidates({
+			cutoff,
+			cursor: claim.cursor,
+			limit: MEDIA_USAGE_CLEANUP_CANDIDATE_LIMIT,
+			cleanupLease: cleanupLease(leaseToken),
+			canIssueStatement,
+		});
+		if (candidates) {
 			candidateRows = candidates.length;
 			scanHasMore = candidates.length === MEDIA_USAGE_CLEANUP_CANDIDATE_LIMIT;
 

package/src/menus/index.ts

@@ -11,11 +11,13 @@
 import type { Kysely } from "kysely";
 import { sql } from "kysely";
 
+import { menuTag } from "../cache/chrome-tags.js";
 import type { Database } from "../database/types.js";
 import { validateIdentifier } from "../database/validate.js";
 import { resolveLocale, resolveLocaleChain } from "../i18n/resolve.js";
 import { getDb } from "../loader.js";
 import { cachedQuery, CacheNamespace } from "../object-cache/index.js";
+import type { CacheHint } from "../query.js";
 import { requestCached } from "../request-cache.js";
 import { chunks, SQL_BATCH_SIZE } from "../utils/chunks.js";
 import { sanitizeHref } from "../utils/url.js";
@@ -126,6 +128,20 @@ export async function getMenusWithDb(
 	return query.execute();
 }
 
+/**
+ * Get a menu by name with a Workers edge-cache hint.
+ *
+ * Use the returned `cacheHint` with `Astro.cache.set()` so pages that render
+ * this menu can be purged automatically when the menu is edited.
+ */
+export async function getMenuWithCacheHint(
+	name: string,
+	options: MenuQueryOptions = {},
+): Promise<{ data: Menu | null; cacheHint: CacheHint }> {
+	const data = await getMenu(name, options);
+	return { data, cacheHint: { tags: [menuTag(name)] } };
+}
+
 /**
  * Build a hierarchical menu tree from a flat list of items. Items are
  * resolved against the given `locale` so references land on the right

package/src/object-cache/index.ts

@@ -46,6 +46,8 @@ interface BackendHolder {
 	backend: ObjectCacheBackend | null;
 	/** In-flight initialization promise (dedupes concurrent first calls). */
 	initPromise: Promise<ObjectCacheBackend | null> | null;
+	/** `Date.now()` when the in-flight initialization started. */
+	initPromiseAt?: number;
 	config: Required<Pick<ObjectCacheRuntimeConfig, "keyPrefix">> & {
 		defaultTtl: number;
 		revalidate: number;
@@ -128,6 +130,18 @@ function raceInFlightEpochRead(
 	return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
 }
 
+/** Bound a waiter on another request's backend initialization. */
+function raceInFlightBackendInit(
+	promise: Promise<ObjectCacheBackend | null>,
+	ms: number,
+): Promise<ObjectCacheBackend | null> {
+	let timer: ReturnType<typeof setTimeout>;
+	const timeout = new Promise<ObjectCacheBackend | null>((resolve) => {
+		timer = setTimeout(resolve, Math.max(ms, 1), null);
+	});
+	return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
+}
+
 const BACKEND_KEY = Symbol.for("emdash:object-cache:backend");
 const EPOCH_KEY = Symbol.for("emdash:object-cache:epochs");
 const PENDING_KEY = Symbol.for("emdash:object-cache:pending-bumps");
@@ -215,8 +229,15 @@ const contentWritePersist: { pending: boolean } =
  */
 async function getBackend(): Promise<ObjectCacheBackend | null> {
 	if (holder.initialized) return holder.backend;
-	if (holder.initPromise) return holder.initPromise;
+	if (holder.initPromise) {
+		const age = Date.now() - (holder.initPromiseAt ?? 0);
+		const deadline = epochReadDeadline();
+		if (age < deadline) {
+			return raceInFlightBackendInit(holder.initPromise, deadline - age);
+		}
+	}
 
+	holder.initPromiseAt = Date.now();
 	holder.initPromise = (async () => {
 		try {
 			const mod: {
@@ -258,10 +279,19 @@ async function getBackend(): Promise<ObjectCacheBackend | null> {
 		}
 		holder.initialized = true;
 		holder.initPromise = null;
+		holder.initPromiseAt = undefined;
 		return holder.backend;
 	})();
 
-	return holder.initPromise;
+	const started = holder.initPromise;
+	after(() =>
+		started.then(
+			() => undefined,
+			() => undefined,
+		),
+	);
+
+	return started;
 }
 
 /**
@@ -278,6 +308,7 @@ export function __setObjectCacheBackendForTests(
 ): void {
 	holder.initialized = true;
 	holder.initPromise = null;
+	holder.initPromiseAt = undefined;
 	holder.backend = backend;
 	holder.config = { ...holder.config, ...config };
 	epochCache.clear();
@@ -288,6 +319,17 @@ export function __setObjectCacheBackendForTests(
 	contentWritePersist.pending = false;
 }
 
+/** @internal */
+export function __setObjectCacheBackendInitForTests(
+	promise: Promise<ObjectCacheBackend | null>,
+	startedAt: number,
+): void {
+	holder.initialized = false;
+	holder.backend = null;
+	holder.initPromise = promise;
+	holder.initPromiseAt = startedAt;
+}
+
 /** Build the backend key for a namespace's epoch anchor. */
 function epochKey(namespace: string): string {
 	return `${holder.config.keyPrefix}:epoch:${namespace}`;

package/src/plugin-types.ts

@@ -41,6 +41,7 @@
 import type { Permission } from "@emdash-cms/auth";
 import type { ZodType } from "zod";
 
+import type { SandboxHookErrorEnvelope } from "./plugins/sandbox/hook-result.js";
 import type {
 	CommentAfterCreateEvent,
 	CommentAfterCreateHandler,
@@ -240,12 +241,28 @@ export interface SandboxedMcpTool {
  */
 export interface SandboxedPlugin {
 	hooks?: {
-		[K in keyof HookHandlers]?: HookEntry<K>;
+		[K in keyof HookHandlers]?: K extends "content:beforeSave"
+			? SandboxedContentBeforeSaveHandler | SandboxedContentBeforeSaveConfig
+			: HookEntry<K>;
 	};
 	routes?: Record<string, RouteEntry>;
 	mcp?: { tools: Record<string, SandboxedMcpTool> };
 }
 
+export type SandboxedContentBeforeSaveHandler = (
+	event: ContentHookEvent,
+	ctx: PluginContext,
+) => Promise<Record<string, unknown> | SandboxHookErrorEnvelope | void>;
+
+export interface SandboxedContentBeforeSaveConfig extends Omit<
+	HookConfig<"content:beforeSave">,
+	"handler"
+> {
+	handler: SandboxedContentBeforeSaveHandler;
+}
+
+export type { SandboxHookErrorEnvelope };
+
 /**
  * Re-export of event types so plugin authors can reference them
  * explicitly when needed (helper functions, type predicates). Most

package/src/plugins/hooks.ts

@@ -487,12 +487,14 @@ export class HookPipeline {
 
 	/**
 	 * Run content:beforeSave hooks
-	 * Returns modified content from the pipeline
+	 * Returns modified content from the pipeline. `id` is the existing item's
+	 * ID when updating.
 	 */
 	async runContentBeforeSave(
 		content: Record<string, unknown>,
 		collection: string,
 		isNew: boolean,
+		id?: string,
 	): Promise<{
 		content: Record<string, unknown>;
 		results: HookResult<Record<string, unknown>>[];
@@ -508,6 +510,7 @@ export class HookPipeline {
 				collection,
 				isNew,
 			};
+			if (id !== undefined) event.id = id;
 			const ctx = this.getContext(hook.pluginId);
 			const start = Date.now();