kitcn 0.24.0 → 0.25.0

package/dist/orm/aggregate-index/index.js

@@ -0,0 +1,2136 @@
+import { t as DirectAggregate } from "../../runtime-DfGsZtx3.js";
+import { a as Columns } from "../../table-rmJm5Qio.js";
+import { Y as normalizeTemporalComparableValue, _t as usesSystemCreatedAtAlias, c as AGGREGATE_ERROR, f as createError, gt as PUBLIC_CREATED_AT_FIELD, ht as INTERNAL_CREATION_TIME_FIELD, i as AGGREGATE_STATE_TABLE, it as mapWithConcurrency, l as COUNT_ERROR, n as AGGREGATE_EXTREMA_TABLE, o as getAggregateIndexDefinitions, r as AGGREGATE_MEMBER_TABLE, s as getRankIndexDefinitions, t as AGGREGATE_BUCKET_TABLE } from "../../schema-Besl-rpv.js";
+
+//#region src/orm/aggregate-index/runtime.ts
+const UNDEFINED_SENTINEL = "__kitcnUndefined";
+const FLOAT64_SIGN_BIT = 1n << 63n;
+const FLOAT64_MASK = (1n << 64n) - 1n;
+const DEFAULT_AGGREGATE_CARTESIAN_MAX_KEYS = 4096;
+const DEFAULT_AGGREGATE_WORK_BUDGET = 16384;
+const RANGE_PREFIX_WORK_UNIT_BASE = 2;
+const AGGREGATE_BUCKET_READ_CONCURRENCY = 25;
+const PUBLIC_ID_FIELD = "id";
+const INTERNAL_ID_FIELD = "_id";
+const AGGREGATE_STATE_KIND_METRIC = "metric";
+const AGGREGATE_STATE_KIND_RANK = "rank";
+const COUNT_STATUS_BUILDING = "BUILDING";
+const COUNT_STATUS_READY = "READY";
+/** Stored state is being drained before a rebuild, across several mutations. */
+const COUNT_STATUS_CLEARING = "CLEARING";
+const RANGE_WORK_STATE = Symbol("aggregateRangeWorkState");
+const isPlainObject = (value) => !!value && typeof value === "object" && !Array.isArray(value);
+const normalizeUndefined = (value) => {
+	if (Array.isArray(value)) return value.map((entry) => normalizeUndefined(entry));
+	if (isPlainObject(value)) return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, normalizeUndefined(entry)]));
+	if (value === void 0) return { [UNDEFINED_SENTINEL]: true };
+	return value;
+};
+const serializeStable = (value) => JSON.stringify(normalizeUndefined(value));
+const toConstraintSet = (values) => {
+	const set = /* @__PURE__ */ new Map();
+	for (const value of values) set.set(serializeStable(value), value);
+	return set;
+};
+const intersectConstraintSets = (left, right) => {
+	const result = /* @__PURE__ */ new Map();
+	for (const [key, value] of left.entries()) if (right.has(key)) result.set(key, value);
+	return result;
+};
+const getColumnNames = (tableConfig) => {
+	const names = new Set(Object.keys(tableConfig.table[Columns] ?? {}));
+	names.add(INTERNAL_ID_FIELD);
+	if (usesSystemCreatedAtAlias(tableConfig.table)) names.add(INTERNAL_CREATION_TIME_FIELD);
+	return names;
+};
+const getRelationNames = (tableConfig) => new Set(Object.keys(tableConfig.relations ?? {}));
+const normalizeFilterFieldName = (tableConfig, fieldName) => {
+	if (fieldName === PUBLIC_ID_FIELD) return INTERNAL_ID_FIELD;
+	if (fieldName === PUBLIC_CREATED_AT_FIELD && usesSystemCreatedAtAlias(tableConfig.table)) return INTERNAL_CREATION_TIME_FIELD;
+	return fieldName;
+};
+const createFilterError = (codes, methodName, message) => createError(codes.FILTER_UNSUPPORTED, `${methodName} ${message}`);
+const isRangeComparableValue = (value) => {
+	if (typeof value === "number") return Number.isFinite(value);
+	return typeof value === "string" || typeof value === "boolean";
+};
+const withFieldConstraint = (target, fieldName) => {
+	const existing = target.get(fieldName);
+	if (existing) return existing;
+	const next = {};
+	target.set(fieldName, next);
+	return next;
+};
+const normalizeAggregateComparableValue = (tableConfig, fieldName, value) => {
+	if (fieldName === INTERNAL_CREATION_TIME_FIELD) {
+		if (value instanceof Date) return value.getTime();
+		if (Array.isArray(value)) return value.map((entry) => entry instanceof Date ? entry.getTime() : entry);
+		return value;
+	}
+	return normalizeTemporalComparableValue(tableConfig.table, fieldName, value);
+};
+const pushConstraint = (target, fieldName, values) => {
+	const incoming = toConstraintSet(values);
+	const existing = withFieldConstraint(target, fieldName);
+	if (!existing.values) {
+		existing.values = incoming;
+		return;
+	}
+	existing.values = intersectConstraintSets(existing.values, incoming);
+};
+const pushRangeComparison = (target, fieldName, comparison) => {
+	const existing = withFieldConstraint(target, fieldName);
+	existing.rangeComparisons ??= [];
+	existing.rangeComparisons.push(comparison);
+};
+const matchesRangeComparisons = (value, comparisons) => {
+	if (!isRangeComparableValue(value)) return false;
+	for (const comparison of comparisons) {
+		if (!isRangeComparableValue(comparison.value)) return false;
+		const compared = compareSortableValues(value, comparison.value);
+		if (comparison.operator === "gt" && !(compared > 0)) return false;
+		if (comparison.operator === "gte" && !(compared >= 0)) return false;
+		if (comparison.operator === "lt" && !(compared < 0)) return false;
+		if (comparison.operator === "lte" && !(compared <= 0)) return false;
+	}
+	return true;
+};
+const normalizeConstraints = (constraints, codes, methodName) => {
+	for (const [fieldName, constraint] of constraints.entries()) {
+		if (constraint.rangeComparisons?.length) {
+			for (const comparison of constraint.rangeComparisons) if (!isRangeComparableValue(comparison.value)) throw createFilterError(codes, methodName, `range operators on '${fieldName}' only support finite numbers, strings, and booleans.`);
+		}
+		if (constraint.values && constraint.rangeComparisons?.length) {
+			const filtered = /* @__PURE__ */ new Map();
+			for (const [stableKey, candidate] of constraint.values.entries()) if (matchesRangeComparisons(candidate, constraint.rangeComparisons)) filtered.set(stableKey, candidate);
+			constraint.values = filtered;
+			constraint.rangeComparisons = void 0;
+		}
+		if ((!constraint.values || constraint.values.size === 0) && (!constraint.rangeComparisons || constraint.rangeComparisons.length === 0)) {
+			if (constraint.values && constraint.values.size === 0) continue;
+			constraints.delete(fieldName);
+		}
+	}
+};
+const parseFieldFilter = (tableConfig, fieldName, value, target, codes, methodName) => {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) {
+		pushConstraint(target, fieldName, [normalizeAggregateComparableValue(tableConfig, fieldName, value)]);
+		return;
+	}
+	const filter = value;
+	if (Object.hasOwn(filter, "OR") || Object.hasOwn(filter, "NOT")) throw createFilterError(codes, methodName, `does not support OR/NOT for field '${fieldName}'.`);
+	if (Object.hasOwn(filter, "AND")) {
+		const andEntries = filter.AND;
+		if (!Array.isArray(andEntries)) throw createFilterError(codes, methodName, `field-level AND for '${fieldName}' must be an array.`);
+		for (const entry of andEntries) parseFieldFilter(tableConfig, fieldName, entry, target, codes, methodName);
+	}
+	let hasRecognizedOperator = false;
+	if (Object.hasOwn(filter, "eq")) {
+		hasRecognizedOperator = true;
+		pushConstraint(target, fieldName, [normalizeAggregateComparableValue(tableConfig, fieldName, filter.eq)]);
+	}
+	if (Object.hasOwn(filter, "in")) {
+		hasRecognizedOperator = true;
+		const inValues = filter.in;
+		if (!Array.isArray(inValues)) throw createFilterError(codes, methodName, `field '${fieldName}'.in must be an array.`);
+		pushConstraint(target, fieldName, normalizeAggregateComparableValue(tableConfig, fieldName, inValues));
+	}
+	if (Object.hasOwn(filter, "isNull")) {
+		hasRecognizedOperator = true;
+		if (filter.isNull !== true) throw createFilterError(codes, methodName, `field '${fieldName}'.isNull only supports true.`);
+		pushConstraint(target, fieldName, [null]);
+	}
+	for (const operator of [
+		"gt",
+		"gte",
+		"lt",
+		"lte"
+	]) {
+		if (!Object.hasOwn(filter, operator)) continue;
+		const boundValue = filter[operator];
+		if (boundValue === void 0) continue;
+		hasRecognizedOperator = true;
+		if (boundValue === null || Array.isArray(boundValue) || isPlainObject(boundValue)) throw createFilterError(codes, methodName, `field '${fieldName}'.${operator} requires a scalar bound.`);
+		pushRangeComparison(target, fieldName, {
+			operator,
+			value: normalizeAggregateComparableValue(tableConfig, fieldName, boundValue)
+		});
+	}
+	const unsupportedOperators = Object.keys(filter).filter((operator) => ![
+		"eq",
+		"in",
+		"isNull",
+		"gt",
+		"gte",
+		"lt",
+		"lte",
+		"AND"
+	].includes(operator) && filter[operator] !== void 0);
+	if (unsupportedOperators.length > 0) throw createFilterError(codes, methodName, `does not support operators [${unsupportedOperators.join(", ")}] on '${fieldName}'.`);
+	if (!hasRecognizedOperator && !Object.hasOwn(filter, "AND")) throw createFilterError(codes, methodName, `filter for '${fieldName}' is not supported.`);
+};
+const constraintValuesEqual = (left, right) => {
+	if (!left && !right) return true;
+	if (!left || !right) return false;
+	if (left.size !== right.size) return false;
+	for (const key of left.keys()) if (!right.has(key)) return false;
+	return true;
+};
+const constraintValuesToFilter = (values) => {
+	if (values.size === 1) return values.values().next().value;
+	return { in: [...values.values()] };
+};
+const parseFiniteOrBranch = (options) => {
+	const { branch, tableConfig, codes, methodName } = options;
+	if (Object.hasOwn(branch, "AND") || Object.hasOwn(branch, "OR") || Object.hasOwn(branch, "NOT") || Object.hasOwn(branch, "RAW")) return null;
+	const columnNames = getColumnNames(tableConfig);
+	const relationNames = getRelationNames(tableConfig);
+	const constraints = /* @__PURE__ */ new Map();
+	for (const [key, value] of Object.entries(branch)) {
+		const normalizedKey = normalizeFilterFieldName(tableConfig, key);
+		if (!columnNames.has(normalizedKey)) {
+			if (relationNames.has(key)) throw createFilterError(codes, methodName, `does not support relation filters ('${key}') in v1.`);
+			throw createFilterError(codes, methodName, `filter field '${key}' is not recognized.`);
+		}
+		parseFieldFilter(tableConfig, normalizedKey, value, constraints, codes, methodName);
+	}
+	normalizeConstraints(constraints, codes, methodName);
+	const result = /* @__PURE__ */ new Map();
+	for (const [field, constraint] of constraints.entries()) {
+		if (constraint.rangeComparisons?.length) return null;
+		if (!constraint.values) continue;
+		result.set(field, new Map(constraint.values.entries()));
+	}
+	return result;
+};
+const collapseSafeOrBranches = (options) => {
+	const { branches, tableConfig, codes, methodName } = options;
+	if (branches.length === 0) return null;
+	const branchConstraints = branches.map((branch) => parseFiniteOrBranch({
+		branch,
+		tableConfig,
+		codes,
+		methodName
+	})).filter((entry) => entry !== null);
+	if (branchConstraints.length !== branches.length || branchConstraints.length === 0) return null;
+	const fields = /* @__PURE__ */ new Set();
+	for (const branch of branchConstraints) for (const field of branch.keys()) fields.add(field);
+	if (fields.size === 0) return null;
+	const varyingFields = [];
+	const first = branchConstraints[0];
+	for (const field of fields) {
+		const firstValues = first.get(field);
+		if (branchConstraints.some((branch) => !constraintValuesEqual(firstValues, branch.get(field)))) varyingFields.push(field);
+	}
+	if (varyingFields.length === 0) {
+		const collapsed = {};
+		for (const [field, values] of first.entries()) collapsed[field] = constraintValuesToFilter(values);
+		return collapsed;
+	}
+	if (varyingFields.length !== 1) return null;
+	const varyingField = varyingFields[0];
+	const unionValues = /* @__PURE__ */ new Map();
+	for (const branch of branchConstraints) {
+		const values = branch.get(varyingField);
+		if (!values || values.size === 0) return null;
+		for (const [key, value] of values.entries()) unionValues.set(key, value);
+	}
+	const collapsed = { [varyingField]: constraintValuesToFilter(unionValues) };
+	for (const [field, values] of first.entries()) {
+		if (field === varyingField) continue;
+		collapsed[field] = constraintValuesToFilter(values);
+	}
+	return collapsed;
+};
+const rewriteSafeOrWhere = (options) => {
+	const { where, tableConfig, codes, methodName } = options;
+	if (Object.hasOwn(where, "NOT")) throw createFilterError(codes, methodName, "NOT is not supported in no-scan aggregate/count filters.");
+	const normalized = {};
+	for (const [key, value] of Object.entries(where)) {
+		if (key === "AND") {
+			if (value === void 0) continue;
+			if (!Array.isArray(value)) throw createFilterError(codes, methodName, "AND must be an array of filter objects.");
+			normalized.AND = value.map((entry) => {
+				if (!isPlainObject(entry)) throw createFilterError(codes, methodName, "AND entries must be objects.");
+				return rewriteSafeOrWhere({
+					where: entry,
+					tableConfig,
+					codes,
+					methodName
+				});
+			});
+			continue;
+		}
+		if (key === "OR") continue;
+		normalized[key] = value;
+	}
+	if (!Object.hasOwn(where, "OR")) return normalized;
+	const branches = where.OR;
+	if (!Array.isArray(branches) || branches.length === 0) throw createFilterError(codes, methodName, "OR must be a non-empty array of filter objects.");
+	const collapsedOr = collapseSafeOrBranches({
+		branches: branches.map((entry) => {
+			if (!isPlainObject(entry)) throw createFilterError(codes, methodName, "OR entries must be objects.");
+			return rewriteSafeOrWhere({
+				where: entry,
+				tableConfig,
+				codes,
+				methodName
+			});
+		}),
+		tableConfig,
+		codes,
+		methodName
+	});
+	if (!collapsedOr) throw createFilterError(codes, methodName, "OR rewrite only supports finite index-plannable branches that differ on one scalar eq/in/isNull field.");
+	if (Object.keys(normalized).length === 0) return collapsedOr;
+	return { AND: [normalized, collapsedOr] };
+};
+const parseWhereObject = (where, tableConfig, target, codes, methodName) => {
+	if (Object.hasOwn(where, "OR") || Object.hasOwn(where, "NOT")) throw createFilterError(codes, methodName, "only supports conjunctions (object fields + AND).");
+	if (Object.hasOwn(where, "RAW")) throw createFilterError(codes, methodName, "does not support RAW filters.");
+	if (Object.hasOwn(where, "AND")) {
+		const andEntries = where.AND;
+		if (!Array.isArray(andEntries)) throw createFilterError(codes, methodName, "AND must be an array of filter objects.");
+		for (const entry of andEntries) {
+			if (!isPlainObject(entry)) throw createFilterError(codes, methodName, "AND entries must be objects.");
+			parseWhereObject(entry, tableConfig, target, codes, methodName);
+		}
+	}
+	const columnNames = getColumnNames(tableConfig);
+	const relationNames = getRelationNames(tableConfig);
+	for (const [key, value] of Object.entries(where)) {
+		if (key === "AND") continue;
+		const normalizedKey = normalizeFilterFieldName(tableConfig, key);
+		if (columnNames.has(normalizedKey)) {
+			parseFieldFilter(tableConfig, normalizedKey, value, target, codes, methodName);
+			continue;
+		}
+		if (relationNames.has(key)) throw createFilterError(codes, methodName, `does not support relation filters ('${key}') in v1.`);
+		throw createFilterError(codes, methodName, `filter field '${key}' is not recognized.`);
+	}
+};
+const constraintsToValueRecord = (constraints) => {
+	const record = {};
+	for (const [field, constraint] of constraints.entries()) {
+		if (!constraint.values) continue;
+		record[field] = [...constraint.values.values()];
+	}
+	return record;
+};
+const supportsMetric = (index, metric) => {
+	if (metric.kind === "count") return true;
+	if (metric.kind === "countField") return index.countFields.includes(metric.field);
+	if (metric.kind === "sum") return index.sumFields.includes(metric.field) || index.avgFields.includes(metric.field);
+	if (metric.kind === "avg") return index.avgFields.includes(metric.field);
+	if (metric.kind === "min") return index.minFields.includes(metric.field);
+	return index.maxFields.includes(metric.field);
+};
+const pickAggregateIndex = (indexDefinitions, constrainedFields, metric) => {
+	let best = null;
+	for (const definition of indexDefinitions) {
+		if (!definition.fields.every((field) => constrainedFields.has(field))) continue;
+		const indexFieldSet = new Set(definition.fields);
+		if ([...constrainedFields].some((field) => !indexFieldSet.has(field))) continue;
+		if (!supportsMetric(definition, metric)) continue;
+		if (!best || definition.fields.length > best.fields.length) best = definition;
+	}
+	return best;
+};
+const pickRangeAggregateIndex = (indexDefinitions, constraints, constrainedFields, rangeFieldName, metric) => {
+	let best = null;
+	for (const definition of indexDefinitions) {
+		if (!supportsMetric(definition, metric)) continue;
+		const usesImplicitCreationTimeSuffix = rangeFieldName === INTERNAL_CREATION_TIME_FIELD;
+		const rangeFieldPosition = usesImplicitCreationTimeSuffix ? definition.fields.length : definition.fields.indexOf(rangeFieldName);
+		if (rangeFieldPosition < 0) continue;
+		const indexFieldSet = new Set(definition.fields);
+		if (usesImplicitCreationTimeSuffix) indexFieldSet.add(INTERNAL_CREATION_TIME_FIELD);
+		if ([...constrainedFields].some((field) => !indexFieldSet.has(field))) continue;
+		const prefixFields = definition.fields.slice(0, rangeFieldPosition);
+		if (prefixFields.some((field) => {
+			return !constraints.get(field)?.values;
+		})) continue;
+		if (prefixFields.some((field) => {
+			const fieldConstraint = constraints.get(field);
+			return Boolean(fieldConstraint?.rangeComparisons?.length);
+		})) continue;
+		if (!best || prefixFields.length > best.prefixFields.length || prefixFields.length === best.prefixFields.length && definition.fields.length > best.definition.fields.length) best = {
+			definition,
+			prefixFields
+		};
+	}
+	return best;
+};
+const buildCandidateKeys = (fields, constraints, index = 0, current = [], output = []) => {
+	if (index >= fields.length) {
+		output.push([...current]);
+		return output;
+	}
+	const values = constraints[fields[index]] ?? [];
+	for (const value of values) {
+		current.push(value);
+		buildCandidateKeys(fields, constraints, index + 1, current, output);
+		current.pop();
+	}
+	return output;
+};
+const getAggregateCartesianMaxKeys = (tableConfig) => {
+	const value = tableConfig.defaults?.aggregateCartesianMaxKeys;
+	if (typeof value === "number" && Number.isFinite(value) && value >= 1) return Math.floor(value);
+	return DEFAULT_AGGREGATE_CARTESIAN_MAX_KEYS;
+};
+const getAggregateWorkBudget = (tableConfig) => {
+	const value = tableConfig.defaults?.aggregateWorkBudget;
+	if (typeof value === "number" && Number.isFinite(value) && value >= 1) return Math.floor(value);
+	return DEFAULT_AGGREGATE_WORK_BUDGET;
+};
+const countCartesianCombinations = (fields, constraints, maxCount) => {
+	if (fields.length === 0) return 1;
+	let total = 1;
+	for (const field of fields) {
+		const values = constraints[field] ?? [];
+		if (values.length === 0) return 0;
+		const threshold = Math.max(1, maxCount);
+		const maxBeforeMultiply = Math.floor(threshold / values.length);
+		if (total > maxBeforeMultiply) return threshold + 1;
+		total *= values.length;
+	}
+	return total;
+};
+const enforceCartesianExpansionGuards = (options) => {
+	const cartesianMaxKeys = getAggregateCartesianMaxKeys(options.tableConfig);
+	const workBudget = getAggregateWorkBudget(options.tableConfig);
+	const workUnitsPerCombination = Math.max(1, options.workUnitsPerCombination);
+	const maxCombinationsByWork = Math.max(1, Math.floor(workBudget / workUnitsPerCombination));
+	const maxTrackedCombinations = Math.max(cartesianMaxKeys, maxCombinationsByWork);
+	const combinations = countCartesianCombinations(options.fields, options.fieldValues, maxTrackedCombinations);
+	if (combinations === 0) return;
+	if (combinations > cartesianMaxKeys) throw createFilterError(options.codes, options.methodName, `expands IN filters to ${combinations} key combinations on aggregateIndex '${options.indexName}', exceeding aggregateCartesianMaxKeys (${cartesianMaxKeys}). Reduce IN list sizes, split the query, add a narrower aggregateIndex, or increase defineSchema(..., { defaults: { aggregateCartesianMaxKeys } }).`);
+	const estimatedWork = combinations * workUnitsPerCombination;
+	if (estimatedWork > workBudget) throw createFilterError(options.codes, options.methodName, `estimated ${options.workLabel} is ${estimatedWork} units on aggregateIndex '${options.indexName}', exceeding aggregateWorkBudget (${workBudget}). Reduce IN fan-out, split the query, or increase defineSchema(..., { defaults: { aggregateWorkBudget } }).`);
+};
+const hasLogicalOr = (where) => {
+	if (Object.hasOwn(where, "OR")) return true;
+	const andEntries = where.AND;
+	if (!Array.isArray(andEntries)) return false;
+	return andEntries.some((entry) => isPlainObject(entry) && hasLogicalOr(entry));
+};
+const combineDnfBranches = (options) => {
+	const { left, right, maxBranches, codes, methodName } = options;
+	if (left.length === 0 || right.length === 0) return [];
+	const threshold = Math.max(1, maxBranches);
+	const maxBeforeMultiply = Math.floor(threshold / right.length);
+	if (left.length > maxBeforeMultiply) throw createFilterError(codes, methodName, `OR rewrite expands to ${left.length * right.length} branches, exceeding aggregateCartesianMaxKeys (${threshold}). Reduce OR fan-out, split the query, or increase defineSchema(..., { defaults: { aggregateCartesianMaxKeys } }).`);
+	const combined = [];
+	for (const leftBranch of left) for (const rightBranch of right) combined.push([...leftBranch, ...rightBranch]);
+	return combined;
+};
+const expandWhereToFiniteDnf = (options) => {
+	const { where, maxBranches, codes, methodName } = options;
+	if (Object.hasOwn(where, "NOT")) throw createFilterError(codes, methodName, "NOT is not supported in no-scan aggregate/count filters.");
+	if (Object.hasOwn(where, "RAW")) throw createFilterError(codes, methodName, "does not support RAW filters.");
+	const scalarClause = {};
+	for (const [key, value] of Object.entries(where)) {
+		if (key === "AND" || key === "OR") continue;
+		scalarClause[key] = value;
+	}
+	let branches = [[]];
+	if (Object.keys(scalarClause).length > 0) branches = branches.map((branch) => [...branch, scalarClause]);
+	if (Object.hasOwn(where, "AND")) {
+		const andEntries = where.AND;
+		if (!Array.isArray(andEntries)) throw createFilterError(codes, methodName, "AND must be an array of filter objects.");
+		for (const entry of andEntries) {
+			if (!isPlainObject(entry)) throw createFilterError(codes, methodName, "AND entries must be objects.");
+			const entryBranches = expandWhereToFiniteDnf({
+				where: entry,
+				maxBranches,
+				codes,
+				methodName
+			});
+			branches = combineDnfBranches({
+				left: branches,
+				right: entryBranches,
+				maxBranches,
+				codes,
+				methodName
+			});
+		}
+	}
+	if (Object.hasOwn(where, "OR")) {
+		const orEntries = where.OR;
+		if (!Array.isArray(orEntries) || orEntries.length === 0) throw createFilterError(codes, methodName, "OR must be a non-empty array of filter objects.");
+		const orBranches = [];
+		for (const entry of orEntries) {
+			if (!isPlainObject(entry)) throw createFilterError(codes, methodName, "OR entries must be objects.");
+			const expanded = expandWhereToFiniteDnf({
+				where: entry,
+				maxBranches,
+				codes,
+				methodName
+			});
+			orBranches.push(...expanded);
+			if (orBranches.length > maxBranches) throw createFilterError(codes, methodName, `OR rewrite expands to ${orBranches.length} branches, exceeding aggregateCartesianMaxKeys (${maxBranches}). Reduce OR fan-out, split the query, or increase defineSchema(..., { defaults: { aggregateCartesianMaxKeys } }).`);
+		}
+		branches = combineDnfBranches({
+			left: branches,
+			right: orBranches,
+			maxBranches,
+			codes,
+			methodName
+		});
+	}
+	return branches;
+};
+const branchToWhere = (branch) => {
+	if (branch.length === 0) return {};
+	if (branch.length === 1) return branch[0];
+	return { AND: branch };
+};
+const compileFiniteOrUnionPlan = (options) => {
+	const { tableConfig, where, metric, aggregateIndexes, codes, methodName, throwNotIndexed } = options;
+	if (!hasLogicalOr(where)) return null;
+	const cartesianMaxKeys = getAggregateCartesianMaxKeys(tableConfig);
+	const workBudget = getAggregateWorkBudget(tableConfig);
+	const branches = expandWhereToFiniteDnf({
+		where,
+		maxBranches: Math.max(1, Math.min(cartesianMaxKeys, workBudget)),
+		codes,
+		methodName
+	});
+	if (branches.length === 0) throw createFilterError(codes, methodName, "OR must include at least one branch.");
+	const dedupedKeyCandidates = /* @__PURE__ */ new Map();
+	let selectedIndexName = null;
+	let selectedIndexFields = null;
+	let totalBranchCandidates = 0;
+	for (const branch of branches) {
+		const branchWhere = branchToWhere(branch);
+		const constraints = /* @__PURE__ */ new Map();
+		parseWhereObject(branchWhere, tableConfig, constraints, codes, methodName);
+		normalizeConstraints(constraints, codes, methodName);
+		if ([...constraints.entries()].filter(([, constraint]) => (constraint.rangeComparisons?.length ?? 0) > 0).map(([field]) => field).length > 0) throw createFilterError(codes, methodName, "OR rewrite supports finite eq/in/isNull branches only in v1. Range operators inside OR are not supported.");
+		const matchedIndex = pickAggregateIndex(aggregateIndexes, new Set(constraints.keys()), metric);
+		if (!matchedIndex) throwNotIndexed();
+		const exactIndex = matchedIndex;
+		if (selectedIndexName === null || selectedIndexFields === null) {
+			selectedIndexName = exactIndex.name;
+			selectedIndexFields = exactIndex.fields;
+		} else if (selectedIndexName !== exactIndex.name || selectedIndexFields.length !== exactIndex.fields.length || selectedIndexFields.some((field, index) => field !== exactIndex.fields[index])) throw createFilterError(codes, methodName, `OR branches must resolve to a single aggregateIndex. Found incompatible branches between '${selectedIndexName}' and '${exactIndex.name}'.`);
+		const rawFieldValues = constraintsToValueRecord(constraints);
+		const fieldValues = Object.fromEntries(exactIndex.fields.map((field) => [field, rawFieldValues[field] ?? []]));
+		enforceCartesianExpansionGuards({
+			tableConfig,
+			codes,
+			methodName,
+			indexName: exactIndex.name,
+			fields: exactIndex.fields,
+			fieldValues,
+			workUnitsPerCombination: 1,
+			workLabel: "OR-branch key lookup work"
+		});
+		if (Object.values(fieldValues).some((values) => values.length === 0)) continue;
+		const branchCandidates = buildCandidateKeys(exactIndex.fields, fieldValues);
+		totalBranchCandidates += branchCandidates.length;
+		for (const keyParts of branchCandidates) dedupedKeyCandidates.set(serializeCountKeyParts(keyParts), keyParts);
+	}
+	if (!selectedIndexName || !selectedIndexFields) throw createFilterError(codes, methodName, "OR rewrite did not resolve to any index-plannable branch.");
+	const uniqueKeyCount = dedupedKeyCandidates.size;
+	if (uniqueKeyCount > cartesianMaxKeys) throw createFilterError(codes, methodName, `OR rewrite expands to ${uniqueKeyCount} unique key combinations on aggregateIndex '${selectedIndexName}', exceeding aggregateCartesianMaxKeys (${cartesianMaxKeys}). Reduce OR fan-out, split the query, or increase defineSchema(..., { defaults: { aggregateCartesianMaxKeys } }).`);
+	const estimatedWork = branches.length + totalBranchCandidates;
+	if (estimatedWork > workBudget) throw createFilterError(codes, methodName, `estimated OR rewrite work is ${estimatedWork} units on aggregateIndex '${selectedIndexName}', exceeding aggregateWorkBudget (${workBudget}). Reduce OR fan-out, split the query, or increase defineSchema(..., { defaults: { aggregateWorkBudget } }).`);
+	return {
+		tableName: tableConfig.name,
+		indexName: selectedIndexName,
+		indexFields: selectedIndexFields,
+		fieldValues: {},
+		keyCandidates: [...dedupedKeyCandidates.values()],
+		rangeConstraint: null,
+		postFieldValues: {},
+		metric
+	};
+};
+const serializeCountKeyParts = (parts) => serializeStable(parts);
+const compileAggregatePlan = (tableConfig, where, metric, codes, methodName) => {
+	const normalizedWhere = where ?? {};
+	if (!isPlainObject(normalizedWhere)) throw createFilterError(codes, methodName, "where must be an object filter.");
+	const aggregateIndexes = getAggregateIndexDefinitions(tableConfig);
+	const throwNotIndexed = (fieldList) => {
+		if (metric.kind === "count") throw createError(codes.NOT_INDEXED, `No matching aggregateIndex found for count() on '${tableConfig.name}'. Add an aggregateIndex for [${fieldList}] and run aggregateBackfill.`);
+		if (metric.kind === "countField") throw createError(codes.NOT_INDEXED, `No matching aggregateIndex found for count(select: { ${metric.field}: true }) on '${tableConfig.name}'. Declare aggregateIndex(...).on(...).count(...) and run aggregateBackfill.`);
+		if (metric.kind === "avg") throw createError(codes.NOT_INDEXED, `No matching aggregateIndex found for avg('${metric.field}') on '${tableConfig.name}'. Declare aggregateIndex(...).on(...).avg(...) (or .all() for unfiltered) and run aggregateBackfill.`);
+		throw createError(codes.NOT_INDEXED, `No matching aggregateIndex found for ${metric.kind}('${metric.field}') on '${tableConfig.name}'. Declare aggregateIndex(...).on(...).${metric.kind}(...) (or .all() for unfiltered) and run aggregateBackfill.`);
+	};
+	const finiteOrUnionPlan = compileFiniteOrUnionPlan({
+		tableConfig,
+		where: normalizedWhere,
+		metric,
+		aggregateIndexes,
+		codes,
+		methodName,
+		throwNotIndexed: () => throwNotIndexed("OR branches")
+	});
+	if (finiteOrUnionPlan) return finiteOrUnionPlan;
+	const constraints = /* @__PURE__ */ new Map();
+	parseWhereObject(rewriteSafeOrWhere({
+		where: normalizedWhere,
+		tableConfig,
+		codes,
+		methodName
+	}), tableConfig, constraints, codes, methodName);
+	normalizeConstraints(constraints, codes, methodName);
+	const constrainedFields = new Set(constraints.keys());
+	const rangeFields = [...constraints.entries()].filter(([, constraint]) => (constraint.rangeComparisons?.length ?? 0) > 0).map(([field]) => field);
+	if (rangeFields.length > 1) throw createFilterError(codes, methodName, `supports range operators on at most one field in v1. Found [${rangeFields.join(", ")}].`);
+	const fieldList = [...constrainedFields].join(", ");
+	if (rangeFields.length === 0) {
+		const matchedIndex = pickAggregateIndex(aggregateIndexes, constrainedFields, metric);
+		if (!matchedIndex) throwNotIndexed(fieldList);
+		const exactIndex = matchedIndex;
+		const rawFieldValues = constraintsToValueRecord(constraints);
+		const fieldValues = Object.fromEntries(exactIndex.fields.map((field) => [field, rawFieldValues[field] ?? []]));
+		enforceCartesianExpansionGuards({
+			tableConfig,
+			codes,
+			methodName,
+			indexName: exactIndex.name,
+			fields: exactIndex.fields,
+			fieldValues,
+			workUnitsPerCombination: 1,
+			workLabel: "key lookup work"
+		});
+		for (const values of Object.values(fieldValues)) if (values.length === 0) return {
+			tableName: tableConfig.name,
+			indexName: exactIndex.name,
+			indexFields: exactIndex.fields,
+			fieldValues,
+			rangeConstraint: null,
+			postFieldValues: {},
+			metric
+		};
+		return {
+			tableName: tableConfig.name,
+			indexName: exactIndex.name,
+			indexFields: exactIndex.fields,
+			fieldValues,
+			rangeConstraint: null,
+			postFieldValues: {},
+			metric
+		};
+	}
+	const rangeFieldName = rangeFields[0];
+	const rangeComparisons = constraints.get(rangeFieldName)?.rangeComparisons ?? [];
+	const matchedRangeIndex = pickRangeAggregateIndex(aggregateIndexes, constraints, constrainedFields, rangeFieldName, metric);
+	if (!matchedRangeIndex) throwNotIndexed(fieldList);
+	const rangeIndex = matchedRangeIndex;
+	const prefixFieldValues = Object.fromEntries(rangeIndex.prefixFields.map((field) => [field, [...constraints.get(field)?.values?.values() ?? []]]));
+	const postFieldValues = {};
+	for (const field of rangeIndex.definition.fields) {
+		if (field === rangeFieldName || rangeIndex.prefixFields.includes(field)) continue;
+		const values = constraints.get(field)?.values;
+		if (!values) continue;
+		postFieldValues[field] = [...values.values()];
+	}
+	const rangeWorkUnits = RANGE_PREFIX_WORK_UNIT_BASE + Object.keys(postFieldValues).length;
+	enforceCartesianExpansionGuards({
+		tableConfig,
+		codes,
+		methodName,
+		indexName: rangeIndex.definition.name,
+		fields: rangeIndex.prefixFields,
+		fieldValues: prefixFieldValues,
+		workUnitsPerCombination: rangeWorkUnits,
+		workLabel: "range-prefix work"
+	});
+	return {
+		tableName: tableConfig.name,
+		indexName: rangeIndex.definition.name,
+		indexFields: rangeIndex.definition.fields,
+		fieldValues: prefixFieldValues,
+		rangeConstraint: {
+			fieldName: rangeFieldName,
+			comparisons: rangeComparisons,
+			prefixFields: rangeIndex.prefixFields,
+			workBudget: getAggregateWorkBudget(tableConfig),
+			filterErrorCode: codes.FILTER_UNSUPPORTED,
+			methodName
+		},
+		postFieldValues,
+		metric
+	};
+};
+const compileCountQueryPlan = (tableConfig, where) => {
+	const plan = compileAggregatePlan(tableConfig, where, { kind: "count" }, COUNT_ERROR, "count()");
+	return {
+		tableName: plan.tableName,
+		indexName: plan.indexName,
+		indexFields: plan.indexFields,
+		fieldValues: plan.fieldValues,
+		keyCandidates: plan.keyCandidates,
+		rangeConstraint: plan.rangeConstraint,
+		postFieldValues: plan.postFieldValues
+	};
+};
+const compileCountFieldQueryPlan = (tableConfig, where, field) => compileAggregatePlan(tableConfig, where, {
+	kind: "countField",
+	field
+}, COUNT_ERROR, `count(select: { ${field}: true })`);
+const compileAggregateQueryPlan = (tableConfig, where, metric) => compileAggregatePlan(tableConfig, where, metric, AGGREGATE_ERROR, (() => {
+	if (metric.kind === "countField") return `count(select: { ${metric.field}: true })`;
+	if (metric.kind === "avg") return `avg('${metric.field}')`;
+	return `${metric.kind}()`;
+})());
+const deepEquals = (left, right) => serializeStable(left) === serializeStable(right);
+const normalizeSumValues = (values) => {
+	const output = {};
+	for (const [field, value] of Object.entries(values)) if (typeof value === "number" && Number.isFinite(value)) output[field] = value;
+	return output;
+};
+const normalizeNonNullCountValues = (values) => {
+	const output = {};
+	for (const [field, value] of Object.entries(values)) if (typeof value === "number" && Number.isFinite(value)) output[field] = value;
+	return output;
+};
+const normalizeExtremaValues = (values) => ({ ...values });
+const mergeSumValues = (baseValues, deltaValues) => {
+	const merged = { ...baseValues };
+	for (const [field, delta] of Object.entries(deltaValues)) {
+		const next = (merged[field] ?? 0) + delta;
+		if (next === 0) {
+			delete merged[field];
+			continue;
+		}
+		merged[field] = next;
+	}
+	return merged;
+};
+const mergeCountValues = (baseValues, deltaValues) => {
+	const merged = { ...baseValues };
+	for (const [field, delta] of Object.entries(deltaValues)) {
+		const next = (merged[field] ?? 0) + delta;
+		if (next === 0) {
+			delete merged[field];
+			continue;
+		}
+		merged[field] = next;
+	}
+	return merged;
+};
+const negateSumValues = (values) => Object.fromEntries(Object.entries(values).map(([field, value]) => [field, -value]));
+const negateCountValues = (values) => Object.fromEntries(Object.entries(values).map(([field, value]) => [field, -value]));
+const listBucketsByHash = async (db, tableName, indexName, keyHash) => await db.query(AGGREGATE_BUCKET_TABLE).withIndex("by_table_index_hash", (q) => q.eq("tableKey", tableName).eq("indexName", indexName).eq("keyHash", keyHash)).collect();
+const getBucketByKey = async (db, tableName, indexName, keyParts) => {
+	return (await listBucketsByHash(db, tableName, indexName, serializeCountKeyParts(keyParts))).find((bucket) => deepEquals(bucket.keyParts, keyParts)) ?? null;
+};
+const listBucketsByHashPrefix = async (db, tableName, indexName, scan, limit) => await db.query(AGGREGATE_BUCKET_TABLE).withIndex("by_table_index_hash", (q) => {
+	const scoped = q.eq("tableKey", tableName).eq("indexName", indexName);
+	return (scan.after === void 0 ? scoped.gte("keyHash", scan.start) : scoped.gt("keyHash", scan.after)).lt("keyHash", scan.end);
+}).take(limit);
+const getExtremaByValue = async (db, tableName, indexName, keyHash, fieldName, value) => {
+	const valueHash = serializeStable(value);
+	return (await db.query(AGGREGATE_EXTREMA_TABLE).withIndex("by_table_index_hash_field_value", (q) => q.eq("tableKey", tableName).eq("indexName", indexName).eq("keyHash", keyHash).eq("fieldName", fieldName).eq("valueHash", valueHash)).collect()).find((row) => deepEquals(row.value, value)) ?? null;
+};
+const takeMembersForIndex = async (db, tableName, indexName, limit) => await db.query(AGGREGATE_MEMBER_TABLE).withIndex("by_kind_table_index", (q) => q.eq("kind", AGGREGATE_STATE_KIND_METRIC).eq("tableKey", tableName).eq("indexName", indexName)).take(limit);
+const takeBucketsForIndex = async (db, tableName, indexName, limit) => await db.query(AGGREGATE_BUCKET_TABLE).withIndex("by_table_index", (q) => q.eq("tableKey", tableName).eq("indexName", indexName)).take(limit);
+const takeExtremaForIndex = async (db, tableName, indexName, limit) => await db.query(AGGREGATE_EXTREMA_TABLE).withIndex("by_table_index", (q) => q.eq("tableKey", tableName).eq("indexName", indexName)).take(limit);
+const applyBucketDelta = async (db, tableName, indexName, keyParts, deltaCount, deltaSums, deltaNonNullCounts) => {
+	if (deltaCount === 0 && Object.keys(deltaSums).length === 0 && Object.keys(deltaNonNullCounts).length === 0) return;
+	const existing = await getBucketByKey(db, tableName, indexName, keyParts);
+	const now = Date.now();
+	if (!existing) {
+		if (deltaCount < 0) return;
+		await db.insert(AGGREGATE_BUCKET_TABLE, {
+			tableKey: tableName,
+			indexName,
+			keyHash: serializeCountKeyParts(keyParts),
+			keyParts,
+			count: deltaCount,
+			sumValues: deltaSums,
+			nonNullCountValues: deltaNonNullCounts,
+			updatedAt: now
+		});
+		return;
+	}
+	const nextCount = existing.count + deltaCount;
+	if (nextCount <= 0) {
+		await db.delete(AGGREGATE_BUCKET_TABLE, existing._id);
+		return;
+	}
+	const nextSumValues = mergeSumValues(normalizeSumValues(existing.sumValues), deltaSums);
+	const nextNonNullCountValues = mergeCountValues(normalizeNonNullCountValues(existing.nonNullCountValues), deltaNonNullCounts);
+	await db.patch(AGGREGATE_BUCKET_TABLE, existing._id, {
+		count: nextCount,
+		sumValues: nextSumValues,
+		nonNullCountValues: nextNonNullCountValues,
+		updatedAt: now
+	});
+};
+const encodeNumberSortKey = (value) => {
+	const view = /* @__PURE__ */ new DataView(/* @__PURE__ */ new ArrayBuffer(8));
+	view.setFloat64(0, value);
+	let bits = view.getBigUint64(0);
+	if ((bits & FLOAT64_SIGN_BIT) !== 0n) bits = ~bits & FLOAT64_MASK;
+	else bits |= FLOAT64_SIGN_BIT;
+	return bits.toString(16).padStart(16, "0");
+};
+const toComparableSortKey = (value) => {
+	if (typeof value === "number") {
+		if (!Number.isFinite(value)) throw createError(AGGREGATE_ERROR.FILTER_UNSUPPORTED, `Aggregate min/max only support finite numbers, strings, and booleans. Received ${String(value)}.`);
+		return `n:${encodeNumberSortKey(value)}`;
+	}
+	if (typeof value === "string") return `s:${value}`;
+	if (typeof value === "boolean") return `b:${value ? "1" : "0"}`;
+	throw createError(AGGREGATE_ERROR.FILTER_UNSUPPORTED, `Aggregate min/max only support finite numbers, strings, and booleans. Received '${typeof value}'.`);
+};
+const compareSortableValues = (left, right) => {
+	const leftKey = toComparableSortKey(left);
+	const rightKey = toComparableSortKey(right);
+	if (leftKey < rightKey) return -1;
+	if (leftKey > rightKey) return 1;
+	return 0;
+};
+const applyExtremaDelta = async (db, tableName, indexName, keyHash, fieldName, value, deltaCount) => {
+	if (deltaCount === 0) return;
+	const existing = await getExtremaByValue(db, tableName, indexName, keyHash, fieldName, value);
+	const now = Date.now();
+	if (!existing) {
+		if (deltaCount < 0) return;
+		await db.insert(AGGREGATE_EXTREMA_TABLE, {
+			tableKey: tableName,
+			indexName,
+			keyHash,
+			fieldName,
+			valueHash: serializeStable(value),
+			value,
+			sortKey: toComparableSortKey(value),
+			count: deltaCount,
+			updatedAt: now
+		});
+		return;
+	}
+	const nextCount = existing.count + deltaCount;
+	if (nextCount <= 0) {
+		await db.delete(AGGREGATE_EXTREMA_TABLE, existing._id);
+		return;
+	}
+	await db.patch(AGGREGATE_EXTREMA_TABLE, existing._id, {
+		count: nextCount,
+		updatedAt: now
+	});
+};
+const buildKeyHashPrefixBounds = (prefixParts) => {
+	if (prefixParts.length === 0) return {
+		start: "[",
+		end: "[￿"
+	};
+	const start = `${serializeCountKeyParts(prefixParts).slice(0, -1)},`;
+	return {
+		start,
+		end: `${start}\uffff`
+	};
+};
+const matchesKeyPrefix = (keyParts, prefixParts) => prefixParts.every((value, index) => deepEquals(keyParts[index], value));
+/**
+* A prefix scan only bounds the key tuple's leading equality fields, so every
+* bucket it returns still has to clear the range predicate and any equality
+* field that sits after the range field in the index.
+*/
+const matchesRangePlanBucket = (options) => {
+	const { bucket, indexFields } = options;
+	if (!matchesKeyPrefix(bucket.keyParts, options.prefixParts)) return false;
+	if (!matchesRangeComparisons(bucket.keyParts[options.rangeFieldIndex], options.comparisons)) return false;
+	for (const [field, allowedValues] of Object.entries(options.postFieldSets)) {
+		const fieldIndex = indexFields.indexOf(field);
+		if (fieldIndex < 0) return false;
+		if (!allowedValues.has(serializeStable(bucket.keyParts[fieldIndex]))) return false;
+	}
+	return true;
+};
+const readPlanBuckets = async (db, plan) => {
+	if (!plan.rangeConstraint) return (await mapWithConcurrency(plan.keyCandidates ?? buildCandidateKeys(plan.indexFields, plan.fieldValues), AGGREGATE_BUCKET_READ_CONCURRENCY, (keyParts) => getBucketByKey(db, plan.tableName, plan.indexName, keyParts))).filter((bucket) => bucket !== null);
+	const prefixCandidates = buildCandidateKeys(plan.rangeConstraint.prefixFields, plan.fieldValues);
+	const rangeFieldIndex = plan.indexFields.indexOf(plan.rangeConstraint.fieldName);
+	if (rangeFieldIndex < 0) return [];
+	const postFieldSets = Object.fromEntries(Object.entries(plan.postFieldValues).map(([field, values]) => [field, toConstraintSet(values)]));
+	const workBudget = plan.rangeConstraint.workBudget ?? DEFAULT_AGGREGATE_WORK_BUDGET;
+	const scanLimit = workBudget + 1;
+	let pending = prefixCandidates.map((prefixParts) => ({
+		prefixParts,
+		...buildKeyHashPrefixBounds(prefixParts)
+	}));
+	const matchedById = /* @__PURE__ */ new Map();
+	let scanned = 0;
+	while (pending.length > 0 && scanned < scanLimit) {
+		const remaining = scanLimit - scanned;
+		const batch = pending.slice(0, Math.min(AGGREGATE_BUCKET_READ_CONCURRENCY, remaining));
+		const share = Math.floor(remaining / batch.length);
+		const pages = await mapWithConcurrency(batch, AGGREGATE_BUCKET_READ_CONCURRENCY, (scan) => listBucketsByHashPrefix(db, plan.tableName, plan.indexName, scan, share));
+		const next = pending.slice(batch.length);
+		for (let index = 0; index < batch.length; index += 1) {
+			const scan = batch[index];
+			const page = pages[index];
+			scanned += page.length;
+			for (const bucket of page) if (matchesRangePlanBucket({
+				bucket,
+				prefixParts: scan.prefixParts,
+				indexFields: plan.indexFields,
+				rangeFieldIndex,
+				comparisons: plan.rangeConstraint.comparisons,
+				postFieldSets
+			})) matchedById.set(String(bucket._id), bucket);
+			const lastBucket = page.at(-1);
+			if (page.length < share || !lastBucket) continue;
+			next.push({
+				...scan,
+				after: lastBucket.keyHash
+			});
+		}
+		pending = next;
+	}
+	if (scanned > workBudget) {
+		const fanOut = prefixCandidates.length > 1 ? ` across ${prefixCandidates.length} equality-prefix combinations` : "";
+		throw createError(plan.rangeConstraint.filterErrorCode ?? AGGREGATE_ERROR.FILTER_UNSUPPORTED, `${plan.rangeConstraint.methodName ?? "aggregate()"} range filter on '${plan.rangeConstraint.fieldName}' scans more than ${workBudget} aggregate buckets${fanOut} on aggregateIndex '${plan.indexName}'. Narrow the equality prefix, shrink the IN lists it expands to, reduce the range field's cardinality, add a narrower aggregateIndex, or increase defineSchema(..., { defaults: { aggregateWorkBudget } }).`);
+	}
+	const buckets = [...matchedById.values()];
+	buckets[RANGE_WORK_STATE] = {
+		scannedBuckets: scanned,
+		reservedExtremaReads: 0
+	};
+	return buckets;
+};
+const sortFieldValueRecord = (values) => Object.fromEntries(Object.keys(values).sort().map((field) => [field, values[field] ?? []]));
+const getPlanBucketCacheKey = (plan) => serializeStable({
+	tableName: plan.tableName,
+	indexName: plan.indexName,
+	indexFields: plan.indexFields,
+	fieldValues: sortFieldValueRecord(plan.fieldValues),
+	keyCandidates: plan.keyCandidates ?? null,
+	rangeConstraint: plan.rangeConstraint ? {
+		fieldName: plan.rangeConstraint.fieldName,
+		comparisons: [...plan.rangeConstraint.comparisons],
+		prefixFields: plan.rangeConstraint.prefixFields
+	} : null,
+	postFieldValues: sortFieldValueRecord(plan.postFieldValues)
+});
+const readPlanBucketsWithCache = async (db, plan, bucketCache) => {
+	if (!bucketCache) return await readPlanBuckets(db, plan);
+	const cacheKey = getPlanBucketCacheKey(plan);
+	const existing = bucketCache.get(cacheKey);
+	if (existing) return await existing;
+	const pending = readPlanBuckets(db, plan);
+	bucketCache.set(cacheKey, pending);
+	try {
+		return await pending;
+	} catch (error) {
+		bucketCache.delete(cacheKey);
+		throw error;
+	}
+};
+const readCountFromBuckets = async (db, plan, bucketCache) => {
+	return (await readPlanBucketsWithCache(db, plan, bucketCache)).reduce((sum, bucket) => sum + bucket.count, 0);
+};
+const readSumFromBuckets = async (db, plan, bucketCache) => {
+	if (plan.metric.kind !== "sum") throw new Error("readSumFromBuckets() requires a sum aggregate plan.");
+	let total = 0;
+	let totalNonNull = 0;
+	const buckets = await readPlanBucketsWithCache(db, plan, bucketCache);
+	for (const bucket of buckets) {
+		const sumValues = normalizeSumValues(bucket.sumValues);
+		const countValues = normalizeNonNullCountValues(bucket.nonNullCountValues);
+		total += sumValues[plan.metric.field] ?? 0;
+		totalNonNull += countValues[plan.metric.field] ?? 0;
+	}
+	if (totalNonNull === 0) return null;
+	return total;
+};
+const readCountFieldFromBuckets = async (db, plan, bucketCache) => {
+	if (plan.metric.kind !== "countField") throw new Error("readCountFieldFromBuckets() requires a countField aggregate plan.");
+	let total = 0;
+	const buckets = await readPlanBucketsWithCache(db, plan, bucketCache);
+	for (const bucket of buckets) {
+		const countValues = normalizeNonNullCountValues(bucket.nonNullCountValues);
+		total += countValues[plan.metric.field] ?? 0;
+	}
+	return total;
+};
+const readAverageFromBuckets = async (db, plan, bucketCache) => {
+	if (plan.metric.kind !== "avg") throw new Error("readAverageFromBuckets() requires an avg aggregate plan.");
+	let totalSum = 0;
+	let totalNonNull = 0;
+	const buckets = await readPlanBucketsWithCache(db, plan, bucketCache);
+	for (const bucket of buckets) {
+		const sumValues = normalizeSumValues(bucket.sumValues);
+		const countValues = normalizeNonNullCountValues(bucket.nonNullCountValues);
+		totalSum += sumValues[plan.metric.field] ?? 0;
+		totalNonNull += countValues[plan.metric.field] ?? 0;
+	}
+	if (totalNonNull === 0) return null;
+	return totalSum / totalNonNull;
+};
+const readKeyExtrema = async (db, params) => {
+	let query = db.query(AGGREGATE_EXTREMA_TABLE).withIndex("by_table_index_hash_field_sort", (q) => q.eq("tableKey", params.tableName).eq("indexName", params.indexName).eq("keyHash", params.keyHash).eq("fieldName", params.fieldName));
+	if (params.kind === "max") query = query.order("desc");
+	return (await query.take(1))[0]?.value ?? null;
+};
+const readExtremaFromBuckets = async (db, plan, bucketCache) => {
+	if (plan.metric.kind !== "min" && plan.metric.kind !== "max") throw new Error("readExtremaFromBuckets() requires a min/max aggregate plan.");
+	let selected = null;
+	const buckets = await readPlanBucketsWithCache(db, plan, bucketCache);
+	const metric = plan.metric;
+	const rangeWork = buckets[RANGE_WORK_STATE];
+	if (rangeWork && plan.rangeConstraint) {
+		const workBudget = plan.rangeConstraint.workBudget ?? DEFAULT_AGGREGATE_WORK_BUDGET;
+		const requestedWork = buckets.length;
+		const totalWork = rangeWork.scannedBuckets + rangeWork.reservedExtremaReads + requestedWork;
+		if (totalWork > workBudget) throw createError(plan.rangeConstraint.filterErrorCode ?? AGGREGATE_ERROR.FILTER_UNSUPPORTED, `${plan.rangeConstraint.methodName ?? "aggregate()"} range filter on '${plan.rangeConstraint.fieldName}' needs ${totalWork} aggregate work units (${rangeWork.scannedBuckets} bucket reads and ${rangeWork.reservedExtremaReads + requestedWork} extrema reads), exceeding aggregateWorkBudget (${workBudget}) on aggregateIndex '${plan.indexName}'. Narrow the range, add a narrower aggregateIndex, or increase defineSchema(..., { defaults: { aggregateWorkBudget } }).`);
+		rangeWork.reservedExtremaReads += requestedWork;
+	}
+	const values = await mapWithConcurrency(buckets, AGGREGATE_BUCKET_READ_CONCURRENCY, (bucket) => readKeyExtrema(db, {
+		tableName: plan.tableName,
+		indexName: plan.indexName,
+		keyHash: bucket.keyHash,
+		fieldName: metric.field,
+		kind: metric.kind
+	}));
+	for (const value of values) {
+		if (value === null || value === void 0) continue;
+		if (selected === null) {
+			selected = value;
+			continue;
+		}
+		const comparison = compareSortableValues(value, selected);
+		if (plan.metric.kind === "min" && comparison < 0) {
+			selected = value;
+			continue;
+		}
+		if (plan.metric.kind === "max" && comparison > 0) selected = value;
+	}
+	return selected;
+};
+const getMemberByDoc = async (db, tableName, indexName, docId) => {
+	return (await db.query(AGGREGATE_MEMBER_TABLE).withIndex("by_kind_table_index_doc", (q) => q.eq("kind", AGGREGATE_STATE_KIND_METRIC).eq("tableKey", tableName).eq("indexName", indexName).eq("docId", docId)).collect())[0] ?? null;
+};
+const isComparableAggregateValue = (value) => {
+	if (typeof value === "number") return Number.isFinite(value);
+	return typeof value === "string" || typeof value === "boolean";
+};
+const computeAggregateMetricValues = (doc, definition) => {
+	const sumValues = {};
+	for (const field of [...definition.sumFields, ...definition.avgFields]) {
+		const value = doc[field];
+		if (value === null || value === void 0) continue;
+		if (typeof value !== "number" || !Number.isFinite(value)) throw createError(AGGREGATE_ERROR.FILTER_UNSUPPORTED, `aggregateIndex '${definition.name}' sum('${field}') requires finite number values.`);
+		sumValues[field] = value;
+	}
+	const nonNullCountValues = {};
+	for (const field of [
+		...definition.countFields,
+		...definition.sumFields,
+		...definition.avgFields
+	]) {
+		const value = doc[field];
+		if (value === null || value === void 0) continue;
+		nonNullCountValues[field] = 1;
+	}
+	const extremaFields = new Set([...definition.minFields, ...definition.maxFields]);
+	const extremaValues = {};
+	for (const field of extremaFields) {
+		const value = doc[field];
+		if (value === null || value === void 0) continue;
+		if (!isComparableAggregateValue(value)) throw createError(AGGREGATE_ERROR.FILTER_UNSUPPORTED, `aggregateIndex '${definition.name}' ${field} must be a finite number, string, or boolean for min/max.`);
+		extremaValues[field] = value;
+	}
+	return {
+		sumValues,
+		extremaValues,
+		nonNullCountValues
+	};
+};
+const toExtremaDeltas = (keyHash, values, delta) => Object.entries(values).map(([fieldName, value]) => ({
+	keyHash,
+	fieldName,
+	value,
+	delta
+}));
+const accumulateNumberValues = (target, source) => {
+	for (const [field, value] of Object.entries(source)) {
+		const next = (target[field] ?? 0) + value;
+		if (next === 0) {
+			delete target[field];
+			continue;
+		}
+		target[field] = next;
+	}
+};
+/**
+* Pure half of aggregate reconciliation: works out what a single document's
+* membership change implies, without touching the database. Callers batch these
+* and flush once so a page of documents sharing a key tuple writes its bucket
+* one time instead of once per document.
+*/
+const computeMembershipDelta = (existing, params) => {
+	const { tableName, indexName, docId, keyParts, metricValues } = params;
+	if (!keyParts || !metricValues) {
+		if (!existing) return {
+			buckets: [],
+			extrema: [],
+			member: { kind: "none" }
+		};
+		return {
+			buckets: [{
+				keyHash: serializeCountKeyParts(existing.keyParts),
+				keyParts: existing.keyParts,
+				deltaCount: -1,
+				deltaSums: negateSumValues(normalizeSumValues(existing.sumValues)),
+				deltaNonNullCounts: negateCountValues(normalizeNonNullCountValues(existing.nonNullCountValues))
+			}],
+			extrema: toExtremaDeltas(existing.keyHash, normalizeExtremaValues(existing.extremaValues), -1),
+			member: {
+				kind: "delete",
+				id: existing._id
+			}
+		};
+	}
+	const normalizedKeyParts = keyParts.map((part) => normalizeUndefined(part));
+	const keyHash = serializeCountKeyParts(normalizedKeyParts);
+	const now = Date.now();
+	const normalizedNextSumValues = normalizeSumValues(metricValues.sumValues);
+	const normalizedNextNonNullCountValues = normalizeNonNullCountValues(metricValues.nonNullCountValues);
+	const normalizedNextExtremaValues = normalizeExtremaValues(metricValues.extremaValues);
+	if (existing && existing.keyHash === keyHash && deepEquals(existing.keyParts, normalizedKeyParts) && deepEquals(normalizeSumValues(existing.sumValues), normalizedNextSumValues) && deepEquals(normalizeNonNullCountValues(existing.nonNullCountValues), normalizedNextNonNullCountValues) && deepEquals(normalizeExtremaValues(existing.extremaValues), normalizedNextExtremaValues)) return {
+		buckets: [],
+		extrema: [],
+		member: { kind: "none" }
+	};
+	const buckets = [];
+	const extrema = [];
+	if (existing) {
+		buckets.push({
+			keyHash: serializeCountKeyParts(existing.keyParts),
+			keyParts: existing.keyParts,
+			deltaCount: -1,
+			deltaSums: negateSumValues(normalizeSumValues(existing.sumValues)),
+			deltaNonNullCounts: negateCountValues(normalizeNonNullCountValues(existing.nonNullCountValues))
+		});
+		extrema.push(...toExtremaDeltas(existing.keyHash, normalizeExtremaValues(existing.extremaValues), -1));
+	}
+	buckets.push({
+		keyHash,
+		keyParts: normalizedKeyParts,
+		deltaCount: 1,
+		deltaSums: normalizedNextSumValues,
+		deltaNonNullCounts: normalizedNextNonNullCountValues
+	});
+	extrema.push(...toExtremaDeltas(keyHash, normalizedNextExtremaValues, 1));
+	const memberFields = {
+		kind: AGGREGATE_STATE_KIND_METRIC,
+		keyHash,
+		keyParts: normalizedKeyParts,
+		sumValues: normalizedNextSumValues,
+		nonNullCountValues: normalizedNextNonNullCountValues,
+		extremaValues: normalizedNextExtremaValues,
+		updatedAt: now
+	};
+	return {
+		buckets,
+		extrema,
+		member: existing ? {
+			kind: "patch",
+			id: existing._id,
+			doc: memberFields
+		} : {
+			kind: "insert",
+			doc: {
+				...memberFields,
+				tableKey: tableName,
+				indexName,
+				docId
+			}
+		}
+	};
+};
+const computeAggregateMembershipDelta = async (db, params) => {
+	return computeMembershipDelta(await getMemberByDoc(db, params.tableName, params.indexName, params.docId), params);
+};
+/**
+* Write half of aggregate reconciliation. Folds bucket deltas by key tuple and
+* extrema deltas by (keyHash, field, value) so each storage document is read and
+* written once regardless of how many source documents contributed to it.
+*/
+const flushAggregateMembershipDeltas = async (db, tableName, indexName, deltas) => {
+	const bucketDeltas = /* @__PURE__ */ new Map();
+	const extremaDeltas = /* @__PURE__ */ new Map();
+	for (const delta of deltas) {
+		for (const bucket of delta.buckets) {
+			const current = bucketDeltas.get(bucket.keyHash);
+			if (!current) {
+				bucketDeltas.set(bucket.keyHash, {
+					keyHash: bucket.keyHash,
+					keyParts: bucket.keyParts,
+					deltaCount: bucket.deltaCount,
+					deltaSums: { ...bucket.deltaSums },
+					deltaNonNullCounts: { ...bucket.deltaNonNullCounts }
+				});
+				continue;
+			}
+			current.deltaCount += bucket.deltaCount;
+			accumulateNumberValues(current.deltaSums, bucket.deltaSums);
+			accumulateNumberValues(current.deltaNonNullCounts, bucket.deltaNonNullCounts);
+		}
+		for (const entry of delta.extrema) {
+			const cacheKey = serializeStable([
+				entry.keyHash,
+				entry.fieldName,
+				serializeStable(entry.value)
+			]);
+			const current = extremaDeltas.get(cacheKey);
+			if (!current) {
+				extremaDeltas.set(cacheKey, { ...entry });
+				continue;
+			}
+			current.delta += entry.delta;
+		}
+	}
+	for (const bucket of bucketDeltas.values()) await applyBucketDelta(db, tableName, indexName, bucket.keyParts, bucket.deltaCount, bucket.deltaSums, bucket.deltaNonNullCounts);
+	for (const entry of extremaDeltas.values()) await applyExtremaDelta(db, tableName, indexName, entry.keyHash, entry.fieldName, entry.value, entry.delta);
+	for (const delta of deltas) {
+		const member = delta.member;
+		if (member.kind === "delete") {
+			await db.delete(AGGREGATE_MEMBER_TABLE, member.id);
+			continue;
+		}
+		if (member.kind === "patch") {
+			await db.patch(AGGREGATE_MEMBER_TABLE, member.id, member.doc);
+			continue;
+		}
+		if (member.kind === "insert") await db.insert(AGGREGATE_MEMBER_TABLE, member.doc);
+	}
+};
+/**
+* Single-document reconciliation. Flushes eagerly so user code reading an
+* aggregate later in the same mutation sees its own writes.
+*/
+const reconcileAggregateMembership = async (db, params) => {
+	const delta = await computeAggregateMembershipDelta(db, params);
+	await flushAggregateMembershipDeltas(db, params.tableName, params.indexName, [delta]);
+};
+const computeCountKeyParts = (doc, fields) => fields.map((field) => normalizeUndefined(doc[field]));
+const applyAggregateIndexesForChange = async (db, tableName, aggregateIndexes, change) => {
+	const docId = String(change.id);
+	for (const aggregateIndex of aggregateIndexes) {
+		const keyParts = change.operation === "delete" ? null : computeCountKeyParts(change.newDoc, aggregateIndex.fields);
+		const metricValues = change.operation === "delete" ? null : computeAggregateMetricValues(change.newDoc, aggregateIndex);
+		await reconcileAggregateMembership(db, {
+			tableName,
+			indexName: aggregateIndex.name,
+			docId,
+			keyParts,
+			metricValues
+		});
+	}
+};
+const getCountState = async (db, tableName, indexName, kind = AGGREGATE_STATE_KIND_METRIC) => {
+	const state = (await db.query(AGGREGATE_STATE_TABLE).withIndex("by_kind_table_index", (q) => q.eq("kind", kind).eq("tableKey", tableName).eq("indexName", indexName)).collect())[0];
+	if (!state) return null;
+	const { tableKey, ...rest } = state;
+	return {
+		...rest,
+		tableName: tableKey
+	};
+};
+const assertAggregateIndexesWritable = async (db, tableName, metricIndexNames, rankIndexNames) => {
+	const clearingStates = await db.query(AGGREGATE_STATE_TABLE).withIndex("by_table_status", (q) => q.eq("tableKey", tableName).eq("status", COUNT_STATUS_CLEARING)).collect();
+	const metricNames = new Set(metricIndexNames);
+	const rankNames = new Set(rankIndexNames);
+	const blockingState = clearingStates.find((state) => state.kind === AGGREGATE_STATE_KIND_RANK ? rankNames.has(state.indexName) : metricNames.has(state.indexName));
+	if (!blockingState) return;
+	const indexType = blockingState.kind === AGGREGATE_STATE_KIND_RANK ? "rankIndex" : "aggregateIndex";
+	throw createError(blockingState.kind === AGGREGATE_STATE_KIND_RANK ? "RANK_INDEX_BUILDING" : AGGREGATE_ERROR.INDEX_BUILDING, `${indexType} '${tableName}.${blockingState.indexName}' is CLEARING. Retry the write after aggregateBackfill reaches BUILDING or READY.`);
+};
+const setCountState = async (db, nextState, kind = AGGREGATE_STATE_KIND_METRIC) => {
+	const existing = await getCountState(db, nextState.tableName, nextState.indexName, kind);
+	const payload = {
+		kind,
+		tableKey: nextState.tableName,
+		indexName: nextState.indexName,
+		keyDefinitionHash: nextState.keyDefinitionHash,
+		metricDefinitionHash: nextState.metricDefinitionHash,
+		status: nextState.status,
+		cursor: nextState.cursor ?? null,
+		processed: nextState.processed,
+		startedAt: nextState.startedAt,
+		updatedAt: nextState.updatedAt,
+		completedAt: nextState.completedAt ?? null,
+		lastError: nextState.lastError ?? null
+	};
+	if (!existing) {
+		await db.insert(AGGREGATE_STATE_TABLE, payload);
+		return;
+	}
+	await db.patch(AGGREGATE_STATE_TABLE, existing._id, payload);
+};
+const setCountStateError = async (db, tableName, indexName, error, kind = AGGREGATE_STATE_KIND_METRIC) => {
+	const now = Date.now();
+	const existing = await getCountState(db, tableName, indexName, kind);
+	const message = error instanceof Error ? error.message : String(error);
+	if (!existing) throw new Error(`Missing count state for '${tableName}.${indexName}' while recording backfill error.`);
+	await db.patch(AGGREGATE_STATE_TABLE, existing._id, {
+		status: existing.status === COUNT_STATUS_CLEARING ? COUNT_STATUS_CLEARING : COUNT_STATUS_BUILDING,
+		updatedAt: now,
+		keyDefinitionHash: existing.keyDefinitionHash,
+		metricDefinitionHash: existing.metricDefinitionHash,
+		lastError: message
+	});
+};
+/**
+* Removes at most `batchSize` documents of an aggregate index's stored state and
+* reports whether anything is left. Callers drive it to completion across
+* transactions, so clearing a large index never has to fit in one mutation.
+*
+* Members are removed through the normal delta machinery rather than raw
+* deletes, so buckets and extrema stay consistent with the members that remain
+* at every intermediate step. That keeps concurrent writers correct while the
+* clear drains. Residual bucket/extrema rows (drift with no member behind them)
+* are swept only once no members are left, and the loop re-checks members
+* afterwards.
+*/
+const clearCountIndexChunk = async (db, tableName, indexName, batchSize) => {
+	const members = await takeMembersForIndex(db, tableName, indexName, batchSize);
+	if (members.length > 0) {
+		await flushAggregateMembershipDeltas(db, tableName, indexName, members.map((member) => computeMembershipDelta(member, {
+			tableName,
+			indexName,
+			docId: member.docId,
+			keyParts: null,
+			metricValues: null
+		})));
+		return {
+			done: false,
+			processed: members.length
+		};
+	}
+	const buckets = await takeBucketsForIndex(db, tableName, indexName, batchSize);
+	if (buckets.length > 0) {
+		for (const bucket of buckets) await db.delete(AGGREGATE_BUCKET_TABLE, bucket._id);
+		return {
+			done: false,
+			processed: buckets.length
+		};
+	}
+	const extrema = await takeExtremaForIndex(db, tableName, indexName, batchSize);
+	if (extrema.length > 0) {
+		for (const entry of extrema) await db.delete(AGGREGATE_EXTREMA_TABLE, entry._id);
+		return {
+			done: false,
+			processed: extrema.length
+		};
+	}
+	return {
+		done: true,
+		processed: 0
+	};
+};
+const ensureIndexReady = async (db, tableName, indexName, code, indexLabel) => {
+	const state = await getCountState(db, tableName, indexName);
+	if (!state || state.status !== COUNT_STATUS_READY) throw createError(code, `${indexLabel} '${tableName}.${indexName}' is BUILDING. Run aggregateBackfill until READY.`);
+};
+const ensureCountIndexReady = async (db, tableName, indexName) => ensureIndexReady(db, tableName, indexName, COUNT_ERROR.INDEX_BUILDING, "aggregateIndex");
+const ensureAggregateIndexReady = async (db, tableName, indexName) => ensureIndexReady(db, tableName, indexName, AGGREGATE_ERROR.INDEX_BUILDING, "aggregateIndex");
+const listSchemaAggregateIndexes = (schema) => {
+	const entries = [];
+	for (const tableConfig of Object.values(schema)) {
+		const aggregateIndexes = getAggregateIndexDefinitions(tableConfig);
+		for (const aggregateIndex of aggregateIndexes) entries.push({
+			tableName: tableConfig.name,
+			indexName: aggregateIndex.name,
+			fields: aggregateIndex.fields,
+			countFields: aggregateIndex.countFields,
+			sumFields: aggregateIndex.sumFields,
+			avgFields: aggregateIndex.avgFields,
+			minFields: aggregateIndex.minFields,
+			maxFields: aggregateIndex.maxFields
+		});
+	}
+	return entries;
+};
+const isIndexCountZero = (plan) => Array.isArray(plan.keyCandidates) && plan.keyCandidates.length === 0 || [...Object.values(plan.fieldValues), ...Object.values(plan.postFieldValues)].some((values) => values.length === 0);
+const isAggregatePlanZero = (plan) => Array.isArray(plan.keyCandidates) && plan.keyCandidates.length === 0 || [...Object.values(plan.fieldValues), ...Object.values(plan.postFieldValues)].some((values) => values.length === 0);
+
+//#endregion
+//#region src/orm/aggregate-index/rank-runtime.ts
+const isObject = (value) => !!value && typeof value === "object" && !Array.isArray(value);
+const stableEquals = (left, right) => JSON.stringify(left) === JSON.stringify(right);
+const RANK_MEMBER_KIND = AGGREGATE_STATE_KIND_RANK;
+const RANK_ERROR = {
+	FILTER_UNSUPPORTED: "RANK_FILTER_UNSUPPORTED",
+	NOT_INDEXED: "RANK_NOT_INDEXED",
+	INDEX_BUILDING: "RANK_INDEX_BUILDING",
+	RLS_UNSUPPORTED: "RANK_RLS_UNSUPPORTED"
+};
+const createRankError = (code, message) => /* @__PURE__ */ new Error(`${code}: ${message}`);
+const rankAggregateName = (tableName, indexName) => `${tableName}.${indexName}`;
+const rankAggregate = (tableName, indexName) => new DirectAggregate({ name: rankAggregateName(tableName, indexName) });
+const toRankValue = (value) => {
+	if (value === null || value === void 0) return null;
+	if (value instanceof Date) return value.getTime();
+	if (typeof value === "number" && Number.isFinite(value)) return value;
+	throw createRankError(RANK_ERROR.FILTER_UNSUPPORTED, `rankIndex order field values must be finite numbers or dates; received '${typeof value}'.`);
+};
+const decodeRankValue = (value, direction) => {
+	if (value === null || value === void 0) return null;
+	if (typeof value === "number") return direction === "desc" ? -value : value;
+	return value;
+};
+const getRankSortKey = (definition, doc, docId) => {
+	const key = [];
+	for (const orderField of definition.orderFields) {
+		const rawValue = toRankValue(doc[orderField.field]);
+		if (rawValue === null) {
+			key.push(null);
+			continue;
+		}
+		key.push(orderField.direction === "desc" ? -rawValue : rawValue);
+	}
+	key.push(docId);
+	return key;
+};
+const toPublicRankKey = (definition, key) => {
+	if (!Array.isArray(key)) return key;
+	const restored = key.slice(0, definition.orderFields.length).map((value, index) => decodeRankValue(value, definition.orderFields[index].direction));
+	return restored.length === 1 ? restored[0] : restored;
+};
+const getRankSumValue = (definition, doc) => {
+	if (!definition.sumField) return 1;
+	const raw = doc[definition.sumField];
+	if (raw === null || raw === void 0) return 0;
+	if (typeof raw !== "number" || !Number.isFinite(raw)) throw createRankError(RANK_ERROR.FILTER_UNSUPPORTED, `rankIndex '${definition.name}' sum field '${definition.sumField}' must be a finite number.`);
+	return raw;
+};
+const validateRankWhereValue = (value) => {
+	if (value === null || value === void 0) return null;
+	if (isObject(value)) {
+		if (Object.hasOwn(value, "eq")) return value.eq ?? null;
+		if (value.isNull === true) return null;
+		throw createRankError(RANK_ERROR.FILTER_UNSUPPORTED, "rank() where supports only eq and isNull: true on partition fields.");
+	}
+	if (Array.isArray(value)) throw createRankError(RANK_ERROR.FILTER_UNSUPPORTED, "rank() where does not support IN arrays in v1.");
+	return value;
+};
+const collectWhere = (where, fields, out) => {
+	if (Object.hasOwn(where, "OR") || Object.hasOwn(where, "NOT")) throw createRankError(RANK_ERROR.FILTER_UNSUPPORTED, "rank() where supports conjunctions only (object fields + AND).");
+	if (Object.hasOwn(where, "RAW")) throw createRankError(RANK_ERROR.FILTER_UNSUPPORTED, "rank() where does not support RAW filters.");
+	const andEntries = where.AND;
+	if (andEntries !== void 0) {
+		if (!Array.isArray(andEntries)) throw createRankError(RANK_ERROR.FILTER_UNSUPPORTED, "rank() where AND must be an array.");
+		for (const entry of andEntries) {
+			if (!isObject(entry)) throw createRankError(RANK_ERROR.FILTER_UNSUPPORTED, "rank() where AND entries must be objects.");
+			collectWhere(entry, fields, out);
+		}
+	}
+	for (const [field, rawValue] of Object.entries(where)) {
+		if (field === "AND") continue;
+		if (!fields.has(field)) throw createRankError(RANK_ERROR.FILTER_UNSUPPORTED, `rank() where field '${field}' is not a partition field.`);
+		const nextValue = validateRankWhereValue(rawValue);
+		const prevValue = out.get(field);
+		if (prevValue !== void 0 && !stableEquals(prevValue, nextValue)) throw createRankError(RANK_ERROR.FILTER_UNSUPPORTED, `rank() where has conflicting constraints for '${field}'.`);
+		out.set(field, nextValue);
+	}
+};
+const buildNamespace = (definition, values) => {
+	if (definition.partitionFields.length === 0) return;
+	const parts = definition.partitionFields.map((field) => values.get(field));
+	return parts.length === 1 ? parts[0] : parts;
+};
+const ensureRankAllowedForRls = (tableConfig, rlsMode) => {
+	if ((typeof tableConfig.table.isRlsEnabled === "function" ? tableConfig.table.isRlsEnabled() : false) && rlsMode !== "skip") throw createRankError(RANK_ERROR.RLS_UNSUPPORTED, `rank() is not available for table '${tableConfig.name}' in RLS-restricted contexts in v1.`);
+};
+const compileRankPlan = (tableConfig, indexName, where) => {
+	const definition = getRankIndexDefinitions(tableConfig).find((entry) => entry.name === indexName);
+	if (!definition) throw createRankError(RANK_ERROR.NOT_INDEXED, `No rankIndex '${indexName}' found on '${tableConfig.name}'. Declare rankIndex('${indexName}') and run aggregateBackfill.`);
+	if (!isObject(where ?? {})) throw createRankError(RANK_ERROR.FILTER_UNSUPPORTED, "rank() where must be an object filter.");
+	const values = /* @__PURE__ */ new Map();
+	collectWhere(where ?? {}, new Set(definition.partitionFields), values);
+	for (const field of definition.partitionFields) if (!values.has(field)) throw createRankError(RANK_ERROR.NOT_INDEXED, `rank() on '${tableConfig.name}.${indexName}' requires all partition fields constrained: [${definition.partitionFields.join(", ")}].`);
+	return {
+		tableName: tableConfig.name,
+		indexName,
+		definition,
+		namespace: buildNamespace(definition, values)
+	};
+};
+const ensureRankIndexReady = async (db, tableName, indexName) => {
+	const state = await getCountState(db, tableName, indexName, AGGREGATE_STATE_KIND_RANK);
+	if (!state || state.status !== COUNT_STATUS_READY) throw createRankError(RANK_ERROR.INDEX_BUILDING, `rankIndex '${tableName}.${indexName}' is BUILDING. Run aggregateBackfill until READY.`);
+};
+const getRankMemberByDoc = async (db, tableName, indexName, docId) => {
+	return (await db.query(AGGREGATE_MEMBER_TABLE).withIndex("by_kind_table_index_doc", (q) => q.eq("kind", RANK_MEMBER_KIND).eq("tableKey", tableName).eq("indexName", indexName).eq("docId", docId)).collect())[0] ?? null;
+};
+const takeRankMembers = async (db, tableName, indexName, limit) => await db.query(AGGREGATE_MEMBER_TABLE).withIndex("by_kind_table_index", (q) => q.eq("kind", RANK_MEMBER_KIND).eq("tableKey", tableName).eq("indexName", indexName)).take(limit);
+const rankCtx = (db) => ({
+	db,
+	orm: void 0
+});
+/** Trees dropped per invocation once every rank member has been removed. */
+const RANK_TREE_DROP_BATCH = 16;
+/**
+* Removes at most `batchSize` rank members and reports whether anything is
+* left. Each member is removed from the btree before its row is dropped, so the
+* tree stays consistent with the members that remain and a partially drained
+* clear can safely resume in a later mutation.
+*/
+const clearRankIndexChunk = async (db, tableName, indexName, batchSize) => {
+	const aggregate = rankAggregate(tableName, indexName);
+	const ctx = rankCtx(db);
+	const members = await takeRankMembers(db, tableName, indexName, batchSize);
+	if (members.length > 0) {
+		for (const member of members) {
+			if (member.rankKey !== void 0) await aggregate.deleteIfExists(ctx, {
+				id: member.docId,
+				key: member.rankKey,
+				namespace: member.rankNamespace
+			});
+			await db.delete(AGGREGATE_MEMBER_TABLE, member._id);
+		}
+		return {
+			done: false,
+			processed: members.length
+		};
+	}
+	const done = await aggregate.deleteTrees(ctx, RANK_TREE_DROP_BATCH);
+	return {
+		done,
+		processed: done ? 0 : RANK_TREE_DROP_BATCH
+	};
+};
+const reconcileRankMembership = async (db, params) => {
+	const { tableName, definition, docId, doc } = params;
+	const existing = await getRankMemberByDoc(db, tableName, definition.name, docId);
+	const aggregate = rankAggregate(tableName, definition.name);
+	const ctx = rankCtx(db);
+	const now = Date.now();
+	if (!doc) {
+		if (existing?.rankKey !== void 0) {
+			await aggregate.delete(ctx, {
+				id: docId,
+				key: existing.rankKey,
+				namespace: existing.rankNamespace
+			});
+			await db.delete(AGGREGATE_MEMBER_TABLE, existing._id);
+		}
+		return;
+	}
+	const namespace = buildNamespace(definition, new Map(definition.partitionFields.map((field) => [field, doc[field]])));
+	const key = getRankSortKey(definition, doc, docId);
+	const sumValue = getRankSumValue(definition, doc);
+	if (existing && stableEquals(existing.rankNamespace, namespace) && stableEquals(existing.rankKey, key) && (existing.rankSumValue ?? 0) === sumValue) return;
+	if (existing?.rankKey !== void 0) {
+		await aggregate.replace(ctx, {
+			id: docId,
+			key: existing.rankKey,
+			namespace: existing.rankNamespace
+		}, {
+			key,
+			namespace,
+			sumValue
+		});
+		await db.patch(AGGREGATE_MEMBER_TABLE, existing._id, {
+			kind: RANK_MEMBER_KIND,
+			keyHash: "__rank__",
+			keyParts: [],
+			sumValues: {},
+			nonNullCountValues: {},
+			extremaValues: {},
+			rankNamespace: namespace,
+			rankKey: key,
+			rankSumValue: sumValue,
+			updatedAt: now
+		});
+		return;
+	}
+	await aggregate.insert(ctx, {
+		id: docId,
+		key,
+		namespace,
+		sumValue
+	});
+	await db.insert(AGGREGATE_MEMBER_TABLE, {
+		kind: RANK_MEMBER_KIND,
+		tableKey: tableName,
+		indexName: definition.name,
+		docId,
+		keyHash: "__rank__",
+		keyParts: [],
+		sumValues: {},
+		nonNullCountValues: {},
+		extremaValues: {},
+		rankNamespace: namespace,
+		rankKey: key,
+		rankSumValue: sumValue,
+		updatedAt: now
+	});
+};
+const applyRankIndexesForChange = async (db, tableName, rankIndexes, change) => {
+	const docId = String(change.id);
+	for (const rankIndex of rankIndexes) await reconcileRankMembership(db, {
+		tableName,
+		definition: rankIndex,
+		docId,
+		doc: change.operation === "delete" ? null : change.newDoc
+	});
+};
+const readRankCount = async (db, plan) => {
+	return await rankAggregate(plan.tableName, plan.indexName).count(rankCtx(db), { namespace: plan.namespace });
+};
+const readRankSum = async (db, plan) => {
+	return await rankAggregate(plan.tableName, plan.indexName).sum(rankCtx(db), { namespace: plan.namespace });
+};
+const toPublicRankItem = (plan, item) => ({
+	id: item.id,
+	key: toPublicRankKey(plan.definition, item.key),
+	sumValue: item.sumValue
+});
+const readRankAtWithCount = async (db, plan, offset, count) => {
+	if (count <= 0) return null;
+	const normalizedOffset = offset < 0 ? count + offset : offset;
+	if (normalizedOffset < 0 || normalizedOffset >= count) return null;
+	return toPublicRankItem(plan, await rankAggregate(plan.tableName, plan.indexName).at(rankCtx(db), offset, { namespace: plan.namespace }));
+};
+const readRankAt = async (db, plan, offset) => await readRankAtWithCount(db, plan, offset, await readRankCount(db, plan));
+const readRankIndexOf = async (db, plan, args) => {
+	const member = await getRankMemberByDoc(db, plan.tableName, plan.indexName, args.id);
+	if (!member || member.rankKey === void 0) return -1;
+	if (!stableEquals(member.rankNamespace, plan.namespace)) return -1;
+	return await rankAggregate(plan.tableName, plan.indexName).indexOf(rankCtx(db), member.rankKey, {
+		namespace: plan.namespace,
+		id: args.id
+	});
+};
+const readRankPaginate = async (db, plan, cursor, limit) => {
+	const paged = await rankAggregate(plan.tableName, plan.indexName).paginate(rankCtx(db), {
+		namespace: plan.namespace,
+		cursor: cursor ?? void 0,
+		pageSize: limit
+	});
+	return {
+		continueCursor: paged.cursor ?? "",
+		isDone: paged.isDone,
+		page: paged.page.map((item) => toPublicRankItem(plan, item))
+	};
+};
+const readRankMin = async (db, plan) => {
+	const item = await rankAggregate(plan.tableName, plan.indexName).min(rankCtx(db), { namespace: plan.namespace });
+	return item ? toPublicRankItem(plan, item) : null;
+};
+const readRankMax = async (db, plan) => {
+	const item = await rankAggregate(plan.tableName, plan.indexName).max(rankCtx(db), { namespace: plan.namespace });
+	return item ? toPublicRankItem(plan, item) : null;
+};
+const readRankRandom = async (db, plan) => {
+	const count = await readRankCount(db, plan);
+	if (count <= 0) return null;
+	return await readRankAtWithCount(db, plan, Math.floor(Math.random() * count), count);
+};
+
+//#endregion
+//#region src/orm/aggregate-index/backfill.ts
+const DEFAULT_BACKFILL_BATCH_SIZE = 1e3;
+const getBackfillMode = (candidate) => {
+	if (candidate === void 0) return "resume";
+	if (candidate === "resume" || candidate === "rebuild" || candidate === "prune") return candidate;
+	throw new Error("countBackfill mode must be one of 'resume', 'rebuild', or 'prune'.");
+};
+const getBackfillBatchSize = (candidate) => {
+	if (candidate === void 0) return DEFAULT_BACKFILL_BATCH_SIZE;
+	if (typeof candidate !== "number" || !Number.isInteger(candidate)) throw new Error("countBackfill batchSize must be a positive integer.");
+	if (candidate < 1) throw new Error("countBackfill batchSize must be a positive integer.");
+	return candidate;
+};
+const matchesFilter = (target, args) => {
+	if (args.tableName && target.tableName !== args.tableName) return false;
+	if (args.indexName && target.indexName !== args.indexName) return false;
+	return true;
+};
+const getTargets = (schema, args) => {
+	const metricTargets = listSchemaAggregateIndexes(schema).map((entry) => ({
+		kind: "metric",
+		tableName: entry.tableName,
+		indexName: entry.indexName,
+		fields: entry.fields,
+		countFields: entry.countFields,
+		sumFields: entry.sumFields,
+		avgFields: entry.avgFields,
+		minFields: entry.minFields,
+		maxFields: entry.maxFields
+	}));
+	const rankTargets = [];
+	for (const tableConfig of Object.values(schema)) {
+		const rankIndexes = getRankIndexDefinitions(tableConfig);
+		for (const rankIndex of rankIndexes) rankTargets.push({
+			kind: "rank",
+			tableName: tableConfig.name,
+			indexName: rankIndex.name,
+			fields: rankIndex.partitionFields,
+			orderFields: rankIndex.orderFields,
+			rankSumField: rankIndex.sumField
+		});
+	}
+	return [...metricTargets, ...rankTargets].filter((entry) => matchesFilter(entry, args));
+};
+const dedupe = (fields) => [...new Set(fields)];
+const computeMetricDefinition = (target) => ({
+	countFields: dedupe(target.countFields ?? []),
+	sumFields: dedupe(target.sumFields ?? []),
+	avgFields: dedupe(target.avgFields ?? []),
+	minFields: dedupe(target.minFields ?? []),
+	maxFields: dedupe(target.maxFields ?? [])
+});
+const computeKeyDefinitionHash = (target) => JSON.stringify({
+	kind: target.kind,
+	fields: target.fields,
+	orderFields: target.orderFields ?? []
+});
+const computeMetricDefinitionHash = (target) => target.kind === "rank" ? JSON.stringify({ sumField: target.rankSumField ?? null }) : JSON.stringify(computeMetricDefinition(target));
+const parseMetricDefinitionHash = (metricDefinitionHash) => {
+	let parsed;
+	try {
+		parsed = JSON.parse(metricDefinitionHash);
+	} catch {
+		throw new Error(`Invalid metricDefinitionHash payload: ${metricDefinitionHash}`);
+	}
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("Invalid metricDefinitionHash payload shape.");
+	const pick = (key) => {
+		const candidate = parsed[key];
+		if (!Array.isArray(candidate)) throw new Error(`metricDefinitionHash is missing '${key}'.`);
+		if (candidate.some((entry) => typeof entry !== "string")) throw new Error(`metricDefinitionHash has non-string value in '${key}'.`);
+		return dedupe(candidate);
+	};
+	return {
+		countFields: pick("countFields"),
+		sumFields: pick("sumFields"),
+		avgFields: pick("avgFields"),
+		minFields: pick("minFields"),
+		maxFields: pick("maxFields")
+	};
+};
+const toMetricStorageDefinition = (metricDefinition) => ({
+	sumFields: new Set([...metricDefinition.sumFields, ...metricDefinition.avgFields]),
+	nonNullCountFields: new Set([...metricDefinition.countFields, ...metricDefinition.avgFields]),
+	extremaFields: new Set([...metricDefinition.minFields, ...metricDefinition.maxFields])
+});
+const requiresMetricBackfill = (existingMetricDefinitionHash, targetMetricDefinitionHash) => {
+	const existingDefinition = parseMetricDefinitionHash(existingMetricDefinitionHash);
+	const targetDefinition = parseMetricDefinitionHash(targetMetricDefinitionHash);
+	const existingStorage = toMetricStorageDefinition(existingDefinition);
+	const targetStorage = toMetricStorageDefinition(targetDefinition);
+	const hasMissing = (target, existing) => {
+		for (const field of target) if (!existing.has(field)) return true;
+		return false;
+	};
+	return hasMissing(targetStorage.sumFields, existingStorage.sumFields) || hasMissing(targetStorage.nonNullCountFields, existingStorage.nonNullCountFields) || hasMissing(targetStorage.extremaFields, existingStorage.extremaFields);
+};
+function createCountBackfillHandlers(schema, getChunkRef) {
+	const serializeKey = (kind, tableName, indexName) => `${kind}\u0000${tableName}\u0000${indexName}`;
+	const stateKindFor = (kind) => kind === "rank" ? AGGREGATE_STATE_KIND_RANK : AGGREGATE_STATE_KIND_METRIC;
+	const scheduleChunk = async (ctx, tableName, indexName, batchSize) => {
+		const chunkRef = getChunkRef?.();
+		if (ctx.scheduler && chunkRef) await ctx.scheduler.runAfter(0, chunkRef, {
+			tableName,
+			indexName,
+			batchSize
+		});
+	};
+	/**
+	* Drains an index's stored state until it is empty or the shared per-mutation
+	* budget runs out. Returns true only when the index is fully cleared, so the
+	* caller knows whether to advance the state machine or reschedule.
+	*/
+	const drainIndexClear = async (ctx, kind, tableName, indexName, batchSize, budget) => {
+		while (budget.remaining > 0) {
+			const limit = Math.min(batchSize, budget.remaining);
+			const step = kind === "rank" ? await clearRankIndexChunk(ctx.db, tableName, indexName, limit) : await clearCountIndexChunk(ctx.db, tableName, indexName, limit);
+			if (step.done) return true;
+			budget.remaining -= Math.max(step.processed, 1);
+		}
+		return false;
+	};
+	const pruneRemovedState = async (ctx, args, targets, batchSize, clearBudget) => {
+		const targetKeys = new Set(targets.map((target) => serializeKey(target.kind, target.tableName, target.indexName)));
+		const states = await ctx.db.query(AGGREGATE_STATE_TABLE).collect();
+		const stateByKey = new Map(states.map((state) => [serializeKey(state.kind === AGGREGATE_STATE_KIND_RANK ? "rank" : "metric", state.tableKey, state.indexName), state]));
+		const existingKeys = /* @__PURE__ */ new Set();
+		for (const state of states) existingKeys.add(serializeKey(state.kind === AGGREGATE_STATE_KIND_RANK ? "rank" : "metric", state.tableKey, state.indexName));
+		if (args.tableName && args.indexName) {
+			const tableName = args.tableName;
+			const indexName = args.indexName;
+			const [bucket, extrema, metricMember, rankMember] = await Promise.all([
+				ctx.db.query(AGGREGATE_BUCKET_TABLE).withIndex("by_table_index", (q) => q.eq("tableKey", tableName).eq("indexName", indexName)).first(),
+				ctx.db.query(AGGREGATE_EXTREMA_TABLE).withIndex("by_table_index", (q) => q.eq("tableKey", tableName).eq("indexName", indexName)).first(),
+				ctx.db.query(AGGREGATE_MEMBER_TABLE).withIndex("by_kind_table_index", (q) => q.eq("kind", AGGREGATE_STATE_KIND_METRIC).eq("tableKey", tableName).eq("indexName", indexName)).first(),
+				ctx.db.query(AGGREGATE_MEMBER_TABLE).withIndex("by_kind_table_index", (q) => q.eq("kind", AGGREGATE_STATE_KIND_RANK).eq("tableKey", tableName).eq("indexName", indexName)).first()
+			]);
+			if (bucket || extrema || metricMember) existingKeys.add(serializeKey("metric", tableName, indexName));
+			if (rankMember) existingKeys.add(serializeKey("rank", tableName, indexName));
+		}
+		let pruned = 0;
+		let pruning = 0;
+		for (const key of existingKeys) {
+			const [kind, tableName, indexName] = key.split("\0");
+			if (args.tableName && tableName !== args.tableName) continue;
+			if (args.indexName && indexName !== args.indexName) continue;
+			if (targetKeys.has(key)) continue;
+			const state = stateByKey.get(key);
+			if (!await drainIndexClear(ctx, kind, tableName, indexName, batchSize, clearBudget)) {
+				const now = Date.now();
+				await setCountState(ctx.db, {
+					tableName,
+					indexName,
+					kind: stateKindFor(kind),
+					keyDefinitionHash: state?.keyDefinitionHash ?? "",
+					metricDefinitionHash: state?.metricDefinitionHash ?? "",
+					status: COUNT_STATUS_CLEARING,
+					cursor: null,
+					processed: 0,
+					startedAt: now,
+					updatedAt: now,
+					completedAt: null,
+					lastError: null
+				}, stateKindFor(kind));
+				await scheduleChunk(ctx, tableName, indexName, batchSize);
+				pruning += 1;
+				continue;
+			}
+			if (state) await ctx.db.delete(AGGREGATE_STATE_TABLE, state._id);
+			pruned += 1;
+		}
+		return {
+			pruned,
+			pruning
+		};
+	};
+	/**
+	* Finishes clearing an index that no longer exists in the schema. Orphans have
+	* no backfill target, so they are driven purely by their CLEARING state row.
+	* Returns true when this invocation handled one.
+	*/
+	const drainOrphanClear = async (ctx, args, targets, batchSize) => {
+		const targetKeys = new Set(targets.map((target) => serializeKey(target.kind, target.tableName, target.indexName)));
+		const states = await ctx.db.query(AGGREGATE_STATE_TABLE).collect();
+		for (const state of states) {
+			if (state.status !== COUNT_STATUS_CLEARING) continue;
+			const kind = state.kind === AGGREGATE_STATE_KIND_RANK ? "rank" : "metric";
+			if (targetKeys.has(serializeKey(kind, state.tableKey, state.indexName))) continue;
+			if (args.tableName && state.tableKey !== args.tableName) continue;
+			if (args.indexName && state.indexName !== args.indexName) continue;
+			if (await drainIndexClear(ctx, kind, state.tableKey, state.indexName, batchSize, { remaining: batchSize })) {
+				await ctx.db.delete(AGGREGATE_STATE_TABLE, state._id);
+				return true;
+			}
+			await ctx.db.patch(AGGREGATE_STATE_TABLE, state._id, { updatedAt: Date.now() });
+			await scheduleChunk(ctx, state.tableKey, state.indexName, batchSize);
+			return true;
+		}
+		return false;
+	};
+	const kickoff = async (ctx, args) => {
+		const targets = getTargets(schema, args);
+		const mode = getBackfillMode(args.mode);
+		const batchSize = getBackfillBatchSize(args.batchSize);
+		const clearBudget = { remaining: batchSize };
+		const { pruned, pruning } = await pruneRemovedState(ctx, args, targets, batchSize, clearBudget);
+		if (mode === "prune") return {
+			targets: targets.length,
+			mode,
+			scheduled: 0,
+			skippedReady: 0,
+			needsRebuild: 0,
+			pruned,
+			pruning,
+			status: "ok"
+		};
+		const now = Date.now();
+		let scheduled = 0;
+		let skippedReady = 0;
+		let needsRebuild = 0;
+		for (const target of targets) {
+			const stateKind = target.kind === "rank" ? AGGREGATE_STATE_KIND_RANK : AGGREGATE_STATE_KIND_METRIC;
+			const existing = await getCountState(ctx.db, target.tableName, target.indexName, stateKind);
+			const keyDefinitionHash = computeKeyDefinitionHash(target);
+			const metricDefinitionHash = computeMetricDefinitionHash(target);
+			const nextStateBase = {
+				tableName: target.tableName,
+				indexName: target.indexName,
+				keyDefinitionHash,
+				metricDefinitionHash
+			};
+			if (mode === "rebuild") {
+				const cleared = await drainIndexClear(ctx, target.kind, target.tableName, target.indexName, batchSize, clearBudget);
+				await setCountState(ctx.db, {
+					...nextStateBase,
+					kind: stateKind,
+					status: cleared ? COUNT_STATUS_BUILDING : COUNT_STATUS_CLEARING,
+					cursor: null,
+					processed: 0,
+					startedAt: now,
+					updatedAt: now,
+					completedAt: null,
+					lastError: null
+				}, stateKind);
+			} else if (existing) {
+				if (existing.keyDefinitionHash !== keyDefinitionHash) {
+					needsRebuild += 1;
+					continue;
+				}
+				if (existing.metricDefinitionHash !== metricDefinitionHash) {
+					if (!(target.kind === "rank" ? true : requiresMetricBackfill(existing.metricDefinitionHash, metricDefinitionHash)) && existing.status === COUNT_STATUS_READY) {
+						await setCountState(ctx.db, {
+							...nextStateBase,
+							kind: stateKind,
+							status: COUNT_STATUS_READY,
+							cursor: null,
+							processed: existing.processed,
+							startedAt: existing.startedAt,
+							updatedAt: now,
+							completedAt: existing.completedAt ?? now,
+							lastError: null
+						}, stateKind);
+						skippedReady += 1;
+						continue;
+					}
+					await setCountState(ctx.db, {
+						...nextStateBase,
+						kind: stateKind,
+						status: COUNT_STATUS_BUILDING,
+						cursor: null,
+						processed: 0,
+						startedAt: now,
+						updatedAt: now,
+						completedAt: null,
+						lastError: null
+					}, stateKind);
+				} else if (existing.status === COUNT_STATUS_READY) {
+					skippedReady += 1;
+					continue;
+				}
+			} else await setCountState(ctx.db, {
+				...nextStateBase,
+				kind: stateKind,
+				status: COUNT_STATUS_BUILDING,
+				cursor: null,
+				processed: 0,
+				startedAt: now,
+				updatedAt: now,
+				completedAt: null,
+				lastError: null
+			}, stateKind);
+			await scheduleChunk(ctx, target.tableName, target.indexName, batchSize);
+			scheduled += 1;
+		}
+		return {
+			targets: targets.length,
+			mode,
+			scheduled,
+			skippedReady,
+			needsRebuild,
+			pruned,
+			pruning,
+			status: "ok"
+		};
+	};
+	const chunk = async (ctx, args) => {
+		const batchSize = getBackfillBatchSize(args.batchSize);
+		const targets = getTargets(schema, args);
+		if (!(Boolean(args.tableName && args.indexName) && targets.length === 1) && await drainOrphanClear(ctx, args, targets, batchSize)) return { status: "ok" };
+		if (targets.length > 1) {
+			for (const target of targets) {
+				const stateKind = target.kind === "rank" ? AGGREGATE_STATE_KIND_RANK : AGGREGATE_STATE_KIND_METRIC;
+				const state = await getCountState(ctx.db, target.tableName, target.indexName, stateKind);
+				if (!state || state.status !== COUNT_STATUS_READY) return chunk(ctx, {
+					tableName: target.tableName,
+					indexName: target.indexName,
+					batchSize
+				});
+			}
+			return { status: "ok" };
+		}
+		for (const target of targets) {
+			const stateKind = target.kind === "rank" ? AGGREGATE_STATE_KIND_RANK : AGGREGATE_STATE_KIND_METRIC;
+			try {
+				const state = await getCountState(ctx.db, target.tableName, target.indexName, stateKind);
+				if (!state || state.status === COUNT_STATUS_READY) continue;
+				if (state.status === COUNT_STATUS_CLEARING) {
+					const cleared = await drainIndexClear(ctx, target.kind, target.tableName, target.indexName, batchSize, { remaining: batchSize });
+					const clearedAt = Date.now();
+					await setCountState(ctx.db, {
+						tableName: target.tableName,
+						indexName: target.indexName,
+						kind: stateKind,
+						keyDefinitionHash: state.keyDefinitionHash,
+						metricDefinitionHash: state.metricDefinitionHash,
+						status: cleared ? COUNT_STATUS_BUILDING : COUNT_STATUS_CLEARING,
+						cursor: null,
+						processed: 0,
+						startedAt: state.startedAt,
+						updatedAt: clearedAt,
+						completedAt: null,
+						lastError: null
+					}, stateKind);
+					await scheduleChunk(ctx, target.tableName, target.indexName, batchSize);
+					continue;
+				}
+				const cursor = state.cursor ?? null;
+				const page = await ctx.db.query(target.tableName).withIndex("by_creation_time").paginate({
+					cursor,
+					numItems: batchSize
+				});
+				const pendingDeltas = [];
+				for (const doc of page.page) if (target.kind === "rank") await reconcileRankMembership(ctx.db, {
+					tableName: target.tableName,
+					definition: {
+						name: target.indexName,
+						partitionFields: target.fields,
+						orderFields: target.orderFields ?? [],
+						sumField: target.rankSumField
+					},
+					docId: String(doc._id),
+					doc
+				});
+				else pendingDeltas.push(await computeAggregateMembershipDelta(ctx.db, {
+					tableName: target.tableName,
+					indexName: target.indexName,
+					docId: String(doc._id),
+					keyParts: computeCountKeyParts(doc, target.fields),
+					metricValues: computeAggregateMetricValues(doc, {
+						name: target.indexName,
+						fields: target.fields,
+						countFields: target.countFields ?? [],
+						sumFields: target.sumFields ?? [],
+						avgFields: target.avgFields ?? [],
+						minFields: target.minFields ?? [],
+						maxFields: target.maxFields ?? []
+					})
+				}));
+				if (pendingDeltas.length > 0) await flushAggregateMembershipDeltas(ctx.db, target.tableName, target.indexName, pendingDeltas);
+				const now = Date.now();
+				const nextProcessed = state.processed + page.page.length;
+				if (page.isDone) {
+					await setCountState(ctx.db, {
+						tableName: target.tableName,
+						indexName: target.indexName,
+						kind: stateKind,
+						keyDefinitionHash: state.keyDefinitionHash,
+						metricDefinitionHash: state.metricDefinitionHash,
+						status: COUNT_STATUS_READY,
+						cursor: null,
+						processed: nextProcessed,
+						startedAt: state.startedAt,
+						updatedAt: now,
+						completedAt: now,
+						lastError: null
+					}, stateKind);
+					continue;
+				}
+				await setCountState(ctx.db, {
+					tableName: target.tableName,
+					indexName: target.indexName,
+					kind: stateKind,
+					keyDefinitionHash: state.keyDefinitionHash,
+					metricDefinitionHash: state.metricDefinitionHash,
+					status: COUNT_STATUS_BUILDING,
+					cursor: page.continueCursor,
+					processed: nextProcessed,
+					startedAt: state.startedAt,
+					updatedAt: now,
+					completedAt: null,
+					lastError: null
+				}, stateKind);
+				await scheduleChunk(ctx, target.tableName, target.indexName, batchSize);
+			} catch (error) {
+				await setCountStateError(ctx.db, target.tableName, target.indexName, error, stateKind);
+				throw error;
+			}
+		}
+		return { status: "ok" };
+	};
+	const status = async (ctx, args) => {
+		const states = await ctx.db.query(AGGREGATE_STATE_TABLE).collect();
+		const statesByKey = new Map(states.map((entry) => [`${entry.kind === AGGREGATE_STATE_KIND_RANK ? "rank" : "metric"}:${entry.tableKey}:${entry.indexName}`, entry]));
+		return getTargets(schema, args).map((target) => {
+			const key = `${target.kind}:${target.tableName}:${target.indexName}`;
+			const entry = statesByKey.get(key);
+			if (!entry) return {
+				kind: target.kind === "rank" ? AGGREGATE_STATE_KIND_RANK : AGGREGATE_STATE_KIND_METRIC,
+				tableName: target.tableName,
+				indexName: target.indexName,
+				keyDefinitionHash: computeKeyDefinitionHash(target),
+				metricDefinitionHash: computeMetricDefinitionHash(target),
+				status: COUNT_STATUS_BUILDING,
+				cursor: null,
+				processed: 0,
+				startedAt: 0,
+				updatedAt: 0,
+				completedAt: null,
+				lastError: null
+			};
+			const { tableKey, ...rest } = entry;
+			return {
+				...rest,
+				tableName: tableKey
+			};
+		});
+	};
+	return {
+		kickoff,
+		chunk,
+		status
+	};
+}
+
+//#endregion
+//#region src/orm/aggregate-index/capability.ts
+/**
+* Registers the aggregate-index runtime with `createOrm()`.
+*
+* Required by `aggregateIndex(...)` / `rankIndex(...)` schemas, by
+* `count()` / `aggregate()` / `rank()` queries, and by the backfill handlers
+* exposed through `orm.api()`. Importing this pulls the aggregate btree
+* runtime into the calling Convex module, so only register it where it is
+* actually used.
+*
+* Each entry forwards through the module namespace rather than capturing the
+* binding, so the resolved implementation is read per call. Snapshotting the
+* bindings here would freeze the capability at construction time and make the
+* runtime unobservable to anything that wraps a module export.
+*/
+const aggregateCapability = () => ({
+	kind: "aggregate",
+	value: {
+		applyAggregateIndexesForChange: (...args) => applyAggregateIndexesForChange(...args),
+		applyRankIndexesForChange: (...args) => applyRankIndexesForChange(...args),
+		assertAggregateIndexesWritable: (...args) => assertAggregateIndexesWritable(...args),
+		compileAggregateQueryPlan: (...args) => compileAggregateQueryPlan(...args),
+		compileCountFieldQueryPlan: (...args) => compileCountFieldQueryPlan(...args),
+		compileCountQueryPlan: (...args) => compileCountQueryPlan(...args),
+		compileRankPlan: (...args) => compileRankPlan(...args),
+		createCountBackfillHandlers: (...args) => createCountBackfillHandlers(...args),
+		ensureAggregateIndexReady: (...args) => ensureAggregateIndexReady(...args),
+		ensureCountIndexReady: (...args) => ensureCountIndexReady(...args),
+		ensureRankAllowedForRls: (...args) => ensureRankAllowedForRls(...args),
+		ensureRankIndexReady: (...args) => ensureRankIndexReady(...args),
+		isAggregatePlanZero: (...args) => isAggregatePlanZero(...args),
+		isIndexCountZero: (...args) => isIndexCountZero(...args),
+		readAverageFromBuckets: (...args) => readAverageFromBuckets(...args),
+		readCountFieldFromBuckets: (...args) => readCountFieldFromBuckets(...args),
+		readCountFromBuckets: (...args) => readCountFromBuckets(...args),
+		readExtremaFromBuckets: (...args) => readExtremaFromBuckets(...args),
+		readRankAt: (...args) => readRankAt(...args),
+		readRankCount: (...args) => readRankCount(...args),
+		readRankIndexOf: (...args) => readRankIndexOf(...args),
+		readRankMax: (...args) => readRankMax(...args),
+		readRankMin: (...args) => readRankMin(...args),
+		readRankPaginate: (...args) => readRankPaginate(...args),
+		readRankRandom: (...args) => readRankRandom(...args),
+		readRankSum: (...args) => readRankSum(...args),
+		readSumFromBuckets: (...args) => readSumFromBuckets(...args)
+	}
+});
+
+//#endregion
+export { aggregateCapability };