emdash 0.40.1 → 0.42.0

package/src/api/handlers/staged-references.ts

@@ -0,0 +1,208 @@
+import type { Kysely } from "kysely";
+
+import { RelationRepository } from "../../database/repositories/relation.js";
+import { RevisionRepository } from "../../database/repositories/revision.js";
+import type { Database } from "../../database/types.js";
+import {
+	STAGED_REFERENCES_KEY,
+	type StagedReferenceBaselines,
+	type StagedReferences,
+} from "../../references/staged.js";
+import type { ApiResult } from "../types.js";
+import { validateOppositeSideLimit, writeReferenceSelection } from "./relations.js";
+import {
+	referenceFieldConstraints,
+	validateReferenceSelection,
+	type ReferenceFieldConstraints,
+} from "./validate-references.js";
+
+export {
+	mergeStagedReferenceBaselines,
+	mergeStagedReferences,
+	pageStagedGroups,
+	readStagedReferenceBaselines,
+	readStagedReferences,
+	REFERENCE_PAGE_LIMIT,
+	REFERENCE_PAGE_MAX_LIMIT,
+	STAGED_REFERENCES_BASELINE_KEY,
+	STAGED_REFERENCES_KEY,
+} from "../../references/staged.js";
+export type {
+	PageOfGroups,
+	StagedReferenceBaselines,
+	StagedReferences,
+} from "../../references/staged.js";
+
+/** One bound field's live selection as translation groups. */
+async function liveFieldSelection(
+	repo: RelationRepository,
+	field: ReferenceFieldConstraints,
+	entryGroup: string,
+): Promise<string[]> {
+	const links =
+		field.relationSide === "child"
+			? await repo.getParents(field.relation, entryGroup)
+			: await repo.getChildren(field.relation, entryGroup);
+	return links.map((link) => (field.relationSide === "child" ? link.parentGroup : link.childGroup));
+}
+
+/**
+ * Re-check what publication is about to make live against the relation's current
+ * cardinality.
+ *
+ * A draft can sit unpublished across a schema edit that makes its field required
+ * or narrows the relation's limits, and across another entry claiming what it
+ * selected. It is publication — not the save that staged it — that has to hold
+ * the line on both ends. So this walks the collection's bound fields rather than
+ * the staged keys: a field added as required after the entry was written appears
+ * in no existing draft, and iterating `staged` would never reach it. A field the
+ * draft does stage needs no link read.
+ */
+export async function validateStagedReferences(
+	db: Kysely<Database>,
+	collection: string,
+	staged: StagedReferences,
+	entryGroup: string,
+	baselines?: StagedReferenceBaselines,
+): Promise<ApiResult<true>> {
+	const repo = new RelationRepository(db);
+	for (const field of (await referenceFieldConstraints(db, collection)).values()) {
+		const isStaged = Object.hasOwn(staged, field.slug);
+		let groups = isStaged ? (staged[field.slug] ?? []) : undefined;
+		const baseline = baselines?.[field.slug];
+		if (groups && baseline) {
+			const live = await liveFieldSelection(repo, field, entryGroup);
+			groups = applyReferenceDiff(baseline, groups, live);
+		}
+		groups ??= await liveFieldSelection(repo, field, entryGroup);
+		const valid = validateReferenceSelection(field, groups);
+		if (!valid.success) return valid;
+
+		// Only a staged selection can have gone stale: a live one is already
+		// within the limits it was written under.
+		if (!isStaged || field.relationId === null) continue;
+		const far = await validateOppositeSideLimit(db, {
+			relationId: field.relationId,
+			farLimit: field.maxOpposite,
+			side: field.relationSide,
+			entryGroup,
+			groups,
+		});
+		if (!far.success) return far;
+	}
+	return { success: true, data: true };
+}
+
+/**
+ * The live selection, in the same shape a draft stages: every bound reference
+ * field on the collection, by field slug, as translation groups.
+ *
+ * One link read per bound field. Used where both selections have to be
+ * comparable — the live and draft sides of a compare — never on a render path.
+ */
+export async function liveReferenceSelection(
+	db: Kysely<Database>,
+	collection: string,
+	entryGroup: string,
+): Promise<StagedReferences> {
+	const repo = new RelationRepository(db);
+	const selection: StagedReferences = {};
+	for (const field of (await referenceFieldConstraints(db, collection)).values()) {
+		selection[field.slug] = await liveFieldSelection(repo, field, entryGroup);
+	}
+	return selection;
+}
+
+/**
+ * Compute the selection that results from applying the staged-versus-baseline
+ * diff on top of the current live selection.
+ *
+ * Additions and removals made in the draft win. Items the draft left unchanged
+ * follow the current live selection, preserving additions and removals made
+ * from the relation's opposite end.
+ */
+function applyReferenceDiff(baseline: string[], staged: string[], live: string[]): string[] {
+	const baselineSet = new Set(baseline);
+	const stagedSet = new Set(staged);
+	const liveSet = new Set(live);
+	const additionSet = new Set(staged.filter((group) => !baselineSet.has(group)));
+	const removalSet = new Set(baseline.filter((group) => !stagedSet.has(group)));
+
+	const result: string[] = [];
+	const seen = new Set<string>();
+	for (const group of staged) {
+		if ((!additionSet.has(group) && !liveSet.has(group)) || seen.has(group)) continue;
+		result.push(group);
+		seen.add(group);
+	}
+	for (const group of live) {
+		if (removalSet.has(group) || seen.has(group)) continue;
+		result.push(group);
+		seen.add(group);
+	}
+	return result;
+}
+
+/**
+ * Record the complete live selection in the revision publication just made live.
+ *
+ * A draft stages only the fields its saves named, and a revision written from
+ * the columns stages none. Restoring either would otherwise leave whatever was
+ * published after it linked in the fields it does not carry.
+ */
+export async function recordPublishedReferences(
+	db: Kysely<Database>,
+	collection: string,
+	revisionId: string,
+	entryGroup: string,
+): Promise<void> {
+	const selection = await liveReferenceSelection(db, collection, entryGroup);
+	if (Object.keys(selection).length === 0) return;
+	await new RevisionRepository(db).mergeData(revisionId, { [STAGED_REFERENCES_KEY]: selection });
+}
+
+/**
+ * Promote a staged selection to live links.
+ *
+ * A field slug the collection no longer carries as a bound reference field is
+ * skipped: the revision outlived the field, and there is no relation left to
+ * write into.
+ *
+ * When `baselines` are provided, each staged field is promoted as a diff
+ * against its baseline rather than as a wholesale replacement. That prevents a
+ * draft saved before a concurrent opposite-end publish from undoing the links
+ * that publish added or removed.
+ */
+export async function applyStagedReferences(
+	db: Kysely<Database>,
+	collection: string,
+	entryGroup: string,
+	staged: StagedReferences,
+	baselines?: StagedReferenceBaselines,
+): Promise<void> {
+	const constraints = await referenceFieldConstraints(db, collection);
+	const repo = new RelationRepository(db);
+	for (const [fieldSlug, groups] of Object.entries(staged)) {
+		const field = constraints.get(fieldSlug);
+		if (!field) continue;
+
+		const baseline = baselines?.[fieldSlug];
+		let selection: string[];
+		if (baseline) {
+			const live = await liveFieldSelection(repo, field, entryGroup);
+			selection = applyReferenceDiff(baseline, groups, live);
+		} else {
+			// Older drafts and restored live revisions carry no baseline; keep the
+			// previous wholesale-replacement behavior rather than silently changing
+			// their semantics.
+			selection = groups;
+		}
+
+		await writeReferenceSelection(db, {
+			relation: field.relation,
+			side: field.relationSide,
+			entryGroup,
+			groups: selection,
+		});
+	}
+}

