emdash 1.3.0 → 1.4.0

package/src/database/repositories/menu.ts

@@ -13,16 +13,23 @@
  * single menu item survives content translations.
  */
 
-import type { Kysely, Selectable } from "kysely";
+import type { Compilable, Insertable, Kysely, Selectable } from "kysely";
 import { ulid } from "ulidx";
 
+import { localeMatches, localeOrder } from "../../i18n/query.js";
 import { invalidateMenuObjectCache } from "../../object-cache/index.js";
+import { SQL_BATCH_SIZE, chunks } from "../../utils/chunks.js";
+import {
+	executeAtomicBatchIfSupported,
+	isPostgres,
+	supportsAtomicBatch,
+} from "../dialect-helpers.js";
 import { withTransaction } from "../transaction.js";
 import type { Database, MenuItemTable, MenuTable } from "../types.js";
 
 /**
- * Thrown from inside a repository transaction when the menu the caller
- * resolved earlier has since been deleted. Handlers translate this to a
+ * Thrown by a repository write when the menu the caller resolved earlier has
+ * since been deleted. Handlers translate this to a
  * `NOT_FOUND` API response. Necessary because D1 disables FK enforcement
  * (so `ON DELETE CASCADE` won't fire), and an unchecked `setItems` would
  * happily insert items whose `menu_id` no longer exists, leaving orphans.
@@ -34,6 +41,103 @@ export class MenuGoneError extends Error {
 	}
 }
 
+export class MenuItemParentError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "MenuItemParentError";
+	}
+}
+
+interface MenuWriteStatement extends Compilable {
+	execute(): Promise<unknown>;
+}
+
+/**
+ * Run the statements as one atomic batch where the adapter supports it (D1),
+ * otherwise inside a transaction. D1 has no interactive transactions, so a
+ * `withTransaction` there would commit each statement on its own. `check`
+ * runs inside the transaction, or just before the batch on D1, where a read
+ * can't be part of it.
+ */
+async function executeMenuWrite(
+	db: Kysely<Database>,
+	buildStatements: (target: Kysely<Database>) => readonly MenuWriteStatement[],
+	check?: (target: Kysely<Database>) => Promise<void>,
+): Promise<void> {
+	if (supportsAtomicBatch(db)) {
+		await check?.(db);
+		const statements = buildStatements(db);
+		if (statements.length > 0) await executeAtomicBatchIfSupported(db, statements);
+		return;
+	}
+	await withTransaction(db, async (trx) => {
+		await check?.(trx);
+		for (const statement of buildStatements(trx)) {
+			await statement.execute();
+		}
+	});
+}
+
+function insertItemRows(target: Kysely<Database>, rows: Insertable<MenuItemTable>[]) {
+	const first = rows[0];
+	if (!first) return [];
+	// Postgres still has the `parent_id` foreign key and checks it after each
+	// statement, and a copied child can come before its parent, so it gets a
+	// single insert. SQLite has no such key, and the chunks keep each insert
+	// within D1's bound-parameter limit.
+	if (isPostgres(target)) return [target.insertInto("_emdash_menu_items").values(rows)];
+	const rowsPerInsert = Math.max(1, Math.floor(SQL_BATCH_SIZE / Object.keys(first).length));
+	return chunks(rows, rowsPerInsert).map((chunk) =>
+		target.insertInto("_emdash_menu_items").values(chunk),
+	);
+}
+
+async function validateItemParents(
+	db: Kysely<Database>,
+	menuId: string,
+	changes: ReadonlyArray<{ id: string; parentId: string | null }>,
+	newItemId?: string,
+): Promise<void> {
+	const rows = await db
+		.selectFrom("_emdash_menu_items")
+		.select(["id", "parent_id"])
+		.where("menu_id", "=", menuId)
+		.execute();
+	const parents = new Map(rows.map((row) => [row.id, row.parent_id]));
+	if (newItemId !== undefined) parents.set(newItemId, null);
+
+	const originalParents = new Map(parents);
+	const scopedChanges = changes.filter((change) => parents.has(change.id));
+	// Overlay the whole batch before walking: a valid reorder may temporarily
+	// form a cycle if its entries are considered one at a time.
+	for (const change of scopedChanges) {
+		parents.set(change.id, change.parentId);
+	}
+
+	const validated = new Set<string>();
+	const changedIds = new Set(scopedChanges.map((change) => change.id));
+	for (const id of changedIds) {
+		const parentId = parents.get(id) ?? null;
+		if (id !== newItemId && parentId === originalParents.get(id)) continue;
+		if (parentId !== null && !parents.has(parentId)) {
+			throw new MenuItemParentError("Parent item must exist in the same menu");
+		}
+		const path = new Set<string>();
+		let cursor: string | null = id;
+		while (cursor !== null && !validated.has(cursor)) {
+			if (path.has(cursor)) {
+				throw new MenuItemParentError("A menu item cannot be its own ancestor");
+			}
+			// Deleted ancestors render as roots; unchanged legacy links must not
+			// prevent editing or reordering the remaining menu items.
+			if (!parents.has(cursor)) break;
+			path.add(cursor);
+			cursor = parents.get(cursor) ?? null;
+		}
+		for (const ancestorId of path) validated.add(ancestorId);
+	}
+}
+
 // ---------------------------------------------------------------------------
 // Entity shapes (camelCase — what the API returns)
 // ---------------------------------------------------------------------------
