emdash 0.40.0 → 0.41.0

package/src/database/repositories/revision.ts

@@ -110,6 +110,22 @@ export class RevisionRepository {
 		return row ? this.normalizeRow(row) : null;
 	}
 
+	/** Shallow-merge `patch` into a stored revision's data. */
+	async mergeData(id: string, patch: Record<string, unknown>): Promise<void> {
+		const row = await this.db
+			.selectFrom("revisions")
+			.select("data")
+			.where("id", "=", id)
+			.executeTakeFirst();
+		if (!row) return;
+		const data: Record<string, unknown> = { ...JSON.parse(row.data), ...patch };
+		await this.db
+			.updateTable("revisions")
+			.set({ data: JSON.stringify(data) })
+			.where("id", "=", id)
+			.execute();
+	}
+
 	/**
 	 * Get all revisions for an entry (newest first)
 	 *

package/src/database/repositories/types.ts

@@ -236,6 +236,18 @@ export interface FindManyResult<T> {
 	total?: number;
 }
 
+/**
+ * Order value stamped into a cursor over a *staged* reference selection, whose
+ * anchor is a translation group rather than a row in the link table.
+ *
+ * A preview and a public render page the same field from different places, so a
+ * cursor can cross that boundary in either direction — the draft publishes, or
+ * the preview session ends, mid-pagination. Both sides recognise this marker so
+ * they can tell a foreign cursor from a malformed one and restart the field's
+ * page rather than failing or silently emptying it.
+ */
+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 }));
@@ -314,6 +326,32 @@ export interface ContentItem {
 	 * revision history.
 	 */
 	liveData?: Record<string, unknown>;
+	/**
+	 * First page of each reference field's resolved selection, keyed by field
+	 * slug. Only populated when the caller opts in via `handleContentGet`'s
+	 * `referenceOptions` param (see content.ts) — hydration is never
+	 * unconditional because it can leak draft ids/slugs to callers without
+	 * `content:read_drafts`.
+	 *
+	 * Shape mirrors `EntryRef` from `api/handlers/relations.ts`, duplicated
+	 * here (rather than imported) so the database layer doesn't depend on
+	 * the api/handlers layer.
+	 */
+	references?: Record<
+		string,
+		{
+			children: Array<{
+				id: string;
+				slug: string | null;
+				collection: string;
+				title: string | null;
+				locale: string | null;
+				translationGroup: string | null;
+				sortOrder?: number;
+			}>;
+			nextCursor?: string;
+		}
+	>;
 }
 
 export class EmDashValidationError extends Error {

package/src/database/transaction.ts

@@ -29,7 +29,18 @@ export async function withTransaction<DB, T>(
 	db: Kysely<DB>,
 	fn: (trx: Kysely<DB> | Transaction<DB>) => Promise<T>,
 ): Promise<T> {
-	if (db.isTransaction) return fn(db);
+	// Nested call: `db` is already a transaction. Kysely rejects calling
+	// `.transaction()` on a `Transaction` outright (a hard error, not the
+	// "transactions are not supported" message the probe below expects), so a
+	// naive nested `withTransaction(trx, ...)` call would always throw on any
+	// dialect that supports real transactions. Running `fn` directly against
+	// the existing transaction makes the nested work part of the enclosing
+	// one — exactly what nested callers (e.g. a handler composing two
+	// repositories that each self-wrap in `withTransaction`) want: the whole
+	// chain commits or rolls back together.
+	if (db.isTransaction) {
+		return fn(db);
+	}
 	// Fast path: we already know transactions work
 	if (transactionsSupported === true) {
 		return db.transaction().execute(fn);

package/src/database/types.ts

@@ -976,23 +976,32 @@ export interface BylineFieldGroupValueTable {
 // between content entries, linked by `translation_group` so they are
 // locale-agnostic — no foreign keys, mirroring `content_taxonomies`.
 
+/**
+ * A relation definition. Not localized — a relation joins the same two
+ * collections whatever language you read it in, and its role labels are
+ * single-valued like a collection's. See migration 086.
+ */
 export interface RelationTable {
 	id: string;
-	name: string;
+	slug: string;
 	parent_collection: string;
 	child_collection: string;
 	parent_label: string;
 	child_label: string;
-	locale: Generated<string>;
-	translation_group: string;
+	parent_label_singular: string | null;
+	child_label_singular: string | null;
+	/** How many children one parent may hold. NULL means unlimited. */
+	max_children_per_parent: number | null;
+	/** How many parents one child may hold. NULL means unlimited. */
+	max_parents_per_child: number | null;
 	created_at: Generated<string>;
 	updated_at: Generated<string>;
 }
 
 export interface ContentReferenceTable {
 	id: string;
-	/** Stores `_emdash_relations.translation_group` (locale-agnostic). No FK. */
-	relation_group: string;
+	/** Stores `_emdash_relations.id`. No FK. */
+	relation_id: string;
 	/** Parent entry's `translation_group`. */
 	parent_group: string;
 	/** Child entry's `translation_group`. */

package/src/emdash-runtime.ts

@@ -28,6 +28,12 @@ import {
 	handleMediaUpload as uploadMedia,
 	type MediaUploadInput,
 } from "./api/handlers/media-upload.js";
+import { resolveReferenceSelection } from "./api/handlers/relations.js";
+import {
+	mergeStagedReferences,
+	STAGED_REFERENCES_KEY,
+	type StagedReferences,
+} from "./api/handlers/staged-references.js";
 import { validateRev } from "./api/rev.js";
 import { getSiteBaseUrl } from "./api/site-url.js";
 import type {
@@ -126,6 +132,7 @@ import type {
 import { normalizePluginCapabilities } from "./plugins/types.js";
 import { recordSchedulerHeartbeatSafely } from "./scheduler-health.js";
 import { primeRegisteredCollections } from "./schema/collection-slugs-cache.js";
+import { isStoragelessField, isStoragelessFieldRow } from "./schema/types.js";
 import type { CollectionWithFields } from "./schema/types.js";
 import { isMissingTableError } from "./utils/db-errors.js";
 import { hashString } from "./utils/hash.js";
@@ -184,6 +191,7 @@ interface PageContributions {
 
 import { after } from "./after.js";
 import { maybeRunScheduledBackup } from "./api/handlers/backup.js";
+import { changedStoragelessDataKeys, storagelessDataKeyError } from "./api/handlers/content.js";
 import { loadBundleFromR2 } from "./api/handlers/marketplace.js";
 import { runSystemCleanup } from "./cleanup.js";
 import {
@@ -226,6 +234,7 @@ import {
 	handleMediaList,
 	handleMediaGet,
 	handleMediaCreate,
+	handleMediaRegisterUpload,
 	handleMediaUpdate,
 	handleMediaReplaceMetadata,
 	handleMediaDelete,
@@ -285,6 +294,7 @@ const DRAFT_ONLY_UPDATE_KEYS = new Set([
 	"slug",
 	"locale",
 	"skipRevision",
+	"references",
 	"actor",
 	"migrateBlocks",
 	"replaceBlocks",
@@ -3128,6 +3138,7 @@ export class EmDashRuntime {
 				implicit: i18nConfig === null,
 			},
 			marketplace: !!this.config.marketplace,
+			sandboxEnabled: this.runtimeDeps.sandboxEnabled && this.runtimeDeps.sandboxBypassed !== true,
 			registry,
 			registryConfigurationError,
 		};
@@ -3218,8 +3229,13 @@ export class EmDashRuntime {
 		return handleContentAuthors(this.db, collection);
 	}
 
-	async handleContentGet(collection: string, id: string, locale?: string) {
-		const result = await handleContentGet(this.db, collection, id, locale);
+	async handleContentGet(
+		collection: string,
+		id: string,
+		locale?: string,
+		referenceOptions?: { includeDrafts: boolean },
+	) {
+		const result = await handleContentGet(this.db, collection, id, locale, referenceOptions);
 		return this.hydrateDraftData(result);
 	}
 
@@ -3316,6 +3332,7 @@ export class EmDashRuntime {
 			locale?: string;
 			translationOf?: string;
 			taxonomies?: Record<string, string[]>;
+			references?: Record<string, string[]>;
 			actor?: ActorInfo;
 			migrateBlocks?: boolean;
 			replaceBlocks?: boolean;
@@ -3352,11 +3369,18 @@ export class EmDashRuntime {
 				await this.db
 					.selectFrom("_emdash_fields as field")
 					.innerJoin("_emdash_collections as collection", "collection.id", "field.collection_id")
-					.select("field.slug")
+					.select(["field.slug", "field.type", "field.validation"])
 					.where("collection.slug", "=", collection)
 					.where("field.translatable", "=", 0)
 					.execute()
-			).map((field) => field.slug);
+			)
+				// A storage-less field has nothing in `data` worth sharing: its
+				// selection is keyed by translation group, so every translation
+				// already reads the same edges. What the source row does carry under
+				// that slug is the frozen column a field bound after the fact left
+				// behind, and copying it would send a key `data` no longer accepts.
+				.filter((field) => !isStoragelessFieldRow(field))
+				.map((field) => field.slug);
 			const siblings = await repo.findTranslations(
 				collection,
 				source.translationGroup ?? source.id,
@@ -3500,6 +3524,7 @@ export class EmDashRuntime {
 				noIndex?: boolean;
 			};
 			taxonomies?: Record<string, string[]>;
+			references?: Record<string, string[]>;
 			publishedAt?: string | null;
 			locale?: string;
 			/** Replace the previous autosave revision after staging this save. */
@@ -3550,11 +3575,30 @@ export class EmDashRuntime {
 
 		// Loaded once and threaded through normalization, the stale-key drop and the draft
 		// merge below: each of those needs the field list and the registry does not cache.
-		const collectionInfo = bodyWithoutRev.data
-			? await this.schemaRegistry.getCollectionWithFields(collection).catch(() => null)
-			: null;
+		// A save carrying only a reference selection reaches the draft merge without any
+		// data, so it needs the collection loaded just the same.
+		const collectionInfo =
+			bodyWithoutRev.data || bodyWithoutRev.references
+				? await this.schemaRegistry.getCollectionWithFields(collection).catch(() => null)
+				: null;
 		const knownFieldSlugs = new Set((collectionInfo?.fields ?? []).map((f) => f.slug));
 
+		// A collection that keeps drafts merges `data` into a revision instead of
+		// writing columns, so a reference field's slug would land in the revision
+		// JSON and never reach the check the column writer's own path makes. Both
+		// operands are already in hand here, so the check costs nothing.
+		if (bodyWithoutRev.data && collectionInfo) {
+			const storageless = new Set(
+				collectionInfo.fields.filter(isStoragelessField).map((field) => field.slug),
+			);
+			const changed = changedStoragelessDataKeys(
+				storageless,
+				bodyWithoutRev.data,
+				resolvedItem?.data ?? {},
+			);
+			if (changed.length > 0) return storagelessDataKeyError(changed);
+		}
+
 		// Run beforeSave hooks if data is provided
 		let processedData = bodyWithoutRev.data;
 		let resolvedBlockTypes: Awaited<ReturnType<typeof resolveBlockTypes>> | undefined;
@@ -3646,9 +3690,32 @@ export class EmDashRuntime {
 		// Draft data lives only in the revisions table.
 		let usesDraftRevisions = false;
 		let draftStorageChanged = false;
-		if (processedData) {
+		if (processedData || bodyWithoutRev.references) {
 			if (collectionInfo?.supports?.includes("revisions")) {
 				usesDraftRevisions = true;
+
+				// Resolve a pending selection to translation groups before it is
+				// staged, so a bad id or an over-long selection fails this save the
+				// way a direct link write would, and publication has nothing left to
+				// resolve.
+				let stagedReferences: StagedReferences | undefined;
+				if (bodyWithoutRev.references) {
+					stagedReferences = {};
+					for (const [fieldSlug, selectedIds] of Object.entries(bodyWithoutRev.references)) {
+						const resolved = await resolveReferenceSelection(
+							this.db,
+							collection,
+							resolvedId,
+							fieldSlug,
+							selectedIds,
+						);
+						if (!resolved.success) {
+							return { success: false as const, error: resolved.error };
+						}
+						stagedReferences[fieldSlug] = resolved.data.groups;
+					}
+				}
+
 				const revisionRepo = new RevisionRepository(this.db);
 				let existing = await repo.findById(collection, resolvedId);
 
@@ -3660,12 +3727,12 @@ export class EmDashRuntime {
 					} else {
 						baseData = existing.data;
 					}
-					let attemptData = processedData;
+					let attemptData = processedData ?? {};
 					try {
 						attemptData = await normalizeBlocksData(
 							this.db,
 							collectionInfo,
-							processedData,
+							attemptData,
 							baseData,
 							blockWriteOptions,
 							true,
@@ -3703,6 +3770,9 @@ export class EmDashRuntime {
 					if (bodyWithoutRev.slug !== undefined) {
 						mergedData._slug = bodyWithoutRev.slug;
 					}
+					if (stagedReferences) {
+						mergedData[STAGED_REFERENCES_KEY] = mergeStagedReferences(baseData, stagedReferences);
+					}
 
 					const revision = await revisionRepo.create({
 						collection,
@@ -3794,13 +3864,19 @@ export class EmDashRuntime {
 						...bodyWithoutRev,
 						data: usesDraftRevisions ? undefined : processedData,
 						slug: usesDraftRevisions ? undefined : bodyWithoutRev.slug,
+						references: usesDraftRevisions ? undefined : bodyWithoutRev.references,
 						authorId: bodyWithoutRev.authorId,
 						bylines: bodyWithoutRev.bylines,
 					});
 
 		const liveContentChanged = usesDraftRevisions
 			? liveMetaTouched
-			: Boolean(processedData || bodyWithoutRev.slug !== undefined || liveMetaTouched);
+			: Boolean(
+					processedData ||
+					bodyWithoutRev.slug !== undefined ||
+					bodyWithoutRev.references ||
+					liveMetaTouched,
+				);
 
 		// Hydrate draft data BEFORE firing afterSave hooks so the hook sees
 		// the same effective data the response surfaces — for revision-
@@ -4572,6 +4648,33 @@ export class EmDashRuntime {
 		return result;
 	}
 
+	async handleMediaRegisterUpload(input: { storageKey: string; authorId?: string }) {
+		if (!this.storage) {
+			return {
+				success: false as const,
+				error: { code: "NO_STORAGE", message: "Storage not configured" },
+			};
+		}
+		const result = await handleMediaRegisterUpload(this.db, this.storage, input);
+
+		if (result.success && this.hooks.hasHooks("media:afterUpload")) {
+			const item = result.data.item;
+			const mediaItem: MediaItem = {
+				id: item.id,
+				filename: item.filename,
+				mimeType: item.mimeType,
+				size: item.size,
+				url: `/media/${item.id}/${item.filename}`,
+				createdAt: item.createdAt,
+			};
+			this.hooks
+				.runMediaAfterUpload(mediaItem)
+				.catch((err) => console.error("EmDash afterUpload hook error:", err));
+		}
+
+		return result;
+	}
+
 	async handleMediaCreate(input: {
 		filename: string;
 		mimeType: string;

package/src/index.ts

@@ -88,6 +88,7 @@ export {
 	handleMediaList,
 	handleMediaGet,
 	handleMediaCreate,
+	handleMediaRegisterUpload,
 	handleMediaUpdate,
 	handleMediaReplaceMetadata,
 	handleMediaDelete,
@@ -150,6 +151,7 @@ export { decodeSlug, slugify } from "./utils/slugify.js";
 export {
 	getEmDashCollection,
 	getEmDashEntry,
+	getEmDashReferences,
 	getEditMeta,
 	getTranslations,
 	resolveEmDashPath,
@@ -162,8 +164,17 @@ export type {
 	EditFieldMeta,
 	EntryResult,
 	EmDashCollections,
+	EmDashCollectionReferences,
 	InferCollectionData,
+	InferCollectionReferences,
+	ReferencePage,
+	ReferencePages,
+	ReferenceQuery,
+	ReferenceResult,
+	ReferenceSelection,
 	ResolvePathResult,
+	SelectableReferences,
+	SelectedReferences,
 	TranslationSummary,
 	TranslationsResult,
 	WhereRange,

package/src/loader.ts

@@ -23,6 +23,7 @@ import { getI18nConfig } from "./i18n/config.js";
 import type { Database } from "./index.js";
 import { primeSeoPanel } from "./page/seo-panel.js";
 import { getRequestContext } from "./request-context.js";
+import { chunks, SQL_BATCH_SIZE } from "./utils/chunks.js";
 import { isMissingColumnError, isMissingTableError } from "./utils/db-errors.js";
 
 const FIELD_NAME_PATTERN = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
@@ -64,6 +65,9 @@ const SEO_FOLDED_COLUMN = "_emdash_seo";
 /** Folded boolean field slugs used to restore SQLite integer values. */
 const BOOLEAN_FIELDS_FOLDED_COLUMN = "_emdash_boolean_fields";
 
+/** Rank of a row among its translation group's variants, in {@link loadEntriesByGroups}. */
+const VARIANT_RANK_COLUMN = "_emdash_variant_rank";
+
 /**
  * System columns excluded from entry.data
  * Note: slug is intentionally NOT excluded - it's useful as data.slug in templates
@@ -97,6 +101,7 @@ const SYSTEM_COLUMNS = new Set([
 	"_emdash_bylines_exist",
 	SEO_FOLDED_COLUMN,
 	BOOLEAN_FIELDS_FOLDED_COLUMN,
+	VARIANT_RANK_COLUMN,
 ]);
 
 /** Markers for byline/taxonomy hydration folded into the content query. */
@@ -567,6 +572,104 @@ function mapRowToData(
 	return data;
 }
 
+/**
+ * The entry id Astro addresses a row by: its slug, prefixed with the locale
+ * whenever i18n routing would prefix the URL. Shared by every path that builds
+ * a loader entry so a referenced entry carries the same id it would have been
+ * loaded under directly.
+ */
+function entryIdForRow(row: Record<string, unknown>): string {
+	const i18nConfig = virtualConfig?.i18n;
+	const slug = rowStr(row, "slug") || rowStr(row, "id");
+	const locale = rowStr(row, "locale");
+	const shouldPrefix =
+		i18nConfig &&
+		i18nConfig.locales.length > 1 &&
+		locale !== "" &&
+		(locale !== i18nConfig.defaultLocale || i18nConfig.prefixDefaultLocale);
+	return shouldPrefix ? `${locale}/${slug}` : slug;
+}
+
+/** A loader entry as {@link emdashLoader} builds one, before the query layer wraps it. */
+export interface LoadedEntry {
+	id: string;
+	slug: string;
+	status: string;
+	data: Record<string, unknown>;
+	cacheHint: { tags: string[]; lastModified?: Date };
+}
+
+/**
+ * Load one locale variant of each translation group, in one query per
+ * `SQL_BATCH_SIZE` chunk of groups.
+ *
+ * A group's variant is the first of `localeChain` it has, or else its lowest
+ * locale code: a reference names a translation group, so a target that exists
+ * only outside the chain is still a real reference. Groups with no surviving
+ * variant are absent from the result.
+ *
+ * The rows go through the same {@link mapRowToData} as a direct entry load, so
+ * a referenced entry's `data` carries the same dates, booleans and normalized
+ * media values a caller would get from `getEmDashEntry`. Bylines and taxonomy
+ * terms are not hydrated; each would cost a correlated subquery per row.
+ */
+export async function loadEntriesByGroups(
+	type: string,
+	translationGroups: string[],
+	options: { publishedOnly?: boolean; localeChain?: readonly string[] } = {},
+): Promise<LoadedEntry[]> {
+	if (translationGroups.length === 0) return [];
+	const db = await getDb();
+	const tableName = getTableName(type);
+	const statusFilter = options.publishedOnly ? sql`AND status = ${"published"}` : sql``;
+	const booleanFieldsSelect = foldedBooleanFieldsSelect(db, type);
+	const localeChain = options.localeChain ?? [];
+	const chainPosition =
+		localeChain.length > 0
+			? sql`CASE locale ${sql.join(
+					localeChain.map((locale, index) => sql`WHEN ${locale} THEN ${sql.lit(index)}`),
+					sql` `,
+				)} ELSE ${sql.lit(localeChain.length)} END,`
+			: sql``;
+
+	const entries: LoadedEntry[] = [];
+	try {
+		for (const chunk of chunks(translationGroups, SQL_BATCH_SIZE)) {
+			const result = await sql<Record<string, unknown>>`
+				SELECT * FROM (
+					SELECT *, ${booleanFieldsSelect},
+						ROW_NUMBER() OVER (
+							PARTITION BY translation_group ORDER BY ${chainPosition} locale ASC
+						) AS ${sql.ref(VARIANT_RANK_COLUMN)}
+					FROM ${sql.ref(tableName)}
+					WHERE translation_group IN (${sql.join(chunk.map((group) => sql`${group}`))})
+					AND deleted_at IS NULL
+					${statusFilter}
+				) AS variants
+				WHERE ${sql.ref(VARIANT_RANK_COLUMN)} = 1
+				ORDER BY translation_group ASC
+			`.execute(db);
+			const booleanFields = parseFoldedBooleanFields(result.rows[0]);
+			for (const row of result.rows) {
+				entries.push({
+					id: entryIdForRow(row),
+					slug: rowStr(row, "slug"),
+					status: rowStr(row, "status", "draft"),
+					data: mapRowToData(row, booleanFields),
+					cacheHint: {
+						tags: [rowStr(row, "id")],
+						lastModified: row.updated_at ? new Date(rowStr(row, "updated_at")) : undefined,
+					},
+				});
+			}
+		}
+	} catch (error) {
+		if (isMissingTableError(error)) return [];
+		throw error;
+	}
+	return entries;
+}
+
 function parseFoldedBooleanFields(row: Record<string, unknown> | undefined): Set<string> {
 	const raw = row?.[BOOLEAN_FIELDS_FOLDED_COLUMN];
 	let values: unknown;
@@ -743,6 +846,48 @@ function isWhereRange(value: WhereValue): value is WhereRange {
 	return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 
+/**
+ * Keys a `where` or `orderBy` can name that belong to the table rather than to
+ * a field. `slug` is one of them; {@link SYSTEM_COLUMNS} leaves it out because
+ * it is kept in `entry.data` for templates.
+ */
+const SYSTEM_QUERY_KEYS: ReadonlySet<string> = new Set([...SYSTEM_COLUMNS, "slug"]);
+
+/**
+ * The first of `keys` that names a reference field bound to a relation, or
+ * undefined.
+ *
+ * Such a field has no column: a `WHERE` on it fails with "no such column", which
+ * the catch below reads as an empty collection, and a field bound after its
+ * column existed answers from values it stopped writing. Both read to a template
+ * as "nothing matched", so the key has to be caught before the query is built.
+ *
+ * System columns are answered without a lookup, and the lookup itself is cached
+ * per request and in the schema object-cache namespace, so a render that filters
+ * by an ordinary field pays for this at most once between schema changes, and a
+ * render that filters by nothing never pays at all.
+ */
+async function findStoragelessQueryKey(
+	collection: string,
+	keys: string[],
+): Promise<string | undefined> {
+	const candidates = keys.filter((key) => !SYSTEM_QUERY_KEYS.has(key));
+	if (candidates.length === 0) return undefined;
+	const { getReferenceFieldMap } = await import("./references/field-map.js");
+	const bound = await getReferenceFieldMap(collection);
+	return candidates.find((key) => bound.has(key));
+}
+
+/**
+ * A boolean field owns an INTEGER column (`FIELD_TYPE_TO_COLUMN`) and its
+ * values are written as 0/1, so binding a native `true` against one is a type
+ * error on PostgreSQL. SQLite accepts the boolean and compares it as 1, which
+ * is why filtering by a boolean field only ever broke on one dialect.
+ */
+function bindableFilterValue(value: unknown): unknown {
+	return typeof value === "boolean" ? (value ? 1 : 0) : value;
+}
+
 /**
  * Build AND conditions for non-taxonomy field filters.
  * Returns an array of sql fragments; empty if no field filters apply.
@@ -763,16 +908,19 @@ function buildFieldConditions(
 		const ref = tablePrefix ? sql.ref(`${tablePrefix}.${key}`) : sql.ref(key);
 
 		if (isWhereRange(value)) {
-			if (value.gt !== undefined) conditions.push(sql`${ref} > ${value.gt}`);
-			if (value.gte !== undefined) conditions.push(sql`${ref} >= ${value.gte}`);
-			if (value.lt !== undefined) conditions.push(sql`${ref} < ${value.lt}`);
-			if (value.lte !== undefined) conditions.push(sql`${ref} <= ${value.lte}`);
+			const { gt, gte, lt, lte } = value;
+			if (gt !== undefined) conditions.push(sql`${ref} > ${bindableFilterValue(gt)}`);
+			if (gte !== undefined) conditions.push(sql`${ref} >= ${bindableFilterValue(gte)}`);
+			if (lt !== undefined) conditions.push(sql`${ref} < ${bindableFilterValue(lt)}`);
+			if (lte !== undefined) conditions.push(sql`${ref} <= ${bindableFilterValue(lte)}`);
 		} else if (Array.isArray(value)) {
 			if (value.length > 0) {
-				conditions.push(sql`${ref} IN (${sql.join(value.map((v) => sql`${v}`))})`);
+				conditions.push(
+					sql`${ref} IN (${sql.join(value.map((v) => sql`${bindableFilterValue(v)}`))})`,
+				);
 			}
 		} else {
-			conditions.push(sql`${ref} = ${value}`);
+			conditions.push(sql`${ref} = ${bindableFilterValue(value)}`);
 		}
 	}
 
@@ -1303,6 +1451,19 @@ export function emdashLoader(): LiveLoader<EntryData, EntryFilter, CollectionFil
 					}
 				}
 
+				const storagelessKey = await findStoragelessQueryKey(type, [
+					...Object.keys(fieldFilters),
+					...Object.keys(orderBy ?? {}),
+				]);
+				if (storagelessKey) {
+					const message = `Cannot filter or sort "${type}" by "${storagelessKey}": it is a reference field bound to a relation, and its links are not stored on the entry. Read them with getEmDashEntry(..., { references }) or getEmDashReferences().`;
+					// Warned as well as returned, the way the missing-column catch
+					// below warns: a template that renders `entries` without reading
+					// `error` would otherwise see the same empty list this replaced.
+					console.warn(`[emdash] where filter: ${message}`);
+					return { error: new Error(message) };
+				}
+
 				// A byline or taxonomy filter with no values matches nothing —
 				// short-circuit before building SQL (an empty `IN ()` is invalid
 				// SQL on both dialects).
@@ -1440,17 +1601,9 @@ export function emdashLoader(): LiveLoader<EntryData, EntryFilter, CollectionFil
 				const rows = hasMore ? result.rows.slice(0, limit) : result.rows;
 
 				// Map rows to entries
-				const i18nConfig = virtualConfig?.i18n;
-				const i18nEnabled = i18nConfig && i18nConfig.locales.length > 1;
 				const booleanFields = parseFoldedBooleanFields(rows[0]);
 				const entries = rows.map((row) => {
-					const slug = rowStr(row, "slug") || rowStr(row, "id");
-					const rowLocale = rowStr(row, "locale");
-					const shouldPrefix =
-						i18nEnabled &&
-						rowLocale !== "" &&
-						(rowLocale !== i18nConfig.defaultLocale || i18nConfig.prefixDefaultLocale);
-					const id = shouldPrefix ? `${rowLocale}/${slug}` : slug;
+					const id = entryIdForRow(row);
 					const data = mapRowToData(row, booleanFields);
 					stashFolded(data, row);
 					return {
@@ -1612,13 +1765,7 @@ export function emdashLoader(): LiveLoader<EntryData, EntryFilter, CollectionFil
 
 				const i18nConfig = virtualConfig?.i18n;
 				const i18nEnabled = i18nConfig && i18nConfig.locales.length > 1;
-				const entrySlug = rowStr(row, "slug") || rowStr(row, "id");
-				const entryLocale = rowStr(row, "locale");
-				const shouldPrefixEntry =
-					i18nEnabled &&
-					entryLocale !== "" &&
-					(entryLocale !== i18nConfig.defaultLocale || i18nConfig.prefixDefaultLocale);
-				const entryId = shouldPrefixEntry ? `${entryLocale}/${entrySlug}` : entrySlug;
+				const entryId = entryIdForRow(row);
 
 				// Preview mode: override content fields with revision data,
 				// keeping system metadata from the content table row.