emdash 1.2.0 → 1.3.1

package/src/database/repositories/menu.ts

@@ -16,6 +16,7 @@
 import type { Kysely, Selectable } from "kysely";
 import { ulid } from "ulidx";
 
+import { localeMatches, localeOrder } from "../../i18n/query.js";
 import { invalidateMenuObjectCache } from "../../object-cache/index.js";
 import { withTransaction } from "../transaction.js";
 import type { Database, MenuItemTable, MenuTable } from "../types.js";
@@ -34,6 +35,59 @@ export class MenuGoneError extends Error {
 	}
 }
 
+export class MenuItemParentError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "MenuItemParentError";
+	}
+}
+
+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 +279,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 +304,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 +353,7 @@ export class MenuRepository {
 			.selectFrom("_emdash_menus")
 			.select("id")
 			.where("name", "=", name)
-			.where("locale", "=", locale)
+			.where(localeMatches("locale", locale))
 			.executeTakeFirst();
 		return row !== undefined;
 	}
@@ -460,6 +518,10 @@ 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
@@ -472,7 +534,6 @@ export class MenuRepository {
 			sortOrder = ((maxOrder?.max as number) ?? -1) + 1;
 		}
 
-		const id = ulid();
 		await this.db
 			.insertInto("_emdash_menu_items")
 			.values({
@@ -520,6 +581,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;
@@ -634,8 +698,8 @@ export class MenuRepository {
 	 * malicious payload cannot move foreign items into this menu's siblings.
 	 */
 	async reorderItems(menuId: string, items: ReorderItem[]): Promise<MenuItem[]> {
-		invalidateMenuObjectCache();
-		return withTransaction(this.db, async (trx) => {
+		const updated = await withTransaction(this.db, async (trx) => {
+			await validateItemParents(trx, menuId, items);
 			for (const item of items) {
 				await trx
 					.updateTable("_emdash_menu_items")
@@ -653,5 +717,7 @@ export class MenuRepository {
 				.execute();
 			return rows.map(rowToMenuItem);
 		});
+		invalidateMenuObjectCache();
+		return updated;
 	}
 }

package/src/database/repositories/plugin-storage.ts

@@ -37,10 +37,16 @@ import type {
 	ConditionalDeleteResult,
 } from "../../plugins/types.js";
 import { chunks, SQL_BATCH_SIZE } from "../../utils/chunks.js";
-import { pluginDataWriteExpr, pluginDataUpdateGuard } from "../dialect-helpers.js";
+import { isPostgres, pluginDataWriteExpr, pluginDataUpdateGuard } from "../dialect-helpers.js";
 import { withTransaction } from "../transaction.js";
 import type { Database } from "../types.js";
-import { encodeCursor, decodeCursor } from "./types.js";
+import {
+	encodeCursor,
+	decodeCursor,
+	InvalidCursorError,
+	MAX_CURSOR_LENGTH,
+	type SortFieldBoundary,
+} from "./types.js";
 
 /**
  * SQLSTATEs a losing concurrent `updateIf` writer can abort with.
@@ -114,6 +120,54 @@ function nullRank(expr: RawBuilder<unknown>): RawBuilder<number> {
 	return sql`(case when ${expr} is null then 1 else 0 end)`;
 }
 
+/**
+ * Comparison value for an orderBy cursor, matching the type of the ordered
+ * JSON expression.
+ *
+ * On Postgres the order expression is jsonb, so non-missing cursor values are
+ * cast to jsonb. This is important for explicit JSON `null`: the bound value
+ * must be the jsonb `null` scalar, not SQL NULL, because Postgres
+ * `data::jsonb->'field'` returns jsonb `null` for an explicit null and SQL NULL
+ * for a missing key. SQLite extracts SQL NULL for both cases, so a missing
+ * boundary and an explicit null both bind SQL NULL.
+ */
+function cursorFieldValue(db: Kysely<Database>, boundary: SortFieldBoundary): RawBuilder<unknown> {
+	if (boundary.missing) {
+		return sql`null`;
+	}
+	if (isPostgres(db)) {
+		return sql`${sql.val(JSON.stringify(boundary.value))}::jsonb`;
+	}
+	return sql.val(boundary.value);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function sortBoundaries(data: unknown, orderFields: string[]): SortFieldBoundary[] {
+	const record = isRecord(data) ? data : undefined;
+	return orderFields.map((field) => {
+		if (record !== undefined && Object.hasOwn(record, field)) {
+			return { value: record[field], missing: false };
+		}
+		return { missing: true };
+	});
+}
+
+function isScalarSortBoundary(boundary: SortFieldBoundary): boolean {
+	if (boundary.missing) {
+		return true;
+	}
+	const value = boundary.value;
+	return (
+		value === null ||
+		typeof value === "string" ||
+		typeof value === "number" ||
+		typeof value === "boolean"
+	);
+}
+
 export class PluginStorageRepository<T = unknown> implements StorageCollection<T> {
 	private indexedFields: Set<string>;
 
@@ -403,15 +457,43 @@ export class PluginStorageRepository<T = unknown> implements StorageCollection<T
 					);
 				}
 				const op = descending ? sql`<` : sql`>`;
-				// The cursor row's sort values, recomputed with the same expression
-				// rather than carried in the cursor, so nothing is bound as a literal
-				// and neither dialect has to coerce a JSON value to compare it.
+				const cursorSortValues = decoded.sortValues;
+
+				// New cursors carry the ordered field values so paging survives deletion
+				// of the anchor row. Legacy cursors fall back to re-reading the anchor;
+				// if it has been deleted we can no longer compute the seek boundary, so
+				// we surface a clear error instead of returning a wrong page.
+				//
+				// SQLite's json_extract returns scalar values, so cursors that encode
+				// objects or arrays cannot be bound as query parameters there. On any
+				// dialect we also skip cursor-bound values when they would make the
+				// cursor exceed the length cap, and fall back to the anchor lookup.
+				const useCursorValues =
+					cursorSortValues !== undefined &&
+					cursorSortValues.length === orderEntries.length &&
+					(isPostgres(this.db) || cursorSortValues.every(isScalarSortBoundary));
+
 				const cursorExpr = (field: string): RawBuilder<unknown> =>
 					sql`(select ${sql.raw(jsonOrderExtract(this.db, field))} from _plugin_storage where plugin_id = ${this.pluginId} and collection = ${this.collection} and id = ${decoded.id})`;
 
-				const fields = orderEntries.map(([field]) => {
+				if (!useCursorValues) {
+					const anchorExists = await this.db
+						.selectFrom("_plugin_storage")
+						.select(sql`1`.as("one"))
+						.where("plugin_id", "=", this.pluginId)
+						.where("collection", "=", this.collection)
+						.where("id", "=", decoded.id)
+						.executeTakeFirst();
+					if (!anchorExists) {
+						throw new InvalidCursorError(cursor);
+					}
+				}
+
+				const fields = orderEntries.map(([field], index) => {
 					const own = sortExpr(field);
-					const theirs = cursorExpr(field);
+					const theirs = useCursorValues
+						? cursorFieldValue(this.db, cursorSortValues[index])
+						: cursorExpr(field);
 					return {
 						equal: sql`(${nullRank(own)} = ${nullRank(theirs)} and (${nullRank(own)} = 1 or ${own} = ${theirs}))`,
 						after: sql`(${nullRank(own)} ${op} ${nullRank(theirs)} or (${nullRank(own)} = ${nullRank(theirs)} and ${nullRank(own)} = 0 and ${own} ${op} ${theirs}))`,
@@ -466,7 +548,26 @@ export class PluginStorageRepository<T = unknown> implements StorageCollection<T
 		if (hasMore) {
 			const lastItem = rows[limit - 1];
 			if (lastItem) {
-				nextCursor = encodeCursor(lastItem.created_at, lastItem.id);
+				let sortValues: SortFieldBoundary[] | undefined;
+				if (orderEntries.length > 0) {
+					const parsed: unknown = JSON.parse(lastItem.data);
+					const candidate = sortBoundaries(
+						parsed,
+						orderEntries.map(([field]) => field),
+					);
+					// Only encode scalar boundaries. Non-scalar values cannot be bound
+					// on SQLite, and large values can blow past the cursor length cap.
+					// In both cases we fall back to the legacy anchor-row lookup.
+					if (candidate.every(isScalarSortBoundary)) {
+						sortValues = candidate;
+					}
+				}
+				nextCursor = encodeCursor(lastItem.created_at, lastItem.id, sortValues);
+				// If the scalar values still produced an oversized cursor, drop them
+				// and rely on the anchor row instead.
+				if (nextCursor.length > MAX_CURSOR_LENGTH) {
+					nextCursor = encodeCursor(lastItem.created_at, lastItem.id, undefined);
+				}
 			}
 		}
 

package/src/database/repositories/revision.ts

@@ -20,6 +20,17 @@ export interface Revision {
 	createdAt: string;
 }
 
+export interface RevisionAuthor {
+	id: string;
+	/** `null` when the account has no display name. */
+	name: string | null;
+}
+
+export interface RevisionWithAuthor extends Revision {
+	/** `null` when no author was recorded or the account no longer exists. */
+	author: RevisionAuthor | null;
+}
+
 export interface CreateRevisionInput {
 	collection: string;
 	entryId: string;
@@ -136,13 +147,15 @@ export class RevisionRepository {
 		collection: string,
 		entryId: string,
 		options: { limit?: number } = {},
-	): Promise<Revision[]> {
+	): Promise<RevisionWithAuthor[]> {
 		let query = this.db
 			.selectFrom("revisions")
-			.selectAll()
-			.where("collection", "=", collection)
-			.where("entry_id", "=", entryId)
-			.orderBy("id", "desc");
+			.leftJoin("users", "users.id", "revisions.author_id")
+			.selectAll("revisions")
+			.select(["users.id as author_user_id", "users.name as author_name"])
+			.where("revisions.collection", "=", collection)
+			.where("revisions.entry_id", "=", entryId)
+			.orderBy("revisions.id", "desc");
 
 		if (options.limit) {
 			query = query.limit(options.limit);
@@ -156,7 +169,12 @@ export class RevisionRepository {
 		return rows.map((row, index) => {
 			const normalized = data[index];
 			if (!normalized) throw new Error("Failed to normalize revision data");
-			return this.rowToRevision(row, normalized);
+			return {
+				...this.rowToRevision(row, normalized),
+				author: row.author_user_id
+					? { id: row.author_user_id, name: row.author_name?.trim() || null }
+					: null,
+			};
 		});
 	}
 

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

@@ -10,7 +10,7 @@ import { encodeBase64, decodeBase64 } from "../../utils/base64.js";
  * REST schemas also clamp at 2048 — this 4096 cap is a defense-in-depth
  * floor inside the repository helpers.
  */
-const MAX_CURSOR_LENGTH = 4096;
+export const MAX_CURSOR_LENGTH = 4096;
 
 export interface CreateContentInput {
 	/** Explicit content ID for stable seed imports. Omit to generate a ULID. */
@@ -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 */
@@ -250,9 +254,33 @@ export interface FindManyResult<T> {
  */
 export const STAGED_CURSOR_MARKER = "staged";
 
-/** Encode a cursor from order value + id */
-export function encodeCursor(orderValue: string, id: string): string {
-	return encodeBase64(JSON.stringify({ orderValue, id }));
+/**
+ * Boundary for a single ordered field inside a cursor.
+ *
+ * `missing` distinguishes "the document has no value for this field" from
+ * "the document stores JSON `null`". SQLite can only tell these apart at the
+ * SQL layer, but PostgreSQL orders `data::jsonb->'field'` differently for the
+ * two cases, so the seek boundary must carry both possibilities.
+ */
+export interface SortFieldBoundary {
+	value?: unknown;
+	missing?: boolean;
+}
+
+/** Encode a cursor from order value + id, optionally carrying the ordered field values. */
+export function encodeCursor(
+	orderValue: string,
+	id: string,
+	sortValues?: SortFieldBoundary[],
+): string {
+	const payload: { orderValue: string; id: string; sortValues?: SortFieldBoundary[] } = {
+		orderValue,
+		id,
+	};
+	if (sortValues !== undefined && sortValues.length > 0) {
+		payload.sortValues = sortValues;
+	}
+	return encodeBase64(JSON.stringify(payload));
 }
 
 /**
@@ -271,13 +299,36 @@ export class InvalidCursorError extends Error {
 	}
 }
 
+function isSortFieldBoundary(item: unknown): item is SortFieldBoundary {
+	if (item === null || typeof item !== "object") {
+		return false;
+	}
+	const candidate = item as { value?: unknown; missing?: unknown };
+	if (candidate.missing !== undefined && typeof candidate.missing !== "boolean") {
+		return false;
+	}
+	return true;
+}
+
+function normalizeSortBoundary(item: unknown): SortFieldBoundary {
+	if (isSortFieldBoundary(item)) {
+		return { value: item.value, missing: item.missing };
+	}
+	// Fall back for plain values that predate the structured boundary format.
+	return { value: item, missing: false };
+}
+
 /**
  * Decode a cursor to order value + id.
  *
  * Throws `InvalidCursorError` if the cursor is empty, not valid base64,
  * not valid JSON, or doesn't contain string `orderValue` and `id` fields.
  */
-export function decodeCursor(cursor: string): { orderValue: string; id: string } {
+export function decodeCursor(cursor: string): {
+	orderValue: string;
+	id: string;
+	sortValues?: SortFieldBoundary[];
+} {
 	if (!cursor) throw new InvalidCursorError(cursor);
 	if (cursor.length > MAX_CURSOR_LENGTH) throw new InvalidCursorError(cursor);
 	let parsed: unknown;
@@ -289,11 +340,22 @@ export function decodeCursor(cursor: string): { orderValue: string; id: string }
 	if (parsed === null || typeof parsed !== "object") {
 		throw new InvalidCursorError(cursor);
 	}
-	const candidate = parsed as { orderValue?: unknown; id?: unknown };
+	const candidate = parsed as { orderValue?: unknown; id?: unknown; sortValues?: unknown };
 	if (typeof candidate.orderValue !== "string" || typeof candidate.id !== "string") {
 		throw new InvalidCursorError(cursor);
 	}
-	return { orderValue: candidate.orderValue, id: candidate.id };
+	let sortValues: SortFieldBoundary[] | undefined;
+	if (candidate.sortValues !== undefined) {
+		if (!Array.isArray(candidate.sortValues)) {
+			throw new InvalidCursorError(cursor);
+		}
+		sortValues = candidate.sortValues.map(normalizeSortBoundary);
+	}
+	return {
+		orderValue: candidate.orderValue,
+		id: candidate.id,
+		sortValues,
+	};
 }
 
 export interface ContentItem {
@@ -392,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";
+	}
+}