package/src/api/handlers/update-check.ts

@@ -0,0 +1,236 @@
+/**
+ * Core update status handler.
+ *
+ * Caches the publish times of stable `emdash` releases from the npm
+ * registry in the options table, and reports the newest release that has
+ * been public for the minimum release age when it is newer than the
+ * running `VERSION`. A stale or missing cache schedules a deferred refresh.
+ */
+
+import type { Kysely } from "kysely";
+
+import { after } from "../../after.js";
+import { OptionsRepository } from "../../database/repositories/options.js";
+import type { Database } from "../../database/types.js";
+import { parseDurationSeconds } from "../../registry/config.js";
+import { VERSION } from "../../version.js";
+import { ErrorCode } from "../errors.js";
+import type { ApiResult } from "../types.js";
+
+/** Options-table key for the cached registry result. */
+export const CORE_UPDATE_OPTION = "emdash:core_update_check";
+
+/** Check the registry at most once per day, whether or not the check succeeds. */
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+
+/** npm packument for `emdash`: the `latest` dist-tag and each version's publish time. */
+const REGISTRY_URL = "https://registry.npmjs.org/emdash";
+
+/** Default time a release must be public before admins are told about it. */
+export const DEFAULT_MINIMUM_RELEASE_AGE = "24h";
+
+const REGISTRY_TIMEOUT_MS = 10_000;
+
+/** Cached registry state, stored in the options table. */
+interface CoreUpdateCache {
+	/** Publish time (ISO) of each non-deprecated stable release up to the `latest` dist-tag. */
+	releases: Record<string, string>;
+	/** ISO timestamp of the last registry check. */
+	checkedAt: string;
+}
+
+export interface CoreUpdateStatus {
+	/** The running EmDash version (`"dev"` in uncompiled dev/test runs). */
+	current: string;
+	/**
+	 * Newest stable release that has been public for the minimum release
+	 * age, or null when no check has completed yet.
+	 */
+	latest: string | null;
+	updateAvailable: boolean;
+	/** ISO timestamp of the last registry check, if any. */
+	checkedAt: string | null;
+}
+
+const SEMVER_RE = /^(\d+)\.(\d+)\.(\d+)(-.+)?$/;
+const STABLE_RE = /^\d+\.\d+\.\d+$/;
+
+/**
+ * True when `latest` is a strictly newer release than `current`.
+ *
+ * Handles plain `major.minor.patch` versions. Anything unparsable —
+ * including the `"dev"` fallback version — compares as "not newer", so
+ * dev/test runs never show the banner. On an equal base version, a stable
+ * release is newer than a prerelease of it, so a site running
+ * `0.24.0-beta.1` is notified when `0.24.0` ships. Prerelease identifiers
+ * are not compared to each other.
+ */
+export function isNewerVersion(latest: string, current: string): boolean {
+	const l = SEMVER_RE.exec(latest);
+	const c = SEMVER_RE.exec(current);
+	if (!l || !c) return false;
+	for (let i = 1; i <= 3; i++) {
+		const a = Number(l[i]);
+		const b = Number(c[i]);
+		if (a !== b) return a > b;
+	}
+	return !l[4] && !!c[4];
+}
+
+function field(value: unknown, key: string): unknown {
+	return typeof value === "object" && value !== null && Object.hasOwn(value, key)
+		? (Reflect.get(value, key) as unknown)
+		: undefined;
+}
+
+/**
+ * Fetch the stable releases and their publish times from the npm registry
+ * and cache them. Exported for tests; production callers go through
+ * `handleCoreUpdateStatus`, which defers this via `after()`.
+ */
+export async function refreshCoreUpdateCache(
+	db: Kysely<Database>,
+	fetchImpl: typeof fetch = fetch,
+): Promise<void> {
+	const response = await fetchImpl(REGISTRY_URL, {
+		headers: { accept: "application/json" },
+		signal: AbortSignal.timeout(REGISTRY_TIMEOUT_MS),
+	});
+	if (!response.ok) {
+		throw new Error(`registry responded ${response.status}`);
+	}
+	const body: unknown = await response.json();
+	const latest = field(field(body, "dist-tags"), "latest");
+	if (typeof latest !== "string" || !STABLE_RE.test(latest)) {
+		throw new Error("registry response missing a valid version");
+	}
+	const time = field(body, "time");
+	const versions = field(body, "versions");
+	const releases: Record<string, string> = {};
+	if (typeof time === "object" && time !== null) {
+		for (const [version, publishedAt] of Object.entries(time)) {
+			if (!STABLE_RE.test(version) || isNewerVersion(version, latest)) continue;
+			const manifest = field(versions, version);
+			if (manifest === undefined || field(manifest, "deprecated") !== undefined) continue;
+			if (typeof publishedAt !== "string" || Number.isNaN(Date.parse(publishedAt))) continue;
+			releases[version] = publishedAt;
+		}
+	}
+	if (!releases[latest]) {
+		throw new Error("registry response missing a publish time for the latest version");
+	}
+	const cache: CoreUpdateCache = { releases, checkedAt: new Date().toISOString() };
+	await new OptionsRepository(db).set(CORE_UPDATE_OPTION, cache);
+}
+
+function parseCache(value: unknown): CoreUpdateCache | null {
+	const releases = field(value, "releases");
+	const checkedAt = field(value, "checkedAt");
+	if (typeof releases !== "object" || releases === null || typeof checkedAt !== "string") {
+		return null;
+	}
+	// An unparsable checkedAt would make the staleness math NaN (never
+	// stale), freezing a corrupt cache forever — treat it as no cache so
+	// the next request schedules a refresh that overwrites it.
+	if (Number.isNaN(Date.parse(checkedAt))) return null;
+	const valid: Record<string, string> = {};
+	for (const [version, publishedAt] of Object.entries(releases)) {
+		if (
+			STABLE_RE.test(version) &&
+			typeof publishedAt === "string" &&
+			!Number.isNaN(Date.parse(publishedAt))
+		) {
+			valid[version] = publishedAt;
+		}
+	}
+	return { releases: valid, checkedAt };
+}
+
+/** The newest release published at least `minimumAgeMs` before `now`. */
+function newestReleased(
+	releases: Record<string, string>,
+	now: Date,
+	minimumAgeMs: number,
+): string | null {
+	let newest: string | null = null;
+	for (const [version, publishedAt] of Object.entries(releases)) {
+		if (now.getTime() - Date.parse(publishedAt) < minimumAgeMs) continue;
+		if (!newest || isNewerVersion(version, newest)) newest = version;
+	}
+	return newest;
+}
+
+/**
+ * Seconds a release must be public before it is reported, from the
+ * `updateCheck` option. Throws on an invalid duration.
+ */
+export function minimumReleaseAgeSeconds(
+	option: boolean | { minimumReleaseAge?: string | number } | null | undefined,
+): number {
+	const age = typeof option === "object" ? option?.minimumReleaseAge : undefined;
+	return parseDurationSeconds(age ?? DEFAULT_MINIMUM_RELEASE_AGE);
+}
+
+/**
+ * Report the cached update status and, when the cache is stale (or
+ * missing), kick a deferred registry refresh. Never blocks on the
+ * network: the first request after install/expiry reports the previous
+ * state and the next request sees the refreshed one.
+ */
+export async function handleCoreUpdateStatus(
+	db: Kysely<Database>,
+	options?: { now?: Date; enabled?: boolean; minimumReleaseAgeSeconds?: number; current?: string },
+): Promise<ApiResult<CoreUpdateStatus>> {
+	const current = options?.current ?? VERSION;
+	if (options?.enabled === false) {
+		return {
+			success: true,
+			data: { current, latest: null, updateAvailable: false, checkedAt: null },
+		};
+	}
+
+	try {
+		const repo = new OptionsRepository(db);
+		const cache = parseCache(await repo.get(CORE_UPDATE_OPTION));
+
+		const now = options?.now ?? new Date();
+		const minimumAgeMs =
+			(options?.minimumReleaseAgeSeconds ?? minimumReleaseAgeSeconds(undefined)) * 1000;
+		const stale = !cache || now.getTime() - Date.parse(cache.checkedAt) >= CHECK_INTERVAL_MS;
+		// A "dev" version can never compare as outdated, so skip the
+		// registry round-trip entirely in uncompiled dev/test runs.
+		if (stale && current !== "dev") {
+			after(async () => {
+				try {
+					await refreshCoreUpdateCache(db);
+				} catch (error) {
+					console.warn("[update-check] registry refresh failed:", error);
+					const latestCache = parseCache(await repo.get(CORE_UPDATE_OPTION));
+					if (latestCache?.checkedAt !== cache?.checkedAt) return;
+					const retryLater: CoreUpdateCache = {
+						releases: cache?.releases ?? {},
+						checkedAt: new Date().toISOString(),
+					};
+					await repo.set(CORE_UPDATE_OPTION, retryLater);
+				}
+			});
+		}
+
+		const latest = cache ? newestReleased(cache.releases, now, minimumAgeMs) : null;
+		return {
+			success: true,
+			data: {
+				current,
+				latest,
+				updateAvailable: latest ? isNewerVersion(latest, current) : false,
+				checkedAt: cache?.checkedAt ?? null,
+			},
+		};
+	} catch (error) {
+		console.error("[update-check] status read failed:", error);
+		return {
+			success: false,
+			error: { code: ErrorCode.UPDATE_CHECK_ERROR, message: "Failed to read update status" },
+		};
+	}
+}

