content-query 0.0.2 → 0.2.0

package/dist/content-N1gYshjg.mjs

@@ -0,0 +1,1028 @@
+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 { t as assertServerOnly } from "./server-only-CIJUlyL-.mjs";
+import { _ as not, t as and, x as validateExpression, y as or } from "./operators-UqWUhKQJ.mjs";
+//#region src/artifacts/types.ts
+const CODEC_VERSION = "devalue-6.0.2";
+//#endregion
+//#region src/runtime/relationships.ts
+/** Encodes a scalar match key without coercing strings, numbers, dates, or bigint. */
+function scalarKey(value) {
+	if (value == null) return;
+	if (!isScalar(value)) throw new Error("Relationship keys must be scalars or scalar arrays.");
+	if (value instanceof Date) return `date:${value.getTime()}`;
+	return `${typeof value}:${String(value)}`;
+}
+/** Formats an authored reference value for diagnostics without its internal type prefix. */
+function describeValue(value) {
+	if (typeof value === "string") return JSON.stringify(value);
+	if (typeof value === "bigint") return `${value}n`;
+	if (value instanceof Date && !Number.isNaN(value.getTime())) return value.toISOString();
+	return String(value);
+}
+/** Returns present relationship keys and preserves forward-array multiplicity. */
+function references(record, field) {
+	const value = Object.hasOwn(record, field) ? record[field] : void 0;
+	return (Array.isArray(value) ? value : [value]).flatMap((item) => {
+		const key = scalarKey(item);
+		return key === void 0 ? [] : [{
+			key,
+			value: item
+		}];
+	});
+}
+/** Returns present relationship keys for matching. */
+function keys(record, field) {
+	return references(record, field).map((reference) => reference.key);
+}
+/** Indexes all matching values once for batched relationship loading. */
+function indexRecords(records, field) {
+	const index = /* @__PURE__ */ new Map();
+	for (const record of records) for (const key of new Set(keys(record, field))) {
+		const matches = index.get(key) ?? [];
+		matches.push(record);
+		index.set(key, matches);
+	}
+	return index;
+}
+/**
+* Creates all per-entry relationship matches and validates ownership and cardinality,
+* reporting every invalid reference. Relationships touching a collection in `skipped`
+* are not checked, because its missing entries would produce speculative failures.
+*/
+function prepareRelationships(revision, skipped = /* @__PURE__ */ new Set()) {
+	const errors = [];
+	for (const [collectionName, collection] of Object.entries(revision.collections)) for (const [relationshipName, relation] of Object.entries(collection.relationships)) {
+		if (skipped.has(collectionName) || skipped.has(relation.collection)) continue;
+		/** Records one failure against the entry and field that own the invalid value. */
+		const report = (message, owner, cause) => {
+			errors.push(new ContentError({
+				code: "invalid-reference",
+				operation: "build",
+				collection: owner.collection,
+				id: owner.entry?.id,
+				source: owner.entry ? revision.collections[owner.collection]?.sources?.get(owner.entry.id) : void 0,
+				path: [owner.field],
+				message: `Invalid relationship ${collectionName}.${relationshipName}: ${message}`,
+				cause
+			}));
+		};
+		const declaration = {
+			collection: collectionName,
+			field: relation.from
+		};
+		const target = revision.collections[relation.collection];
+		if (!target || !["one", "many"].includes(relation.type) || ![
+			"from",
+			"to",
+			"none"
+		].includes(relation.referenceSide) || !relation.from || !relation.to) {
+			report("Invalid relationship declaration or unregistered target.", declaration);
+			continue;
+		}
+		if (collection.records.some((record) => Array.isArray(record[relation.from])) && target.records.some((record) => Array.isArray(record[relation.to]))) {
+			report("Array-to-array relationships are unsupported.", declaration);
+			continue;
+		}
+		let sourceIndex;
+		let targetIndex;
+		try {
+			sourceIndex = indexRecords(collection.records, relation.from);
+			targetIndex = indexRecords(target.records, relation.to);
+		} catch (cause) {
+			report(cause instanceof Error ? cause.message : String(cause), declaration, cause);
+			continue;
+		}
+		const reportedOwners = /* @__PURE__ */ new Set();
+		if (relation.referenceSide !== "none") {
+			const inverse = relation.referenceSide === "to";
+			const owning = inverse ? target : collection;
+			const oppositeIndex = inverse ? sourceIndex : targetIndex;
+			const owner = {
+				collection: inverse ? relation.collection : collectionName,
+				field: inverse ? relation.to : relation.from
+			};
+			const opposite = inverse ? collectionName : relation.collection;
+			for (const record of owning.records) {
+				const reported = /* @__PURE__ */ new Set();
+				for (const { key, value } of references(record, owner.field)) {
+					const matches = oppositeIndex.get(key)?.length ?? 0;
+					if (matches === 1 || reported.has(key)) continue;
+					reported.add(key);
+					if (!inverse) reportedOwners.add(record.id);
+					report(matches === 0 ? `Reference ${describeValue(value)} has no target in "${opposite}".` : `Reference ${describeValue(value)} matches ${matches} entries in "${opposite}".`, {
+						...owner,
+						entry: record
+					});
+				}
+			}
+		}
+		const matchesById = /* @__PURE__ */ new Map();
+		for (const record of collection.records) {
+			const candidates = keys(record, relation.from).flatMap((key) => targetIndex.get(key) ?? []);
+			const matches = relation.referenceSide === "from" && Array.isArray(record[relation.from]) ? candidates : [...new Set(candidates)].sort((left, right) => compareStrings(left.id, right.id));
+			if (relation.type === "one" && matches.length > 1 && !reportedOwners.has(record.id)) report(`A singular relationship has ${matches.length} unfiltered matches.`, {
+				...declaration,
+				entry: record
+			});
+			matchesById.set(record.id, matches);
+		}
+		revision.relations.set(relationKey(collectionName, relationshipName), matchesById);
+	}
+	return errors;
+}
+/** Builds a collision-free internal lookup key for a declared relationship. */
+function relationKey(collection, relationship) {
+	return JSON.stringify([collection, relationship]);
+}
+/** Checks the structural declaration independently from observed entry fields. */
+function isRelationship(value) {
+	return typeof value === "object" && value !== null && "collection" in value && typeof value.collection === "string" && "from" in value && typeof value.from === "string" && "to" in value && typeof value.to === "string" && "type" in value && (value.type === "one" || value.type === "many") && "referenceSide" in value && [
+		"from",
+		"to",
+		"none"
+	].includes(String(value.referenceSide));
+}
+//#endregion
+//#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/clauses.ts
+/** Checks scalar field selection for both public query frontends without a schema field catalog. */
+function checkedFields(registry, collection, fields) {
+	const scope = registry[collection];
+	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];
+}
+/** Checks one sort clause with the same cardinality and duplicate rules in either API. */
+function checkedOrder(plan, field, direction, many) {
+	if (!many || typeof field !== "string" || !field || !["asc", "desc"].includes(direction) || plan.order.some((sort) => sort.field === field)) invalidQuery("Invalid or repeated sort, or sorting a singular relationship.");
+	return [...plan.order, {
+		field,
+		direction
+	}];
+}
+/** Checks pagination before either frontend constructs its shared query plan. */
+function checkedPagination(value, many) {
+	if (!many || !Number.isSafeInteger(value) || value < 0) invalidQuery("Pagination requires a nonnegative safe integer and a many-valued scope.");
+	return value;
+}
+/** Finds a payload declaration that queries may request, rejecting unknown names. */
+function payloadDescriptor(registry, collection, name) {
+	const payloads = registry[collection]?.payloads ?? {};
+	if (typeof name !== "string" || !Object.hasOwn(payloads, name)) invalidQuery(`Unknown payload "${String(name)}" for collection "${collection}".`);
+	return payloads[name];
+}
+/** Checks one payload request against the collection's payload names and variant keys. */
+function checkedPayload(registry, collection, name, request) {
+	const { variants } = payloadDescriptor(registry, collection, name);
+	if (request === true || request === void 0) {
+		if (variants.length) invalidQuery(`Payload "${name}" requires variant keys: ${variants.join(", ")}.`);
+		return { variant: {} };
+	}
+	const variant = request;
+	if (!variant || typeof variant !== "object" || Array.isArray(variant) || Object.keys(variant).length !== variants.length || variants.some((key) => !Object.hasOwn(variant, key) || typeof variant[key] !== "string")) invalidQuery(`Payload "${name}" requires exactly these string variant keys: ${variants.join(", ") || "none"}.`);
+	return { variant: Object.fromEntries([...variants].sort().map((key) => [key, variant[key]])) };
+}
+/** Compiles a payloads option into plan requests, omitting payloads set to false. */
+function checkedPayloads(registry, collection, payloads) {
+	const requested = Object.create(null);
+	for (const [name, request] of Object.entries(payloads)) {
+		if (request === false || request === void 0) {
+			payloadDescriptor(registry, collection, name);
+			continue;
+		}
+		requested[name] = checkedPayload(registry, collection, name, request);
+	}
+	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 = {
+	equals: "eq",
+	not: "ne",
+	gt: "gt",
+	gte: "gte",
+	lt: "lt",
+	lte: "lte",
+	in: "in-array",
+	notIn: "not-in-array",
+	contains: "contains",
+	startsWith: "starts-with",
+	endsWith: "ends-with",
+	has: "array-contains",
+	hasSome: "array-contains-any",
+	hasEvery: "array-contains-all",
+	isNull: "is-null",
+	isUndefined: "is-undefined",
+	isMissing: "is-missing"
+};
+/** Requires a plain options record, rejecting arrays and class instances at API boundaries. */
+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.`);
+}
+/** Converts object predicates to the same validated expressions used by fluent operators. */
+function objectWhere(where) {
+	record(where, "where");
+	const expressions = [];
+	for (const [field, condition] of Object.entries(where)) {
+		if ([
+			"AND",
+			"OR",
+			"NOT"
+		].includes(field)) {
+			const children = (Array.isArray(condition) ? condition : [condition]).map(objectWhere);
+			expressions.push(field === "OR" ? or(...children) : field === "NOT" ? and(...children.map(not)) : and(...children));
+			continue;
+		}
+		if (isScalar(condition)) {
+			expressions.push({
+				kind: "predicate",
+				operator: "eq",
+				field,
+				value: condition
+			});
+			continue;
+		}
+		record(condition, `Filter for "${field}"`);
+		for (const [name, value] of Object.entries(condition)) {
+			if (!Object.hasOwn(operators, 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],
+				field,
+				value
+			};
+			if (name.startsWith("is")) {
+				if (typeof value !== "boolean") invalidQuery("Presence predicates require a boolean.");
+				expressions.push(value ? expression : not(expression));
+			} else expressions.push(expression);
+		}
+	}
+	const expression = and(...expressions);
+	validateExpression(expression);
+	return detach(expression);
+}
+/** Compiles explicit object options into the backend-independent fluent query contract. */
+function objectPlan(registry, collection, options, many = true, allowAdjacent = true, pagination = true) {
+	if (!Object.hasOwn(registry, collection)) invalidQuery(`Unknown collection "${collection}".`);
+	record(options, "Query");
+	const allowed = [
+		"where",
+		"select",
+		"orderBy",
+		...pagination ? ["limit", "offset"] : []
+	];
+	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);
+		validateExpression(expression);
+		plan.filters = [detach(expression)];
+	}
+	if (options.orderBy !== void 0) for (const order of Array.isArray(options.orderBy) ? options.orderBy : [options.orderBy]) {
+		record(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");
+		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.");
+		} 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 {
+			if (selection !== true) invalidQuery("Prepared fields must be selected with true.");
+			fields.push(name);
+		}
+		plan = {
+			...plan,
+			select: checkedFields(registry, collection, fields),
+			with: related
+		};
+	}
+	return plan;
+}
+//#endregion
+//#region src/query/builder.ts
+const planSymbol = Symbol("content-query.query-plan");
+const scopeSymbol = Symbol("content-query.query-scope");
+/** Creates immutable root or relationship builders over one backend-independent plan. */
+function createBuilder(registry, run, plan, many = true, root = true, scopeToken = {}, allowAdjacent = true, allowPagination = true) {
+	const scope = registry[plan.collection];
+	if (!scope) invalidQuery(`Unknown collection "${plan.collection}".`);
+	const branch = (next) => createBuilder(registry, run, {
+		...plan,
+		...next
+	}, many, root, scopeToken, allowAdjacent, allowPagination);
+	const builder = {
+		[planSymbol]: plan,
+		[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
+			});
+		},
+		where(configure) {
+			if (typeof configure !== "function") invalidQuery("where() requires a configuration callback.");
+			const expression = configure(new Proxy(Object.create(null), { get: (_target, name) => ({ name }) }));
+			validateExpression(expression);
+			return branch({ filters: [...plan.filters, detach(expression)] });
+		},
+		orderBy(field, direction = "asc") {
+			return branch({ order: checkedOrder(plan, field, direction, many) });
+		},
+		limit(value) {
+			return pagination("limit", value);
+		},
+		offset(value) {
+			return pagination("offset", value);
+		},
+		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.");
+			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;
+			if (!hasSelection(nested) || nested.collection !== relation.collection || !(scopeSymbol in configured) || configured[scopeSymbol] !== nestedScope) invalidQuery("Each relationship callback must return its explicitly selected scoped builder.");
+			return branch({ with: {
+				...plan.with,
+				[name]: nested
+			} });
+		},
+		withPayload(name, variant) {
+			if (!allowAdjacent || Object.hasOwn(plan.payloads ?? {}, name)) invalidQuery("Payloads cannot be repeated or requested in adjacent scopes.");
+			return branch({ payloads: {
+				...plan.payloads,
+				[name]: checkedPayload(registry, plan.collection, name, variant)
+			} });
+		},
+		selectAdjacent(configure) {
+			if (!allowAdjacent || plan.adjacent !== void 0) invalidQuery("Adjacency cannot be repeated or selected recursively.");
+			if (configure === void 0) return branch({ adjacent: true });
+			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 });
+			}
+			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 });
+		},
+		all() {
+			if (!root) invalidQuery("Nested builders have no terminal methods.");
+			return run(plan, "all");
+		},
+		/** Executes a selected root query, matching direct await behavior. */
+		execute() {
+			if (!root) invalidQuery("Nested builders have no terminal methods.");
+			return run(plan, "all");
+		},
+		first() {
+			if (!root) invalidQuery("Nested builders have no terminal methods.");
+			return run(plan, "first");
+		},
+		count() {
+			if (!root) invalidQuery("Nested builders have no terminal methods.");
+			return run(plan, "count");
+		}
+	};
+	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) });
+	}
+	return builder;
+}
+//#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);
+	} };
+}
+//#endregion
+//#region src/query/normalize.ts
+/** Flattens conjunctions so repeated fluent where clauses and object fields share a plan. */
+function conjunction(expression) {
+	return expression.kind === "and" ? expression.expressions.flatMap(conjunction) : [expression];
+}
+/** Normalizes both query frontends at their common execution boundary. */
+function normalizePlan(plan) {
+	return {
+		...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) } : {}
+	};
+}
+//#endregion
+//#region src/runtime/filter.ts
+/** Matches SQL-style percent/underscore patterns without adopting database collation rules. */
+function matchesPattern(actual, pattern, insensitive) {
+	if (typeof actual !== "string") return false;
+	let source = "";
+	let escaped = false;
+	for (const character of pattern) {
+		if (!escaped && character === "\\") {
+			escaped = true;
+			continue;
+		}
+		source += !escaped && character === "%" ? ".*" : !escaped && character === "_" ? "." : character.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+		escaped = false;
+	}
+	if (escaped) source += "\\\\";
+	return new RegExp(`^${source}$`, insensitive ? "isu" : "su").exec(actual)?.[0] === actual;
+}
+/** Evaluates the portable expression tree using the agreed scalar semantics. */
+function matches(record, expression, revision, collection) {
+	if (expression.kind === "and") return expression.expressions.every((child) => matches(record, child, revision, collection));
+	if (expression.kind === "or") return expression.expressions.some((child) => matches(record, child, revision, collection));
+	if (expression.kind === "not") return !matches(record, expression.expressions[0], revision, collection);
+	if (expression.kind === "relation") {
+		const relation = revision && collection === expression.collection && revision.registry[collection]?.relationships[expression.field];
+		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 !== "predicate") return false;
+	const actual = Object.hasOwn(record, expression.field) ? record[expression.field] : void 0;
+	const expected = expression.value;
+	switch (expression.operator) {
+		case "eq": return equal(actual, expected);
+		case "ne": return !equal(actual, expected);
+		case "is-null": return actual === null;
+		case "is-undefined": return actual === void 0;
+		case "is-missing": return !Object.hasOwn(record, expression.field);
+		case "in-array": return expected.some((candidate) => equal(actual, candidate));
+		case "not-in-array": return !expected.some((candidate) => equal(actual, candidate));
+		case "contains": return typeof actual === "string" && actual.includes(expected);
+		case "starts-with": return typeof actual === "string" && actual.startsWith(expected);
+		case "ends-with": return typeof actual === "string" && actual.endsWith(expected);
+		case "like":
+		case "ilike": return matchesPattern(actual, expected, expression.operator === "ilike");
+		case "array-contains": return Array.isArray(actual) && actual.some((candidate) => equal(candidate, expected));
+		case "array-contains-any": return Array.isArray(actual) && expected.some((candidate) => actual.some((item) => equal(item, candidate)));
+		case "array-contains-all": return Array.isArray(actual) && expected.every((candidate) => actual.some((item) => equal(item, candidate)));
+		case "array-contained": return Array.isArray(actual) && actual.every((candidate) => expected.some((item) => equal(candidate, item)));
+		default: {
+			const order = compare(actual, expected);
+			if (order === void 0) return false;
+			return expression.operator === "gt" ? order > 0 : expression.operator === "gte" ? order >= 0 : expression.operator === "lt" ? order < 0 : order <= 0;
+		}
+	}
+}
+//#endregion
+//#region src/runtime/execute.ts
+const recordIndexes = /* @__PURE__ */ new WeakMap();
+/** Narrows root ID-equality queries using one lazy index per immutable collection revision. */
+function queryCandidates(records, plan) {
+	const equality = plan.filters.find((expression) => expression.kind === "predicate" && expression.field === "id" && expression.operator === "eq" && typeof expression.value === "string");
+	if (equality?.kind !== "predicate" || typeof equality.value !== "string") return records;
+	let index = recordIndexes.get(records);
+	if (!index) {
+		index = new Map(records.map((record) => [record.id, record]));
+		recordIndexes.set(records, index);
+	}
+	const record = index.get(equality.value);
+	return record ? [record] : [];
+}
+/** Classifies nullish and unordered special values for direction-independent placement. */
+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] : [];
+	}
+	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) {
+		let category;
+		for (const record of filtered) {
+			const value = Object.hasOwn(record, sort.field) ? record[sort.field] : void 0;
+			if (!isScalar(value)) invalidQuery(`Field "${sort.field}" is not sortable.`);
+			if (value != null) {
+				const current = value instanceof Date ? "date" : typeof value;
+				if (category && category !== current) invalidQuery(`Field "${sort.field}" has mixed sort categories.`);
+				category = current;
+			}
+		}
+	}
+	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;
+	});
+	const offset = plan.offset ?? 0;
+	return filtered.slice(offset, plan.limit === void 0 ? void 0 : offset + plan.limit);
+}
+/** 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 ? {
+		...plan,
+		select: ["id"],
+		allFields: void 0,
+		exclude: void 0,
+		with: {},
+		adjacent: void 0,
+		payloads: void 0,
+		limit: void 0,
+		offset: void 0
+	} : selection;
+	const key = selection === true ? plan : siblingPlan;
+	let candidates = scopes.get(key);
+	if (!candidates) {
+		candidates = /* @__PURE__ */ new WeakMap();
+		scopes.set(key, candidates);
+	}
+	let scope = candidates.get(records);
+	if (!scope) {
+		const ordered = pageRecords([...new Map(records.map((entry) => [entry.id, entry])).values()], siblingPlan, revision, selection === true && preserveOrder);
+		scope = {
+			plan: siblingPlan,
+			records: ordered,
+			positions: new Map(ordered.map((entry, index) => [entry.id, index]))
+		};
+		candidates.set(records, scope);
+	}
+	return scope;
+}
+/**
+* Projects one entry and requested relationships/adjacency from one pinned 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);
+	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.`);
+		const candidates = revision.relations.get(relationKey(plan.collection, name))?.get(record.id) ?? [];
+		const preserveOrder = relation.referenceSide === "from" && Array.isArray(record[relation.from]);
+		const selected = pageRecords(candidates, nested, revision, preserveOrder).map((entry) => project(entry, nested, revision, scopes, candidates, requests, preserveOrder));
+		Object.defineProperty(result, name, {
+			value: relation.type === "many" ? selected : selected[0] ?? null,
+			enumerable: true,
+			configurable: true,
+			writable: true
+		});
+	}
+	if (plan.adjacent) {
+		const candidates = plan.adjacent === true ? 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];
+		const next = index === void 0 ? void 0 : scope.records[index + 1];
+		result._adjacent = {
+			previous: previous ? project(previous, scope.plan, revision, scopes, candidates, requests) : null,
+			next: next ? project(next, scope.plan, revision, scopes, candidates, requests) : null
+		};
+	}
+	if (plan.payloads) requests.push({
+		target: result,
+		collection: plan.collection,
+		id: record.id,
+		payloads: plan.payloads
+	});
+	return result;
+}
+/**
+* Runs the shared JavaScript executor; future adapters can execute the same plan.
+* Rows that requested payloads are appended to `requests` for loading after execution.
+*/
+async function executeQuery(revision, plan, terminal, requests = []) {
+	const collection = revision.collections[plan.collection];
+	if (!collection) invalidQuery(`Unknown collection "${plan.collection}".`);
+	if (terminal === "count") {
+		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);
+	const scopes = /* @__PURE__ */ new WeakMap();
+	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/content.ts
+assertServerOnly();
+/** Maximum payload loads in flight for one query. */
+const PAYLOAD_CONCURRENCY = 16;
+/** Pins the latest valid revision for an entire asynchronous operation. */
+async function pinned(state, operation) {
+	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."
+	});
+	revision.active++;
+	try {
+		return await operation(revision);
+	} finally {
+		revision.active--;
+	}
+}
+/** Checks a decoded built-in payload before any of its values reach a query result. */
+function validBuiltinPayload(payload) {
+	if (!payload || typeof payload !== "object" || Array.isArray(payload)) return false;
+	const { body, markdown, rendered } = payload;
+	return (body === void 0 || typeof body === "string") && (markdown === void 0 || typeof markdown === "string") && (rendered === void 0 || !!rendered && typeof rendered.html === "string" && Array.isArray(rendered.headings) && rendered.headings.every((heading) => !!heading && Number.isInteger(heading.depth) && heading.depth >= 1 && heading.depth <= 6 && typeof heading.slug === "string" && typeof heading.text === "string"));
+}
+/** Lazily loads one entry's built-in payload once per revision, retrying after failures. */
+function loadBuiltin(revision, collection, id) {
+	const key = JSON.stringify([collection, id]);
+	let loaded = revision.payloadCache.get(key);
+	if (!loaded) {
+		loaded = Promise.resolve().then(async () => {
+			const payload = await revision.collections[collection].builtins.get(id)?.() ?? {};
+			if (!validBuiltinPayload(payload)) throw new Error("Invalid prepared payload shape.");
+			return payload;
+		}).catch((cause) => {
+			revision.payloadCache.delete(key);
+			throw contentError(cause, {
+				code: "artifact-error",
+				collection,
+				id,
+				message: "Could not load the prepared entry payload."
+			});
+		});
+		revision.payloadCache.set(key, loaded);
+	}
+	return loaded;
+}
+/** Returns supplied or eagerly compiled output, or renders captured Markdown once per revision. */
+async function renderedPayload(revision, collection, id) {
+	const payload = await loadBuiltin(revision, collection, id);
+	if (payload.rendered) return payload.rendered;
+	if (payload.markdown === void 0) throw new ContentError({
+		code: "not-renderable",
+		collection,
+		id,
+		message: "This entry has no supplied output or supported rendering path."
+	});
+	const key = JSON.stringify([collection, id]);
+	let rendered = revision.renderCache.get(key);
+	if (!rendered) {
+		rendered = Promise.resolve().then(() => {
+			if (!revision.renderMarkdown) throw new Error("Missing packaged Markdown renderer.");
+			return revision.renderMarkdown(payload.markdown);
+		}).catch((cause) => {
+			revision.renderCache.delete(key);
+			throw contentError(cause, {
+				code: "render-error",
+				collection,
+				id,
+				message: "Markdown rendering failed."
+			});
+		});
+		revision.renderCache.set(key, rendered);
+	}
+	return rendered;
+}
+/** Loads one requested payload value from the pinned revision. */
+async function loadPayload(revision, collection, id, name) {
+	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.`);
+}
+/**
+* Loads every requested payload with bounded concurrency, then attaches detached copies under
+* `_payloads`. Each distinct payload loads once; rows that share an entry get independent values.
+*/
+async function attachPayloads(revision, requests) {
+	if (!requests.length) return;
+	const loads = /* @__PURE__ */ new Map();
+	for (const request of requests) for (const name of Object.keys(request.payloads)) {
+		const key = JSON.stringify([
+			request.collection,
+			request.id,
+			name,
+			request.payloads[name]
+		]);
+		if (!loads.has(key)) loads.set(key, {
+			collection: request.collection,
+			id: request.id,
+			name
+		});
+	}
+	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 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([
+		request.collection,
+		request.id,
+		name,
+		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) => {
+		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);
+		},
+		query: createQueryNamespace(registry, run),
+		count(collection, options = {}) {
+			return run(relationalPlan(registry(), collection, options), "count");
+		}
+	};
+}
+/** Keeps dev builders live across host-delivered revisions while pinning active operations. */
+function createLiveRuntime(initial) {
+	const state = { ...initial };
+	return {
+		content: createRuntime(state),
+		update(next) {
+			state.revision = next.revision;
+			state.registry = next.registry;
+			state.error = next.error;
+		}
+	};
+}
+//#endregion
+export { CODEC_VERSION as a, prepareRelationships as i, createRuntime as n, isRelationship as r, createLiveRuntime as t };