emdash 1.1.0 → 1.3.0

package/src/database/repositories/content.ts

@@ -299,6 +299,16 @@ function getTableName(type: string): string {
 	return `ec_${type}`;
 }
 
+function assertPageOffset(offset: number | undefined, cursor: string | undefined): void {
+	if (offset === undefined) return;
+	if (cursor !== undefined) {
+		throw new EmDashValidationError("cursor and offset cannot be used together");
+	}
+	if (!Number.isSafeInteger(offset) || offset < 0) {
+		throw new EmDashValidationError("offset must be a non-negative integer");
+	}
+}
+
 /**
  * Serialize a value for database storage
  * Objects/arrays are JSON-stringified
@@ -837,6 +847,7 @@ export class ContentRepository {
 	): Promise<FindManyResult<ContentItem>> {
 		const tableName = getTableName(type);
 		const limit = Math.max(1, Math.min(options.limit || 50, 100));
+		assertPageOffset(options.offset, options.cursor);
 
 		// Determine ordering
 		const orderField = options.orderBy?.field || "createdAt";
@@ -951,7 +962,11 @@ export class ContentRepository {
 		if (indexedOrderFilter?.kind !== "null") {
 			query = query.orderBy(dbField as any, safeOrderDirection === "ASC" ? "asc" : "desc");
 		}
-		query = query.orderBy("id", safeOrderDirection === "ASC" ? "asc" : "desc").limit(limit + 1);
+		query = query.orderBy("id", safeOrderDirection === "ASC" ? "asc" : "desc");
+		query =
+			options.offset === undefined
+				? query.limit(limit + 1)
+				: query.limit(limit).offset(options.offset);
 
 		// Run the page fetch and the unbounded count together — the UI needs
 		// both to render a stable denominator (kept on every page intentionally),
@@ -1302,7 +1317,9 @@ export class ContentRepository {
 			let stored: Record<string, unknown> = existing.data ?? {};
 			if (existing.draftRevisionId) {
 				const draft = await revisionRepo.findById(existing.draftRevisionId);
-				if (draft?.data) stored = draft.data;
+				// A retired key may survive in the published row while the draft
+				// revision has already shed it, so the baseline has to cover both.
+				if (draft?.data) stored = { ...stored, ...draft.data };
 			}
 			const stale = staleStoredKeys(data, stored, fieldSlugs);
 			if (stale.length > 0) {
@@ -1694,6 +1711,7 @@ export class ContentRepository {
 	): Promise<FindManyResult<ContentItem & { deletedAt: string }>> {
 		const tableName = getTableName(type);
 		const limit = Math.max(1, Math.min(options.limit || 50, 100));
+		assertPageOffset(options.offset, options.cursor);
 
 		// Determine ordering - default to most recently deleted
 		const orderField = options.orderBy?.field || "deletedAt";
@@ -1734,8 +1752,11 @@ export class ContentRepository {
 
 		query = query
 			.orderBy(dbField as any, safeOrderDirection === "ASC" ? "asc" : "desc")
-			.orderBy("id", safeOrderDirection === "ASC" ? "asc" : "desc")
-			.limit(limit + 1);
+			.orderBy("id", safeOrderDirection === "ASC" ? "asc" : "desc");
+		query =
+			options.offset === undefined
+				? query.limit(limit + 1)
+				: query.limit(limit).offset(options.offset);
 
 		const rows = await query.execute();
 		const hasMore = rows.length > limit;

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

@@ -36,10 +36,17 @@ import type {
 	ConditionalWriteResult,
 	ConditionalDeleteResult,
 } from "../../plugins/types.js";
-import { pluginDataWriteExpr, pluginDataUpdateGuard } from "../dialect-helpers.js";
+import { chunks, SQL_BATCH_SIZE } from "../../utils/chunks.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.
@@ -113,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>;
 
@@ -271,18 +326,20 @@ export class PluginStorageRepository<T = unknown> implements StorageCollection<T
 	async getMany(ids: string[]): Promise<Map<string, T>> {
 		if (ids.length === 0) return new Map();
 
-		const rows = await this.db
-			.selectFrom("_plugin_storage")
-			.select(["id", "data"])
-			.where("plugin_id", "=", this.pluginId)
-			.where("collection", "=", this.collection)
-			.where("id", "in", ids)
-			.execute();
-
 		const result = new Map<string, T>();
-		for (const row of rows) {
-			// eslint-disable-next-line typescript/no-unsafe-type-assertion -- JSON.parse returns any; generic callers provide T
-			result.set(row.id, JSON.parse(row.data) as T);
+		for (const batch of chunks(ids, SQL_BATCH_SIZE)) {
+			const rows = await this.db
+				.selectFrom("_plugin_storage")
+				.select(["id", "data"])
+				.where("plugin_id", "=", this.pluginId)
+				.where("collection", "=", this.collection)
+				.where("id", "in", batch)
+				.execute();
+
+			for (const row of rows) {
+				// eslint-disable-next-line typescript/no-unsafe-type-assertion -- JSON.parse returns any; generic callers provide T
+				result.set(row.id, JSON.parse(row.data) as T);
+			}
 		}
 		return result;
 	}
@@ -330,14 +387,20 @@ export class PluginStorageRepository<T = unknown> implements StorageCollection<T
 	async deleteMany(ids: string[]): Promise<number> {
 		if (ids.length === 0) return 0;
 
-		const result = await this.db
-			.deleteFrom("_plugin_storage")
-			.where("plugin_id", "=", this.pluginId)
-			.where("collection", "=", this.collection)
-			.where("id", "in", ids)
-			.executeTakeFirst();
-
-		return Number(result.numDeletedRows ?? 0);
+		return withTransaction(this.db, async (trx) => {
+			let deleted = 0;
+			for (const batch of chunks(ids, SQL_BATCH_SIZE)) {
+				const result = await trx
+					.deleteFrom("_plugin_storage")
+					.where("plugin_id", "=", this.pluginId)
+					.where("collection", "=", this.collection)
+					.where("id", "in", batch)
+					.executeTakeFirst();
+
+				deleted += Number(result.numDeletedRows ?? 0);
+			}
+			return deleted;
+		});
 	}
 
 	/**
@@ -394,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}))`,
@@ -457,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/redirect.ts

@@ -474,7 +474,11 @@ export class RedirectRepository {
 	 */
 	async matchPath(path: string): Promise<RedirectMatch | null> {
 		// 1. Exact match (fast, indexed)
-		const exact = await this.findExactMatch(path);
+		let exact = await this.findExactMatch(path);
+		if (!exact && path.length > 1) {
+			const alt = path.endsWith("/") ? path.slice(0, -1) : `${path}/`;
+			exact = await this.findExactMatch(alt);
+		}
 		if (exact && isSiteRelativeDestination(exact.destination)) {
 			return { redirect: exact, resolvedDestination: exact.destination };
 		}
@@ -638,7 +642,7 @@ export class RedirectRepository {
 	 *
 	 * This is called from the public redirect middleware on every 404 and
 	 * must never throw for an unauthenticated caller — failures bubble up to
-	 * the middleware, which swallows them.
+	 * the middleware, which catches and logs them.
 	 */
 	async log404(entry: {
 		path: string;
@@ -688,6 +692,24 @@ export class RedirectRepository {
 	 * Called by scheduled system cleanup, never by the anonymous request path.
 	 */
 	async cleanup404Log(): Promise<number> {
+		// Cheap precheck: the expensive DELETE is only needed once the table
+		// has grown past MAX_404_LOG_ROWS. Counting a bounded sample avoids
+		// the full-table ORDER BY/NOT IN scan on the overwhelming majority
+		// of cron ticks when there is nothing to evict.
+		const probe = await this.db
+			.selectFrom(
+				this.db
+					.selectFrom("_emdash_404_log")
+					.select(sql`1`.as("one"))
+					.limit(MAX_404_LOG_ROWS + 1)
+					.as("sample"),
+			)
+			.select(({ fn }) => fn.countAll<number>().as("count"))
+			.executeTakeFirstOrThrow();
+		if (Number(probe.count) <= MAX_404_LOG_ROWS) {
+			return 0;
+		}
+
 		// Keep the newest rows in one statement. Deriving the victims inside the
 		// DELETE makes overlapping cleanup runs idempotent: each statement
 		// evaluates the current newest set instead of acting on a stale count.

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.ts

@@ -2,6 +2,7 @@ import { sql, type Kysely, type Selectable } from "kysely";
 import { ulid } from "ulidx";
 
 import { invalidateTaxonomyObjectCache } from "../../object-cache/index.js";
+import { chunks, SQL_BATCH_SIZE } from "../../utils/chunks.js";
 import { slugify } from "../../utils/slugify.js";
 import { withTransaction } from "../transaction.js";
 import type { Database, TaxonomyTable } from "../types.js";
@@ -19,6 +20,8 @@ export interface SiblingPosition {
  * statement inside D1's 100-parameter ceiling.
  */
 const GROUPS_PER_UPDATE = 32;
+/** Rows per `content_taxonomies` insert. Each row binds three parameters. */
+const ASSIGNMENTS_PER_INSERT = 32;
 const NUMERIC_SUFFIX_PATTERN = /^\d+$/;
 
 /** Deal the listed groups back out over the slots they hold, in the order given. */
@@ -618,8 +621,8 @@ export class TaxonomyRepository {
 	}
 
 	/**
-	 * Attach already-resolved term translation groups in one insert and return
-	 * the number of assignments that did not already exist.
+	 * Attach already-resolved term translation groups and return the number of
+	 * assignments that did not already exist.
 	 */
 	async attachGroupsToEntry(
 		collection: string,
@@ -631,22 +634,60 @@ export class TaxonomyRepository {
 		const entryGroup = await this.resolveEntryTranslationGroup(collection, entryId);
 		if (!entryGroup) return 0;
 
-		const result = await this.db
-			.insertInto("content_taxonomies")
-			.values(
-				uniqueGroups.map((taxonomy_id) => ({
-					collection,
-					entry_id: entryGroup,
-					taxonomy_id,
-				})),
-			)
-			.onConflict((oc) => oc.doNothing())
-			.executeTakeFirst();
-		const inserted = Number(result.numInsertedOrUpdatedRows ?? 0n);
+		const inserted = await this.insertAssignments(collection, entryGroup, uniqueGroups);
 		if (inserted > 0) invalidateTaxonomyObjectCache();
 		return inserted;
 	}
 
+	private async insertAssignments(
+		collection: string,
+		entryGroup: string,
+		taxonomyGroups: string[],
+	): Promise<number> {
+		let inserted = 0;
+		try {
+			for (const batch of chunks(taxonomyGroups, ASSIGNMENTS_PER_INSERT)) {
+				// oxlint-disable-next-line no-await-in-loop -- one statement per D1-safe batch
+				const result = await this.db
+					.insertInto("content_taxonomies")
+					.values(batch.map((taxonomy_id) => ({ collection, entry_id: entryGroup, taxonomy_id })))
+					.onConflict((oc) => oc.doNothing())
+					.executeTakeFirst();
+				inserted += Number(result.numInsertedOrUpdatedRows ?? 0n);
+			}
+		} catch (error) {
+			// Earlier batches are already written.
+			if (inserted > 0) invalidateTaxonomyObjectCache();
+			throw error;
+		}
+		return inserted;
+	}
+
+	private async deleteAssignments(
+		collection: string,
+		entryGroup: string,
+		taxonomyGroups: string[],
+	): Promise<number> {
+		let removed = 0;
+		try {
+			for (const batch of chunks(taxonomyGroups, SQL_BATCH_SIZE)) {
+				// oxlint-disable-next-line no-await-in-loop -- one statement per D1-safe batch
+				const result = await this.db
+					.deleteFrom("content_taxonomies")
+					.where("collection", "=", collection)
+					.where("entry_id", "=", entryGroup)
+					.where("taxonomy_id", "in", batch)
+					.executeTakeFirst();
+				removed += Number(result.numDeletedRows ?? 0n);
+			}
+		} catch (error) {
+			// Earlier batches are already deleted.
+			if (removed > 0) invalidateTaxonomyObjectCache();
+			throw error;
+		}
+		return removed;
+	}
+
 	async detachFromEntry(collection: string, entryId: string, taxonomyId: string): Promise<void> {
 		const [entryGroup, taxonomyGroup] = await Promise.all([
 			this.resolveEntryTranslationGroup(collection, entryId),
@@ -674,13 +715,7 @@ export class TaxonomyRepository {
 		const entryGroup = await this.resolveEntryTranslationGroup(collection, entryId);
 		if (!entryGroup) return 0;
 
-		const result = await this.db
-			.deleteFrom("content_taxonomies")
-			.where("collection", "=", collection)
-			.where("entry_id", "=", entryGroup)
-			.where("taxonomy_id", "in", uniqueGroups)
-			.executeTakeFirst();
-		const removed = Number(result.numDeletedRows ?? 0n);
+		const removed = await this.deleteAssignments(collection, entryGroup, uniqueGroups);
 		if (removed > 0) invalidateTaxonomyObjectCache();
 		return removed;
 	}
@@ -792,31 +827,13 @@ export class TaxonomyRepository {
 		const currentGroups = new Set(current.map((r) => r.group));
 
 		const toRemove = [...currentGroups].filter((g) => !newGroups.has(g));
-		if (toRemove.length > 0) {
-			await this.db
-				.deleteFrom("content_taxonomies")
-				.where("collection", "=", collection)
-				.where("entry_id", "=", entryGroup)
-				.where("taxonomy_id", "in", toRemove)
-				.execute();
-		}
-
 		const toAdd = [...newGroups].filter((g) => !currentGroups.has(g));
-		if (toAdd.length > 0) {
-			await this.db
-				.insertInto("content_taxonomies")
-				.values(
-					toAdd.map((taxonomy_id) => ({
-						collection,
-						entry_id: entryGroup,
-						taxonomy_id,
-					})),
-				)
-				.onConflict((oc) => oc.doNothing())
-				.execute();
+		try {
+			if (toRemove.length > 0) await this.deleteAssignments(collection, entryGroup, toRemove);
+			if (toAdd.length > 0) await this.insertAssignments(collection, entryGroup, toAdd);
+		} finally {
+			if (toRemove.length > 0 || toAdd.length > 0) invalidateTaxonomyObjectCache();
 		}
-
-		if (toRemove.length > 0 || toAdd.length > 0) invalidateTaxonomyObjectCache();
 	}
 
 	async clearEntryTerms(collection: string, entryId: string): Promise<number> {
@@ -921,8 +938,6 @@ export class TaxonomyRepository {
 	async countEntriesForTerms(translationGroups: string[]): Promise<Map<string, number>> {
 		if (translationGroups.length === 0) return new Map();
 
-		const { chunks, SQL_BATCH_SIZE } = await import("../../utils/chunks.js");
-
 		const counts = new Map<string, number>();
 		for (const chunk of chunks(translationGroups, SQL_BATCH_SIZE)) {
 			const rows = await this.db

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. */
@@ -223,6 +223,8 @@ export interface FindManyOptions {
 	sortableExtras?: string[];
 	limit?: number;
 	cursor?: string; // Base64-encoded JSON: {orderValue: string, id: string}
+	/** Rows to skip before the page, for numbered pages. Cannot be combined with `cursor`. */
+	offset?: number;
 }
 
 export interface FindManyResult<T> {
@@ -248,9 +250,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));
 }
 
 /**
@@ -269,13 +295,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;
@@ -287,11 +336,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 {