content-query 0.4.0 → 0.5.1

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

@@ -1,7 +1,7 @@
 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, s as equal, t as compare } from "./values-BbTV4QT-.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 { D as resolveRelations, E as or, S as not, k as validateExpression, l as fieldProxy, t as and } from "./operators-Cwy8Kx4o.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
@@ -156,41 +156,140 @@ function variantKey(variant) {
 	return JSON.stringify(Object.fromEntries(Object.keys(variant).sort().map((key) => [key, variant[key]])));
 }
 //#endregion
-//#region src/shared/concurrency.ts
+//#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
+	});
+}
 /**
-* 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.
+* 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 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 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.
 */
-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 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];
 }
@@ -237,236 +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: {}
-	};
-}
-/** Explains the explicit-selection rule wherever a scope returns rows without selecting data. */
-const NO_SELECTION_MESSAGE = "Select fields, relationships, payloads, or adjacent entries before running this query.";
-/**
-* Checks whether a row-returning scope explicitly requests data. Nothing is implicit, not even
-* `id`: a scope must select fields, include a relationship, request a payload, or select adjacency.
-*
-* @param plan - The scope to check; `undefined` when a callback returned no builder.
-* @returns `true` when the scope requests at least one kind of data.
-*/
-function hasSelection(plan) {
-	return !!plan && (!!plan.select?.length || !!plan.adjacent || Object.keys(plan.with).length > 0 || Object.keys(plan.payloads ?? {}).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(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 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) {
-		record$1(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$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;
-			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$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 = 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$1(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))
-	};
-}
-/**
-* 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;
-}
-/** 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")
-			};
-			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",
@@ -486,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 ([
@@ -512,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
 			};
@@ -546,7 +417,7 @@ function objectWhere(where) {
 * @returns The adjacency plan, which always selects explicit data.
 */
 function objectAdjacent(registry, collection, selection) {
-	record(selection, "_adjacent");
+	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.");
@@ -559,7 +430,7 @@ function objectAdjacent(registry, collection, selection) {
 }
 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",
@@ -574,13 +445,13 @@ function objectPlan(registry, collection, options, many = true, allowAdjacent =
 		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 = [];
@@ -594,6 +465,7 @@ function objectPlan(registry, collection, options, many = true, 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);
 		}
@@ -641,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;
@@ -700,55 +575,331 @@ function createBuilder(registry, run, plan, many = true, root = true, scopeToken
 		execute() {
 			return rows("all");
 		},
-		first() {
-			return rows("first");
+		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))
+	};
+}
+/**
+* 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 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());
 		},
-		/** 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");
-		}
-	};
-	if (root) Object.defineProperty(builder, "then", { value: (fulfilled, rejected) => {
-		let result;
-		try {
-			result = rows("all");
-		} catch (cause) {
-			result = Promise.reject(cause);
+		getOwnPropertyDescriptor(_target, name) {
+			return typeof name === "string" && Object.hasOwn(registry(), name) ? {
+				configurable: true,
+				enumerable: true,
+				value: query(name),
+				writable: false
+			} : void 0;
 		}
-		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
+//#region src/shared/concurrency.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.
+* 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 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.
+* @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.
 */
-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));
+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
@@ -844,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;
@@ -871,20 +1029,71 @@ 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) {
@@ -896,7 +1105,8 @@ function neighborScope(plan, records, preserveOrder, scopes, revision) {
 		adjacent: void 0,
 		payloads: void 0,
 		limit: void 0,
-		offset: void 0
+		offset: void 0,
+		paginate: void 0
 	} : selection;
 	const key = neighborsScope === "results" ? plan : siblingPlan;
 	let candidates = scopes.get(key);
@@ -958,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];
@@ -967,49 +1184,21 @@ async function executeQuery(revision, plan, terminal, requests = []) {
 		return queryCandidates(collection.records, plan).filter((record) => plan.filters.every((expression) => matches(record, expression, revision, plan.collection))).length;
 	}
 	if (!hasSelection(plan)) invalidQuery(NO_SELECTION_MESSAGE);
-	const records = pageRecords(queryCandidates(collection.records, plan), plan, revision);
 	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
-//#region src/runtime/query-style.ts
-/**
-* Root `content` members that start each query style. Every other query API hangs off these
-* members, so gating them gates payloads, relationships, and adjacency as well.
-*/
-const queryStyleMembers = {
-	fluent: ["from"],
-	relational: ["query", "count"]
-};
-/**
-* 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 root member.
-*
-* @param member - A gated root `content` 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 member - The disabled root member.
-* @param style - The only style the configuration allows.
-* @returns The error message.
-*/
-function queryStyleDisabledMessage(member, style) {
-	return `content.${member} is unavailable because content-query.config sets queryStyle to "${style}".`;
-}
-//#endregion
 //#region src/runtime/content.ts
 assertServerOnly();
 /** Maximum payload loads in flight for one query. */
@@ -1164,49 +1353,324 @@ async function attachPayloads(revision, requests) {
 	])))]));
 }
 /**
-* Creates the initialized runtime without importing source configuration or schemas.
+* Creates the query runner that pins plan execution and payload loading to one revision.
 *
-* @param state - Mutable session or artifact state; each query reads its current revision.
-* @returns The `content` API. Root members outside the current revision's `queryStyle` throw an
-* `invalid-query` ContentError when accessed or called.
+* @param state - Mutable session, artifact, or combined state; each query reads its revision.
+* @returns A runner for fluent and relational plans.
 */
-function createRuntime(state) {
-	/** Pins query execution and payload loading to exactly the same revision and executor. */
-	const run = (plan, terminal) => pinned(state, async (revision) => {
+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 ?? {};
-	/** Rejects a root member that the current revision's configured query style disables. */
-	function allow(member) {
-		const style = state.revision?.queryStyle;
-		if (style && styleOfMember(member) !== style) invalidQuery(queryStyleDisabledMessage(member, style));
+}
+//#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 queries = createQueryNamespace(registry, run);
-	return {
-		from(collection) {
-			allow("from");
-			return createFrom(registry, run, collection);
+	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 query() {
-			allow("query");
-			return queries;
+		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]);
 		},
-		count(collection, options = {}) {
-			allow("count");
-			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;
@@ -1215,4 +1679,4 @@ function createLiveRuntime(initial) {
 	};
 }
 //#endregion
-export { isRelationship as a, variantKey as i, createRuntime as n, prepareRelationships as o, isQueryStyle as r, CODEC_VERSION as s, 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 };