emdash 1.2.0 → 1.3.1

package/src/media/image-endpoint.ts

@@ -193,6 +193,8 @@ const SAFE_STORAGE_KEY = /^[A-Za-z0-9._-]+$/;
 
 /** Plain decimal digits only -- rejects "1e3", "0x10", "+5", whitespace. */
 const DECIMAL_DIGITS = /^\d+$/;
+const NUMERIC_QUALITY = /^-?\d+(?:\.\d+)?(?:e[+-]?\d+)?$/i;
+const QUALITY_PRESETS: Record<string, number> = { low: 25, mid: 50, high: 80, max: 100 };
 
 /** Whether a storage key is safe to resolve against the storage backend. */
 export function isSafeTransformKey(key: string): boolean {
@@ -256,8 +258,9 @@ export function resolveTransformQuality(
  * Parse and validate `?w=&h=&f=&q=` query params. Width is required (it sizes
  * the rendition); dimensions are bounded so a request can't ask for an
  * unbounded or nonsensical transform. Format falls back to
- * {@link DEFAULT_TRANSFORM_FORMAT} when not requested. `q` is validated when
- * present but otherwise left `undefined` so the caller can apply a per-format
+ * {@link DEFAULT_TRANSFORM_FORMAT} when not requested. `q` accepts Astro presets
+ * or finite numbers rounded and clamped to 1-100. It is otherwise left
+ * `undefined` so the caller can apply a per-format
  * default (lossy formats get one, lossless PNG does not — see
  * {@link DEFAULT_TRANSFORM_QUALITY}).
  */
@@ -281,11 +284,15 @@ export function parseTransformParams(params: URLSearchParams): ParsedTransformPa
 	let quality: number | undefined;
 	const qualityRaw = params.get("q");
 	if (qualityRaw !== null) {
-		const q = Number(qualityRaw);
-		if (!Number.isInteger(q) || q < 1 || q > 100) {
-			return { ok: false, message: "Invalid 'q' (quality), expected 1-100" };
+		if (Object.hasOwn(QUALITY_PRESETS, qualityRaw)) {
+			quality = QUALITY_PRESETS[qualityRaw];
+		} else {
+			const q = NUMERIC_QUALITY.test(qualityRaw) ? Number(qualityRaw) : Number.NaN;
+			if (!Number.isFinite(q)) {
+				return { ok: false, message: "Invalid 'q' (quality), expected a number or Astro preset" };
+			}
+			quality = Math.round(Math.min(100, Math.max(1, q)));
 		}
-		quality = q;
 	}
 
 	return { ok: true, options: { width, height, format, quality } };

package/src/media/local-runtime.ts

@@ -79,6 +79,7 @@ export const createMediaProvider: CreateMediaProviderFn<LocalMediaRuntimeConfig>
 					blurhash: item.blurhash ?? undefined,
 					dominantColor: item.dominantColor ?? undefined,
 					alt: item.alt ?? undefined,
+					caption: item.caption ?? undefined,
 					previewUrl: `/_emdash/api/media/file/${item.storageKey}`,
 					meta: {
 						storageKey: item.storageKey,
@@ -107,6 +108,7 @@ export const createMediaProvider: CreateMediaProviderFn<LocalMediaRuntimeConfig>
 				blurhash: item.blurhash ?? undefined,
 				dominantColor: item.dominantColor ?? undefined,
 				alt: item.alt ?? undefined,
+				caption: item.caption ?? undefined,
 				previewUrl: `/_emdash/api/media/file/${item.storageKey}`,
 				meta: {
 					storageKey: item.storageKey,
@@ -236,6 +238,7 @@ export function repoItemToProviderItem(item: {
 		blurhash: item.blurhash ?? undefined,
 		dominantColor: item.dominantColor ?? undefined,
 		alt: item.alt ?? undefined,
+		caption: item.caption ?? undefined,
 		previewUrl: `/_emdash/api/media/file/${item.storageKey}`,
 		meta: {
 			storageKey: item.storageKey,

package/src/media/normalize.ts

@@ -9,6 +9,7 @@
  * the provider's `get()` method.
  */
 
+import { syncMediaCaption } from "./caption.js";
 import { normalizeFocalPoint } from "./focal-point.js";
 import type { MediaProvider, MediaProviderItem, MediaValue } from "./types.js";
 
@@ -151,7 +152,7 @@ async function resolveInternalUrl(
 	}
 
 	const focalPoint = normalizeFocalPoint(item.focalX, item.focalY);
-	return {
+	return syncMediaCaption({
 		provider: "local",
 		id: item.id,
 		filename: item.filename,
@@ -162,8 +163,9 @@ async function resolveInternalUrl(
 		blurhash: item.blurhash,
 		dominantColor: item.dominantColor,
 		alt: item.alt,
+		caption: item.caption,
 		meta: item.meta,
-	};
+	});
 }
 
 async function resolveLocalId(
@@ -184,7 +186,7 @@ async function resolveLocalId(
 	if (!item) return null;
 
 	const focalPoint = normalizeFocalPoint(item.focalX, item.focalY);
-	return {
+	return syncMediaCaption({
 		provider: "local",
 		id: item.id,
 		filename: item.filename,
@@ -195,13 +197,15 @@ async function resolveLocalId(
 		blurhash: item.blurhash,
 		dominantColor: item.dominantColor,
 		alt: item.alt,
+		caption: item.caption,
 		meta: item.meta,
-	};
+	});
 }
 
 /**
- * Merge provider data into an existing MediaValue, preserving caller-supplied fields.
- * Caller `alt` takes priority over provider `alt` (per-usage, not per-image).
+ * Fill missing media metadata from a provider.
+ * Caller captions, including empty strings, take priority over provider captions.
+ * Provider alt text fills missing or empty caller alt text.
  */
 function mergeProviderData(existing: MediaValue, item: MediaProviderItem): MediaValue {
 	const result = { ...existing };
@@ -223,12 +227,14 @@ function mergeProviderData(existing: MediaValue, item: MediaProviderItem): Media
 	// Fill missing alt (provider alt is fallback, not override)
 	if (!result.alt && item.alt) result.alt = item.alt;
 
+	if (result.caption == null && item.caption != null) result.caption = item.caption;
+
 	// Fill missing meta (merge, don't replace)
 	if (item.meta) {
 		result.meta = { ...item.meta, ...result.meta };
 	}
 
-	return result;
+	return syncMediaCaption(result);
 }
 
 function isRecord(value: unknown): value is Record<string, unknown> {
@@ -258,6 +264,7 @@ function recordToMediaValue(obj: Record<string, unknown>): MediaValue {
 	if (typeof obj.blurhash === "string") result.blurhash = obj.blurhash;
 	if (typeof obj.dominantColor === "string") result.dominantColor = obj.dominantColor;
 	if (typeof obj.alt === "string") result.alt = obj.alt;
+	if (typeof obj.caption === "string") result.caption = obj.caption;
 	if (isRecord(obj.meta)) result.meta = obj.meta;
-	return result;
+	return syncMediaCaption(result);
 }

package/src/media/responsive.ts

@@ -9,6 +9,8 @@
  * resolves inside an Astro project, not in this precompiled package).
  */
 
+import type { EmbedOptions } from "./types.js";
+
 /** Standard responsive breakpoints. Matches CDN-provider srcset generation. */
 export const RESPONSIVE_BREAKPOINTS = [640, 750, 828, 960, 1080, 1280, 1600, 1920];
 
@@ -100,6 +102,7 @@ export type GetImage = (options: {
 	height?: number;
 	widths?: number[];
 	sizes?: string;
+	quality?: EmbedOptions["quality"];
 }) => Promise<{ src: string; srcSet?: { attribute?: string } | undefined }>;
 
 export interface ResponsiveImage {
@@ -127,9 +130,15 @@ export interface ResponsiveImage {
  */
 export async function buildResponsiveImage(
 	getImage: GetImage,
-	opts: { src: string; width?: number; height?: number; originalWidth?: number },
+	opts: {
+		src: string;
+		width?: number;
+		height?: number;
+		originalWidth?: number;
+		quality?: EmbedOptions["quality"];
+	},
 ): Promise<ResponsiveImage | null> {
-	const { src, width, height, originalWidth } = opts;
+	const { src, width, height, originalWidth, quality } = opts;
 	if (!src || !width || !height) return null;
 	if (!ABSOLUTE_HTTP_URL.test(src)) return null;
 	try {
@@ -140,6 +149,7 @@ export async function buildResponsiveImage(
 			height,
 			widths: responsiveWidths(width, originalWidth),
 			sizes,
+			...(quality !== undefined ? { quality } : {}),
 		});
 		// Passthrough: the service returned the source unchanged (unauthorized
 		// host or no optimization available). Don't emit a no-op srcset.

package/src/media/types.ts

@@ -6,6 +6,7 @@
  * alongside the built-in local media library.
  */
 
+import { syncMediaCaption } from "./caption.js";
 import { normalizeFocalPoint } from "./focal-point.js";
 
 /**
@@ -96,6 +97,8 @@ export interface MediaProviderItem {
 	dominantColor?: string;
 	/** Accessibility text */
 	alt?: string;
+	/** Default caption for display or attribution */
+	caption?: string;
 	/** Preview URL for admin UI thumbnail */
 	previewUrl?: string;
 	/** Provider-specific metadata */
@@ -121,6 +124,8 @@ export interface EmbedOptions {
 	height?: number;
 	/** Image format preference */
 	format?: "webp" | "avif" | "jpeg" | "png" | "auto";
+	/** Output quality (numeric or a provider-supported preset). */
+	quality?: number | string;
 }
 
 /**
@@ -143,7 +148,12 @@ export interface ImageEmbed {
 	/** Base URL without transforms, for responsive image generation */
 	cdnBaseUrl?: string;
 	/** For providers with URL-based transforms (Cloudinary, imgix) */
-	getSrc?: (opts: { width?: number; height?: number; format?: string }) => string;
+	getSrc?: (opts: {
+		width?: number;
+		height?: number;
+		format?: string;
+		quality?: EmbedOptions["quality"];
+	}) => string;
 }
 
 export interface VideoEmbed {
@@ -277,6 +287,8 @@ export interface MediaValue {
 	/** Cached LQIP dominant-color placeholder, as a CSS color (images only) */
 	dominantColor?: string;
 	alt?: string;
+	/** Caption for display or attribution */
+	caption?: string;
 
 	/** Provider-specific data needed for embedding */
 	meta?: Record<string, unknown>;
@@ -287,7 +299,7 @@ export interface MediaValue {
  */
 export function mediaItemToValue(providerId: string, item: MediaProviderItem): MediaValue {
 	const focalPoint = normalizeFocalPoint(item.focalX, item.focalY);
-	return {
+	return syncMediaCaption({
 		provider: providerId,
 		id: item.id,
 		filename: item.filename,
@@ -298,6 +310,7 @@ export function mediaItemToValue(providerId: string, item: MediaProviderItem): M
 		blurhash: item.blurhash,
 		dominantColor: item.dominantColor,
 		alt: item.alt,
+		caption: item.caption,
 		meta: item.meta,
-	};
+	});
 }

package/src/media/usage/collection-deletion.ts

@@ -1,6 +1,7 @@
 import { sql, type Kysely, type RawBuilder, type Selectable, type Transaction } from "kysely";
 import { ulid } from "ulidx";
 
+import { deleteSharedCollectionRecords } from "../../database/collection-cleanup.js";
 import { isPostgres } from "../../database/dialect-helpers.js";
 import {
 	decodeCursor,
@@ -555,6 +556,9 @@ export async function deleteActivatedMediaUsageCollection(
 			leaseToken: claim.leaseToken,
 		});
 		if (result.outcome !== "dropped") throw new Error("Collection deletion lost its table fence");
+		// The content table is gone, so the FKs from ec_* to revisions.id are
+		// released and the remaining shared-table records can be removed.
+		await deleteSharedCollectionRecords(db, claim.collectionSlug);
 		if (
 			!(await repository.checkpoint({
 				...lease,

package/src/menus/index.ts

@@ -14,6 +14,8 @@ 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 { getLocaleChainRank, getLocaleRank } from "../i18n/config.js";
+import { localeMatches } from "../i18n/query.js";
 import {
 	resolveLocalizedContentRoutePath,
 	resolveLocale,
@@ -94,13 +96,19 @@ export async function getMenuWithDb(
 		])
 		.where("m.name", "=", name)
 		.orderBy("i.sort_order", "asc");
-	if (chain.length > 0) query = query.where("m.locale", "in", chain);
+	if (chain.length > 0) {
+		query = query.where((eb) => eb.or(chain.map((locale) => localeMatches("m.locale", locale))));
+	}
 	const rows = await query.execute();
-
-	const locales = new Set(rows.map((row) => row.m_locale));
-	const locale =
-		chain.length === 0 ? [...locales].toSorted()[0] : chain.find((l) => locales.has(l));
-	const menuRow = rows.find((row) => row.m_locale === locale);
+	const sortedRows = rows.toSorted((a, b) => {
+		if (chain.length === 0)
+			return a.m_locale.localeCompare(b.m_locale) || a.m_id.localeCompare(b.m_id);
+		return (
+			getLocaleChainRank(a.m_locale, chain) - getLocaleChainRank(b.m_locale, chain) ||
+			a.m_id.localeCompare(b.m_id)
+		);
+	});
+	const menuRow = sortedRows[0];
 	if (!menuRow) return null;
 
 	const menuId = menuRow.m_id;
@@ -146,7 +154,7 @@ export async function getMenusWithDb(
 		.selectFrom("_emdash_menus")
 		.select(["id", "name", "label", "locale"])
 		.orderBy("name", "asc");
-	if (locale !== undefined) query = query.where("locale", "=", locale);
+	if (locale !== undefined) query = query.where(localeMatches("locale", locale));
 	return query.execute();
 }
 
@@ -439,11 +447,13 @@ function shouldPreferLocalizedRow(
 	locale: string,
 ): boolean {
 	if (!existing) return true;
-	if (candidate.locale === locale) return existing.locale !== locale || candidate.id < existing.id;
-	if (existing.locale === locale) return false;
+	const candidateRank = getLocaleRank(candidate.locale, locale);
+	const existingRank = getLocaleRank(existing.locale, locale);
 	return (
-		candidate.locale < existing.locale ||
-		(candidate.locale === existing.locale && candidate.id < existing.id)
+		candidateRank < existingRank ||
+		(candidateRank === existingRank &&
+			(candidate.locale < existing.locale ||
+				(candidate.locale === existing.locale && candidate.id < existing.id)))
 	);
 }
 

package/src/migrations/direct-executor.ts

@@ -1,6 +1,10 @@
 import { type Dialect, Kysely } from "kysely";
 
-import { clearMigrationLock, readMigrationLock } from "../database/migration-lock.js";
+import {
+	armMigrationLockTakeOver,
+	clearMigrationLock,
+	readMigrationLock,
+} from "../database/migration-lock.js";
 import {
 	getExactMigrationStatus,
 	runMigrations,
@@ -45,25 +49,47 @@ function createReport(
 	return report;
 }
 
-async function releaseLock(db: Kysely<Database>, lockId: string | undefined): Promise<void> {
+function confirmedLockId(lockId: string | undefined): number {
 	if (!lockId || !LOCK_ID_PATTERN.test(lockId)) {
-		throw new Error("Releasing the migration lock requires the lock id reported by status.");
+		throw new Error("The migration lock id must be the one reported by status.");
 	}
-	const lock = Number(lockId);
-	// Read before writing: on Postgres the lock column is a 32-bit integer that
-	// a lock id does not fit, and no Postgres lock is ever held in it.
-	const heldSince = await readMigrationLock(db);
-	if (heldSince === lock && (await clearMigrationLock(db, lock))) return;
-	const current = heldSince === lock ? await readMigrationLock(db) : heldSince;
+	return Number(lockId);
+}
+
+function lockMismatchError(current: number | null): Error {
 	// No lock ids here: the CLI's redaction can rewrite digits that match an
 	// environment value.
-	throw new Error(
+	return new Error(
 		current === null
 			? "The migration lock is not held."
-			: "The migration lock has a different id now. Check the status again before releasing it.",
+			: "The migration lock has a different id now. Check the status again.",
 	);
 }
 
+async function releaseLock(db: Kysely<Database>, lockId: string | undefined): Promise<void> {
+	const lock = confirmedLockId(lockId);
+	// Read before writing: on Postgres the lock column is a 32-bit integer that
+	// a lock id does not fit, and no Postgres lock is ever held in it.
+	const heldSince = await readMigrationLock(db);
+	if (heldSince === lock && (await clearMigrationLock(db, lock))) return;
+	throw lockMismatchError(heldSince === lock ? await readMigrationLock(db) : heldSince);
+}
+
+async function takeOverLock(
+	db: Kysely<Database>,
+	lockId: string | undefined,
+	pending: boolean,
+): Promise<void> {
+	const lock = confirmedLockId(lockId);
+	// With nothing pending no run takes the lock, so releasing it is enough.
+	if (!pending) return releaseLock(db, lockId);
+	const heldSince = await readMigrationLock(db);
+	if (heldSince !== lock) throw lockMismatchError(heldSince);
+	// No run on this database takes the lock in its row, so nothing can claim
+	// it between the release and this run.
+	if (!armMigrationLockTakeOver(db, lock)) await releaseLock(db, lockId);
+}
+
 async function verifyRequest(request: MigrationRequest): Promise<void> {
 	const identity = await getCoreMigrationIdentity();
 	if (
@@ -95,6 +121,9 @@ async function executeRequest(
 			`Cannot apply migrations with unknown applied migrations: ${initialStatus.unknownApplied.join(", ")}`,
 		);
 	}
+	if (request.action === "take-over-lock") {
+		await takeOverLock(db, request.lockId, initialStatus.pending.length > 0);
+	}
 	if (initialStatus.pending.length === 0) {
 		return createReport(target, initialStatus, []);
 	}
@@ -133,7 +162,8 @@ export function createDirectMigrationExecutor(
 			if (
 				request.action !== "check" &&
 				request.action !== "apply" &&
-				request.action !== "release-lock"
+				request.action !== "release-lock" &&
+				request.action !== "take-over-lock"
 			) {
 				throw new Error("Unsupported migration action.");
 			}

package/src/migrations/manifest.ts

@@ -23,6 +23,7 @@ const i18nConfigSchema = z
 	.object({
 		defaultLocale: z.string().min(1),
 		locales: z.array(z.string().min(1)).min(1),
+		localeAliases: z.record(z.string(), z.string()).optional(),
 		fallback: z.record(z.string(), z.string()).optional(),
 		prefixDefaultLocale: z.boolean().optional(),
 	})

package/src/migrations/protocol.ts

@@ -1,6 +1,6 @@
 import type { I18nConfig } from "../i18n/config.js";
 
-export type MigrationAction = "check" | "apply" | "release-lock";
+export type MigrationAction = "check" | "apply" | "release-lock" | "take-over-lock";
 
 export interface MigrationRequest {
 	action: MigrationAction;
@@ -9,7 +9,11 @@ export interface MigrationRequest {
 		emdashVersion: string;
 		migrationSetFingerprint: string;
 	};
-	/** For `release-lock`: the lock id a `check` reported. Another lock is left alone. */
+	/**
+	 * For `release-lock` and `take-over-lock`: the lock id a `check` reported.
+	 * Another lock is left alone. `take-over-lock` applies pending migrations
+	 * under that lock without freeing it first.
+	 */
 	lockId?: string;
 }
 

package/src/plugins/adapt-sandbox-entry.ts

@@ -13,6 +13,7 @@
 import { z } from "zod";
 
 import type { PluginDescriptor } from "../astro/integration/runtime.js";
+import { safeJsonSchemaToZod } from "../mcp/json-schema.js";
 import type { RouteEntry, RouteHandler, SandboxedPlugin } from "../plugin-types.js";
 import { PLUGIN_CAPABILITIES, HOOK_NAMES } from "./manifest-schema.js";
 import { sanitizeHeadersForSandbox } from "./request-meta.js";
@@ -355,7 +356,10 @@ export function adaptSandboxEntry(
 				// `emdash-plugin build` removes `mcp` from the runtime module and
 				// ships the tools in the descriptor instead.
 				...Object.fromEntries(
-					(descriptor.mcp?.tools ?? []).map((tool) => [tool.name, toolFromManifest(tool)]),
+					(descriptor.mcp?.tools ?? []).map((tool) => [
+						tool.name,
+						toolFromManifest(tool, pluginId),
+					]),
 				),
 				...Object.fromEntries(
 					Object.entries(definition.mcp?.tools ?? {}).map(([name, tool]) => [
@@ -380,21 +384,27 @@ export function adaptSandboxEntry(
  * on first use: turning JSON Schema back into Zod takes milliseconds per
  * tool, and this adapter runs on every cold start, public requests included.
  */
-function toolFromManifest(tool: ManifestMcpTool): PluginMcpToolDefinition {
+function toolFromManifest(tool: ManifestMcpTool, pluginId: string): PluginMcpToolDefinition {
 	let input: z.ZodType | undefined;
-	let output: z.ZodType | undefined;
+	let output: z.ZodType | null | undefined;
 	return {
 		description: tool.description,
 		route: tool.route,
 		destructive: tool.destructive,
 		get input() {
-			input ??= z.fromJSONSchema({ ...tool.inputSchema });
+			input ??=
+				safeJsonSchemaToZod({ ...tool.inputSchema }, `${pluginId}/${tool.name}`, "input") ??
+				z.record(z.string(), z.unknown());
 			return input;
 		},
 		get output() {
 			if (!tool.outputSchema) return undefined;
-			output ??= z.fromJSONSchema({ ...tool.outputSchema });
-			return output;
+			if (output === undefined) {
+				output =
+					safeJsonSchemaToZod({ ...tool.outputSchema }, `${pluginId}/${tool.name}`, "output") ??
+					null;
+			}
+			return output ?? undefined;
 		},
 	};
 }

package/src/plugins/byline-access.ts

@@ -8,6 +8,7 @@ import {
 } from "../database/repositories/types.js";
 import type { Database } from "../database/types.js";
 import { validateIdentifier } from "../database/validate.js";
+import { localeMatches } from "../i18n/query.js";
 import { chunks, SQL_BATCH_SIZE } from "../utils/chunks.js";
 import type { BylineAccess, BylineCreditInfo, BylineInfo } from "./types.js";
 
@@ -116,7 +117,8 @@ export function createBylineAccess(db: Kysely<Database>): BylineAccess {
 				.orderBy("created_at", "desc")
 				.orderBy("id", "desc")
 				.limit(limit + 1);
-			if (options?.locale !== undefined) query = query.where("locale", "=", options.locale);
+			if (options?.locale !== undefined)
+				query = query.where(localeMatches("locale", options.locale));
 			if (options?.cursor) {
 				const decoded = decodeCursor(options.cursor);
 				query = query.where((eb) =>

package/src/plugins/context.ts

@@ -403,8 +403,7 @@ export function createTaxonomyAccess(db: Kysely<Database>): TaxonomyAccess {
 
 	return {
 		async getAll(options?: TaxonomyReadOptions): Promise<TaxonomyDefInfo[]> {
-			let query = selectTaxonomyDefs(db);
-			if (options?.locale !== undefined) query = query.where("d.locale", "=", options.locale);
+			const query = selectTaxonomyDefs(db, options?.locale);
 			const rows = await query.orderBy("d.name", "asc").execute();
 			return rows.map((row) => ({
 				name: row.name,

package/src/plugins/state.ts

@@ -298,14 +298,11 @@ export class PluginStateRepository {
 }
 
 /**
- * Internal: map a `_plugin_state` row to the public `PluginState` shape.
- *
- * Kept at module scope so the three select paths (`get`, `getAll`,
- * `getMarketplacePlugins`, `getRegistryPlugins`) stay byte-identical in
- * their handling of nullable columns -- adding a new column to the table
- * means changing this function and nothing else.
+ * Map a `_plugin_state` row to the public `PluginState` shape. Every read
+ * path uses this, so adding a column to the table means changing this
+ * function and nothing else.
  */
-interface PluginStateRow {
+export interface PluginStateRow {
 	plugin_id: string;
 	status: string;
 	version: string;
@@ -322,7 +319,7 @@ interface PluginStateRow {
 	mcp_tools_consent: string | null;
 }
 
-function rowToPluginState(row: PluginStateRow): PluginState {
+export function rowToPluginState(row: PluginStateRow): PluginState {
 	return {
 		pluginId: row.plugin_id,
 		status: toPluginStatus(row.status),

package/src/plugins/storage-indexes.ts

@@ -135,19 +135,23 @@ export async function createStorageIndexes(
 			});
 			await createSql.execute(db);
 
-			// Track in _plugin_indexes table
+			// Track in _plugin_indexes table. Only rewrite the row when the stored
+			// fields differ from the declared ones so repeated identical syncs do
+			// not perform needless writes (see issue #4228).
+			const fieldsJson = JSON.stringify(fields);
 			await db
 				.insertInto("_plugin_indexes")
 				.values({
 					plugin_id: pluginId,
 					collection,
 					index_name: indexName,
-					fields: JSON.stringify(fields),
+					fields: fieldsJson,
 				})
 				.onConflict((oc) =>
 					oc
 						.columns(["plugin_id", "collection", "index_name"])
-						.doUpdateSet({ fields: JSON.stringify(fields) }),
+						.doUpdateSet({ fields: fieldsJson })
+						.whereRef("_plugin_indexes.fields", "!=", "excluded.fields"),
 				)
 				.execute();