package/src/api/handlers/validate-references.ts

@@ -0,0 +1,146 @@
+import type { Kysely } from "kysely";
+
+import type { Database } from "../../database/types.js";
+import { requestCached } from "../../request-cache.js";
+import type { ApiResult } from "../types.js";
+
+export interface ReferenceFieldConstraints {
+	/** Field slug — how the entry API addresses the selection. */
+	slug: string;
+	/** Relation slug the field binds to. */
+	relation: string;
+	/** Relation id, for the reads that address the link table directly. */
+	relationId: string | null;
+	/** Which end of the relation the field's own collection sits on. */
+	relationSide: "parent" | "child";
+	/** How many entries this side of the relation may hold. `null` is unlimited. */
+	maxSelected: number | null;
+	/** How many this field's selection may hand each entry it selects. */
+	maxOpposite: number | null;
+	required: boolean;
+}
+
+function validationError(message: string): ApiResult<never> {
+	return { success: false, error: { code: "VALIDATION_ERROR", message } };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null;
+}
+
+/**
+ * Every reference field on a collection that is bound to a relation, by field
+ * slug — the key the entry API takes a selection under.
+ */
+export function referenceFieldConstraints(
+	db: Kysely<Database>,
+	collection: string,
+): Promise<Map<string, ReferenceFieldConstraints>> {
+	return requestCached(`reference-field-constraints:${collection}`, async () => {
+		const fields = await db
+			.selectFrom("_emdash_fields")
+			.innerJoin("_emdash_collections", "_emdash_collections.id", "_emdash_fields.collection_id")
+			.select(["_emdash_fields.slug", "_emdash_fields.required", "_emdash_fields.validation"])
+			.where("_emdash_collections.slug", "=", collection)
+			.where("_emdash_fields.type", "=", "reference")
+			.execute();
+
+		// Cardinality lives on the relation, not the field: with both ends of a
+		// relation bindable, two fields carrying their own limits could disagree
+		// about one edge set. The field contributes only which end it views.
+		const relations = await db
+			.selectFrom("_emdash_relations")
+			.select(["id", "slug", "max_children_per_parent", "max_parents_per_child"])
+			.execute();
+		const limits = new Map(relations.map((r) => [r.slug, r]));
+
+		const constraints = new Map<string, ReferenceFieldConstraints>();
+		for (const field of fields) {
+			if (!field.validation) continue;
+
+			let parsed: unknown;
+			try {
+				parsed = JSON.parse(field.validation);
+			} catch {
+				continue;
+			}
+			if (!isRecord(parsed) || typeof parsed.relation !== "string") continue;
+
+			const relation = limits.get(parsed.relation);
+			const relationSide = parsed.relationSide === "child" ? "child" : "parent";
+			const onChildSide = relationSide === "child";
+
+			constraints.set(field.slug, {
+				slug: field.slug,
+				relation: parsed.relation,
+				relationId: relation?.id ?? null,
+				relationSide,
+				maxSelected: onChildSide
+					? (relation?.max_parents_per_child ?? null)
+					: (relation?.max_children_per_parent ?? null),
+				maxOpposite: onChildSide
+					? (relation?.max_children_per_parent ?? null)
+					: (relation?.max_parents_per_child ?? null),
+				required: field.required === 1,
+			});
+		}
+		return constraints;
+	});
+}
+
+/**
+ * The field viewing one end of a relation, for the relation-scoped routes, which
+ * address a relation rather than a field. At most one field binds each
+ * (relation, side), so this is unambiguous.
+ */
+export function constraintsForRelationSide(
+	constraints: Map<string, ReferenceFieldConstraints>,
+	relation: string,
+	side: "parent" | "child",
+): ReferenceFieldConstraints | undefined {
+	for (const field of constraints.values()) {
+		if (field.relation === relation && field.relationSide === side) return field;
+	}
+	return undefined;
+}
+
+export function validateReferenceSelection(
+	constraints: ReferenceFieldConstraints,
+	childIds: string[],
+): ApiResult<true> {
+	const max = constraints.maxSelected;
+	if (max !== null && childIds.length > max) {
+		return validationError(
+			max === 1
+				? `Field '${constraints.slug}' accepts a single reference, received ${childIds.length}.`
+				: `Field '${constraints.slug}' accepts at most ${max} references, received ${childIds.length}.`,
+		);
+	}
+	if (constraints.required && childIds.length === 0) {
+		return validationError(
+			`Field '${constraints.slug}' is required and must reference at least one entry.`,
+		);
+	}
+	return { success: true, data: true };
+}
+
+export async function validateRequiredReferencesPresent(
+	db: Kysely<Database>,
+	collection: string,
+	references: Record<string, string[]> | undefined,
+	translationOf: string | undefined,
+): Promise<ApiResult<true>> {
+	// References belong to a translation group, so a new locale row inherits
+	// the source group's existing edges when its payload omits them.
+	if (translationOf) return { success: true, data: true };
+
+	const constraints = await referenceFieldConstraints(db, collection);
+	for (const field of constraints.values()) {
+		if (!field.required) continue;
+		if (references && Object.hasOwn(references, field.slug)) continue;
+		return validationError(
+			`Field '${field.slug}' is required and must reference at least one entry.`,
+		);
+	}
+	return { success: true, data: true };
+}

