content-query 0.3.0 → 0.5.0

package/dist/{content-N1gYshjg.mjs → collection-Cb5eWGnv.mjs}

@@ -1,7 +1,7 @@
-import { a as invalidQuery, n as contentError, t as ContentError } from "./errors-C2iuBM0G.mjs";
-import { a as detachSelection, c as isScalar, i as detach, n as compareStrings, s as equal, t as compare } from "./values-BbTV4QT-.mjs";
+import { a as invalidQuery, n as contentError, o as payloadIdentity, t as ContentError } from "./errors-Bfd0R4_P.mjs";
+import { a as detachSelection, c as isScalar, i as detach, n as compareStrings, o as encode, r as decode, s as equal, t as compare } from "./values-BbTV4QT-.mjs";
 import { t as assertServerOnly } from "./server-only-CIJUlyL-.mjs";
-import { _ as not, t as and, x as validateExpression, y as or } from "./operators-UqWUhKQJ.mjs";
+import { A as NO_SELECTION_MESSAGE, D as resolveRelations, E as or, F as hasSelection, M as assertAvailable, N as effectiveOrder, P as emptyPlan, S as not, j as PAGINATE_AFTER_LIMIT_MESSAGE, k as validateExpression, l as fieldProxy, t as and } from "./operators-D-w1-gDg.mjs";
 //#region src/artifacts/types.ts
 const CODEC_VERSION = "devalue-6.0.2";
 //#endregion
@@ -144,41 +144,152 @@ function isRelationship(value) {
 	].includes(String(value.referenceSide));
 }
 //#endregion
-//#region src/shared/concurrency.ts
+//#region src/runtime/revision.ts
 /**
-* Maps items through an asynchronous callback with at most `limit` callbacks in flight.
-* Results keep input order; the first rejection rejects the whole map after started work settles.
+* Serializes a variant combination with sorted keys, so preparation, artifacts, and query plans
+* agree on one identity. A payload without variants uses `{}`.
 *
-* @param items - Values to process.
-* @param limit - Maximum number of concurrent callbacks; values below one are treated as one.
-* @param callback - Asynchronous work for one item and its index.
-* @returns The callback results in input order.
+* @param variant - The variant combination.
+* @returns The canonical variant key.
 */
