emdash 0.28.1 → 0.30.0

package/src/database/repositories/media-usage.ts

@@ -20,7 +20,7 @@ import type {
 	MediaUsageTable,
 } from "../types.js";
 import { validateIdentifier } from "../validate.js";
-import { decodeCursor, encodeCursor, type FindManyResult } from "./types.js";
+import { decodeCursor, encodeCursor, InvalidCursorError, type FindManyResult } from "./types.js";
 
 type DatabaseExecutor = Kysely<Database> | Transaction<Database>;
 type MediaUsageSourceNullableStringColumn =
@@ -36,6 +36,23 @@ const OCCURRENCE_INSERT_BATCH_SIZE = Math.max(
 	1,
 	Math.floor(SQL_BATCH_SIZE / OCCURRENCE_BIND_COLUMNS),
 );
+const CONTENT_SOURCE_ELIGIBILITY = sql<boolean>`(
+	s.source_variant = 'draft_overlay'
+	OR (
+		s.source_variant = 'columns'
+		AND (
+			s.content_status = 'published'
+			OR NOT EXISTS (
+				SELECT 1
+				FROM _emdash_media_usage_sources AS overlay
+				WHERE overlay.source_type = 'content'
+					AND overlay.collection_slug = s.collection_slug
+					AND overlay.content_id = s.content_id
+					AND overlay.source_variant = 'draft_overlay'
+			)
+		)
+	)
+)`;
 
 export interface MediaUsageSourceInput {
 	sourceKey: string;
@@ -193,6 +210,24 @@ export interface FindMediaUsageOptions {
 	cursor?: string;
 }
 
+export interface MediaUsageCollectionIndexStatusScope {
+	collectionSlug: string;
+	status: string | null;
+	schemaVersion: number | null;
+}
+
+export interface MediaUsageEntrySource {
+	source: MediaUsageSource;
+	occurrences: MediaUsageOccurrence[];
+}
+
+export interface MediaUsageEntryGroup {
+	collectionSlug: string;
+	contentId: string;
+	contentDeletedAt: string | null;
+	sources: MediaUsageEntrySource[];
+}
+
 interface MediaUsageSourceRow {
 	source_key: string;
 	source_type: string;
@@ -280,6 +315,11 @@ interface JoinedUsageRow {
 	occurrence_created_at: string;
 }
 
+interface GroupedUsageRow extends JoinedUsageRow {
+	entry_deleted_at: string | null;
+	has_more: number;
+}
+
 /** Persistence-only repository for the internal media usage projection tables. */
 export class MediaUsageRepository {
 	constructor(private db: Kysely<Database>) {}
@@ -420,6 +460,169 @@ export class MediaUsageRepository {
 		};
 	}
 
+	async findActiveEntryCountsByMediaIds(mediaIds: readonly string[]): Promise<Map<string, number>> {
+		const uniqueMediaIds = [...new Set(mediaIds)];
+		const counts = new Map(uniqueMediaIds.map((mediaId) => [mediaId, 0]));
+
+		for (const mediaIdBatch of chunks(uniqueMediaIds, SQL_BATCH_SIZE)) {
+			const visibleEntries = this.currentContentMediaUsageBaseQuery()
+				.select([
+					"u.media_id as media_id",
+					"s.collection_slug as collection_slug",
+					"s.content_id as content_id",
+				])
+				.where("u.media_id", "in", mediaIdBatch)
+				.where((eb) =>
+					eb.not(
+						eb.exists(
+							eb
+								.selectFrom("_emdash_media_usage_sources as deleted_source")
+								.select("deleted_source.source_key")
+								.where("deleted_source.source_type", "=", "content")
+								.whereRef("deleted_source.collection_slug", "=", "s.collection_slug")
+								.whereRef("deleted_source.content_id", "=", "s.content_id")
+								.where("deleted_source.source_variant", "in", ["columns", "draft_overlay"])
+								.where("deleted_source.content_deleted_at", "is not", null),
+						),
+					),
+				)
+				.distinct()
+				.as("visible_entries");
+
+			const rows = await this.db
+				.selectFrom(visibleEntries)
+				.select("media_id")
+				.select((eb) => eb.fn.countAll<number>().as("usage_count"))
+				.groupBy("media_id")
+				.execute();
+
+			for (const row of rows) {
+				if (row.media_id !== null) counts.set(row.media_id, Number(row.usage_count));
+			}
+		}
+
+		return counts;
+	}
+
+	async findCollectionIndexStatusScopes(
+		identity: Pick<MediaUsageIndexStatusIdentity, "adapterId" | "scopeType">,
+	): Promise<MediaUsageCollectionIndexStatusScope[]> {
+		const rows = await this.db
+			.selectFrom("_emdash_collections as collection")
+			.leftJoin("_emdash_media_usage_index_status as status", (join) =>
+				join
+					.on("status.adapter_id", "=", identity.adapterId)
+					.on("status.scope_type", "=", identity.scopeType)
+					.onRef("status.scope_key", "=", "collection.slug"),
+			)
+			.select([
+				"collection.slug as collection_slug",
+				"status.status as status",
+				"status.schema_version as schema_version",
+			])
+			.orderBy("collection.slug", "asc")
+			.execute();
+
+		return rows.map((row) => ({
+			collectionSlug: row.collection_slug,
+			status: row.status,
+			schemaVersion: row.schema_version === null ? null : Number(row.schema_version),
+		}));
+	}
+
+	async findCurrentEntryUsagePageByMediaId(
+		mediaId: string,
+		options: FindMediaUsageOptions = {},
+	): Promise<FindManyResult<MediaUsageEntryGroup>> {
+		const requestedLimit = Math.floor(options.limit ?? 50);
+		const limit = Number.isFinite(requestedLimit) ? Math.min(Math.max(1, requestedLimit), 100) : 50;
+		const cursor = options.cursor ? decodeCursor(options.cursor) : null;
+		if (cursor && (cursor.orderValue.length === 0 || cursor.id.length === 0)) {
+			throw new InvalidCursorError(options.cursor ?? "");
+		}
+		let matchedGroups = this.currentContentMediaUsageBaseQuery()
+			.select(["s.collection_slug as collection_slug", "s.content_id as content_id"])
+			.where("u.media_id", "=", mediaId)
+			.distinct();
+		if (cursor) {
+			matchedGroups = matchedGroups.where((eb) =>
+				eb.or([
+					eb("s.collection_slug", ">", cursor.orderValue),
+					eb.and([
+						eb("s.collection_slug", "=", cursor.orderValue),
+						eb("s.content_id", ">", cursor.id),
+					]),
+				]),
+			);
+		}
+		matchedGroups = matchedGroups
+			.orderBy("s.collection_slug", "asc")
+			.orderBy("s.content_id", "asc")
+			.limit(limit + 1);
+
+		const rows: GroupedUsageRow[] = await this.db
+			.with("matched_groups", () => matchedGroups)
+			.with("page_groups", (db) =>
+				db
+					.selectFrom("matched_groups")
+					.selectAll()
+					.orderBy("collection_slug", "asc")
+					.orderBy("content_id", "asc")
+					.limit(limit),
+			)
+			.with("entry_state", (db) =>
+				db
+					.selectFrom("page_groups as page")
+					.crossJoin("_emdash_media_usage_sources as state")
+					.select(["page.collection_slug", "page.content_id"])
+					.select((eb) =>
+						eb.fn.max<string | null>("state.content_deleted_at").as("entry_deleted_at"),
+					)
+					.whereRef("page.collection_slug", "=", "state.collection_slug")
+					.whereRef("page.content_id", "=", "state.content_id")
+					.where("state.source_type", "=", "content")
+					.where("state.source_variant", "in", ["columns", "draft_overlay"])
+					.groupBy(["page.collection_slug", "page.content_id"]),
+			)
+			.selectFrom("entry_state as page")
+			.crossJoin("_emdash_media_usage_sources as s")
+			.crossJoin("_emdash_media_usage as u")
+			.whereRef("page.collection_slug", "=", "s.collection_slug")
+			.whereRef("page.content_id", "=", "s.content_id")
+			.whereRef("s.source_key", "=", "u.source_key")
+			.whereRef("s.current_generation", "=", "u.generation")
+			.select(currentUsageSelect)
+			.select("page.entry_deleted_at")
+			.select(
+				sql<number>`CASE
+					WHEN (SELECT COUNT(*) FROM matched_groups) > ${limit} THEN 1
+					ELSE 0
+				END`.as("has_more"),
+			)
+			.where("u.media_id", "=", mediaId)
+			.where("s.source_type", "=", "content")
+			.where("s.collection_slug", "is not", null)
+			.where("s.content_id", "is not", null)
+			.where("s.source_variant", "in", ["columns", "draft_overlay"])
+			.where(CONTENT_SOURCE_ELIGIBILITY)
+			.orderBy("s.collection_slug", "asc")
+			.orderBy("s.content_id", "asc")
+			.orderBy("s.source_variant", "asc")
+			.orderBy("s.source_key", "asc")
+			.orderBy("u.field_path", "asc")
+			.orderBy("u.occurrence_index", "asc")
+			.orderBy("u.id", "asc")
+			.execute();
+
+		const items = groupUsageRows(rows);
+		const result: FindManyResult<MediaUsageEntryGroup> = { items };
+		if (Number(rows[0]?.has_more ?? 0) === 1 && items.length > 0) {
+			const last = items.at(-1)!;
+			result.nextCursor = encodeCursor(last.collectionSlug, last.contentId);
+		}
+		return result;
+	}
+
 	async findCurrentUsageByMediaId(mediaId: string): Promise<MediaUsageRecord[]> {
 		const rows = await this.db
 			.selectFrom("_emdash_media_usage_sources as s")
@@ -889,6 +1092,20 @@ export class MediaUsageRepository {
 			.select(currentUsageSelect);
 	}
 
+	private currentContentMediaUsageBaseQuery() {
+		return this.db
+			.selectFrom("_emdash_media_usage as u")
+			.crossJoin("_emdash_media_usage_sources as s")
+			.innerJoin("_emdash_collections as collection", "collection.slug", "s.collection_slug")
+			.whereRef("s.source_key", "=", "u.source_key")
+			.whereRef("s.current_generation", "=", "u.generation")
+			.where("s.source_type", "=", "content")
+			.where("s.collection_slug", "is not", null)
+			.where("s.content_id", "is not", null)
+			.where("s.source_variant", "in", ["columns", "draft_overlay"])
+			.where(CONTENT_SOURCE_ELIGIBILITY);
+	}
+
 	private async deleteSourceKeys(sourceKeys: readonly string[]): Promise<number> {
 		const uniqueSourceKeys = [...new Set(sourceKeys)];
 		if (uniqueSourceKeys.length === 0) return 0;
@@ -1229,6 +1446,38 @@ const currentUsageSelect = [
 	"u.created_at as occurrence_created_at",
 ] as const;
 
+function groupUsageRows(rows: readonly GroupedUsageRow[]): MediaUsageEntryGroup[] {
+	const groups: MediaUsageEntryGroup[] = [];
+
+	for (const row of rows) {
+		if (row.collection_slug === null || row.content_id === null) continue;
+		const record = rowToUsageRecord(row);
+		let group = groups.at(-1);
+		if (
+			!group ||
+			group.collectionSlug !== row.collection_slug ||
+			group.contentId !== row.content_id
+		) {
+			group = {
+				collectionSlug: row.collection_slug,
+				contentId: row.content_id,
+				contentDeletedAt: row.entry_deleted_at,
+				sources: [],
+			};
+			groups.push(group);
+		}
+
+		let source = group.sources.at(-1);
+		if (!source || source.source.sourceKey !== record.source.sourceKey) {
+			source = { source: record.source, occurrences: [] };
+			group.sources.push(source);
+		}
+		source.occurrences.push(record.occurrence);
+	}
+
+	return groups;
+}
+
 function rowToSource(row: MediaUsageSourceRow): MediaUsageSource {
 	return {
 		sourceKey: row.source_key,

package/src/database/repositories/media.ts

@@ -118,7 +118,7 @@ export class MediaRepository {
 
 		await this.db.insertInto("media").values(row).execute();
 
-		return this.rowToItem(row as MediaRow);
+		return this.rowToItem(row);
 	}
 
 	/**

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

@@ -7,7 +7,7 @@
  * @see PLUGIN-SYSTEM.md § Plugin Storage > Full API Reference
  */
 
-import type { Kysely } from "kysely";
+import type { Kysely, RawBuilder } from "kysely";
 import { sql } from "kysely";
 
 import {
@@ -15,7 +15,7 @@ import {
 	validateWhereClause,
 	validateOrderByClause,
 	getIndexedFields,
-	jsonExtract,
+	jsonOrderExtract,
 } from "../../plugins/storage-query.js";
 import type {
 	StorageCollection,
@@ -27,6 +27,26 @@ import { withTransaction } from "../transaction.js";
 import type { Database } from "../types.js";
 import { encodeCursor, decodeCursor } from "./types.js";
 
+/**
+ * Interleave a `?`-placeholder SQL string with its params into a single
+ * boolean raw expression. Used as a WHERE predicate directly — wrapping it
+ * in `(...) = 1` breaks on Postgres, which has a strict boolean type (#920).
+ */
+function rawWhereExpr(sqlText: string, params: unknown[]): RawBuilder<boolean> {
+	const parts: ReturnType<typeof sql>[] = [];
+	let paramIndex = 0;
+	const sqlParts = sqlText.split("?");
+	for (let i = 0; i < sqlParts.length; i++) {
+		if (i > 0) {
+			parts.push(sql`${params[paramIndex++]}`);
+		}
+		if (sqlParts[i]) {
+			parts.push(sql.raw(sqlParts[i]));
+		}
+	}
+	return sql<boolean>`(${sql.join(parts, sql.raw(""))})`;
+}
+
 /**
  * Plugin Storage Repository
  *
@@ -211,19 +231,7 @@ export class PluginStorageRepository<T = unknown> implements StorageCollection<T
 		// Add JSON extraction WHERE conditions
 		const whereResult = buildWhereClause(this.db, where);
 		if (whereResult.sql) {
-			// Use sql template to add the raw WHERE conditions with params
-			const whereSqlParts: ReturnType<typeof sql>[] = [];
-			let paramIndex = 0;
-			const sqlParts = whereResult.sql.split("?");
-			for (let i = 0; i < sqlParts.length; i++) {
-				if (i > 0) {
-					whereSqlParts.push(sql`${whereResult.params[paramIndex++]}`);
-				}
-				if (sqlParts[i]) {
-					whereSqlParts.push(sql.raw(sqlParts[i]));
-				}
-			}
-			query = query.where(({ eb }) => eb(sql.join(whereSqlParts, sql.raw("")), "=", sql.raw("1")));
+			query = query.where(rawWhereExpr(whereResult.sql, whereResult.params));
 		}
 
 		// Handle cursor-based pagination — throws on invalid cursor.
@@ -237,7 +245,9 @@ export class PluginStorageRepository<T = unknown> implements StorageCollection<T
 		// Build ORDER BY using sql template
 		if (Object.keys(orderBy).length > 0) {
 			for (const [field, direction] of Object.entries(orderBy)) {
-				const extract = jsonExtract(this.db, field);
+				// Order over the jsonb-native value on Postgres so numeric fields sort
+				// numerically, not lexically. See pluginDataOrderExpr.
+				const extract = jsonOrderExtract(this.db, field);
 				const orderExpr =
 					direction === "desc" ? sql`${sql.raw(extract)} desc` : sql`${sql.raw(extract)} asc`;
 				query = query.orderBy(orderExpr);
@@ -289,26 +299,13 @@ export class PluginStorageRepository<T = unknown> implements StorageCollection<T
 		if (where && Object.keys(where).length > 0) {
 			const whereResult = buildWhereClause(this.db, where);
 			if (whereResult.sql) {
-				// Use sql template to add the raw WHERE conditions with params
-				const whereSqlParts: ReturnType<typeof sql>[] = [];
-				let paramIndex = 0;
-				const sqlParts = whereResult.sql.split("?");
-				for (let i = 0; i < sqlParts.length; i++) {
-					if (i > 0) {
-						whereSqlParts.push(sql`${whereResult.params[paramIndex++]}`);
-					}
-					if (sqlParts[i]) {
-						whereSqlParts.push(sql.raw(sqlParts[i]));
-					}
-				}
-				query = query.where(({ eb }) =>
-					eb(sql.join(whereSqlParts, sql.raw("")), "=", sql.raw("1")),
-				);
+				query = query.where(rawWhereExpr(whereResult.sql, whereResult.params));
 			}
 		}
 
 		const result = await query.executeTakeFirst();
-		return result?.count ?? 0;
+		// Number() because the pg driver returns COUNT(*) (bigint) as a string.
+		return Number(result?.count ?? 0);
 	}
 }
 

package/src/database/repositories/redirect.ts

@@ -347,7 +347,11 @@ export class RedirectRepository {
 	/**
 	 * Create an auto-redirect when a content slug changes.
 	 * Uses the collection's URL pattern to compute old/new URLs.
-	 * Collapses existing redirect chains pointing to the old URL.
+	 * Collapses existing redirect chains pointing to the old URL and
+	 * removes redirects that would shadow the now-live new URL, so a
+	 * rename that is later reverted cannot form a loop (#1986).
+	 *
+	 * Returns null when old and new URL are identical (nothing to redirect).
 	 */
 	async createAutoRedirect(
 		collection: string,
@@ -355,7 +359,7 @@ export class RedirectRepository {
 		newSlug: string,
 		contentId: string,
 		urlPattern: string | null,
-	): Promise<Redirect> {
+	): Promise<Redirect | null> {
 		const oldUrl = urlPattern
 			? urlPattern.replace("{slug}", oldSlug).replace("{id}", contentId)
 			: `/${collection}/${oldSlug}`;
@@ -363,9 +367,17 @@ export class RedirectRepository {
 			? urlPattern.replace("{slug}", newSlug).replace("{id}", contentId)
 			: `/${collection}/${newSlug}`;
 
+		// A redirect from a URL to itself would make the page unreachable
+		if (oldUrl === newUrl) return null;
+
 		// Collapse chains: update any existing redirects pointing to the old URL
 		await this.collapseChains(oldUrl, newUrl);
 
+		// The new URL serves live content again — any redirect from it would
+		// shadow the page. This also removes the self-redirect that chain
+		// collapsing produces when a rename A → B is reverted (A → A).
+		await this.db.deleteFrom("_emdash_redirects").where("source", "=", newUrl).execute();
+
 		// Check if a redirect from this source already exists
 		const existing = await this.findBySource(oldUrl);
 		if (existing) {

package/src/database/repositories/relation.ts

@@ -3,6 +3,7 @@ import { ulid } from "ulidx";
 
 import { chunks, SQL_BATCH_SIZE } from "../../utils/chunks.js";
 import type { Database, RelationTable, ContentReferenceTable } from "../types.js";
+import { decodeCursor, encodeCursor, InvalidCursorError, type FindManyResult } from "./types.js";
 
 export interface Relation {
 	id: string;
@@ -17,8 +18,12 @@ export interface Relation {
 
 export interface CreateRelationInput {
 	name: string;
-	parentCollection: string;
-	childCollection: string;
+	/** Required for a base relation; ignored (inherited from the source) when
+	 * `translationOf` is set. */
+	parentCollection?: string;
+	/** Required for a base relation; ignored (inherited from the source) when
+	 * `translationOf` is set. */
+	childCollection?: string;
 	parentLabel: string;
 	childLabel: string;
 	/** Omit to let the DB default (current value: 'en') apply. Higher layers
@@ -73,9 +78,9 @@ export class RelationRepository {
 		const now = new Date().toISOString();
 
 		let translationGroup = id;
-		let name = input.name;
-		let parentCollection = input.parentCollection;
-		let childCollection = input.childCollection;
+		let name: string;
+		let parentCollection: string;
+		let childCollection: string;
 
 		if (input.translationOf) {
 			const source = await this.findById(input.translationOf);
@@ -87,6 +92,18 @@ export class RelationRepository {
 			name = source.name;
 			parentCollection = source.parentCollection;
 			childCollection = source.childCollection;
+		} else {
+			// A base relation carries its own structural fields. The API layer's Zod
+			// schema enforces this; guard here too since the repo trusts its inputs
+			// and the columns are NOT NULL.
+			if (input.parentCollection === undefined || input.childCollection === undefined) {
+				throw new Error(
+					"parentCollection and childCollection are required unless translationOf is set",
+				);
+			}
+			name = input.name;
+			parentCollection = input.parentCollection;
+			childCollection = input.childCollection;
 		}
 
 		await this.db
@@ -319,6 +336,61 @@ export class RelationRepository {
 		return rows.map((row) => this.rowToReference(row));
 	}
 
+	/**
+	 * Forward traversal, paginated: one page of a parent's children for a
+	 * relation, ordered by `(sort_order, id)`. Use this on request paths — a
+	 * parent's children are capped but still up to 1000, and an unbounded read
+	 * scales poorly. Returns `{ items, nextCursor? }`; the cursor's order value is
+	 * the row's `sort_order`. Default limit 50, max 100.
+	 */
+	async getChildrenPage(
+		relation: string,
+		parentGroup: string,
+		options: { limit?: number; cursor?: string } = {},
+	): Promise<FindManyResult<ContentReference>> {
+		const relationGroup = await this.resolveRelationGroup(relation);
+		if (!relationGroup) return { items: [] };
+
+		const limit = Math.min(options.limit || 50, 100);
+
+		let query = this.db
+			.selectFrom("_emdash_content_references")
+			.selectAll()
+			.where("relation_group", "=", relationGroup)
+			.where("parent_group", "=", parentGroup);
+
+		if (options.cursor) {
+			const decoded = decodeCursor(options.cursor);
+			const sortOrder = Number(decoded.orderValue);
+			// `decodeCursor` only guarantees `orderValue` is a string; a hand-crafted
+			// cursor with a non-numeric order value would coerce to NaN and blow up at
+			// the driver bind as a 500. A bad cursor is a client error — surface it as
+			// INVALID_CURSOR (400). Server-issued cursors are always numeric here.
+			if (!Number.isFinite(sortOrder)) throw new InvalidCursorError(options.cursor);
+			query = query.where((eb) =>
+				eb.or([
+					eb("sort_order", ">", sortOrder),
+					eb.and([eb("sort_order", "=", sortOrder), eb("id", ">", decoded.id)]),
+				]),
+			);
+		}
+
+		const rows = await query
+			.orderBy("sort_order", "asc")
+			.orderBy("id", "asc")
+			.limit(limit + 1)
+			.execute();
+
+		const hasMore = rows.length > limit;
+		const items = rows.slice(0, limit).map((row) => this.rowToReference(row));
+		const result: FindManyResult<ContentReference> = { items };
+		const last = items.at(-1);
+		if (hasMore && last) {
+			result.nextCursor = encodeCursor(String(last.sortOrder), last.id);
+		}
+		return result;
+	}
+
 	/** Backlink traversal: the parents that reference a child for a relation. */
 	async getParents(relation: string, childGroup: string): Promise<ContentReference[]> {
 		const relationGroup = await this.resolveRelationGroup(relation);
@@ -346,6 +418,15 @@ export class RelationRepository {
 	 * relying on the insert's onConflict to silently drop them. Not wrapped in a
 	 * transaction: a crash between the delete and insert leaves the parent with
 	 * no children — acceptable for a replace-all, since a retry restores state.
+	 *
+	 * Concurrency: two simultaneous replace-all calls for the same (relation,
+	 * parent) can interleave their deletes and inserts and merge into the union of
+	 * both sets (a lost update — neither "replace" wins). This is non-corrupting —
+	 * keyset pagination stays totally ordered via the `(sort_order, id)` tiebreak
+	 * even with duplicate sort_orders — and a single client editing one parent's
+	 * children serially never hits it. A D1-portable fix isn't available (no
+	 * multi-statement transactions), so concurrent replace-all on one parent is
+	 * unsupported by design rather than guarded here.
 	 */
 	async setChildren(relation: string, parentGroup: string, childGroups: string[]): Promise<void> {
 		const relationGroup = await this.resolveRelationGroup(relation);
@@ -381,6 +462,50 @@ export class RelationRepository {
 			.execute();
 	}
 
+	/**
+	 * Backlink traversal, paginated: one page of the parents that reference a
+	 * child for a relation, ordered by `id`. Unlike a parent's children, a
+	 * child's backlinks are *unbounded* — one popular entry can be referenced by
+	 * arbitrarily many parents — so this read must paginate. Returns
+	 * `{ items, nextCursor? }`; the cursor's order value is the row `id`. Default
+	 * limit 50, max 100.
+	 */
+	async getParentsPage(
+		relation: string,
+		childGroup: string,
+		options: { limit?: number; cursor?: string } = {},
+	): Promise<FindManyResult<ContentReference>> {
+		const relationGroup = await this.resolveRelationGroup(relation);
+		if (!relationGroup) return { items: [] };
+
+		const limit = Math.min(options.limit || 50, 100);
+
+		let query = this.db
+			.selectFrom("_emdash_content_references")
+			.selectAll()
+			.where("relation_group", "=", relationGroup)
+			.where("child_group", "=", childGroup);
+
+		if (options.cursor) {
+			const decoded = decodeCursor(options.cursor);
+			query = query.where("id", ">", decoded.id);
+		}
+
+		const rows = await query
+			.orderBy("id", "asc")
+			.limit(limit + 1)
+			.execute();
+
+		const hasMore = rows.length > limit;
+		const items = rows.slice(0, limit).map((row) => this.rowToReference(row));
+		const result: FindManyResult<ContentReference> = { items };
+		const last = items.at(-1);
+		if (hasMore && last) {
+			result.nextCursor = encodeCursor(last.id, last.id);
+		}
+		return result;
+	}
+
 	/**
 	 * Remove every edge where `group` is the parent OR the child — i.e. ensure no
 	 * orphaned reference edges survive when a content entry is deleted. The