package/src/api/redirect.ts

@@ -1,14 +1,22 @@
+// eslint-disable-next-line no-control-regex -- rejecting control characters is the whole point of this regex
+const CONTROL_CHARACTERS = /[\u0000-\u001f\u007f]/;
+
 /**
  * Validate that a redirect URL is a safe local path.
  *
  * Rejects:
  * - Protocol-relative URLs (`//evil.com`)
  * - Backslash bypass (`/\evil.com` — browsers normalize `\` to `/` in Location headers)
+ * - Control characters (`/\t/evil.com` — browsers strip tab/CR/LF, leaving `//evil.com`)
  * - Absolute URLs (`https://evil.com`)
  * - Empty / nullish values
  */
 export function isSafeRedirect(url: string | null | undefined): url is string {
 	return (
-		typeof url === "string" && url.startsWith("/") && !url.startsWith("//") && !url.includes("\\")
+		typeof url === "string" &&
+		url.startsWith("/") &&
+		!url.startsWith("//") &&
+		!url.includes("\\") &&
+		!CONTROL_CHARACTERS.test(url)
 	);
 }

package/src/api/schemas/content.ts

@@ -3,6 +3,7 @@ import { z } from "zod";
 import { SQL_BATCH_SIZE } from "../../utils/chunks.js";
 import { bylineSummarySchema, bylineCreditSchema, contentBylineInputSchema } from "./bylines.js";
 import { cursorPaginationQuery, httpUrl, localeCode } from "./common.js";
