kitcn 0.18.0 → 0.20.0

package/dist/orm/index.js

@@ -1,6 +1,6 @@
-import { A as vectorIndex, B as ConvexColumnBuilder, C as RlsPolicy, D as rankIndex, E as index, F as arrayOf, I as custom, L as json, M as createSystemFields, N as integer, O as searchIndex, P as id, R as objectOf, S as TablePolymorphic, T as aggregateIndex, V as entityKind, _ as OrmSchemaRelations, a as deletion, b as TableDeleteConfig, c as Columns, d as OrmSchemaDefinition, f as OrmSchemaExtensionRelations, g as OrmSchemaOptions, h as OrmSchemaExtensions, i as convexTable, j as text, k as uniqueIndex, l as EnableRLS, m as OrmSchemaExtensionTriggers, o as discriminator, p as OrmSchemaExtensionTables, s as Brand, t as DirectAggregate, u as OrmContext, v as OrmSchemaTriggers, w as rlsPolicy, x as TableName, y as RlsPolicies, z as unionOf } from "../runtime-DmVSOe24.js";
+import { A as vectorIndex, B as ConvexColumnBuilder, C as RlsPolicy, D as rankIndex, E as index, F as arrayOf, I as custom, L as json, M as createSystemFields, N as integer, O as searchIndex, P as id, R as objectOf, S as TablePolymorphic, T as aggregateIndex, V as entityKind, _ as OrmSchemaRelations, a as deletion, b as TableDeleteConfig, c as Columns, d as OrmSchemaDefinition, f as OrmSchemaExtensionRelations, g as OrmSchemaOptions, h as OrmSchemaExtensions, i as convexTable, j as text, k as uniqueIndex, l as EnableRLS, m as OrmSchemaExtensionTriggers, o as discriminator, p as OrmSchemaExtensionTables, s as Brand, t as DirectAggregate, u as OrmContext, v as OrmSchemaTriggers, w as rlsPolicy, x as TableName, y as RlsPolicies, z as unionOf } from "../runtime-6DJxpDfb.js";
 import { a as pretendRequired, i as pretend, n as deprecated } from "../validators-C7LelqTN.js";
-import { A as like, B as or, C as gt, D as isFieldReference, E as inArray, F as not, I as notBetween, L as notIlike, M as lte, N as matchLikePattern, O as isNotNull, P as ne, R as notInArray, S as filterValuesEqual, T as ilike, V as startsWith, _ as contains, a as indexKeyWithinBounds, b as fieldRef, c as streamIndexRange, d as and, f as arrayContained, g as column, h as between, i as getIndexFields, j as lt, k as isNull, l as isUnsetToken, m as arrayOverlaps, n as EmptyStream, o as mergedStream, p as arrayContains, r as QueryStream, s as stream, t as getByIdWithOrmQueryFallback, u as unsetToken, v as endsWith, w as gte, x as filterValueInList, y as eq, z as notLike } from "../query-context-CJE_hYA3.js";
+import { A as like, B as or, C as gt, D as isFieldReference, E as inArray, F as not, I as notBetween, L as notIlike, M as lte, N as matchLikePattern, O as isNotNull, P as ne, R as notInArray, S as filterValuesEqual, T as ilike, V as startsWith, _ as contains, a as indexKeyWithinBounds, b as fieldRef, c as streamIndexRange, d as and, f as arrayContained, g as column, h as between, i as getIndexFields, j as lt, k as isNull, l as isUnsetToken, m as arrayOverlaps, n as EmptyStream, o as mergedStream, p as arrayContains, r as QueryStream, s as stream, t as getByIdWithOrmQueryFallback, u as unsetToken, v as endsWith, w as gte, x as filterValueInList, y as eq, z as notLike } from "../query-context-BzihIpnM.js";
 import { compareValues, v } from "convex/values";
 import { defineSchema as defineSchema$1, internalActionGeneric, internalMutationGeneric } from "convex/server";
 
