emdash 0.40.0 → 0.41.0

package/src/registry/artifact-fetch.ts

@@ -4,14 +4,6 @@ import type { RequestOptions } from "node:https";
 import { resolveAndValidateExternalUrlTarget, SsrfError } from "../security/ssrf.js";
 
 const TRAILING_DOT = /\.+$/;
-const HEADER_END = new Uint8Array([13, 10, 13, 10]);
-const CRLF = new Uint8Array([13, 10]);
-const STATUS_LINE_RE = /^HTTP\/1\.[01] ([2-5][0-9]{2})(?: .*)?$/;
-const HEADER_NAME_RE = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/;
-const FOLDED_HEADER_RE = /^[ \t]/;
-const CONTENT_LENGTH_RE = /^(0|[1-9][0-9]*)$/;
-const CHUNK_SIZE_RE = /^[0-9A-Fa-f]+$/;
-const MAX_HEADER_BYTES = 32 * 1024;
 const LOCALHOST_HOSTNAMES = new Set([
 	"localhost",
 	"localhost.localdomain",
@@ -29,7 +21,8 @@ export interface RegistryArtifactTransportInput {
 export interface RegistryArtifactTransport {
 	fetch(input: RegistryArtifactTransportInput): Promise<{
 		response: Response;
-		connectedAddress: string;
+		/** Workers Fetch does not expose its connected peer; DNS validation still runs before dispatch. */
+		connectedAddress: string | null;
 	}>;
 }
 
@@ -130,7 +123,7 @@ export async function fetchRegistryArtifactUrl(
 		signal: options.signal,
 		maxResponseBytes: options.maxResponseBytes,
 	});
-	if (!target.addresses.includes(result.connectedAddress)) {
+	if (result.connectedAddress !== null && !target.addresses.includes(result.connectedAddress)) {
 		await result.response.body?.cancel().catch(() => undefined);
 		throw new Error("Registry artifact transport connected outside the validated address set");
 	}
@@ -138,86 +131,59 @@ export async function fetchRegistryArtifactUrl(
 }
 
 async function createRuntimeRegistryArtifactTransport(): Promise<RegistryArtifactTransport> {
-	try {
-		// @ts-ignore - virtual module
-		const sockets: unknown = await import("cloudflare:sockets");
-		const connect = objectProperty(sockets, "connect");
-		if (!isWorkerSocketConnect(connect)) throw new TypeError("Workers socket binding is invalid");
-		return createWorkersRegistryArtifactTransport(connect);
-	} catch {
-		return createNodeRegistryArtifactTransport();
-	}
-}
-
-export interface RegistryArtifactWorkerSocket {
-	readonly opened: Promise<unknown>;
-	readonly readable: ReadableStream<Uint8Array>;
-	readonly writable: WritableStream<Uint8Array>;
-	startTls(options: { expectedServerHostname: string }): RegistryArtifactWorkerSocket;
-	close(): Promise<void>;
+	return isCloudflareWorkersRuntime()
+		? createWorkersRegistryArtifactTransport()
+		: createNodeRegistryArtifactTransport();
 }
 
-export type RegistryArtifactWorkerSocketConnect = (
-	address: { hostname: string; port: number },
-	options: { secureTransport: "starttls"; allowHalfOpen: false },
-) => RegistryArtifactWorkerSocket;
-
 export function createWorkersRegistryArtifactTransport(
-	connect: RegistryArtifactWorkerSocketConnect,
+	workerFetch: typeof globalThis.fetch = globalThis.fetch,
 ): RegistryArtifactTransport {
 	return {
 		async fetch(input) {
-			let lastError: unknown;
-			for (const address of input.allowedAddresses) {
-				if (input.signal.aborted) throw new Error("Registry artifact request was aborted");
-				let socket: RegistryArtifactWorkerSocket | undefined;
-				let tls: RegistryArtifactWorkerSocket | undefined;
-				try {
-					socket = connect(
-						{ hostname: address, port: parseHttpsPort(input.url) },
-						{ secureTransport: "starttls", allowHalfOpen: false },
-					);
-					await abortable(socket.opened, input.signal, () => socket?.close());
-					tls = socket.startTls({
-						expectedServerHostname: stripIpv6Brackets(input.url.hostname),
-					});
-					await abortable(tls.opened, input.signal, () => tls?.close());
-					const writer = tls.writable.getWriter();
-					try {
-						await abortable(writer.write(buildHttpRequest(input.url)), input.signal, () =>
-							tls?.close(),
-						);
-					} finally {
-						writer.releaseLock();
-					}
-					const bytes = await readWorkerSocketResponse(
-						tls,
-						input.maxResponseBytes + MAX_HEADER_BYTES,
-						input.signal,
-					);
-					await tls.close().catch(() => undefined);
-					return {
-						response: parsedResponseToWebResponse(
-							parsePinnedHttpResponse(bytes, input.maxResponseBytes),
-						),
-						connectedAddress: address,
-					};
-				} catch (error) {
-					await Promise.all([
-						tls?.close().catch(() => undefined),
-						socket?.close().catch(() => undefined),
-					]);
-					if (input.signal.aborted) throw error;
-					lastError = error;
-				}
-			}
-			throw new Error("Registry artifact transport could not connect to an approved address", {
-				cause: lastError,
+			const response = await workerFetch(input.url, {
+				redirect: "manual",
+				signal: input.signal,
+				headers: { "Accept-Encoding": "identity" },
 			});
+			return {
+				response: limitResponseBody(response, input.maxResponseBytes),
+				connectedAddress: null,
+			};
 		},
 	};
 }
 
+function isCloudflareWorkersRuntime(): boolean {
+	return (
+		typeof navigator !== "undefined" &&
+		typeof navigator.userAgent === "string" &&
+		navigator.userAgent.includes("Cloudflare-Workers")
+	);
+}
+
+function limitResponseBody(response: Response, maxBytes: number): Response {
+	if (!response.body) return response;
+	let received = 0;
+	const body = response.body.pipeThrough(
+		new TransformStream<Uint8Array, Uint8Array>({
+			transform(chunk, controller) {
+				received += chunk.byteLength;
+				if (received > maxBytes) {
+					controller.error(new RangeError("Registry artifact response exceeds its byte limit"));
+					return;
+				}
+				controller.enqueue(chunk);
+			},
+		}),
+	);
+	return new Response(body, {
+		status: response.status,
+		statusText: response.statusText,
+		headers: response.headers,
+	});
+}
+
 export type RegistryArtifactNodeRequest = (
 	options: RequestOptions,
 	callback: (response: IncomingMessage) => void,
@@ -315,71 +281,6 @@ interface ParsedHttpResponse {
 	body: Uint8Array;
 }
 
-function parsePinnedHttpResponse(bytes: Uint8Array, maxResponseBytes: number): ParsedHttpResponse {
-	const headerEnd = findSequence(bytes, HEADER_END, 0);
-	if (headerEnd === -1 || headerEnd > MAX_HEADER_BYTES) {
-		throw new Error("Registry artifact response headers are invalid or too large");
-	}
-	const headerText = new TextDecoder("utf-8", { fatal: true }).decode(bytes.subarray(0, headerEnd));
-	const lines = headerText.split("\r\n");
-	const statusMatch = STATUS_LINE_RE.exec(lines.shift() ?? "");
-	if (!statusMatch) throw new Error("Registry artifact response status line is invalid");
-	const headers = new Headers();
-	const rawHeaders = new Map<string, string[]>();
-	for (const line of lines) {
-		if (FOLDED_HEADER_RE.test(line)) {
-			throw new Error("Registry artifact response uses folded headers");
-		}
-		const separator = line.indexOf(":");
-		if (separator < 1) throw new Error("Registry artifact response header is invalid");
-		const name = line.slice(0, separator);
-		const value = line.slice(separator + 1).trim();
-		if (!HEADER_NAME_RE.test(name) || containsInvalidHeaderValue(value)) {
-			throw new Error("Registry artifact response header is invalid");
-		}
-		const normalized = name.toLowerCase();
-		const values = rawHeaders.get(normalized) ?? [];
-		values.push(value);
-		rawHeaders.set(normalized, values);
-		headers.append(name, value);
-	}
-	const contentEncoding = rawHeaders.get("content-encoding");
-	if (
-		contentEncoding &&
-		(contentEncoding.length !== 1 || contentEncoding[0]?.toLowerCase() !== "identity")
-	) {
-		throw new Error("Registry artifact response content encoding is unsupported");
-	}
-	const contentLength = rawHeaders.get("content-length");
-	const transferEncoding = rawHeaders.get("transfer-encoding");
-	if (contentLength && transferEncoding) {
-		throw new Error("Registry artifact response framing is ambiguous");
-	}
-	const bodyBytes = bytes.subarray(headerEnd + HEADER_END.length);
-	let body: Uint8Array;
-	if (transferEncoding) {
-		if (transferEncoding.length !== 1 || transferEncoding[0]?.toLowerCase() !== "chunked") {
-			throw new Error("Registry artifact response transfer encoding is unsupported");
-		}
-		body = decodeChunkedBody(bodyBytes, maxResponseBytes);
-	} else if (contentLength) {
-		if (contentLength.length !== 1 || !CONTENT_LENGTH_RE.test(contentLength[0])) {
-			throw new Error("Registry artifact response content length is invalid");
-		}
-		const length = Number(contentLength[0]);
-		if (!Number.isSafeInteger(length) || length !== bodyBytes.byteLength) {
-			throw new Error("Registry artifact response body length does not match its framing");
-		}
-		body = new Uint8Array(bodyBytes);
-	} else {
-		body = new Uint8Array(bodyBytes);
-	}
-	if (body.byteLength > maxResponseBytes) {
-		throw new RangeError("Registry artifact response exceeds its byte limit");
-	}
-	return { status: Number(statusMatch[1]), headers, body };
-}
-
 function parsedResponseToWebResponse(parsed: ParsedHttpResponse): Response {
 	const bodyAllowed = ![204, 205, 304].includes(parsed.status);
 	let body: ArrayBuffer | null = null;
@@ -393,95 +294,6 @@ function parsedResponseToWebResponse(parsed: ParsedHttpResponse): Response {
 	});
 }
 
-function buildHttpRequest(url: URL): Uint8Array {
-	return new TextEncoder().encode(
-		[
-			`GET ${url.pathname}${url.search} HTTP/1.1`,
-			`Host: ${url.host}`,
-			"Connection: close",
-			"Accept-Encoding: identity",
-			"",
-			"",
-		].join("\r\n"),
-	);
-}
-
-async function readWorkerSocketResponse(
-	socket: RegistryArtifactWorkerSocket,
-	maximumBytes: number,
-	signal: AbortSignal,
-): Promise<Uint8Array> {
-	const reader = socket.readable.getReader();
-	const chunks: Uint8Array[] = [];
-	let total = 0;
-	try {
-		for (;;) {
-			const next = await abortable(reader.read(), signal, () => socket.close());
-			if (next.done) break;
-			total += next.value.byteLength;
-			if (total > maximumBytes) {
-				throw new RangeError("Registry artifact response exceeds its byte limit");
-			}
-			chunks.push(next.value);
-		}
-	} finally {
-		reader.releaseLock();
-	}
-	return concatBytes(chunks, total);
-}
-
-function decodeChunkedBody(bytes: Uint8Array, maximumBytes: number): Uint8Array {
-	const chunks: Uint8Array[] = [];
-	let offset = 0;
-	let total = 0;
-	for (;;) {
-		const lineEnd = findSequence(bytes, CRLF, offset);
-		if (lineEnd === -1 || lineEnd - offset > 128) {
-			throw new Error("Registry artifact chunk size line is invalid");
-		}
-		const sizeText = new TextDecoder().decode(bytes.subarray(offset, lineEnd)).split(";", 1)[0];
-		if (!sizeText || !CHUNK_SIZE_RE.test(sizeText)) {
-			throw new Error("Registry artifact chunk size is invalid");
-		}
-		const size = Number.parseInt(sizeText, 16);
-		if (!Number.isSafeInteger(size)) throw new Error("Registry artifact chunk size is invalid");
-		offset = lineEnd + CRLF.length;
-		if (size === 0) {
-			if (
-				offset + CRLF.length !== bytes.length ||
-				bytes[offset] !== 13 ||
-				bytes[offset + 1] !== 10
-			) {
-				throw new Error("Registry artifact chunk trailer is invalid");
-			}
-			break;
-		}
-		if (offset + size + CRLF.length > bytes.length) {
-			throw new Error("Registry artifact chunk body is truncated");
-		}
-		if (bytes[offset + size] !== 13 || bytes[offset + size + 1] !== 10) {
-			throw new Error("Registry artifact chunk delimiter is invalid");
-		}
-		total += size;
-		if (total > maximumBytes) {
-			throw new RangeError("Registry artifact response exceeds its byte limit");
-		}
-		chunks.push(new Uint8Array(bytes.subarray(offset, offset + size)));
-		offset += size + CRLF.length;
-	}
-	return concatBytes(chunks, total);
-}
-
-function findSequence(bytes: Uint8Array, sequence: Uint8Array, start: number): number {
-	outer: for (let offset = start; offset <= bytes.length - sequence.length; offset += 1) {
-		for (let index = 0; index < sequence.length; index += 1) {
-			if (bytes[offset + index] !== sequence[index]) continue outer;
-		}
-		return offset;
-	}
-	return -1;
-}
-
 function concatBytes(chunks: readonly Uint8Array[], total: number): Uint8Array {
 	const bytes = new Uint8Array(total);
 	let offset = 0;
@@ -492,14 +304,6 @@ function concatBytes(chunks: readonly Uint8Array[], total: number): Uint8Array {
 	return bytes;
 }
 
-function containsInvalidHeaderValue(value: string): boolean {
-	for (const character of value) {
-		const code = character.codePointAt(0)!;
-		if (code === 0 || code === 10 || code === 13) return true;
-	}
-	return false;
-}
-
 function parseHttpsPort(url: URL): number {
 	const port = url.port === "" ? 443 : Number(url.port);
 	if (!Number.isSafeInteger(port) || port < 1 || port > 65_535) {
@@ -511,33 +315,3 @@ function parseHttpsPort(url: URL): number {
 function stripIpv6Brackets(hostname: string): string {
 	return hostname.startsWith("[") && hostname.endsWith("]") ? hostname.slice(1, -1) : hostname;
 }
-
-function objectProperty(value: unknown, key: string): unknown {
-	if (typeof value !== "object" || value === null) return undefined;
-	return Object.getOwnPropertyDescriptor(value, key)?.value;
-}
-
-function isWorkerSocketConnect(value: unknown): value is RegistryArtifactWorkerSocketConnect {
-	return typeof value === "function";
-}
-
-async function abortable<T>(
-	operation: Promise<T>,
-	signal: AbortSignal,
-	onAbort: () => void | Promise<void>,
-): Promise<T> {
-	if (signal.aborted) throw new Error("Registry artifact request was aborted");
-	let abort: (() => void) | undefined;
-	const aborted = new Promise<never>((_resolve, reject) => {
-		abort = () => {
-			void onAbort();
-			reject(new Error("Registry artifact request was aborted"));
-		};
-		signal.addEventListener("abort", abort, { once: true });
-	});
-	try {
-		return await Promise.race([operation, aborted]);
-	} finally {
-		if (abort) signal.removeEventListener("abort", abort);
-	}
-}

package/src/schema/registry.ts

@@ -11,6 +11,7 @@ import { ulid } from "ulidx";
 
 import { refreshDevTypes } from "../astro/dev-typegen.js";
 import {
+	columnExists,
 	currentTimestamp,
 	isPostgres,
 	listTablesLike,
@@ -65,6 +66,7 @@ import {
 	FIELD_TYPE_TO_COLUMN,
 	REPEATER_SUB_FIELD_TYPES,
 	isIndexableFieldType,
+	isStoragelessField,
 	RESERVED_FIELD_SLUGS,
 	RESERVED_COLLECTION_SLUGS,
 	MAX_BLOCKS_ITEMS,
@@ -152,15 +154,32 @@ const UNORDERED_COLLECTION_RANK = 2147483647;
  */
 const collectionOrder = sql<number>`coalesce(sort_order, ${sql.lit(UNORDERED_COLLECTION_RANK)})`;
 
-function assertIndexableField(type: FieldType, indexed: boolean | undefined, slug: string): void {
-	if (indexed && !isIndexableFieldType(type)) {
+function assertIndexableField(
+	field: { type: FieldType; validation?: FieldValidation | null },
+	indexed: boolean | undefined,
+	slug: string,
+): void {
+	if (!indexed) return;
+	if (!isIndexableFieldType(field.type)) {
 		throw new SchemaError(
-			`Field "${slug}" cannot be indexed because type "${type}" is not a scalar query type`,
+			`Field "${slug}" cannot be indexed because type "${field.type}" is not a scalar query type`,
+			"FIELD_NOT_INDEXABLE",
+		);
+	}
+	if (isStoragelessField(field)) {
+		throw new SchemaError(
+			`Field "${slug}" cannot be indexed because it stores no column to index`,
 			"FIELD_NOT_INDEXABLE",
 		);
 	}
 }
 
+/** A field record's `validation`, which the package carries as any JSON value. */
+function importFieldValidation(value: unknown): FieldValidation | undefined {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined;
+	return value;
+}
+
 function isCollectionSupport(value: unknown): value is CollectionSupport {
 	return typeof value === "string" && VALID_COLLECTION_SUPPORTS.has(value);
 }
@@ -598,7 +617,7 @@ export class SchemaRegistry {
 		const normalizedFields: CreateFieldInput[] = [];
 		for (const field of fields) {
 			this.validateSlug(field.slug, "field");
-			assertIndexableField(field.type, field.indexed, field.slug);
+			assertIndexableField(field, field.indexed, field.slug);
 			if (RESERVED_FIELD_SLUGS.includes(field.slug)) {
 				throw new SchemaError(`Field slug "${field.slug}" is reserved`, "RESERVED_SLUG");
 			}
@@ -961,7 +980,8 @@ export class SchemaRegistry {
 					"INVALID_FIELD_TYPE",
 				);
 			}
-			assertIndexableField(field.type, field.indexed, field.slug);
+			const validation = importFieldValidation(field.validation);
+			assertIndexableField({ type: field.type, validation }, field.indexed, field.slug);
 			if (field.indexed) this.getFieldIndexName(field.id);
 			return {
 				slug: field.slug,
@@ -969,6 +989,7 @@ export class SchemaRegistry {
 				type: field.type,
 				required: field.required,
 				defaultValue: field.defaultValue,
+				validation,
 			};
 		});
 	}
@@ -1105,16 +1126,29 @@ export class SchemaRegistry {
 	}
 
 	/**
-	 * Delete a collection
+	 * The content guard {@link deleteCollection} refuses on, on its own.
+	 *
+	 * A caller that has to cascade before deleting — relations, whose edges point
+	 * at rows the drop is about to take — needs to know the delete is acceptable
+	 * before it changes anything, since the cascade cannot be rolled back on D1.
 	 */
-	async deleteCollection(slug: string, options?: { force?: boolean }): Promise<void> {
+	async assertCollectionDeletable(slug: string, options?: { force?: boolean }): Promise<void> {
+		if (options?.force) return;
 		const existing = await this.getCollection(slug);
-		if (existing && !options?.force && (await this.collectionHasContent(slug))) {
+		if (existing && (await this.collectionHasContent(slug))) {
 			throw new SchemaError(
 				`Collection "${slug}" has content. Use force: true to delete.`,
 				"COLLECTION_HAS_CONTENT",
 			);
 		}
+	}
+
+	/**
+	 * Delete a collection
+	 */
+	async deleteCollection(slug: string, options?: { force?: boolean }): Promise<void> {
+		await this.assertCollectionDeletable(slug, options);
+		const existing = await this.getCollection(slug);
 		const activated = await deleteActivatedMediaUsageCollection(this.db, {
 			collectionId: existing?.id,
 			collectionSlug: slug,
@@ -1230,7 +1264,7 @@ export class SchemaRegistry {
 				? await this.normalizeBlocksFieldValidation(collectionSlug, input, undefined, this.db)
 				: input.validation;
 		const columnType = FIELD_TYPE_TO_COLUMN[input.type];
-		assertIndexableField(input.type, input.indexed, input.slug);
+		assertIndexableField(input, input.indexed, input.slug);
 
 		// Get max sort order
 		const maxSort = await this.db
@@ -1273,17 +1307,21 @@ export class SchemaRegistry {
 					.execute();
 				schemaMutated = true;
 
-				// Add column to content table — pass trx to stay on the same connection
-				await this.addColumn(
-					collectionSlug,
-					input.slug,
-					input.type,
-					{
-						required: input.required,
-						defaultValue: input.defaultValue,
-					},
-					trx,
-				);
+				// Add column to content table — pass trx to stay on the same connection.
+				// A storage-less field persists no column; its values live in a side
+				// table (see `isStoragelessField`). Insert the field row only.
+				if (!isStoragelessField(input)) {
+					await this.addColumn(
+						collectionSlug,
+						input.slug,
+						input.type,
+						{
+							required: input.required,
+							defaultValue: input.defaultValue,
+						},
+						trx,
+					);
+				}
 
 				if (input.indexed) {
 					await this.createFieldIndex(collectionSlug, id, input.slug, trx);
@@ -1390,9 +1428,29 @@ export class SchemaRegistry {
 								field,
 								trx,
 							)
-						: input.validation;
+						: input.validation !== undefined
+							? input.validation
+							: field.validation;
 
 				if (input.type !== undefined && input.type !== field.type) {
+					// A change into or out of storage-less is never a no-op column change:
+					// string -> reference both map to TEXT and would slip past the affinity
+					// check below, yet one has a column and the other does not. An unwired
+					// reference field is column-backed, so its refusal comes from the
+					// text-alias check instead.
+					const storagelessBefore = isStoragelessField(field);
+					const storagelessAfter = isStoragelessField({
+						type: input.type,
+						validation: nextValidation,
+					});
+					if (storagelessBefore !== storagelessAfter) {
+						throw new SchemaError(
+							`Cannot change field "${fieldSlug}" in collection "${collectionSlug}" between ` +
+								`storage-less and column-backed types ("${field.type}" -> "${input.type}").`,
+							"FIELD_TYPE_COLUMN_CHANGE",
+						);
+					}
+
 					const newColumnType = FIELD_TYPE_TO_COLUMN[input.type];
 					if (newColumnType !== field.columnType) {
 						throw new SchemaError(
@@ -1464,7 +1522,11 @@ export class SchemaRegistry {
 				if (input.options !== undefined) updates.options = JSON.stringify(input.options);
 				if (input.sortOrder !== undefined) updates.sort_order = input.sortOrder;
 
-				assertIndexableField(nextType, input.indexed ?? field.indexed, fieldSlug);
+				assertIndexableField(
+					{ type: nextType, validation: nextValidation },
+					input.indexed ?? field.indexed,
+					fieldSlug,
+				);
 				if (Object.keys(updates).length === 0) return field;
 
 				activeCoverageInvalidated = await invalidateContentMediaUsageSchemaChange(
@@ -1636,8 +1698,19 @@ export class SchemaRegistry {
 					await this.dropFieldIndex(field.id, trx);
 				}
 
-				// Drop column from content table — safe now because FTS triggers are gone
-				await this.dropColumn(collectionSlug, fieldSlug, trx);
+				// Drop column from content table — safe now because FTS triggers are gone.
+				// Whether a field is storage-less is a property of the row rather than of
+				// its type: reference fields created before they became storage-less
+				// still carry a column, and skipping the DDL would strand it and block
+				// the slug from ever being reused.
+				const hasColumn = await columnExists(
+					trx,
+					this.getTableName(collectionSlug),
+					this.getColumnName(fieldSlug),
+				);
+				if (hasColumn) {
+					await this.dropColumn(collectionSlug, fieldSlug, trx);
+				}
 			});
 			if (activeCoverageInvalidated) {
 				await invalidateContentMediaUsageSchemaChange(this.db, collectionSlug);
@@ -1777,6 +1850,8 @@ export class SchemaRegistry {
 		if (options.ifNotExists) table = table.ifNotExists();
 
 		for (const field of fields) {
+			if (isStoragelessField(field)) continue;
+
 			const columnName = this.getColumnName(field.slug);
 			const columnType = COLUMN_TYPE_TO_DATA_TYPE[FIELD_TYPE_TO_COLUMN[field.type]];
 			table = table.addColumn(columnName, columnType, (column) => {

package/src/schema/types.ts

@@ -99,6 +99,48 @@ export const FIELD_TYPE_TO_COLUMN: Record<FieldType, ColumnType> = {
 
 export const MAX_BLOCKS_ITEMS = 100;
 
+/**
+ * Field types that *can* persist no `ec_*` column — see `isStoragelessField`
+ * for whether a given row actually does. The `FIELD_TYPE_TO_COLUMN` entry above
+ * is retained deliberately: it doubles as the `isFieldType` guard.
+ */
+export const STORAGELESS_FIELD_TYPES: ReadonlySet<string> = new Set<FieldType>(["reference"]);
+
+/**
+ * Whether a field row keeps its values outside the content table.
+ *
+ * Storage-less is a property of the row, not of the type. A `reference` field
+ * is storage-less once it is bound to a relation: the selection lives as edges
+ * in `_emdash_content_references`. A reference field created before relations
+ * existed — or one whose target collection could not be resolved — still owns a
+ * TEXT column holding an entry id, and behaves like a string field until
+ * something wires it.
+ */
+export function isStoragelessField(field: {
+	type: string;
+	validation?: FieldValidation | null;
+}): boolean {
+	if (!STORAGELESS_FIELD_TYPES.has(field.type)) return false;
+	return typeof field.validation?.relation === "string" && field.validation.relation.length > 0;
+}
+
+/**
+ * `isStoragelessField` for a raw `_emdash_fields` row, whose `validation` is
+ * unparsed JSON. Malformed JSON reads as unwired: a field nothing can resolve a
+ * relation for keeps its column.
+ */
+export function isStoragelessFieldRow(row: { type: string; validation: string | null }): boolean {
+	if (!STORAGELESS_FIELD_TYPES.has(row.type) || !row.validation) return false;
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(row.validation);
+	} catch {
+		return false;
+	}
+	if (typeof parsed !== "object" || parsed === null) return false;
+	return isStoragelessField({ type: row.type, validation: parsed });
+}
+
 /**
  * Features a collection can support
  */
@@ -166,6 +208,19 @@ export interface FieldValidation {
 	minItems?: number; // For repeater fields
 	maxItems?: number; // For repeater fields
 	allowedMimeTypes?: string[];
+	/** Reference fields: the relation's slug. */
+	relation?: string;
+	/**
+	 * Reference fields: which end of the relation this collection sits on.
+	 * `parent` picks children and controls their order; `child` picks parents
+	 * and is unordered, since `sort_order` is scoped to a parent.
+	 */
+	relationSide?: "parent" | "child";
+	/** Reference fields: the collection on the *other* end (derived from the
+	 * relation and the side, denormalized here). */
+	targetCollection?: string;
+	/** Reference fields: allow selecting more than one entry (UI constraint). */
+	multiple?: boolean;
 	allowedTypes?: string[]; // For blocks fields
 	retiredTypes?: string[]; // Server-owned retained types for blocks fields
 }
@@ -435,6 +490,9 @@ export const RESERVED_COLLECTION_SLUGS = [
 	// Shadowed by the static POST /schema/collections/reorder route: a
 	// collection with this slug could never be addressed at its own URL.
 	"reorder",
+	// Shadowed by the static /content-types/relations admin route, for the same
+	// reason: a collection with this slug would be unreachable in the admin.
+	"relations",
 ];
 
 /**