+import { referenceChildrenResponseSchema } from "./relations.js";
 
 // ---------------------------------------------------------------------------
 // Content: Input schemas
@@ -209,6 +210,10 @@ export const contentCreateBody = z
 			description:
 				"Taxonomy term assignments as { taxonomyName: [termSlug, ...] }, resolved in the entry's locale.",
 		}),
+		references: z.record(z.string(), z.array(z.string()).max(1000)).optional().meta({
+			description:
+				"Reference selections as { fieldSlug: [entryId, ...] }, in display order. Written as content-reference links in the same transaction as the entry. A field bound to the child end of its relation selects the entries pointing at this one, which carry no order.",
+		}),
 		publishedAt: contentDateOverride,
 		createdAt: contentDateOverride,
 		migrateBlocks: z.boolean().optional(),
@@ -234,6 +239,10 @@ export const contentUpdateBody = z
 			description:
 				"Replace taxonomy assignments as { taxonomyName: [termSlug, ...] }. Only named taxonomies are touched; pass an empty array to clear a taxonomy.",
 		}),
+		references: z.record(z.string(), z.array(z.string()).max(1000)).optional().meta({
+			description:
+				"Reference selections as { fieldSlug: [entryId, ...] }, in display order. Written as content-reference links in the same transaction as the entry. A field bound to the child end of its relation selects the entries pointing at this one, which carry no order.",
+		}),
 		publishedAt: contentDateOverride,
 		migrateBlocks: z.boolean().optional(),
 		replaceBlocks: z.boolean().optional(),
@@ -264,6 +273,10 @@ export const contentRevisionConditionBody = z
 	})
 	.meta({ id: "ContentRevisionConditionBody" });
 
+export const revisionRestoreBody = z.object({
+	overrideLock: overrideLockFlag,
+});
+
 export const contentPublishBody = contentRevisionConditionBody
 	.extend({
 		// .optional() rather than .nullish(): publishing has no semantic
@@ -374,6 +387,10 @@ export const contentItemSchema = z
 		locale: z.string().nullable(),
 		translationGroup: z.string().nullable(),
 		seo: contentSeoSchema.optional(),
+		// First page of each reference field's selection, keyed by field slug. Only
+		// present when the editor GET path opts into hydration
+		// (`referenceOptions`); omitted otherwise, so it's optional here.
+		references: z.record(z.string(), referenceChildrenResponseSchema).optional(),
 	})
 	.meta({ id: "ContentItem" });