@@ -1658,7 +1658,11 @@ const countStateTable = convexTable(AGGREGATE_STATE_TABLE, {
 	updatedAt: integer().notNull(),
 	completedAt: integer(),
 	lastError: text()
-}, (t) => [index("by_kind_table_index").on(t.kind, t.tableKey, t.indexName), index("by_kind_status").on(t.kind, t.status)]);
+}, (t) => [
+	index("by_kind_table_index").on(t.kind, t.tableKey, t.indexName),
+	index("by_kind_status").on(t.kind, t.status),
+	index("by_table_status").on(t.tableKey, t.status)
+]);
 const rankTreeTable = convexTable(AGGREGATE_RANK_TREE_TABLE, {
 	aggregateName: text().notNull(),
 	maxNodeSize: integer().notNull(),
@@ -1697,12 +1701,15 @@ const FLOAT64_MASK = (1n << 64n) - 1n;
 const DEFAULT_AGGREGATE_CARTESIAN_MAX_KEYS$1 = 4096;
 const DEFAULT_AGGREGATE_WORK_BUDGET$1 = 16384;
 const RANGE_PREFIX_WORK_UNIT_BASE = 2;
+const AGGREGATE_BUCKET_READ_CONCURRENCY = 25;
 const PUBLIC_ID_FIELD$1 = "id";
 const INTERNAL_ID_FIELD$1 = "_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 COUNT_ERROR = {
 	FILTER_UNSUPPORTED: "COUNT_FILTER_UNSUPPORTED",
 	NOT_INDEXED: "COUNT_NOT_INDEXED",
@@ -1716,6 +1723,7 @@ const AGGREGATE_ERROR = {
 	INDEX_BUILDING: "AGGREGATE_INDEX_BUILDING",
 	RLS_UNSUPPORTED: "AGGREGATE_RLS_UNSUPPORTED"
 };
+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));
@@ -2359,7 +2367,10 @@ const compileAggregatePlan = (tableConfig, where, metric, codes, methodName) =>
 		rangeConstraint: {
 			fieldName: rangeFieldName,
 			comparisons: rangeComparisons,
-			prefixFields: rangeIndex.prefixFields
+			prefixFields: rangeIndex.prefixFields,
+			workBudget: getAggregateWorkBudget(tableConfig),
+			filterErrorCode: codes.FILTER_UNSUPPORTED,
+			methodName
 		},
 		postFieldValues,
 		metric
@@ -2428,14 +2439,17 @@ const listBucketsByHash = async (db, tableName, indexName, keyHash) => await db.
 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, prefixStart, prefixEnd) => await db.query(AGGREGATE_BUCKET_TABLE).withIndex("by_table_index_hash", (q) => q.eq("tableKey", tableName).eq("indexName", indexName).gte("keyHash", prefixStart).lt("keyHash", prefixEnd)).collect();
+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 listMembersForIndex = async (db, tableName, indexName) => 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)).collect();
-const listBucketsForIndex = async (db, tableName, indexName) => await db.query(AGGREGATE_BUCKET_TABLE).withIndex("by_table_index", (q) => q.eq("tableKey", tableName).eq("indexName", indexName)).collect();
-const listExtremaForIndex = async (db, tableName, indexName) => await db.query(AGGREGATE_EXTREMA_TABLE).withIndex("by_table_index", (q) => q.eq("tableKey", tableName).eq("indexName", indexName)).collect();
+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);
@@ -2521,10 +2535,6 @@ const applyExtremaDelta = async (db, tableName, indexName, keyHash, fieldName, v
 		updatedAt: now
 	});
 };