@@ -225,7 +329,8 @@ export class MenuRepository {
 				"m.translation_group",
 			])
 			.orderBy("m.name", "asc");
-		if (options.locale !== undefined) query = query.where("m.locale", "=", options.locale);
+		if (options.locale !== undefined)
+			query = query.where(localeMatches("m.locale", options.locale));
 		const rows = await query.execute();
 
 		return rows.map((row) => ({
@@ -249,12 +354,15 @@ export class MenuRepository {
 	 * is supplied) and to detect AMBIGUOUS_LOCALE situations (`length > 1`).
 	 */
 	async findByName(name: string, options: { locale?: string } = {}): Promise<Menu[]> {
-		let query = this.db
-			.selectFrom("_emdash_menus")
-			.selectAll()
-			.where("name", "=", name)
-			.orderBy("locale", "asc");
-		if (options.locale !== undefined) query = query.where("locale", "=", options.locale);
+		let query = this.db.selectFrom("_emdash_menus").selectAll().where("name", "=", name);
+		if (options.locale !== undefined) {
+			query = query
+				.where(localeMatches("locale", options.locale))
+				.orderBy(localeOrder("locale", options.locale), "asc")
+				.orderBy("id", "asc");
+		} else {
+			query = query.orderBy("locale", "asc");
+		}
 		const rows = await query.execute();
 		return rows.map(rowToMenu);
 	}
@@ -295,7 +403,7 @@ export class MenuRepository {
 			.selectFrom("_emdash_menus")
 			.select("id")
 			.where("name", "=", name)
-			.where("locale", "=", locale)
+			.where(localeMatches("locale", locale))
 			.executeTakeFirst();
 		return row !== undefined;
 	}
@@ -313,62 +421,49 @@ export class MenuRepository {
 		const id = ulid();
 
 		let translationGroup: string = id;
-		let sourceMenuId: string | null = null;
+		let sourceItems: Selectable<MenuItemTable>[] = [];
 		if (input.translationOf) {
 			const source = await this.findById(input.translationOf);
 			if (!source) throw new Error("Source menu for translation not found");
 			translationGroup = source.translationGroup ?? source.id;
-			sourceMenuId = source.id;
+			sourceItems = await this.db
+				.selectFrom("_emdash_menu_items")
+				.selectAll()
+				.where("menu_id", "=", source.id)
+				.orderBy("sort_order", "asc")
+				.execute();
 		}
 
-		await withTransaction(this.db, async (trx) => {
-			await trx
-				.insertInto("_emdash_menus")
-				.values({
-					id,
-					name: input.name,
-					label: input.label,
-					...(input.locale !== undefined ? { locale: input.locale } : {}),
-					translation_group: translationGroup,
-				})
-				.execute();
+		// old-id → new-id map so parent pointers land on the clones.
+		const idMap = new Map<string, string>();
+		for (const item of sourceItems) idMap.set(item.id, ulid());
+		const itemRows: Insertable<MenuItemTable>[] = sourceItems.map((item) => ({
+			id: idMap.get(item.id)!,
+			menu_id: id,
+			parent_id: item.parent_id ? (idMap.get(item.parent_id) ?? null) : null,
+			sort_order: item.sort_order,
+			type: item.type,
+			reference_collection: item.reference_collection,
+			reference_id: item.reference_id,
+			custom_url: item.custom_url,
+			label: item.label,
+			title_attr: item.title_attr,
+			target: item.target,
+			css_classes: item.css_classes,
+			...(input.locale !== undefined ? { locale: input.locale } : {}),
+			translation_group: item.translation_group ?? item.id,
+		}));
 
-			if (sourceMenuId) {
-				const sourceItems = await trx
-					.selectFrom("_emdash_menu_items")
-					.selectAll()
-					.where("menu_id", "=", sourceMenuId)
-					.orderBy("sort_order", "asc")
-					.execute();
-				if (sourceItems.length > 0) {
-					// old-id → new-id map so parent pointers land on the clones.
-					const idMap = new Map<string, string>();
-					for (const item of sourceItems) idMap.set(item.id, ulid());
-
-					await trx
-						.insertInto("_emdash_menu_items")
-						.values(
-							sourceItems.map((item) => ({
-								id: idMap.get(item.id)!,
-								menu_id: id,
-								parent_id: item.parent_id ? (idMap.get(item.parent_id) ?? null) : null,
-								sort_order: item.sort_order,
-								type: item.type,
-								reference_collection: item.reference_collection,
-								reference_id: item.reference_id,
-								custom_url: item.custom_url,
-								label: item.label,
-								title_attr: item.title_attr,
-								target: item.target,
-								css_classes: item.css_classes,
-								...(input.locale !== undefined ? { locale: input.locale } : {}),
-								translation_group: item.translation_group ?? item.id,
-							})),
-						)
-						.execute();
-				}
-			}
-		});
+		await executeMenuWrite(this.db, (target) => [
+			target.insertInto("_emdash_menus").values({
+				id,
+				name: input.name,
+				label: input.label,
+				...(input.locale !== undefined ? { locale: input.locale } : {}),
+				translation_group: translationGroup,
+			}),
+			...insertItemRows(target, itemRows),
+		]);
 
 		invalidateMenuObjectCache();
 
@@ -404,10 +499,10 @@ export class MenuRepository {
 		const existing = await this.findById(id);
 		if (!existing) return false;
 
-		await withTransaction(this.db, async (trx) => {
-			await trx.deleteFrom("_emdash_menu_items").where("menu_id", "=", id).execute();
-			await trx.deleteFrom("_emdash_menus").where("id", "=", id).execute();
-		});
+		await executeMenuWrite(this.db, (target) => [
+			target.deleteFrom("_emdash_menu_items").where("menu_id", "=", id),
+			target.deleteFrom("_emdash_menus").where("id", "=", id),
+		]);
 		invalidateMenuObjectCache();
 		return true;
 	}
@@ -460,19 +555,25 @@ export class MenuRepository {
 	 * item's own id, matching the migration 036 backfill.
 	 */
 	async createItem(menuId: string, locale: string, input: CreateMenuItemInput): Promise<MenuItem> {
+		const id = ulid();
+		if (input.parentId !== undefined) {
+			await validateItemParents(this.db, menuId, [{ id, parentId: input.parentId }], id);
+		}
 		let sortOrder = input.sortOrder ?? 0;
 		if (input.sortOrder === undefined) {
-			const maxOrder = await this.db
+			const query = this.db
 				.selectFrom("_emdash_menu_items")
 				.select(({ fn }) => fn.max("sort_order").as("max"))
-				.where("menu_id", "=", menuId)
-				.where("parent_id", "is", input.parentId ?? null)
-				.executeTakeFirst();
+				.where("menu_id", "=", menuId);
+			const maxOrder = await (
+				input.parentId == null
+					? query.where("parent_id", "is", null)
+					: query.where("parent_id", "=", input.parentId)
+			).executeTakeFirst();
 			// eslint-disable-next-line typescript/no-unsafe-type-assertion -- Kysely fn.max returns unknown; always a number for sort_order column
 			sortOrder = ((maxOrder?.max as number) ?? -1) + 1;
 		}
 
-		const id = ulid();
 		await this.db
 			.insertInto("_emdash_menu_items")
 			.values({
@@ -520,6 +621,9 @@ export class MenuRepository {
 			.where("menu_id", "=", menuId)
 			.executeTakeFirst();
 		if (!existing) return null;
+		if (input.parentId !== undefined) {
+			await validateItemParents(this.db, menuId, [{ id: itemId, parentId: input.parentId }]);
+		}
 
 		const values: Record<string, unknown> = {};
 		if (input.label !== undefined) values.label = input.label;
@@ -571,59 +675,57 @@ export class MenuRepository {
 		locale: string,
 		items: SetMenuItem[],
 	): Promise<{ itemCount: number }> {
-		await withTransaction(this.db, async (trx) => {
-			// Re-check menu existence INSIDE the transaction. The handler
-			// resolved by (name, locale) before this call; if a concurrent
-			// menu_delete landed in between, inserting new items would
-			// silently orphan them. The FK from migration 005 was removed
-			// by migration 036 (#1021) and not restored, so nothing at the
-			// schema level stops the orphans. Throw a MenuGoneError so the
-			// rollback fires and the handler returns NOT_FOUND with the
-			// original menu name in the message.
-			const stillThere = await trx
-				.selectFrom("_emdash_menus")
-				.select("id")
-				.where("id", "=", menuId)
-				.executeTakeFirst();
-			if (!stillThere) throw new MenuGoneError(menuId);
-
-			await trx.deleteFrom("_emdash_menu_items").where("menu_id", "=", menuId).execute();
-
-			const insertedIds: string[] = [];
-			for (let i = 0; i < items.length; i++) {
-				const item = items[i];
-				if (!item) continue;
-				const id = ulid();
-				const parentId =
-					item.parentIndex !== undefined ? (insertedIds[item.parentIndex] ?? null) : null;
-				await trx
-					.insertInto("_emdash_menu_items")
-					.values({
-						id,
-						translation_group: id,
-						menu_id: menuId,
-						parent_id: parentId,
-						sort_order: i,
-						type: item.type,
-						reference_collection: item.referenceCollection ?? null,
-						reference_id: item.referenceId ?? null,
-						custom_url: item.customUrl ?? null,
-						label: item.label,
-						title_attr: item.titleAttr ?? null,
-						target: item.target ?? null,
-						css_classes: item.cssClasses ?? null,
-						locale,
-					})
-					.execute();
-				insertedIds.push(id);
-			}
+		const insertedIds: string[] = [];
+		const itemRows: Insertable<MenuItemTable>[] = [];
+		for (let i = 0; i < items.length; i++) {
+			const item = items[i];
+			if (!item) continue;
+			const id = ulid();
+			const parentId =
+				item.parentIndex !== undefined ? (insertedIds[item.parentIndex] ?? null) : null;
+			itemRows.push({
+				id,
+				translation_group: id,
+				menu_id: menuId,
+				parent_id: parentId,
+				sort_order: i,
+				type: item.type,
+				reference_collection: item.referenceCollection ?? null,
+				reference_id: item.referenceId ?? null,
+				custom_url: item.customUrl ?? null,
+				label: item.label,
+				title_attr: item.titleAttr ?? null,
+				target: item.target ?? null,
+				css_classes: item.cssClasses ?? null,
+				locale,
+			});
+			insertedIds.push(id);
+		}
 
-			await trx
-				.updateTable("_emdash_menus")
-				.set({ updated_at: new Date().toISOString() })
-				.where("id", "=", menuId)
-				.execute();
-		});
+		await executeMenuWrite(
+			this.db,
+			(target) => [
+				target.deleteFrom("_emdash_menu_items").where("menu_id", "=", menuId),
+				...insertItemRows(target, itemRows),
+				target
+					.updateTable("_emdash_menus")
+					.set({ updated_at: new Date().toISOString() })
+					.where("id", "=", menuId),
+			],
+			// The handler resolved the menu before this call; if a concurrent
+			// menu_delete landed in between, inserting new items would
+			// silently orphan them. On SQLite the FK from migration 005 was
+			// removed by migration 036 and not restored, so nothing at the
+			// schema level stops the orphans.
+			async (target) => {
+				const stillThere = await target
+					.selectFrom("_emdash_menus")
+					.select("id")
+					.where("id", "=", menuId)
+					.executeTakeFirst();
+				if (!stillThere) throw new MenuGoneError(menuId);
+			},
+		);
 
 		invalidateMenuObjectCache();
 		return { itemCount: items.length };
@@ -634,24 +736,19 @@ export class MenuRepository {
 	 * malicious payload cannot move foreign items into this menu's siblings.
 	 */
 	async reorderItems(menuId: string, items: ReorderItem[]): Promise<MenuItem[]> {
+		await executeMenuWrite(
+			this.db,
+			(target) =>
+				items.map((item) =>
+					target
+						.updateTable("_emdash_menu_items")
+						.set({ parent_id: item.parentId, sort_order: item.sortOrder })
+						.where("id", "=", item.id)
+						.where("menu_id", "=", menuId),
+				),
+			(target) => validateItemParents(target, menuId, items),
+		);
 		invalidateMenuObjectCache();
-		return withTransaction(this.db, async (trx) => {
-			for (const item of items) {
-				await trx
-					.updateTable("_emdash_menu_items")
-					.set({ parent_id: item.parentId, sort_order: item.sortOrder })
-					.where("id", "=", item.id)
-					.where("menu_id", "=", menuId)
-					.execute();
-			}
-
-			const rows = await trx
-				.selectFrom("_emdash_menu_items")
-				.selectAll()
-				.where("menu_id", "=", menuId)
-				.orderBy("sort_order", "asc")
-				.execute();
-			return rows.map(rowToMenuItem);
-		});
+		return this.findItems(menuId);
 	}
 }

package/src/database/repositories/taxonomy-def.ts

@@ -1,5 +1,6 @@
 import { sql, type Kysely } from "kysely";
 
+import { localeMatches, localeOrder } from "../../i18n/query.js";
 import type { Database } from "../types.js";
 
 /**
@@ -20,8 +21,8 @@ export interface TaxonomyStructure {
  * A row that has no group yet, because code without the group table wrote it
  * during a rolling deploy, reads its own copy.
  */
-export function selectTaxonomyDefs(db: Kysely<Database>) {
-	return db
+export function selectTaxonomyDefs(db: Kysely<Database>, locale?: string) {
+	let query = db
 		.selectFrom("_emdash_taxonomy_defs as d")
 		.leftJoin("_emdash_taxonomy_def_groups as g", "g.name", "d.name")
 		.select([
@@ -35,6 +36,12 @@ export function selectTaxonomyDefs(db: Kysely<Database>) {
 			sql<number>`coalesce(g.hierarchical, d.hierarchical)`.as("hierarchical"),
 			sql<string | null>`coalesce(g.collections, d.collections)`.as("collections"),
 		]);
+	if (locale !== undefined) {
+		query = query
+			.where(localeMatches("d.locale", locale))
+			.orderBy(localeOrder("d.locale", locale), "asc");
+	}
+	return query;
 }
 
 /**

package/src/database/repositories/taxonomy.ts

@@ -1,6 +1,8 @@
 import { sql, type Kysely, type Selectable } from "kysely";
 import { ulid } from "ulidx";
 
+import { getLocaleCandidates, getLocaleChainRank, getLocaleRank } from "../../i18n/config.js";
+import { localeMatches, localeOrder } from "../../i18n/query.js";
 import { invalidateTaxonomyObjectCache } from "../../object-cache/index.js";
 import { chunks, SQL_BATCH_SIZE } from "../../utils/chunks.js";
 import { slugify } from "../../utils/slugify.js";
@@ -255,8 +257,11 @@ export class TaxonomyRepository {
 			.selectAll()
 			.where("name", "=", name)
 			.where("slug", "=", slug);
-		if (locale !== undefined) query = query.where("locale", "=", locale);
-		const row = await query.orderBy("locale", "asc").executeTakeFirst();
+		if (locale !== undefined) query = query.where(localeMatches("locale", locale));
+		const row = await query
+			.orderBy(locale !== undefined ? localeOrder("locale", locale) : "locale", "asc")
+			.orderBy("id", "asc")
+			.executeTakeFirst();
 		return row ? this.rowToTaxonomy(row) : null;
 	}
 
@@ -268,7 +273,7 @@ export class TaxonomyRepository {
 			.select("slug")
 			.where("name", "=", name)
 			.where((eb) => eb.or([eb("slug", "=", baseSlug), eb("slug", "like", `${baseSlug}-%`)]));
-		if (locale !== undefined) query = query.where("locale", "=", locale);
+		if (locale !== undefined) query = query.where(localeMatches("locale", locale));
 		const candidates = await query.execute();
 		if (!candidates.some((candidate) => candidate.slug === baseSlug)) return baseSlug;
 
@@ -300,7 +305,7 @@ export class TaxonomyRepository {
 			.orderBy("label", "asc")
 			.orderBy("id", "asc");
 
-		if (options.locale !== undefined) query = query.where("locale", "=", options.locale);
+		if (options.locale !== undefined) query = query.where(localeMatches("locale", options.locale));
 
 		if (options.parentId !== undefined) {
 			if (options.parentId === null) {
@@ -324,7 +329,7 @@ export class TaxonomyRepository {
 			.selectFrom("taxonomies")
 			.selectAll()
 			.where("name", "=", name)
-			.where("locale", "in", locales)
+			.where((eb) => eb.or(locales.map((candidate) => localeMatches("locale", candidate))))
 			.orderBy("sort_order", "asc")
 			.orderBy("label", "asc")
 			.orderBy("id", "asc")
@@ -335,7 +340,13 @@ export class TaxonomyRepository {
 			const term = this.rowToTaxonomy(row);
 			const group = term.translationGroup ?? term.id;
 			const current = selected.get(group);
-			if (!current || term.locale === locale) selected.set(group, term);
+			if (
+				!current ||
+				getLocaleChainRank(term.locale, [locale, defaultLocale]) <
+					getLocaleChainRank(current.locale, [locale, defaultLocale])
+			) {
+				selected.set(group, term);
+			}
 		}
 		return [...selected.values()].toSorted(
 			(a, b) =>
@@ -347,7 +358,7 @@ export class TaxonomyRepository {
 		const limit = Math.max(1, Math.min(options.limit ?? 50, 100));
 		let query = this.db.selectFrom("taxonomies").selectAll().where("name", "=", name);
 
-		if (options.locale !== undefined) query = query.where("locale", "=", options.locale);
+		if (options.locale !== undefined) query = query.where(localeMatches("locale", options.locale));
 
 		if (options.parentId !== undefined) {
 			query =
@@ -397,7 +408,7 @@ export class TaxonomyRepository {
 			.orderBy("sort_order", "asc")
 			.orderBy("label", "asc")
 			.orderBy("id", "asc");
-		if (locale !== undefined) query = query.where("locale", "=", locale);
+		if (locale !== undefined) query = query.where(localeMatches("locale", locale));
 
 		const rows = await query.execute();
 		return rows.map((row) => this.rowToTaxonomy(row));
@@ -742,10 +753,25 @@ export class TaxonomyRepository {
 			.where("content_taxonomies.entry_id", "=", entryGroup);
 
 		if (taxonomyName) query = query.where("taxonomies.name", "=", taxonomyName);
-		if (locale !== undefined) query = query.where("taxonomies.locale", "=", locale);
+		if (locale !== undefined) query = query.where(localeMatches("taxonomies.locale", locale));
 
 		const rows = await query.orderBy("taxonomies.locale", "asc").execute();
-		return rows.map((row) => this.rowToTaxonomy(row));
+		const terms = rows.map((row) => this.rowToTaxonomy(row));
+		if (locale === undefined) return terms;
+		const selected = new Map<string, Taxonomy>();
+		for (const term of terms) {
+			const group = term.translationGroup ?? term.id;
+			const current = selected.get(group);
+			if (
+				!current ||
+				getLocaleRank(term.locale, locale) < getLocaleRank(current.locale, locale) ||
+				(getLocaleRank(term.locale, locale) === getLocaleRank(current.locale, locale) &&
+					term.id < current.id)
+			) {
+				selected.set(group, term);
+			}
+		}
+		return [...selected.values()];
 	}
 
 	async getTermAssignmentsForEntry(
@@ -777,11 +803,18 @@ export class TaxonomyRepository {
 			byGroup.set(row.assignment_group, variants);
 		}
 
+		const chain = [locale, ...(defaultLocale !== locale ? [defaultLocale] : [])];
+		const chainLimit =
+			getLocaleChainRank(defaultLocale, chain) + getLocaleCandidates(defaultLocale).length;
 		return Array.from(byGroup, ([translationGroup, variants]) => {
-			const term =
-				variants.find((variant) => variant.locale === locale) ??
-				variants.find((variant) => variant.locale === defaultLocale) ??
-				null;
+			const candidates = variants
+				.filter((variant) => getLocaleChainRank(variant.locale, chain) < chainLimit)
+				.toSorted(
+					(a, b) =>
+						getLocaleChainRank(a.locale, chain) - getLocaleChainRank(b.locale, chain) ||
+						a.id.localeCompare(b.id),
+				);
+			const term = candidates[0] ?? null;
 			return {
 				translationGroup,
 				term,

package/src/database/repositories/types.ts

@@ -31,6 +31,8 @@ export interface CreateContentInput {
 }
 
 export interface UpdateContentInput {
+	/** Stored locale, supplied by the content handler for alias-aware slug checks. */
+	locale?: string;
 	data?: Record<string, unknown>;
 	status?: string;
 	slug?: string | null;
@@ -41,6 +43,8 @@ export interface UpdateContentInput {
 	/** Revision author, separate from entry ownership. */
 	revisionAuthorId?: string | null;
 	primaryBylineId?: string | null;
+	/** `null` drops the entry's draft revision pointer. */
+	draftRevisionId?: null;
 }
 
 /** SEO fields for content items */
@@ -191,9 +195,9 @@ export interface FindManyOptions {
 		q?: string;
 		/**
 		 * Columns the `q` substring filter is applied to (OR'd together).
-		 * Resolved by the handler from the collection's display fields, slug,
-		 * and any field marked searchable. Each name is validated as a SQL
-		 * identifier.
+		 * Resolved by the handler from the slug and the collection's display
+		 * fields and fields marked searchable, keeping only fields that have a
+		 * column. Each name is validated as a SQL identifier.
 		 */
 		searchColumns?: string[];
 		/**
@@ -450,3 +454,10 @@ export class ContentMutationConflictError extends Error {
 		this.name = "ContentMutationConflictError";
 	}
 }
+
+export class ContentSlugConflictError extends Error {
+	constructor() {
+		super("The slug is already used by another content entry");
+		this.name = "ContentSlugConflictError";
+	}
+}