-async function mapConcurrent(items, limit, callback) {
-	const results = Array.from({ length: items.length });
-	let next = 0;
-	let failure;
-	/** Claims the next unprocessed item until the list is exhausted or work has failed. */
-	async function worker() {
-		while (next < items.length && !failure) {
-			const index = next++;
-			try {
-				results[index] = await callback(items[index], index);
-			} catch (cause) {
-				failure ??= { cause };
-			}
-		}
+function variantKey(variant) {
+	return JSON.stringify(Object.fromEntries(Object.keys(variant).sort().map((key) => [key, variant[key]])));
+}
+//#endregion
+//#region src/query/cursor.ts
+/** Changes whenever the encoded cursor layout changes, so older cursors fail clearly. */
+const CURSOR_VERSION = 1;
+/** Bounds the work spent on client-supplied cursors, which usually arrive in URLs. */
+const MAX_CURSOR_LENGTH = 4096;
+const BASE64URL = /^[A-Za-z0-9_-]+$/;
+/** Encodes UTF-8 text as unpadded base64url without relying on Node's `Buffer`. */
+function toBase64Url(text) {
+	let binary = "";
+	for (const byte of new TextEncoder().encode(text)) binary += String.fromCharCode(byte);
+	return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+/** Decodes unpadded base64url into UTF-8 text, rejecting invalid byte sequences. */
+function fromBase64Url(encoded) {
+	const binary = atob(encoded.replace(/-/g, "+").replace(/_/g, "/"));
+	const bytes = Uint8Array.from(binary, (character) => character.charCodeAt(0));
+	return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+}
+/** Describes an order as `[field, direction]` pairs, the form a cursor records. */
+function orderPairs(order) {
+	return order.map((sort) => [sort.field, sort.direction]);
+}
+/** Checks a decoded cursor order against the query's order without trusting its shape. */
+function sameOrder(candidate, order) {
+	return Array.isArray(candidate) && candidate.length === order.length && order.every((sort, index) => {
+		const pair = candidate[index];
+		return Array.isArray(pair) && pair.length === 2 && pair[0] === sort.field && pair[1] === sort.direction;
+	});
+}
+/** Rejects a client-supplied cursor that cannot position this query. */
+function invalidCursor(collection, message, cause) {
+	throw new ContentError({
+		code: "invalid-cursor",
+		operation: "query",
+		collection,
+		message,
+		cause
+	});
+}
+/**
+* Encodes an entry's position in a query's order as an opaque cursor. The cursor records the
+* collection, the effective order, and the entry's sort values, with rich values such as dates and
+* `BigInt`s preserved.
+*
+* @param collection - The queried collection.
+* @param order - The query's effective order, including the ID tie-breaker.
+* @param key - The entry's values for each sort clause, in order.
+* @returns An opaque, URL-safe cursor string.
+*/
+function encodeCursor(collection, order, key) {
+	return toBase64Url(encode([
+		CURSOR_VERSION,
+		collection,
+		orderPairs(order),
+		[...key]
+	]));
+}
+/**
+* Decodes a cursor into sort values for this query. A cursor stays valid when filters change, but
+* only for the same collection and effective order it was created with.
+*
+* @param cursor - A cursor from an earlier page of the same query.
+* @param collection - The queried collection.
+* @param order - The query's effective order, including the ID tie-breaker.
+* @returns The boundary entry's sort values, in order.
+* @throws ContentError with code `invalid-cursor` when the cursor is malformed or belongs to a
+* different collection or order.
+*/
+function decodeCursor(cursor, collection, order) {
+	if (typeof cursor !== "string" || cursor.length > MAX_CURSOR_LENGTH || !BASE64URL.test(cursor)) invalidCursor(collection, "The cursor is not a cursor returned by paginate().");
+	let decoded;
+	try {
+		decoded = decode(fromBase64Url(cursor));
+	} catch (cause) {
+		invalidCursor(collection, "The cursor is not a cursor returned by paginate().", cause);
 	}
-	const workers = Array.from({ length: Math.min(Math.max(1, limit), items.length) }, worker);
-	await Promise.all(workers);
-	if (failure) throw failure.cause;
-	return results;
+	if (!Array.isArray(decoded) || decoded.length !== 4 || decoded[0] !== CURSOR_VERSION || !Array.isArray(decoded[3]) || !decoded[3].every(isScalar)) invalidCursor(collection, "The cursor is not a cursor returned by paginate().");
+	const [, cursorCollection, cursorOrder, key] = decoded;
+	if (cursorCollection !== collection || !sameOrder(cursorOrder, order) || key.length !== order.length) invalidCursor(collection, "The cursor belongs to a query with a different collection or sort order.");
+	return key;
 }
 //#endregion
 //#region src/query/clauses.ts
+/** Option names that `paginate()` reads; relational options pass the rest to the query plan. */
+const PAGINATE_KEYS = [
+	"page",
+	"size",
+	"after",
+	"before",
+	"total"
+];
+/**
+* Checks `paginate()` options against a selected root plan and compiles them into a page request.
+* Cursors are decoded here, so execution and future backends receive sort values only.
+*
+* @param plan - The root plan to paginate; it must not set its own limit or offset.
+* @param options - `{ page, size }` for page numbers, or `{ size, after?, before?, total? }` for
+* cursors. A `null` cursor starts at the first entry (`after`) or the last entry (`before`).
+* @returns The compiled page request.
+* @throws ContentError with code `invalid-query` for invalid options, or `invalid-cursor` for a
+* cursor from a different collection or order.
+*/
+function checkedPaginate(plan, options) {
+	if (plan.limit !== void 0 || plan.offset !== void 0) invalidQuery(PAGINATE_AFTER_LIMIT_MESSAGE);
+	if (!options || typeof options !== "object" || Array.isArray(options)) invalidQuery("paginate() requires options, such as { page: 1, size: 10 } or { size: 10 }.");
+	const { page, size, after, before, total, ...rest } = options;
+	const [extra] = Object.keys(rest);
+	if (extra !== void 0) invalidQuery(`Unknown paginate() option "${extra}".`);
+	if (!Number.isSafeInteger(size) || size < 1) invalidQuery("paginate() requires a positive safe integer size.");
+	if (page !== void 0) {
+		if (after !== void 0 || before !== void 0 || total !== void 0) invalidQuery("Page-number pagination cannot use after, before, or total; its results always include total.");
+		if (!Number.isSafeInteger(page) || page < 1) invalidQuery("paginate() requires a positive safe integer page, starting at 1.");
+		return {
+			mode: "page",
+			page,
+			size
+		};
+	}
+	if (after !== void 0 && before !== void 0) invalidQuery("paginate() accepts an after or a before cursor, not both.");
+	if (total !== void 0 && typeof total !== "boolean") invalidQuery("paginate() requires total to be a boolean.");
+	const direction = before !== void 0 ? "before" : "after";
+	const cursor = direction === "before" ? before : after;
+	return {
+		mode: "cursor",
+		size,
+		direction,
+		total: total === true,
+		...cursor === null || cursor === void 0 ? {} : { key: decodeCursor(cursor, plan.collection, effectiveOrder(plan)) }
+	};
+}
 /** Checks scalar field selection for both public query frontends without a schema field catalog. */
 function checkedFields(registry, collection, fields) {
 	const scope = registry[collection];
+	for (const field of fields) if (typeof field === "string") assertAvailable(registry, collection, field);
 	if (!scope || fields.some((field) => typeof field !== "string" || !field || field === "_adjacent" || field === "_payloads" || Object.hasOwn(scope.relationships, field)) || new Set(fields).size !== fields.length) invalidQuery("Selection requires distinct prepared fields; use relationship or adjacency selection explicitly.");
 	return [...fields];
 }
@@ -225,204 +336,8 @@ function checkedPayloads(registry, collection, payloads) {
 	return Object.keys(requested).length ? requested : void 0;
 }
 //#endregion
-//#region src/query/plan.ts
-/** Starts a fresh query without binding a content revision until execution. */
-function emptyPlan(collection) {
-	return {
-		collection,
-		filters: [],
-		order: [],
-		with: {}
-	};
-}
-/** Treats explicitly selected relationships and adjacency as row projections too. */
-function hasSelection(plan) {
-	return !!plan && (plan.select !== void 0 || !!plan.allFields || !!plan.adjacent || Object.keys(plan.with).length > 0);
-}
-//#endregion
-//#region src/query/relational.ts
-const operators$1 = {
-	eq: "eq",
-	ne: "ne",
-	gt: "gt",
-	gte: "gte",
-	lt: "lt",
-	lte: "lte",
-	in: "in-array",
-	notIn: "not-in-array",
-	like: "like",
-	ilike: "ilike",
-	notLike: "like",
-	notIlike: "ilike",
-	contains: "contains",
-	startsWith: "starts-with",
-	endsWith: "ends-with",
-	arrayContains: "array-contains-all",
-	arrayOverlaps: "array-contains-any",
-	arrayContained: "array-contained",
-	isNull: "is-null",
-	isNotNull: "is-null",
-	isUndefined: "is-undefined",
-	isMissing: "is-missing"
-};
-/** Requires plain records at each relational options and filter boundary. */
-function record$1(value, label) {
-	if (!value || typeof value !== "object" || Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) invalidQuery(`${label} must be an options object.`);
-}
-/** Compiles a field condition, including field-local boolean composition, into portable expressions. */
-function fieldCondition(field, condition) {
-	if (isScalar(condition)) return {
-		kind: "predicate",
-		operator: "eq",
-		field,
-		value: condition
-	};
-	record$1(condition, `Filter for "${field}"`);
-	const expressions = [];
-	for (const [name, value] of Object.entries(condition)) {
-		if (name === "AND" || name === "OR") {
-			if (!Array.isArray(value)) invalidQuery("Field AND/OR filters require arrays.");
-			const children = value.map((child) => fieldCondition(field, child));
-			expressions.push(name === "AND" ? and(...children) : or(...children));
-			continue;
-		}
-		if (name === "NOT") {
-			expressions.push(not(fieldCondition(field, value)));
-			continue;
-		}
-		if (!Object.hasOwn(operators$1, name)) invalidQuery(`Unknown filter operator "${name}".`);
-		const expression = {
-			kind: "predicate",
-			operator: operators$1[name],
-			field,
-			value
-		};
-		if (name.startsWith("is")) {
-			if (typeof value !== "boolean") invalidQuery("Presence predicates require boolean values.");
-			expressions.push(value !== (name === "isNotNull") ? expression : not(expression));
-		} else expressions.push(name === "notLike" || name === "notIlike" ? not(expression) : expression);
-	}
-	return and(...expressions);
-}
-/** Compiles object predicates and existential relationship filters without loading bodies. */
-function relationalWhere(registry, collection, where) {
-	record$1(where, "where");
-	const expressions = [];
-	for (const [field, condition] of Object.entries(where)) if (field === "AND" || field === "OR" || field === "NOT") {
-		if (field === "OR" && !Array.isArray(condition)) invalidQuery("OR filters require an array.");
-		const children = (Array.isArray(condition) ? condition : [condition]).map((child) => relationalWhere(registry, collection, child));
-		expressions.push(field === "OR" ? or(...children) : field === "NOT" ? and(...children.map(not)) : and(...children));
-	} else if (field === "RAW") {
-		if (typeof condition !== "function") invalidQuery("RAW requires a structured-expression callback.");
-		const expression = condition(new Proxy(Object.create(null), { get: (_target, name) => ({ name }) }));
-		validateExpression(expression);
-		expressions.push(expression);
-	} else if (Object.hasOwn(registry[collection].relationships, field)) {
-		const relation = registry[collection].relationships[field];
-		const expression = {
-			kind: "relation",
-			collection,
-			field,
-			target: relation.collection,
-			expression: relationalWhere(registry, relation.collection, typeof condition === "boolean" ? {} : condition)
-		};
-		expressions.push(condition === false ? not(expression) : expression);
-	} else expressions.push(fieldCondition(field, condition));
-	const expression = and(...expressions);
-	validateExpression(expression);
-	return detach(expression);
-}
-/**
-* Compiles Drizzle-style columns/with options into the shared immutable query plan.
-* Payloads are allowed wherever adjacency is, so sibling scopes never load them.
-*/
-function relationalPlan(registry, collection, options = {}, many = true, allowAdjacent = true, pagination = true) {
-	if (!Object.hasOwn(registry, collection)) invalidQuery(`Unknown collection "${collection}".`);
-	record$1(options, "Query");
-	const allowed = [
-		"columns",
-		"where",
-		"with",
-		...many ? ["orderBy"] : [],
-		...many && pagination ? ["limit", "offset"] : [],
-		...allowAdjacent ? ["adjacent", "payloads"] : []
-	];
-	if (Object.keys(options).some((key) => !allowed.includes(key))) invalidQuery("Unknown relational query option or unsupported scope option.");
-	const plan = emptyPlan(collection);
-	if (options.where !== void 0) plan.filters = [relationalWhere(registry, collection, options.where)];
-	if (options.columns === void 0) plan.allFields = true;
-	else {
-		record$1(options.columns, "columns");
-		const columns = options.columns;
-		if (Object.values(columns).some((value) => typeof value !== "boolean")) invalidQuery("Column selection requires boolean values.");
-		const names = checkedFields(registry, collection, Object.keys(columns));
-		const included = names.filter((name) => columns[name] === true);
-		if (included.length || !names.length) plan.select = included;
-		else {
-			plan.allFields = true;
-			plan.exclude = names;
-		}
-	}
-	if (options.with !== void 0) {
-		record$1(options.with, "with");
-		const related = Object.create(null);
-		for (const [name, selected] of Object.entries(options.with)) {
-			const relation = Object.hasOwn(registry[collection].relationships, name) && registry[collection].relationships[name];
-			if (!relation) invalidQuery(`Unknown relationship "${name}".`);
-			if (selected === false || selected === void 0) continue;
-			related[name] = relationalPlan(registry, relation.collection, selected === true ? {} : selected, relation.type === "many", allowAdjacent);
-		}
-		plan.with = related;
-	}
-	if (options.orderBy !== void 0) {
-		record$1(options.orderBy, "orderBy");
-		if (!Object.keys(options.orderBy).length) invalidQuery("orderBy requires a field.");
-		for (const [field, direction] of Object.entries(options.orderBy)) plan.order = checkedOrder(plan, field, direction, many);
-	}
-	for (const key of ["limit", "offset"]) if (options[key] !== void 0) plan[key] = checkedPagination(options[key], many);
-	if (options.payloads !== void 0) {
-		record$1(options.payloads, "payloads");
-		const payloads = checkedPayloads(registry, collection, options.payloads);
-		if (payloads) plan.payloads = payloads;
-	}
-	if (options.adjacent !== void 0) plan.adjacent = options.adjacent === true ? true : relationalPlan(registry, collection, options.adjacent, true, false, false);
-	return plan;
-}
-/** Creates stable, live collection queries in a dedicated, prototype-free namespace. */
-function createQueryNamespace(registry, run) {
-	const queries = /* @__PURE__ */ new Map();
-	/** Reuses each handle while checking the current registry on every query execution. */
-	function query(name) {
-		let cached = queries.get(name);
-		if (!cached) {
-			cached = {
-				findMany: (options) => run(relationalPlan(registry(), name, options), "all"),
-				findFirst: (options) => run(relationalPlan(registry(), name, options), "first")
-			};
-			queries.set(name, cached);
-		}
-		return cached;
-	}
-	return new Proxy(Object.create(null), {
-		get(_target, name) {
-			return typeof name === "string" && Object.hasOwn(registry(), name) ? query(name) : void 0;
-		},
-		ownKeys() {
-			return Object.keys(registry());
-		},
-		getOwnPropertyDescriptor(_target, name) {
-			return typeof name === "string" && Object.hasOwn(registry(), name) ? {
-				configurable: true,
-				enumerable: true,
-				value: query(name),
-				writable: false
-			} : void 0;
-		}
-	});
-}
-//#endregion
 //#region src/query/object.ts
-const operators = {
+const operators$1 = {
 	equals: "eq",
 	not: "ne",
 	gt: "gt",
@@ -442,12 +357,12 @@ const operators = {
 	isMissing: "is-missing"
 };
 /** Requires a plain options record, rejecting arrays and class instances at API boundaries. */
-function record(value, label) {
+function record$1(value, label) {
 	if (!value || typeof value !== "object" || Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) invalidQuery(`${label} must be an options object.`);
 }
 /** Converts object predicates to the same validated expressions used by fluent operators. */
 function objectWhere(where) {
-	record(where, "where");
+	record$1(where, "where");
 	const expressions = [];
 	for (const [field, condition] of Object.entries(where)) {
 		if ([
@@ -468,16 +383,16 @@ function objectWhere(where) {
 			});
 			continue;
 		}
-		record(condition, `Filter for "${field}"`);
+		record$1(condition, `Filter for "${field}"`);
 		for (const [name, value] of Object.entries(condition)) {
-			if (!Object.hasOwn(operators, name)) invalidQuery(`Unknown filter operator "${name}".`);
+			if (!Object.hasOwn(operators$1, name)) invalidQuery(`Unknown filter operator "${name}".`);
 			if (name === "not" && !isScalar(value)) {
 				expressions.push(not(objectWhere({ [field]: value })));
 				continue;
 			}
 			const expression = {
 				kind: "predicate",
-				operator: operators[name],
+				operator: operators$1[name],
 				field,
 				value
 			};
@@ -492,9 +407,30 @@ function objectWhere(where) {
 	return detach(expression);
 }
 /** Compiles explicit object options into the backend-independent fluent query contract. */
+/**
+* Compiles an object-form `_adjacent` selection. `{ scope: "results", select }` selects neighbors
+* within the current results; other options describe an independent sibling scope.
+*
+* @param registry - The query registry.
+* @param collection - The collection whose neighbors are selected.
+* @param selection - The `_adjacent` value from an object selection.
+* @returns The adjacency plan, which always selects explicit data.
+*/
+function objectAdjacent(registry, collection, selection) {
+	record$1(selection, "_adjacent");
+	const { scope, ...options } = selection;
+	if (scope !== void 0 && scope !== "results" && scope !== "collection") invalidQuery("Adjacent scope must be \"results\" or \"collection\".");
+	if (scope === "results" && Object.keys(options).some((key) => key !== "select")) invalidQuery("Results-scope neighbors only select data; they share the query's filters and order.");
+	const plan = objectPlan(registry, collection, options, true, false, false);
+	if (!hasSelection(plan)) invalidQuery("Adjacent entries require explicit selection.");
+	return {
+		scope: scope === "results" ? "results" : "collection",
+		plan
+	};
+}
 function objectPlan(registry, collection, options, many = true, allowAdjacent = true, pagination = true) {
 	if (!Object.hasOwn(registry, collection)) invalidQuery(`Unknown collection "${collection}".`);
-	record(options, "Query");
+	record$1(options, "Query");
 	const allowed = [
 		"where",
 		"select",
@@ -504,32 +440,32 @@ function objectPlan(registry, collection, options, many = true, allowAdjacent =
 	if (Object.keys(options).some((key) => !allowed.includes(key))) invalidQuery("Unknown query option or pagination in an adjacency scope.");
 	let plan = emptyPlan(collection);
 	if (options.where !== void 0) {
-		const expression = typeof options.where === "function" ? options.where(new Proxy(Object.create(null), { get: (_target, name) => ({ name }) })) : objectWhere(options.where);
+		const expression = typeof options.where === "function" ? options.where(fieldProxy()) : objectWhere(options.where);
 		validateExpression(expression);
-		plan.filters = [detach(expression)];
+		plan.filters = [detach(resolveRelations(registry, collection, expression))];
 	}
 	if (options.orderBy !== void 0) for (const order of Array.isArray(options.orderBy) ? options.orderBy : [options.orderBy]) {
-		record(order, "orderBy");
+		record$1(order, "orderBy");
 		if (!Object.keys(order).length) invalidQuery("orderBy requires a field.");
 		for (const [field, direction] of Object.entries(order)) plan.order = checkedOrder(plan, field, direction, many);
 	}
 	for (const key of ["limit", "offset"]) if (options[key] !== void 0) plan[key] = checkedPagination(options[key], many);
 	if (options.select !== void 0) {
-		record(options.select, "select");
+		record$1(options.select, "select");
 		const selected = Object.entries(options.select).filter(([, value]) => value !== false && value !== void 0);
 		if (!selected.length) invalidQuery("Row-returning queries require a nonempty selection.");
 		const fields = [];
 		const related = Object.create(null);
 		for (const [name, selection] of selected) if (name === "_adjacent") {
 			if (!allowAdjacent) invalidQuery("Adjacency cannot be selected recursively.");
-			plan.adjacent = selection === true ? true : objectPlan(registry, collection, selection, true, false, false);
-			if (plan.adjacent !== true && !plan.adjacent.select) invalidQuery("Adjacent entries require explicit selection.");
+			plan.adjacent = objectAdjacent(registry, collection, selection);
 		} else if (Object.hasOwn(registry[collection].relationships, name)) {
 			const relation = registry[collection].relationships[name];
 			const nested = objectPlan(registry, relation.collection, selection, relation.type === "many", allowAdjacent);
 			if (!nested.select && !nested.adjacent) invalidQuery("Related entries require explicit selection.");
 			related[name] = nested;
 		} else {
+			assertAvailable(registry, collection, name);
 			if (selection !== true) invalidQuery("Prepared fields must be selected with true.");
 			fields.push(name);
 		}
@@ -558,17 +494,13 @@ function createBuilder(registry, run, plan, many = true, root = true, scopeToken
 		[scopeSymbol]: scopeToken,
 		select(...fields) {
 			if (plan.select || fields.length === 0) invalidQuery("select() requires distinct prepared fields and can be called once per scope.");
-			return branch({
-				select: checkedFields(registry, plan.collection, fields),
-				allFields: void 0,
-				exclude: void 0
-			});
+			return branch({ select: checkedFields(registry, plan.collection, fields) });
 		},
 		where(configure) {
 			if (typeof configure !== "function") invalidQuery("where() requires a configuration callback.");
-			const expression = configure(new Proxy(Object.create(null), { get: (_target, name) => ({ name }) }));
+			const expression = configure(fieldProxy());
 			validateExpression(expression);
-			return branch({ filters: [...plan.filters, detach(expression)] });
+			return branch({ filters: [...plan.filters, detach(resolveRelations(registry, plan.collection, expression))] });
 		},
 		orderBy(field, direction = "asc") {
 			return branch({ order: checkedOrder(plan, field, direction, many) });
@@ -581,7 +513,10 @@ function createBuilder(registry, run, plan, many = true, root = true, scopeToken
 		},
 		with(name, configure) {
 			const relation = Object.hasOwn(scope.relationships, name) ? scope.relationships[name] : void 0;
-			if (!relation || Object.hasOwn(plan.with, name) || typeof configure !== "function") invalidQuery("Unknown, repeated, or invalid relationship request.");
+			if (!relation || Object.hasOwn(plan.with, name) || typeof configure !== "function") {
+				assertAvailable(registry, plan.collection, name);
+				invalidQuery("Unknown, repeated, or invalid relationship request.");
+			}
 			const nestedScope = {};
 			const configured = configure(createBuilder(registry, run, emptyPlan(relation.collection), relation.type === "many", false, nestedScope, allowAdjacent));
 			const nested = configured && typeof configured === "object" && planSymbol in configured ? configured[planSymbol] : void 0;
@@ -598,61 +533,373 @@ function createBuilder(registry, run, plan, many = true, root = true, scopeToken
 				[name]: checkedPayload(registry, plan.collection, name, variant)
 			} });
 		},
-		selectAdjacent(configure) {
+		/**
+		* Selects previous and next entries. Field names select neighbors within this scope's results;
+		* a callback or options object describes an independent sibling scope.
+		*/
+		selectAdjacent(...arguments_) {
 			if (!allowAdjacent || plan.adjacent !== void 0) invalidQuery("Adjacency cannot be repeated or selected recursively.");
-			if (configure === void 0) return branch({ adjacent: true });
+			const [configure] = arguments_;
+			if (configure === void 0 || typeof configure === "string") {
+				if (!arguments_.length || arguments_.some((field) => typeof field !== "string")) invalidQuery("selectAdjacent() requires neighbor fields, such as selectAdjacent(\"id\"), or a sibling query.");
+				const selection = {
+					...emptyPlan(plan.collection),
+					select: checkedFields(registry, plan.collection, arguments_)
+				};
+				return branch({ adjacent: {
+					scope: "results",
+					plan: selection
+				} });
+			}
 			if (typeof configure !== "function") {
 				const adjacent = objectPlan(registry, plan.collection, configure, true, false, false);
-				if (!adjacent.select) invalidQuery("Adjacent entries require explicit selection.");
-				return branch({ adjacent });
+				if (!hasSelection(adjacent)) invalidQuery("Adjacent entries require explicit selection.");
+				return branch({ adjacent: {
+					scope: "collection",
+					plan: adjacent
+				} });
 			}
 			const nestedScope = {};
 			const configured = configure(createBuilder(registry, run, emptyPlan(plan.collection), true, false, nestedScope, false, false));
 			const adjacent = configured && typeof configured === "object" && planSymbol in configured ? configured[planSymbol] : void 0;
 			if (!hasSelection(adjacent) || !(scopeSymbol in configured) || configured[scopeSymbol] !== nestedScope) invalidQuery("selectAdjacent() must return its explicitly selected sibling query.");
-			return branch({ adjacent });
+			return branch({ adjacent: {
+				scope: "collection",
+				plan: adjacent
+			} });
 		},
 		all() {
-			if (!root) invalidQuery("Nested builders have no terminal methods.");
-			return run(plan, "all");
+			return rows("all");
 		},
 		/** Executes a selected root query, matching direct await behavior. */
 		execute() {
-			if (!root) invalidQuery("Nested builders have no terminal methods.");
-			return run(plan, "all");
+			return rows("all");
 		},
 		first() {
-			if (!root) invalidQuery("Nested builders have no terminal methods.");
-			return run(plan, "first");
+			return rows("first");
 		},
+		/** Counts matching entries; counting returns no rows, so it needs no selection. */
 		count() {
 			if (!root) invalidQuery("Nested builders have no terminal methods.");
 			return run(plan, "count");
+		},
+		/**
+		* Returns one page with page-number details for `{ page, size }`, or cursor details for
+		* `{ size, after?, before?, total? }`, from one revision.
+		*/
+		paginate(options) {
+			if (!root) invalidQuery("Nested builders have no terminal methods.");
+			if (!hasSelection(plan)) invalidQuery(NO_SELECTION_MESSAGE);
+			return run({
+				...plan,
+				paginate: checkedPaginate(plan, options)
+			}, "paginate");
+		}
+	};
+	if (root) Object.defineProperty(builder, "then", { value: (fulfilled, rejected) => {
+		let result;
+		try {
+			result = rows("all");
+		} catch (cause) {
+			result = Promise.reject(cause);
+		}
+		return result.then(fulfilled, rejected);
+	} });
+	/**
+	* Runs a row-returning terminal. Awaiting an unselected root rejects rather than resolving to the
+	* builder, so a missing selection fails loudly in JavaScript as well as in TypeScript.
+	*/
+	function rows(terminal) {
+		if (!root) invalidQuery("Nested builders have no terminal methods.");
+		if (!hasSelection(plan)) invalidQuery(NO_SELECTION_MESSAGE);
+		return run(plan, terminal);
+	}
+	/** Checks pagination before creating an independent branch. */
+	function pagination(key, value) {
+		if (!allowPagination || plan[key] !== void 0) invalidQuery("Pagination requires a nonnegative safe integer, one call per clause, and a many-valued scope.");
+		return branch({ [key]: checkedPagination(value, many) });
+	}
+	return builder;
+}
+//#endregion
+//#region src/query/from.ts
+/**
+* Starts a fluent root query over one collection. The builder selects nothing until `select()`,
+* `with()`, `withPayload()`, or `selectAdjacent()` requests data; `count()` needs no selection.
+*
+* @param registry - Reads the current query registry, so development builders bind the latest one.
+* @param run - Executes a plan against one pinned revision.
+* @param collection - The collection to query.
+* @returns An immutable, reusable root builder.
+*/
+function createFrom(registry, run, collection) {
+	const current = registry();
+	if (typeof collection !== "string" || !Object.hasOwn(current, collection)) invalidQuery(`Unknown collection "${String(collection)}".`);
+	return createBuilder(current, run, emptyPlan(collection));
+}
+//#endregion
+//#region src/query/relational.ts
+const operators = {
+	eq: "eq",
+	ne: "ne",
+	gt: "gt",
+	gte: "gte",
+	lt: "lt",
+	lte: "lte",
+	in: "in-array",
+	notIn: "not-in-array",
+	like: "like",
+	ilike: "ilike",
+	notLike: "like",
+	notIlike: "ilike",
+	contains: "contains",
+	startsWith: "starts-with",
+	endsWith: "ends-with",
+	arrayContains: "array-contains-all",
+	arrayOverlaps: "array-contains-any",
+	arrayContained: "array-contained",
+	isNull: "is-null",
+	isNotNull: "is-null",
+	isUndefined: "is-undefined",
+	isMissing: "is-missing"
+};
+/** Requires plain records at each relational options and filter boundary. */
+function record(value, label) {
+	if (!value || typeof value !== "object" || Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) invalidQuery(`${label} must be an options object.`);
+}
+/** Compiles a field condition, including field-local boolean composition, into portable expressions. */
+function fieldCondition(field, condition) {
+	if (isScalar(condition)) return {
+		kind: "predicate",
+		operator: "eq",
+		field,
+		value: condition
+	};
+	record(condition, `Filter for "${field}"`);
+	const expressions = [];
+	for (const [name, value] of Object.entries(condition)) {
+		if (name === "AND" || name === "OR") {
+			if (!Array.isArray(value)) invalidQuery("Field AND/OR filters require arrays.");
+			const children = value.map((child) => fieldCondition(field, child));
+			expressions.push(name === "AND" ? and(...children) : or(...children));
+			continue;
+		}
+		if (name === "NOT") {
+			expressions.push(not(fieldCondition(field, value)));
+			continue;
+		}
+		if (!Object.hasOwn(operators, name)) invalidQuery(`Unknown filter operator "${name}".`);
+		const expression = {
+			kind: "predicate",
+			operator: operators[name],
+			field,
+			value
+		};
+		if (name.startsWith("is")) {
+			if (typeof value !== "boolean") invalidQuery("Presence predicates require boolean values.");
+			expressions.push(value !== (name === "isNotNull") ? expression : not(expression));
+		} else expressions.push(name === "notLike" || name === "notIlike" ? not(expression) : expression);
+	}
+	return and(...expressions);
+}
+/** Compiles object predicates and existential relationship filters without loading bodies. */
+function relationalWhere(registry, collection, where) {
+	record(where, "where");
+	const expressions = [];
+	for (const [field, condition] of Object.entries(where)) if (field === "AND" || field === "OR" || field === "NOT") {
+		if (field === "OR" && !Array.isArray(condition)) invalidQuery("OR filters require an array.");
+		const children = (Array.isArray(condition) ? condition : [condition]).map((child) => relationalWhere(registry, collection, child));
+		expressions.push(field === "OR" ? or(...children) : field === "NOT" ? and(...children.map(not)) : and(...children));
+	} else if (field === "RAW") {
+		if (typeof condition !== "function") invalidQuery("RAW requires a structured-expression callback.");
+		const expression = condition(fieldProxy());
+		validateExpression(expression);
+		expressions.push(resolveRelations(registry, collection, expression));
+	} else if (Object.hasOwn(registry[collection].relationships, field)) {
+		const relation = registry[collection].relationships[field];
+		const expression = {
+			kind: "relation",
+			collection,
+			field,
+			target: relation.collection,
+			expression: relationalWhere(registry, relation.collection, typeof condition === "boolean" ? {} : condition)
+		};
+		expressions.push(condition === false ? not(expression) : expression);
+	} else {
+		assertAvailable(registry, collection, field);
+		expressions.push(fieldCondition(field, condition));
+	}
+	const expression = and(...expressions);
+	validateExpression(expression);
+	return detach(expression);
+}
+/**
+* Compiles Drizzle-style columns/with options into the shared immutable query plan.
+* Payloads are allowed wherever adjacency is, so sibling scopes never load them.
+*/
+function relationalPlan(registry, collection, options = {}, many = true, allowAdjacent = true, pagination = true) {
+	if (!Object.hasOwn(registry, collection)) invalidQuery(`Unknown collection "${collection}".`);
+	record(options, "Query");
+	const allowed = [
+		"columns",
+		"where",
+		"with",
+		...many ? ["orderBy"] : [],
+		...many && pagination ? ["limit", "offset"] : [],
+		...allowAdjacent ? ["adjacent", "payloads"] : []
+	];
+	if (Object.keys(options).some((key) => !allowed.includes(key))) invalidQuery("Unknown relational query option or unsupported scope option.");
+	const plan = emptyPlan(collection);
+	if (options.where !== void 0) plan.filters = [relationalWhere(registry, collection, options.where)];
+	if (options.columns !== void 0) {
+		record(options.columns, "columns");
+		const columns = options.columns;
+		if (Object.values(columns).some((value) => value !== true)) invalidQuery("Columns list the fields to include with `true`; omit fields you do not need.");
+		plan.select = checkedFields(registry, collection, Object.keys(columns));
+	}
+	if (options.with !== void 0) {
+		record(options.with, "with");
+		const related = Object.create(null);
+		for (const [name, selected] of Object.entries(options.with)) {
+			const relation = Object.hasOwn(registry[collection].relationships, name) && registry[collection].relationships[name];
+			if (!relation) {
+				assertAvailable(registry, collection, name);
+				invalidQuery(`Unknown relationship "${name}".`);
+			}
+			if (selected === false || selected === void 0) continue;
+			if (selected === true) invalidQuery(`Relationship "${name}" requires nested options that select data, such as { columns: { id: true } }.`);
+			related[name] = selectedPlan(relationalPlan(registry, relation.collection, selected, relation.type === "many", allowAdjacent));
 		}
+		plan.with = related;
+	}
+	if (options.orderBy !== void 0) {
+		record(options.orderBy, "orderBy");
+		if (!Object.keys(options.orderBy).length) invalidQuery("orderBy requires a field.");
+		for (const [field, direction] of Object.entries(options.orderBy)) plan.order = checkedOrder(plan, field, direction, many);
+	}
+	for (const key of ["limit", "offset"]) if (options[key] !== void 0) plan[key] = checkedPagination(options[key], many);
+	if (options.payloads !== void 0) {
+		record(options.payloads, "payloads");
+		const payloads = checkedPayloads(registry, collection, options.payloads);
+		if (payloads) plan.payloads = payloads;
+	}
+	if (options.adjacent !== void 0) plan.adjacent = relationalAdjacent(registry, collection, options.adjacent);
+	return plan;
+}
+/**
+* Compiles relational `adjacent` options. `{ scope: "results", columns, with }` selects neighbors
+* within the current results; other options describe an independent sibling scope.
+*
+* @param registry - The query registry.
+* @param collection - The collection whose neighbors are selected.
+* @param adjacent - The `adjacent` option value.
+* @returns The adjacency plan, which always selects explicit data.
+*/
+function relationalAdjacent(registry, collection, adjacent) {
+	if (adjacent === true) invalidQuery("Adjacent entries select their own data, such as { scope: \"results\", columns: { id: true } }.");
+	record(adjacent, "adjacent");
+	const { scope, ...options } = adjacent;
+	if (scope !== void 0 && scope !== "results" && scope !== "collection") invalidQuery("Adjacent scope must be \"results\" or \"collection\".");
+	if (scope === "results" && Object.keys(options).some((key) => key !== "columns" && key !== "with")) invalidQuery("Results-scope neighbors only select data; they share the query's filters and order.");
+	return {
+		scope: scope === "results" ? "results" : "collection",
+		plan: selectedPlan(relationalPlan(registry, collection, options, true, false, false))
 	};
-	if (root && hasSelection(plan)) Object.defineProperty(builder, "then", { value: (fulfilled, rejected) => run(plan, "all").then(fulfilled, rejected) });
-	/** Checks pagination before creating an independent branch. */
-	function pagination(key, value) {
-		if (!allowPagination || plan[key] !== void 0) invalidQuery("Pagination requires a nonnegative safe integer, one call per clause, and a many-valued scope.");
-		return branch({ [key]: checkedPagination(value, many) });
+}
+/**
+* Rejects a row-returning scope that requests no data.
+*
+* @param plan - A root, relationship, or sibling scope.
+* @returns The same plan when it selects fields, relationships, payloads, or adjacency.
+*/
+function selectedPlan(plan) {
+	if (!hasSelection(plan)) invalidQuery(NO_SELECTION_MESSAGE);
+	return plan;
+}
+/**
+* Separates `paginate()` options from the query options they accompany.
+*
+* @param options - Relational query options plus `page`, `size`, `after`, `before`, or `total`.
+* @returns The query options, then the pagination options.
+*/
+function splitPaginate(options) {
+	record(options, "Query");
+	if (Object.hasOwn(options, "limit") || Object.hasOwn(options, "offset")) invalidQuery(PAGINATE_AFTER_LIMIT_MESSAGE);
+	const query = {};
+	const request = {};
+	for (const [key, value] of Object.entries(options)) (PAGINATE_KEYS.includes(key) ? request : query)[key] = value;
+	return [query, request];
+}
+/** Creates stable, live collection queries in a dedicated, prototype-free namespace. */
+function createQueryNamespace(registry, run) {
+	const queries = /* @__PURE__ */ new Map();
+	/** Reuses each handle while checking the current registry on every query execution. */
+	function query(name) {
+		let cached = queries.get(name);
+		if (!cached) {
+			cached = {
+				findMany: (options) => run(selectedPlan(relationalPlan(registry(), name, options)), "all"),
+				findFirst: (options) => run(selectedPlan(relationalPlan(registry(), name, options)), "first"),
+				paginate: (options) => {
+					const [query, request] = splitPaginate(options);
+					const plan = selectedPlan(relationalPlan(registry(), name, query, true, true, false));
+					return run({
+						...plan,
+						paginate: checkedPaginate(plan, request)
+					}, "paginate");
+				}
+			};
+			queries.set(name, cached);
+		}
+		return cached;
 	}
-	return builder;
+	return new Proxy(Object.create(null), {
+		get(_target, name) {
+			return typeof name === "string" && Object.hasOwn(registry(), name) ? query(name) : void 0;
+		},
+		ownKeys() {
+			return Object.keys(registry());
+		},
+		getOwnPropertyDescriptor(_target, name) {
+			return typeof name === "string" && Object.hasOwn(registry(), name) ? {
+				configurable: true,
+				enumerable: true,
+				value: query(name),
+				writable: false
+			} : void 0;
+		}
+	});
 }
 //#endregion
-//#region src/query/select.ts
-/** Defers collection validation until from(), preserving the immutable selection across reuse. */
-function createSelect(registry, run, fields) {
-	const selected = [...fields];
-	return { 
-	/** Binds the current registry and prepares a reusable root query. */
-from(collection) {
-		const current = registry();
-		if (!Object.hasOwn(current, collection)) invalidQuery(`Unknown collection "${collection}".`);
-		const plan = emptyPlan(collection);
-		if (selected.length) plan.select = checkedFields(current, collection, selected);
-		else plan.allFields = true;
-		return createBuilder(current, run, plan);
-	} };
+//#region src/shared/concurrency.ts
+/**
+* Maps items through an asynchronous callback with at most `limit` callbacks in flight.
+* Results keep input order; the first rejection rejects the whole map after started work settles.
+*
+* @param items - Values to process.
+* @param limit - Maximum number of concurrent callbacks; values below one are treated as one.
+* @param callback - Asynchronous work for one item and its index.
+* @returns The callback results in input order.
+*/
+async function mapConcurrent(items, limit, callback) {
+	const results = Array.from({ length: items.length });
+	let next = 0;
+	let failure;
+	/** Claims the next unprocessed item until the list is exhausted or work has failed. */
+	async function worker() {
+		while (next < items.length && !failure) {
+			const index = next++;
+			try {
+				results[index] = await callback(items[index], index);
+			} catch (cause) {
+				failure ??= { cause };
+			}
+		}
+	}
+	const workers = Array.from({ length: Math.min(Math.max(1, limit), items.length) }, worker);
+	await Promise.all(workers);
+	if (failure) throw failure.cause;
+	return results;
 }
 //#endregion
 //#region src/query/normalize.ts
@@ -667,7 +914,10 @@ function normalizePlan(plan) {
 		...plan.select === void 0 && Object.keys(plan.with).length ? { select: [] } : {},
 		filters: plan.filters.flatMap(conjunction),
 		with: Object.fromEntries(Object.entries(plan.with).map(([name, nested]) => [name, normalizePlan(nested)])),
-		...plan.adjacent && plan.adjacent !== true ? { adjacent: normalizePlan(plan.adjacent) } : {}
+		...plan.adjacent ? { adjacent: {
+			scope: plan.adjacent.scope,
+			plan: normalizePlan(plan.adjacent.plan)
+		} } : {}
 	};
 }
 //#endregion
@@ -698,6 +948,7 @@ function matches(record, expression, revision, collection) {
 		if (!revision || !relation || relation.collection !== expression.target) invalidQuery("Relationship filter no longer matches the prepared collection scope.");
 		return (revision.relations.get(relationKey(expression.collection, expression.field))?.get(record.id) ?? []).some((candidate) => matches(candidate, expression.expression, revision, expression.target));
 	}
+	if (expression.kind === "has") invalidQuery("has() filters must be passed to a query's where() before execution.");
 	if (expression.kind !== "predicate") return false;
 	const actual = Object.hasOwn(record, expression.field) ? record[expression.field] : void 0;
 	const expected = expression.value;
@@ -744,25 +995,32 @@ function queryCandidates(records, plan) {
 function sortGroup(value) {
 	return value == null ? 2 : typeof value === "number" && Number.isNaN(value) || value instanceof Date && Number.isNaN(value.getTime()) ? 1 : 0;
 }
-/** Filters, orders, and pages one collection or one parent's related candidates. */
-function pageRecords(records, plan, revision, preserveOrder = false) {
-	if (records.length <= 1 && !plan.order.length) {
-		const record = records[0];
-		return record && plan.filters.every((expression) => matches(record, expression, revision, plan.collection)) && (plan.offset ?? 0) === 0 && plan.limit !== 0 ? [record] : [];
+/**
+* Orders two entries by their sort values. Null, undefined, and missing values sort last in both
+* directions, preceded by `NaN` and invalid dates; ties fall through to the next clause.
+*/
+function compareKeys(left, right, order) {
+	for (const [index, sort] of order.entries()) {
+		const leftValue = left[index];
+		const rightValue = right[index];
+		const group = sortGroup(leftValue) - sortGroup(rightValue);
+		if (group) return group;
+		if (sortGroup(leftValue) !== 0) continue;
+		const comparison = compare(leftValue, rightValue) ?? 0;
+		if (comparison) return sort.direction === "desc" ? -comparison : comparison;
 	}
-	const filtered = records.filter((record) => plan.filters.every((expression) => matches(record, expression, revision, plan.collection)));
-	const order = plan.order.length ? [...plan.order] : preserveOrder ? [] : [{
-		field: "id",
-		direction: "asc"
-	}];
-	if (order.length && !order.some((sort) => sort.field === "id")) order.push({
-		field: "id",
-		direction: "asc"
-	});
-	for (const sort of order) {
+	return 0;
+}
+/** Filters and orders one collection or one parent's related candidates, keeping sort keys. */
+function orderedEntries(records, plan, revision, order) {
+	const entries = records.filter((record) => plan.filters.every((expression) => matches(record, expression, revision, plan.collection))).map((record) => ({
+		record,
+		key: order.map((sort) => Object.hasOwn(record, sort.field) ? record[sort.field] : void 0)
+	}));
+	for (const [index, sort] of order.entries()) {
 		let category;
-		for (const record of filtered) {
-			const value = Object.hasOwn(record, sort.field) ? record[sort.field] : void 0;
+		for (const { key } of entries) {
+			const value = key[index];
 			if (!isScalar(value)) invalidQuery(`Field "${sort.field}" is not sortable.`);
 			if (value != null) {
 				const current = value instanceof Date ? "date" : typeof value;
@@ -771,36 +1029,86 @@ function pageRecords(records, plan, revision, preserveOrder = false) {
 			}
 		}
 	}
-	if (order.length) filtered.sort((left, right) => {
-		for (const sort of order) {
-			const leftValue = Object.hasOwn(left, sort.field) ? left[sort.field] : void 0;
-			const rightValue = Object.hasOwn(right, sort.field) ? right[sort.field] : void 0;
-			const group = sortGroup(leftValue) - sortGroup(rightValue);
-			if (group) return group;
-			if (sortGroup(leftValue) !== 0) continue;
-			const comparison = compare(leftValue, rightValue) ?? 0;
-			if (comparison) return sort.direction === "desc" ? -comparison : comparison;
-		}
-		return 0;
-	});
+	if (order.length) entries.sort((left, right) => compareKeys(left.key, right.key, order));
+	return entries;
+}
+/** Filters, orders, and pages one collection or one parent's related candidates. */
+function pageRecords(records, plan, revision, preserveOrder = false) {
+	if (records.length <= 1 && !plan.order.length) {
+		const record = records[0];
+		return record && plan.filters.every((expression) => matches(record, expression, revision, plan.collection)) && (plan.offset ?? 0) === 0 && plan.limit !== 0 ? [record] : [];
+	}
 	const offset = plan.offset ?? 0;
-	return filtered.slice(offset, plan.limit === void 0 ? void 0 : offset + plan.limit);
+	return orderedEntries(records, plan, revision, effectiveOrder(plan, preserveOrder)).slice(offset, plan.limit === void 0 ? void 0 : offset + plan.limit).map((entry) => entry.record);
+}
+/** Finds the first position where a predicate that flips from false to true once becomes true. */
+function firstIndex(items, predicate) {
+	let low = 0;
+	let high = items.length;
+	while (low < high) {
+		const middle = low + high >>> 1;
+		if (predicate(items[middle])) high = middle;
+		else low = middle + 1;
+	}
+	return low;
+}
+/**
+* Selects one page of a root scope's ordered entries and describes where it sits. Page numbers
+* count from 1, and page 1 exists even when nothing matches. Cursors position a page strictly after
+* or before the boundary entry's sort values, so a deleted boundary entry still pages correctly.
+*/
+function pageOf(entries, request, order, collection) {
+	if (request.mode === "page") {
+		const total = entries.length;
+		const pageCount = Math.max(1, Math.ceil(total / request.size));
+		const start = (request.page - 1) * request.size;
+		return {
+			entries: entries.slice(start, start + request.size),
+			info: {
+				total,
+				page: request.page,
+				pageCount,
+				hasNextPage: request.page < pageCount,
+				hasPreviousPage: request.page > 1
+			}
+		};
+	}
+	const { key } = request;
+	let start;
+	let end;
+	if (request.direction === "after") {
+		start = key ? firstIndex(entries, (entry) => compareKeys(entry.key, key, order) > 0) : 0;
+		end = Math.min(entries.length, start + request.size);
+	} else {
+		end = key ? firstIndex(entries, (entry) => compareKeys(entry.key, key, order) >= 0) : entries.length;
+		start = Math.max(0, end - request.size);
+	}
+	const page = entries.slice(start, end);
+	return {
+		entries: page,
+		info: {
+			startCursor: page.length ? encodeCursor(collection, order, page[0].key) : null,
+			endCursor: page.length ? encodeCursor(collection, order, page.at(-1).key) : null,
+			hasNextPage: end < entries.length,
+			hasPreviousPage: start > 0,
+			...request.total ? { total: entries.length } : {}
+		}
+	};
 }
 /** Builds a sibling index once per scope, before pagination and within the pinned revision. */
 function neighborScope(plan, records, preserveOrder, scopes, revision) {
-	const selection = plan.adjacent;
-	const siblingPlan = selection === true ? {
+	const { scope: neighborsScope, plan: selection } = plan.adjacent;
+	const siblingPlan = neighborsScope === "results" ? {
 		...plan,
-		select: ["id"],
-		allFields: void 0,
-		exclude: void 0,
-		with: {},
+		select: selection.select,
+		with: selection.with,
 		adjacent: void 0,
 		payloads: void 0,
 		limit: void 0,
-		offset: void 0
+		offset: void 0,
+		paginate: void 0
 	} : selection;
-	const key = selection === true ? plan : siblingPlan;
+	const key = neighborsScope === "results" ? plan : siblingPlan;
 	let candidates = scopes.get(key);
 	if (!candidates) {
 		candidates = /* @__PURE__ */ new WeakMap();
@@ -808,7 +1116,7 @@ function neighborScope(plan, records, preserveOrder, scopes, revision) {
 	}
 	let scope = candidates.get(records);
 	if (!scope) {
-		const ordered = pageRecords([...new Map(records.map((entry) => [entry.id, entry])).values()], siblingPlan, revision, selection === true && preserveOrder);
+		const ordered = pageRecords([...new Map(records.map((entry) => [entry.id, entry])).values()], siblingPlan, revision, neighborsScope === "results" && preserveOrder);
 		scope = {
 			plan: siblingPlan,
 			records: ordered,
@@ -823,9 +1131,8 @@ function neighborScope(plan, records, preserveOrder, scopes, revision) {
 * Requested payloads are recorded for the caller to load after projection.
 */
 function project(record, plan, revision, scopes, scopeRecords, requests, preserveScopeOrder = false) {
-	if (!plan.select && !plan.allFields && !plan.adjacent) invalidQuery("Row-returning queries require select().");
-	const fields = plan.allFields ? Object.keys(record).filter((field) => !plan.exclude?.includes(field)) : plan.select ?? [];
-	const result = detachSelection(record, fields);
+	if (!hasSelection(plan)) invalidQuery(NO_SELECTION_MESSAGE);
+	const result = detachSelection(record, plan.select ?? []);
 	for (const [name, nested] of Object.entries(plan.with)) {
 		const relation = revision.registry[plan.collection].relationships[name];
 		if (!relation || relation.collection !== nested.collection || relation.type === "one" && (nested.limit !== void 0 || nested.offset !== void 0 || nested.order.length > 0)) invalidQuery(`Relationship "${name}" no longer matches the prepared query scope.`);
@@ -840,7 +1147,7 @@ function project(record, plan, revision, scopes, scopeRecords, requests, preserv
 		});
 	}
 	if (plan.adjacent) {
-		const candidates = plan.adjacent === true ? scopeRecords : revision.collections[plan.collection].records;
+		const candidates = plan.adjacent.scope === "results" ? scopeRecords : revision.collections[plan.collection].records;
 		const scope = neighborScope(plan, candidates, preserveScopeOrder, scopes, revision);
 		const index = scope.positions.get(record.id);
 		const previous = index === void 0 ? void 0 : scope.records[index - 1];
@@ -861,6 +1168,13 @@ function project(record, plan, revision, scopes, scopeRecords, requests, preserv
 /**
 * Runs the shared JavaScript executor; future adapters can execute the same plan.
 * Rows that requested payloads are appended to `requests` for loading after execution.
+*
+* @param revision - The pinned revision to read.
+* @param plan - A normalized query plan.
+* @param terminal - `all` returns rows, `first` one row or undefined, `count` a number, and
+* `paginate` the page object for the plan's `paginate` request.
+* @param requests - Collects rows that requested payloads.
+* @returns The terminal's result.
 */
 async function executeQuery(revision, plan, terminal, requests = []) {
 	const collection = revision.collections[plan.collection];
@@ -869,9 +1183,19 @@ async function executeQuery(revision, plan, terminal, requests = []) {
 		if (plan.payloads) invalidQuery("Counts cannot request payloads.");
 		return queryCandidates(collection.records, plan).filter((record) => plan.filters.every((expression) => matches(record, expression, revision, plan.collection))).length;
 	}
-	if (!plan.select && !plan.allFields && !plan.adjacent) invalidQuery("Row-returning queries require select().");
-	const records = pageRecords(queryCandidates(collection.records, plan), plan, revision);
+	if (!hasSelection(plan)) invalidQuery(NO_SELECTION_MESSAGE);
 	const scopes = /* @__PURE__ */ new WeakMap();
+	if (terminal === "paginate") {
+		if (!plan.paginate) invalidQuery("paginate requires a page request.");
+		if (plan.limit !== void 0 || plan.offset !== void 0) invalidQuery(PAGINATE_AFTER_LIMIT_MESSAGE);
+		const order = effectiveOrder(plan);
+		const { entries, info } = pageOf(orderedEntries(queryCandidates(collection.records, plan), plan, revision, order), plan.paginate, order, plan.collection);
+		return {
+			items: entries.map((entry) => project(entry.record, plan, revision, scopes, collection.records, requests)),
+			...info
+		};
+	}
+	const records = pageRecords(queryCandidates(collection.records, plan), plan, revision);
 	return terminal === "first" ? records[0] ? project(records[0], plan, revision, scopes, collection.records, requests) : void 0 : records.map((record) => project(record, plan, revision, scopes, collection.records, requests));
 }
 //#endregion
@@ -951,11 +1275,48 @@ async function renderedPayload(revision, collection, id) {
 	}
 	return rendered;
 }
+/** Lazily loads one custom payload variant once per revision, retrying after failures. */
+function loadCustom(revision, collection, id, name, variant) {
+	const entries = revision.collections[collection].payloads?.get(name);
+	if (!entries) invalidQuery(`Payload "${name}" no longer matches the prepared collection.`);
+	const load = entries.get(id)?.get(variantKey(variant));
+	if (!load) return Promise.reject(new ContentError({
+		code: "variant-not-found",
+		operation: "query",
+		collection,
+		id,
+		payload: name,
+		variant,
+		message: `Entry "${id}" has no ${payloadIdentity(name, variant)} payload.`
+	}));
+	const key = JSON.stringify([
+		collection,
+		id,
+		name,
+		variantKey(variant)
+	]);
+	let loaded = revision.payloadCache.get(key);
+	if (!loaded) {
+		loaded = Promise.resolve().then(load).catch((cause) => {
+			revision.payloadCache.delete(key);
+			throw contentError(cause, {
+				code: "artifact-error",
+				collection,
+				id,
+				payload: name,
+				variant,
+				message: `Could not load the prepared ${payloadIdentity(name, variant)} payload.`
+			});
+		});
+		revision.payloadCache.set(key, loaded);
+	}
+	return loaded;
+}
 /** Loads one requested payload value from the pinned revision. */
-async function loadPayload(revision, collection, id, name) {
+async function loadPayload(revision, collection, id, name, variant) {
 	if (name === "_body") return (await loadBuiltin(revision, collection, id)).body;
 	if (name === "_rendered") return renderedPayload(revision, collection, id);
-	invalidQuery(`Payload "${name}" no longer matches the prepared collection.`);
+	return loadCustom(revision, collection, id, name, variant);
 }
 /**
 * Loads every requested payload with bounded concurrency, then attaches detached copies under
@@ -974,13 +1335,14 @@ async function attachPayloads(revision, requests) {
 		if (!loads.has(key)) loads.set(key, {
 			collection: request.collection,
 			id: request.id,
-			name
+			name,
+			variant: request.payloads[name].variant
 		});
 	}
 	const keys = [...loads.keys()];
 	const values = await mapConcurrent(keys, PAYLOAD_CONCURRENCY, (key) => {
-		const { collection, id, name } = loads.get(key);
-		return loadPayload(revision, collection, id, name);
+		const { collection, id, name, variant } = loads.get(key);
+		return loadPayload(revision, collection, id, name, variant);
 	});
 	const loaded = new Map(keys.map((key, index) => [key, values[index]]));
 	for (const request of requests) request.target._payloads = Object.fromEntries(Object.keys(request.payloads).map((name) => [name, detach(loaded.get(JSON.stringify([
@@ -990,33 +1352,325 @@ async function attachPayloads(revision, requests) {
 		request.payloads[name]
 	])))]));
 }
-/** Creates the initialized runtime without importing source configuration or schemas. */
-function createRuntime(state) {
-	/** Pins query execution and payload loading to exactly the same revision and executor. */
-	const run = (plan, terminal) => pinned(state, async (revision) => {
+/**
+* Creates the query runner that pins plan execution and payload loading to one revision.
+*
+* @param state - Mutable session, artifact, or combined state; each query reads its revision.
+* @returns A runner for fluent and relational plans.
+*/
+function createRunner(state) {
+	return (plan, terminal) => pinned(state, async (revision) => {
 		const normalized = normalizePlan(plan);
 		const requests = [];
 		const result = revision.execute ? await revision.execute(normalized, terminal, requests) : await executeQuery(revision, normalized, terminal, requests);
 		await attachPayloads(revision, requests);
 		return result;
 	});
-	/** Reads the current registry without capturing a development revision in either API. */
-	const registry = () => state.registry ?? state.revision?.registry ?? {};
-	return {
-		select(...fields) {
-			return createSelect(registry, run, fields);
+}
+//#endregion
+//#region src/runtime/query-style.ts
+/**
+* Collection members that start each query style. Every other query API hangs off these members,
+* so gating them gates payloads, relationships, and adjacency as well. `count()` without options
+* belongs to both styles; `count(options)` takes relational options.
+*/
+const queryStyleMembers = {
+	fluent: [
+		"select",
+		"where",
+		"orderBy",
+		"limit",
+		"offset",
+		"with",
+		"withPayload",
+		"selectAdjacent"
+	],
+	relational: [
+		"findMany",
+		"findFirst",
+		"paginate",
+		"count(options)"
+	]
+};
+/**
+* Checks whether a configured or manifest value names a supported query style.
+*
+* @param value - The untrusted `queryStyle` value.
+* @returns `true` for `"fluent"` or `"relational"`.
+*/
+function isQueryStyle(value) {
+	return value === "fluent" || value === "relational";
+}
+/**
+* Finds the style that owns a collection member.
+*
+* @param member - A gated collection member.
+* @returns The style whose queries start at that member.
+*/
+function styleOfMember(member) {
+	return queryStyleMembers.fluent.includes(member) ? "fluent" : "relational";
+}
+/**
+* Formats the runtime message that matches {@link QueryStyleDisabled}.
+*
+* @param collection - The queried collection.
+* @param member - The disabled member.
+* @param style - The only style the configuration allows.
+* @returns The error message.
+*/
+function queryStyleDisabledMessage(collection, member, style) {
+	return `${collection}.${member} is unavailable because content-query.config sets queryStyle to "${style}".`;
+}
+//#endregion
+//#region src/runtime/collection.ts
+assertServerOnly();
+/** The collections each handle loads: its own first, then supplied ones in name order. */
+const handleSources = /* @__PURE__ */ new WeakMap();
+/** Combined revisions by the primary collection's revision and the loaded collection names. */
+const combinations = /* @__PURE__ */ new WeakMap();
+const relationalMembers = [
+	"findMany",
+	"findFirst",
+	"paginate"
+];
+/** Reads the source state's current revision, which must still contain the collection. */
+function currentRevision({ name, state }) {
+	if (state.error) throw state.error;
+	const revision = state.revision;
+	if (!revision) throw new ContentError({
+		code: "artifact-error",
+		message: "No prepared content revision is available."
+	});
+	if (!Object.hasOwn(revision.collections, name) || !Object.hasOwn(revision.registry, name)) invalidQuery(`Unknown collection "${name}".`);
+	return revision;
+}
+/**
+* Describes exactly the loaded collections. Relationships whose target is not loaded become
+* `unavailable`, so queries that use them report which collection to supply.
+*/
+function scopeRegistry(sources, descriptors) {
+	const loaded = new Set(sources.map((source) => source.name));
+	const registry = Object.create(null);
+	sources.forEach((source, index) => {
+		const descriptor = descriptors[index] ?? { relationships: {} };
+		const relationships = Object.create(null);
+		const unavailable = Object.create(null);
+		for (const [name, relation] of Object.entries(descriptor.relationships)) if (loaded.has(relation.collection)) relationships[name] = relation;
+		else unavailable[name] = relation.collection;
+		registry[source.name] = {
+			relationships,
+			...descriptor.payloads ? { payloads: descriptor.payloads } : {},
+			...Object.keys(unavailable).length ? { unavailable } : {}
+		};
+	});
+	return registry;
+}
+/** Builds one revision over exactly the loaded collections, relating only loaded relationships. */
+function combine(sources, parts) {
+	const registry = scopeRegistry(sources, sources.map((source, index) => parts[index].registry[source.name]));
+	const collections = Object.create(null);
+	sources.forEach((source, index) => {
+		const prepared = parts[index].collections[source.name];
+		collections[source.name] = {
+			get records() {
+				return prepared.records;
+			},
+			get builtins() {
+				return prepared.builtins;
+			},
+			get payloads() {
+				return prepared.payloads;
+			},
+			get sources() {
+				return prepared.sources;
+			},
+			relationships: registry[source.name].relationships
+		};
+	});
+	const shared = parts.every((part) => part === parts[0]);
+	const revision = {
+		registry,
+		collections,
+		relations: /* @__PURE__ */ new Map(),
+		active: 0,
+		payloadCache: shared ? parts[0].payloadCache : /* @__PURE__ */ new Map(),
+		renderCache: shared ? parts[0].renderCache : /* @__PURE__ */ new Map(),
+		get renderMarkdown() {
+			return parts.find((part) => part.renderMarkdown)?.renderMarkdown;
+		},
+		...parts[0].queryStyle ? { queryStyle: parts[0].queryStyle } : {}
+	};
+	let active = 0;
+	Object.defineProperty(revision, "active", {
+		get: () => active,
+		set: (value) => {
+			for (const part of new Set(parts)) part.active += value - active;
+			active = value;
+		}
+	});
+	const errors = prepareRelationships(revision);
+	if (errors.length) throw new ContentError({
+		code: "artifact-error",
+		message: "Could not relate the supplied collections. Rebuild content so every collection comes from the same build.",
+		cause: errors[0]
+	});
+	return revision;
+}
+/** Returns the cached revision over the loaded collections, rebuilding it when a source changed. */
+function loadedRevision(sources) {
+	const parts = sources.map(currentRevision);
+	let cache = combinations.get(parts[0]);
+	if (!cache) {
+		cache = /* @__PURE__ */ new Map();
+		combinations.set(parts[0], cache);
+	}
+	const key = JSON.stringify(sources.map((source) => source.name));
+	const cached = cache.get(key);
+	if (cached && cached.parts.every((part, index) => part === parts[index])) return cached.revision;
+	const revision = combine(sources, parts);
+	cache.set(key, {
+		parts,
+		revision
+	});
+	return revision;
+}
+/**
+* Reads the registry that queries build against. While a source holds an error, it falls back to
+* the declared registries, so queries still build and running them reports the error.
+*/
+function loadedRegistry(sources) {
+	if (sources.every((source) => !source.state.error && source.state.revision)) return loadedRevision(sources).registry;
+	return scopeRegistry(sources, sources.map(({ name, state }) => {
+		const registry = state.revision?.registry ?? state.registry;
+		return registry && Object.hasOwn(registry, name) ? registry[name] : void 0;
+	}));
+}
+/** Orders sources canonically and rejects two different copies of one collection. */
+function normalizeSources(primary, supplied) {
+	const byName = /* @__PURE__ */ new Map([[primary.name, primary]]);
+	for (const source of supplied) {
+		const existing = byName.get(source.name);
+		if (existing && existing.state !== source.state) invalidQuery(`using() received two different copies of collection "${source.name}".`);
+		byName.set(source.name, existing ?? source);
+	}
+	const others = [...byName.values()].filter((source) => source !== primary).sort((left, right) => left.name < right.name ? -1 : left.name > right.name ? 1 : 0);
+	return Object.freeze([primary, ...others]);
+}
+/**
+* Creates the query handle for one collection. Its queries load only that collection plus the
+* collections passed to `using()`; relationships into any other collection are unavailable.
+*
+* @param primary - The queried collection and the state that holds it.
+* @param supplied - Collections that relationships may load.
+* @returns The collection handle.
+*/
+function createCollection(primary, supplied = []) {
+	const sources = normalizeSources(primary, supplied);
+	const name = primary.name;
+	const run = createRunner({
+		get error() {
+			return sources.map((source) => source.state.error).find(Boolean);
+		},
+		get revision() {
+			return loadedRevision(sources);
+		}
+	});
+	const registry = () => loadedRegistry(sources);
+	const queries = createQueryNamespace(registry, run);
+	/** Rejects a member that the collection's configured query style disables. */
+	function allow(member) {
+		const style = primary.state.revision?.queryStyle;
+		if (style && styleOfMember(member) !== style) invalidQuery(queryStyleDisabledMessage(name, member, style));
+	}
+	const handle = {
+		using(...collections) {
+			const extra = collections.flatMap((collection) => {
+				const found = collection && typeof collection === "object" ? handleSources.get(collection) : void 0;
+				if (!found) invalidQuery("using() accepts collections imported from their #content-query entries.");
+				return found;
+			});
+			return createCollection(primary, [...sources.slice(1), ...extra]);
 		},
-		query: createQueryNamespace(registry, run),
-		count(collection, options = {}) {
-			return run(relationalPlan(registry(), collection, options), "count");
+		count(options) {
+			if (options !== void 0) allow("count(options)");
+			return run(relationalPlan(registry(), name, options ?? {}), "count");
 		}
 	};
+	for (const member of relationalMembers) handle[member] = (options) => {
+		allow(member);
+		return queries[name][member](options);
+	};
+	for (const member of queryStyleMembers.fluent) handle[member] = (...arguments_) => {
+		allow(member);
+		return createFrom(registry, run, name)[member](...arguments_);
+	};
+	handleSources.set(handle, sources);
+	return handle;
+}
+/**
+* Creates a live map of collection handles over one state, for sessions and tests. Handles are
+* created on first access and keep reading the state's current revision.
+*
+* @param state - Session or artifact state.
+* @returns Collection handles keyed by collection name.
+*/
+function createCollections(state) {
+	const handles = /* @__PURE__ */ new Map();
+	const names = () => Object.keys(state.revision?.registry ?? state.registry ?? {});
+	/** Reuses one handle per name, so `using()` can recognize it. */
+	function handle(name) {
+		let cached = handles.get(name);
+		if (!cached) {
+			cached = createCollection({
+				name,
+				state
+			});
+			handles.set(name, cached);
+		}
+		return cached;
+	}
+	/** Exposes current collections, and any name while an error makes queries report it. */
+	function exposed(name) {
+		return typeof name === "string" && (names().includes(name) || state.error !== void 0 && name !== "then");
+	}
+	return new Proxy(Object.create(null), {
+		get(_target, name) {
+			return exposed(name) ? handle(name) : void 0;
+		},
+		has(_target, name) {
+			return exposed(name);
+		},
+		ownKeys() {
+			return names();
+		},
+		getOwnPropertyDescriptor(_target, name) {
+			return exposed(name) ? {
+				configurable: true,
+				enumerable: true,
+				value: handle(name),
+				writable: false
+			} : void 0;
+		}
+	});
 }
-/** Keeps dev builders live across host-delivered revisions while pinning active operations. */
-function createLiveRuntime(initial) {
-	const state = { ...initial };
+/**
+* Keeps one collection handle live across host-delivered development revisions.
+*
+* @param initial - The first prepared state.
+* @param name - The collection the handle queries.
+* @returns The handle and an `update()` that switches its state to a newer revision or error.
+*/
+function createLiveCollection(initial, name) {
+	const state = {
+		revision: initial.revision,
+		registry: initial.registry,
+		error: initial.error
+	};
 	return {
-		content: createRuntime(state),
+		collection: createCollection({
+			name,
+			state
+		}),
 		update(next) {
 			state.revision = next.revision;
 			state.registry = next.registry;
@@ -1025,4 +1679,4 @@ function createLiveRuntime(initial) {
 	};
 }
 //#endregion
-export { CODEC_VERSION as a, prepareRelationships as i, createRuntime as n, isRelationship as r, createLiveRuntime as t };
+export { variantKey as a, CODEC_VERSION as c, isQueryStyle as i, createCollections as n, isRelationship as o, createLiveCollection as r, prepareRelationships as s, createCollection as t };