-const applyExtremaValuesDelta = async (db, tableName, indexName, keyHash, values, delta) => {
-	if (delta === 0) return;
-	for (const [fieldName, value] of Object.entries(values)) await applyExtremaDelta(db, tableName, indexName, keyHash, fieldName, value, delta);
-};
 const buildKeyHashPrefixBounds = (prefixParts) => {
 	if (prefixParts.length === 0) return {
 		start: "[",
@@ -2537,47 +2547,73 @@ const buildKeyHashPrefixBounds = (prefixParts) => {
 	};
 };
 const matchesKeyPrefix = (keyParts, prefixParts) => prefixParts.every((value, index) => deepEquals(keyParts[index], value));
-const readPlanBuckets = async (db, plan) => {
-	if (!plan.rangeConstraint) {
-		const keyCandidates = plan.keyCandidates ?? buildCandidateKeys(plan.indexFields, plan.fieldValues);
-		const matched = [];
-		for (const keyParts of keyCandidates) {
-			const bucket = await getBucketByKey(db, plan.tableName, plan.indexName, keyParts);
-			if (!bucket) continue;
-			matched.push(bucket);
-		}
-		return matched;
+/**
+* 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$1;
+	const scanLimit = workBudget + 1;
+	let pending = prefixCandidates.map((prefixParts) => ({
+		prefixParts,
+		...buildKeyHashPrefixBounds(prefixParts)
+	}));
 	const matchedById = /* @__PURE__ */ new Map();
-	for (const prefixParts of prefixCandidates) {
-		const { start, end } = buildKeyHashPrefixBounds(prefixParts);
-		const buckets = await listBucketsByHashPrefix(db, plan.tableName, plan.indexName, start, end);
-		for (const bucket of buckets) {
-			if (!matchesKeyPrefix(bucket.keyParts, prefixParts)) continue;
-			const rangeValue = bucket.keyParts[rangeFieldIndex];
-			if (!matchesRangeComparisons(rangeValue, plan.rangeConstraint.comparisons)) continue;
-			let matchesPostFields = true;
-			for (const [field, allowedValues] of Object.entries(postFieldSets)) {
-				const fieldIndex = plan.indexFields.indexOf(field);
-				if (fieldIndex < 0) {
-					matchesPostFields = false;
-					break;
-				}
-				const value = bucket.keyParts[fieldIndex];
-				if (!allowedValues.has(serializeStable(value))) {
-					matchesPostFields = false;
-					break;
-				}
-			}
-			if (!matchesPostFields) continue;
-			matchedById.set(String(bucket._id), bucket);
+	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 } }).`);
 	}
-	return [...matchedById.values()];
+	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({
@@ -2657,14 +2693,23 @@ 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);
-	for (const bucket of buckets) {
-		const value = await readKeyExtrema(db, {
-			tableName: plan.tableName,
-			indexName: plan.indexName,
-			keyHash: bucket.keyHash,
-			fieldName: plan.metric.field,
-			kind: plan.metric.kind
-		});
+	const metric = plan.metric;
+	const rangeWork = buckets[RANGE_WORK_STATE];
+	if (rangeWork && plan.rangeConstraint) {
+		const workBudget = plan.rangeConstraint.workBudget ?? DEFAULT_AGGREGATE_WORK_BUDGET$1;
+		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;
@@ -2718,16 +2763,50 @@ const computeAggregateMetricValues = (doc, definition) => {
 		nonNullCountValues
 	};
 };
-const reconcileAggregateMembership = async (db, params) => {
+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;
-	const existing = await getMemberByDoc(db, tableName, indexName, docId);
 	if (!keyParts || !metricValues) {
-		if (existing) {
-			await applyBucketDelta(db, tableName, indexName, existing.keyParts, -1, negateSumValues(normalizeSumValues(existing.sumValues)), negateCountValues(normalizeNonNullCountValues(existing.nonNullCountValues)));
-			await applyExtremaValuesDelta(db, tableName, indexName, existing.keyHash, normalizeExtremaValues(existing.extremaValues), -1);
-			await db.delete(AGGREGATE_MEMBER_TABLE, existing._id);
-		}
-		return;
+		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);
@@ -2735,40 +2814,122 @@ const reconcileAggregateMembership = async (db, params) => {
 	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)) {
-		await db.patch(AGGREGATE_MEMBER_TABLE, existing._id, { updatedAt: now });
-		return;
-	}
-	if (existing) {
-		await applyBucketDelta(db, tableName, indexName, existing.keyParts, -1, negateSumValues(normalizeSumValues(existing.sumValues)), negateCountValues(normalizeNonNullCountValues(existing.nonNullCountValues)));
-		await applyExtremaValuesDelta(db, tableName, indexName, existing.keyHash, normalizeExtremaValues(existing.extremaValues), -1);
-	}
-	await applyBucketDelta(db, tableName, indexName, normalizedKeyParts, 1, normalizedNextSumValues, normalizedNextNonNullCountValues);
-	await applyExtremaValuesDelta(db, tableName, indexName, keyHash, normalizedNextExtremaValues, 1);
+	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) {
-		await db.patch(AGGREGATE_MEMBER_TABLE, existing._id, {
-			kind: AGGREGATE_STATE_KIND_METRIC,
-			keyHash,
-			keyParts: normalizedKeyParts,
-			sumValues: normalizedNextSumValues,
-			nonNullCountValues: normalizedNextNonNullCountValues,
-			extremaValues: normalizedNextExtremaValues,
-			updatedAt: now
+		buckets.push({
+			keyHash: serializeCountKeyParts(existing.keyParts),
+			keyParts: existing.keyParts,
+			deltaCount: -1,
+			deltaSums: negateSumValues(normalizeSumValues(existing.sumValues)),
+			deltaNonNullCounts: negateCountValues(normalizeNonNullCountValues(existing.nonNullCountValues))
 		});
-		return;
+		extrema.push(...toExtremaDeltas(existing.keyHash, normalizeExtremaValues(existing.extremaValues), -1));
 	}
-	await db.insert(AGGREGATE_MEMBER_TABLE, {
+	buckets.push({
+		keyHash,
+		keyParts: normalizedKeyParts,
+		deltaCount: 1,
+		deltaSums: normalizedNextSumValues,
+		deltaNonNullCounts: normalizedNextNonNullCountValues
+	});
+	extrema.push(...toExtremaDeltas(keyHash, normalizedNextExtremaValues, 1));
+	const memberFields = {
 		kind: AGGREGATE_STATE_KIND_METRIC,
-		tableKey: tableName,
-		indexName,
-		docId,
 		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) => {
@@ -2794,6 +2955,15 @@ const getCountState = async (db, tableName, indexName, kind = AGGREGATE_STATE_KI
 		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 = {
@@ -2822,20 +2992,60 @@ const setCountStateError = async (db, tableName, indexName, error, kind = AGGREG
 	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: COUNT_STATUS_BUILDING,
+		status: existing.status === COUNT_STATUS_CLEARING ? COUNT_STATUS_CLEARING : COUNT_STATUS_BUILDING,
 		updatedAt: now,
 		keyDefinitionHash: existing.keyDefinitionHash,
 		metricDefinitionHash: existing.metricDefinitionHash,
 		lastError: message
 	});
 };
-const clearCountIndexData = async (db, tableName, indexName) => {
-	const members = await listMembersForIndex(db, tableName, indexName);
-	for (const member of members) await db.delete(AGGREGATE_MEMBER_TABLE, member._id);
-	const buckets = await listBucketsForIndex(db, tableName, indexName);
-	for (const bucket of buckets) await db.delete(AGGREGATE_BUCKET_TABLE, bucket._id);
-	const extrema = await listExtremaForIndex(db, tableName, indexName);
-	for (const entry of extrema) await db.delete(AGGREGATE_EXTREMA_TABLE, entry._id);
+/**
+* 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 createCountError = (code, message) => createError(code, message);
 const createAggregateError = (code, message) => createError(code, message);
@@ -2993,15 +3203,42 @@ const ensureRankIndexReady = async (db, tableName, indexName) => {
 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 listRankMembers = async (db, tableName, indexName) => await db.query(AGGREGATE_MEMBER_TABLE).withIndex("by_kind_table_index", (q) => q.eq("kind", RANK_MEMBER_KIND).eq("tableKey", tableName).eq("indexName", indexName)).collect();
+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
 });
-const clearRankIndexData = async (db, tableName, indexName) => {
-	await rankAggregate(tableName, indexName).clearAll(rankCtx(db));
-	const members = await listRankMembers(db, tableName, indexName);
-	for (const member of members) await db.delete(AGGREGATE_MEMBER_TABLE, member._id);
+/** 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;
@@ -3023,10 +3260,7 @@ const reconcileRankMembership = async (db, params) => {
 	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) {
-		await db.patch(AGGREGATE_MEMBER_TABLE, existing._id, { updatedAt: now });
-		return;
-	}
+	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,
@@ -3093,14 +3327,13 @@ const toPublicRankItem = (plan, item) => ({
 	key: toPublicRankKey(plan.definition, item.key),
 	sumValue: item.sumValue
 });
-const readRankAt = async (db, plan, offset) => {
-	const aggregate = rankAggregate(plan.tableName, plan.indexName);
-	const count = await aggregate.count(rankCtx(db), { namespace: plan.namespace });
+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 aggregate.at(rankCtx(db), offset, { namespace: plan.namespace }));
+	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;
@@ -3122,12 +3355,18 @@ const readRankPaginate = async (db, plan, cursor, limit) => {
 		page: paged.page.map((item) => toPublicRankItem(plan, item))
 	};
 };
-const readRankMin = async (db, plan) => await readRankAt(db, plan, 0);
-const readRankMax = async (db, plan) => await readRankAt(db, plan, -1);
+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 readRankAt(db, plan, Math.floor(Math.random() * count));
+	return await readRankAtWithCount(db, plan, Math.floor(Math.random() * count), count);
 };
 
 //#endregion
@@ -3227,65 +3466,115 @@ const requiresMetricBackfill = (existingMetricDefinitionHash, targetMetricDefini
 	};
 	return hasMissing(targetStorage.sumFields, existingStorage.sumFields) || hasMissing(targetStorage.nonNullCountFields, existingStorage.nonNullCountFields) || hasMissing(targetStorage.extremaFields, existingStorage.extremaFields);
 };
-const listDistinctIndexTuples = async (db, tableName, indexName, fields) => {
-	const tuples = [];
-	let current = await db.query(tableName).withIndex(indexName).first();
-	while (current) {
-		const row = current;
-		const tuple = {};
-		for (const field of fields) tuple[field] = row[field];
-		tuples.push(tuple);
-		current = null;
-		for (let depth = fields.length - 1; depth >= 0 && !current; depth -= 1) current = await db.query(tableName).withIndex(indexName, (q) => {
-			let range = q;
-			for (let i = 0; i < depth; i += 1) range = range.eq(fields[i], tuple[fields[i]]);
-			return range.gt(fields[depth], tuple[fields[depth]]);
-		}).first();
-	}
-	return tuples;
-};
 function createCountBackfillHandlers(schema, getChunkRef) {
 	const serializeKey = (kind, tableName, indexName) => `${kind}\u0000${tableName}\u0000${indexName}`;
-	const pruneRemovedState = async (ctx, args, targets) => {
+	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 [bucketRows, memberRows, extremaRows] = await Promise.all([
-			listDistinctIndexTuples(ctx.db, AGGREGATE_BUCKET_TABLE, "by_table_index", ["tableKey", "indexName"]),
-			listDistinctIndexTuples(ctx.db, AGGREGATE_MEMBER_TABLE, "by_kind_table_index", [
-				"kind",
-				"tableKey",
-				"indexName"
-			]),
-			listDistinctIndexTuples(ctx.db, AGGREGATE_EXTREMA_TABLE, "by_table_index", ["tableKey", "indexName"])
-		]);
 		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));
-		for (const row of bucketRows) existingKeys.add(serializeKey("metric", row.tableKey, row.indexName));
-		for (const row of memberRows) {
-			const kind = row.kind === AGGREGATE_STATE_KIND_RANK ? "rank" : "metric";
-			existingKeys.add(serializeKey(kind, row.tableKey, row.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));
 		}
-		for (const row of extremaRows) existingKeys.add(serializeKey("metric", row.tableKey, row.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;
-			if (kind === "metric") await clearCountIndexData(ctx.db, tableName, indexName);
-			else await clearRankIndexData(ctx.db, tableName, indexName);
 			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;
+		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 pruned = await pruneRemovedState(ctx, args, targets);
+		const clearBudget = { remaining: batchSize };
+		const { pruned, pruning } = await pruneRemovedState(ctx, args, targets, batchSize, clearBudget);
 		if (mode === "prune") return {
 			targets: targets.length,
 			mode,
@@ -3293,6 +3582,7 @@ function createCountBackfillHandlers(schema, getChunkRef) {
 			skippedReady: 0,
 			needsRebuild: 0,
 			pruned,
+			pruning,
 			status: "ok"
 		};
 		const now = Date.now();
@@ -3311,12 +3601,11 @@ function createCountBackfillHandlers(schema, getChunkRef) {
 				metricDefinitionHash
 			};
 			if (mode === "rebuild") {
-				if (target.kind === "rank") await clearRankIndexData(ctx.db, target.tableName, target.indexName);
-				else await clearCountIndexData(ctx.db, target.tableName, target.indexName);
+				const cleared = await drainIndexClear(ctx, target.kind, target.tableName, target.indexName, batchSize, clearBudget);
 				await setCountState(ctx.db, {
 					...nextStateBase,
 					kind: stateKind,
-					status: COUNT_STATUS_BUILDING,
+					status: cleared ? COUNT_STATUS_BUILDING : COUNT_STATUS_CLEARING,
 					cursor: null,
 					processed: 0,
 					startedAt: now,
@@ -3371,12 +3660,7 @@ function createCountBackfillHandlers(schema, getChunkRef) {
 				completedAt: null,
 				lastError: null
 			}, stateKind);
-			const chunkRef = getChunkRef?.();
-			if (ctx.scheduler && chunkRef) await ctx.scheduler.runAfter(0, chunkRef, {
-				tableName: target.tableName,
-				indexName: target.indexName,
-				batchSize
-			});
+			await scheduleChunk(ctx, target.tableName, target.indexName, batchSize);
 			scheduled += 1;
 		}
 		return {
@@ -3386,12 +3670,14 @@ function createCountBackfillHandlers(schema, getChunkRef) {
 			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;
@@ -3409,11 +3695,32 @@ function createCountBackfillHandlers(schema, getChunkRef) {
 			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: {
@@ -3425,7 +3732,7 @@ function createCountBackfillHandlers(schema, getChunkRef) {
 					docId: String(doc._id),
 					doc
 				});
-				else await reconcileAggregateMembership(ctx.db, {
+				else pendingDeltas.push(await computeAggregateMembershipDelta(ctx.db, {
 					tableName: target.tableName,
 					indexName: target.indexName,
 					docId: String(doc._id),
@@ -3439,7 +3746,8 @@ function createCountBackfillHandlers(schema, getChunkRef) {
 						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) {
@@ -3473,12 +3781,7 @@ function createCountBackfillHandlers(schema, getChunkRef) {
 					completedAt: null,
 					lastError: null
 				}, stateKind);
-				const chunkRef = getChunkRef?.();
-				if (ctx.scheduler && chunkRef) await ctx.scheduler.runAfter(0, chunkRef, {
-					tableName: target.tableName,
-					indexName: target.indexName,
-					batchSize
-				});
+				await scheduleChunk(ctx, target.tableName, target.indexName, batchSize);
 			} catch (error) {
 				await setCountStateError(ctx.db, target.tableName, target.indexName, error, stateKind);
 				throw error;
@@ -4585,6 +4888,42 @@ var BufferedQueryStream = class BufferedQueryStream extends QueryStream {
 		return this.equalityIndexFilter;
 	}
 };
+const ID_LIST_POSITION_FIELD = "__kitcn_id_list_position";
+/**
+* Reads an `id` / `id in [...]` where one document at a time, in the order the
+* ids were given.
+*
+* The index key is the position in the de-duplicated id list, so a cursor names
+* a position and `narrow` drops entries without reading them. A page reads only
+* the listed positions it visits, not every id in the list on every page.
+*/
+var LazyIdListQueryStream = class LazyIdListQueryStream extends QueryStream {
+	constructor(readId, entries, order) {
+		super();
+		this.readId = readId;
+		this.entries = entries;
+		this.order = order;
+	}
+	iterWithKeys() {
+		const entries = this.entries;
+		const readId = this.readId;
+		return { async *[Symbol.asyncIterator]() {
+			for (const [position, id] of entries) yield [await readId(id), [position]];
+		} };
+	}
+	narrow(indexBounds) {
+		return new LazyIdListQueryStream(this.readId, this.entries.filter(([position]) => indexKeyWithinBounds([position], indexBounds)), this.order);
+	}
+	getOrder() {
+		return this.order;
+	}
+	getIndexFields() {
+		return [ID_LIST_POSITION_FIELD];
+	}
+	getEqualityIndexFilter() {
+		return [];
+	}
+};
 const PIPELINE_LIMIT_ORDINAL_FIELD = "__kitcn_limit_ordinal";
 /** Cap a stream at its first `limit` matching documents without eager reads. */
 var LimitedMatchesQueryStream = class LimitedMatchesQueryStream extends QueryStream {
@@ -5787,9 +6126,12 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 	* The where-clause compiler is built from declared indexes only, and `_id` is
 	* never one of them, so an `id` filter can never be index-selected: it lands
 	* in the post-filters and the stream walks the creation-time index until it
-	* happens on the row. `db.get()` reads exactly the rows asked for, so the ids
-	* are fetched directly and replayed as a creation-time-ordered stream — the
-	* order the scan would have produced, so stage order and cursors are the same.
+	* happens on the row. `db.get()` reads exactly the rows asked for.
+	*
+	* Rows come back in the order the ids were given, one read at a time. Missing
+	* or policy-filtered ids still cost a read, but a page does not reread the
+	* complete list. An `orderBy` on creation time is the exception: an id carries
+	* no creation time, so every id must be read before the first row is placed.
 	*
 	* Returns null when something else already owns the read: a pinned index, an
 	* index the compiler did select, a `where(predicate)`, or an `orderBy` that
@@ -5801,13 +6143,26 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 		const primaryOrder = queryConfig.order?.[0];
 		if (primaryOrder && primaryOrder.field !== INTERNAL_CREATION_TIME_FIELD) return null;
 		const ids = idLookup.kind === "in" ? Array.from(new Map(idLookup.ids.map((id) => [String(id), id])).values()) : [idLookup.id];
-		const rows = (await this._mapWithConcurrency(ids, async (id) => {
-			return this._getById(this.tableConfig.name, id);
-		})).filter((row) => !!row);
+		const readId = (id) => this._getById(this.tableConfig.name, id);
+		if (!primaryOrder) {
+			const entries = ids.map((id, position) => [position, id]);
+			if (order === "desc") entries.reverse();
+			return new LazyIdListQueryStream(readId, entries, order);
+		}
+		const rows = (await this._mapWithConcurrency(ids, readId)).filter((row) => !!row);
 		rows.sort((a, b) => compareValues(a[INTERNAL_CREATION_TIME_FIELD], b[INTERNAL_CREATION_TIME_FIELD]) || compareValues(a[INTERNAL_ID_FIELD], b[INTERNAL_ID_FIELD]));
 		if (order === "desc") rows.reverse();
 		return new BufferedQueryStream(rows.map((row) => [row, [row[INTERNAL_CREATION_TIME_FIELD], row[INTERNAL_ID_FIELD]]]), order, [INTERNAL_CREATION_TIME_FIELD, INTERNAL_ID_FIELD], []);
 	}
+	/**
+	* The declared index a stream read can walk to emit `field` in order.
+	*
+	* A stream orders by the index it scans, so only an index that leads with
+	* the field produces that order.
+	*/
+	_findStreamOrderIndex(field) {
+		return getIndexes(this.tableConfig.table).find((index) => index.fields[0] === field);
+	}
 	_buildBasePipelineStream(queryConfig, wherePredicate, configuredIndex) {
 		const schemaDefinition = this._getSchemaDefinitionOrThrow();
 		let streamQuery = stream(this.db, schemaDefinition).query(this.tableConfig.name);
@@ -5819,8 +6174,8 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 			return indexQuery;
 		});
 		else if (configuredIndex?.name) streamQuery = streamQuery.withIndex(configuredIndex.name, configuredIndex.range ? configuredIndex.range : (q) => q);
-		else if (primaryOrder && primaryOrder.field !== "_creationTime") {
-			const orderIndex = getIndexes(this.tableConfig.table).find((idx) => idx.fields[0] === primaryOrder.field);
+		else if (primaryOrder && primaryOrder.field !== INTERNAL_CREATION_TIME_FIELD) {
+			const orderIndex = this._findStreamOrderIndex(primaryOrder.field);
 			if (orderIndex) streamQuery = streamQuery.withIndex(orderIndex.name, (q) => q);
 		}
 		streamQuery = streamQuery.order(primaryOrderDirection);
@@ -6978,7 +7333,11 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 					streamQuery = mergedStream(streams, pipeline.interleaveBy.map((field) => this._normalizePublicFieldName(field)));
 				}
 			} else {
-				if (isCursorPaginated && maxScan !== void 0 && idLookup?.kind === "in") throw new Error("An id IN pipeline cannot use maxScan because creation-order replay requires reading the complete ID list.");
+				const orderedIdList = isCursorPaginated && maxScan !== void 0 && idLookup?.kind === "in" ? queryConfig.order?.[0] : void 0;
+				if (orderedIdList) {
+					if (orderedIdList.field === INTERNAL_CREATION_TIME_FIELD) throw new Error("An id IN pipeline cannot combine orderBy on createdAt with maxScan, because ordering an id list by creation time requires reading every id in the list. Drop maxScan, or drop orderBy to page in id-list order at one read per row.");
+					if (queryConfig.order?.length !== 1 || configuredIndex?.name || queryConfig.index || !this._findStreamOrderIndex(orderedIdList.field)) throw new Error(`An id IN pipeline cannot combine orderBy on ${this._toPublicFilterFieldName(orderedIdList.field)} with maxScan, because the scan cannot produce that order. It needs a single orderBy field that an index leads with, and no index pinned by withIndex().`);
+				}
 				streamQuery = await this._buildIdLookupStream({
 					configuredIndex,
 					idLookup,
@@ -9336,8 +9695,26 @@ function createOrmDbLifecycle(schema, triggerDefinitions) {
 		if (aggregateIndexes.length === 0 && rankIndexes.length === 0) continue;
 		const existing = tableHooks.get(tableConfig.name) ?? {};
 		const existingChange = existing.change;
+		const metricIndexNames = aggregateIndexes.map((entry) => entry.name);
+		const rankIndexNames = rankIndexes.map((entry) => entry.name);
+		const prependWriteBarrier = (before) => async (data, ctx) => {
+			await assertAggregateIndexesWritable(ctx.db, tableConfig.name, metricIndexNames, rankIndexNames);
+			return before?.(data, ctx);
+		};
 		tableHooks.set(tableConfig.name, {
 			...existing,
+			create: {
+				...existing.create,
+				before: prependWriteBarrier(existing.create?.before)
+			},
+			update: {
+				...existing.update,
+				before: prependWriteBarrier(existing.update?.before)
+			},
+			delete: {
+				...existing.delete,
+				before: prependWriteBarrier(existing.delete?.before)
+			},
 			change: async (change, ctx) => {
 				if (change.operation === "delete") {
 					if (aggregateIndexes.length > 0) await applyAggregateIndexesForChange(ctx.db, tableConfig.name, aggregateIndexes, {