kitcn 0.32.2 → 0.33.0

package/dist/orm/migrations/index.d.ts

@@ -1,3 +1,3 @@
-import { C as MigrationStep, D as defineMigration, E as buildMigrationPlan, O as defineMigrationSet, S as MigrationStateMap, T as MigrationWriteMode, _ as MigrationManifestEntry, a as MAX_STATUS_RUN_LIMIT, b as MigrationRunStatus, c as MigrationRunChunkArgs, d as MigrationAppliedState, f as MigrationDefinition, g as MigrationDriftIssue, h as MigrationDocContext, k as detectMigrationDrift, l as MigrationStatusArgs, m as MigrationDoc, o as MigrationCancelArgs, p as MigrationDirection, s as MigrationRunArgs, u as createMigrationHandlers, v as MigrationMigrateOne, w as MigrationTableName, x as MigrationSet, y as MigrationPlan } from "../../capabilities-BJm_VSDT.js";
-import { Ct as migrationCapability, dt as MIGRATION_STORAGE_TABLE_NAMES, ft as injectMigrationStorageTables, lt as MIGRATION_RUN_TABLE, mt as migrationStorageTables, pt as migrationExtension, ut as MIGRATION_STATE_TABLE } from "../../where-clause-compiler-Dgf4lrO-.js";
+import { C as MigrationStep, D as defineMigration, E as buildMigrationPlan, O as defineMigrationSet, S as MigrationStateMap, T as MigrationWriteMode, _ as MigrationManifestEntry, a as MAX_STATUS_RUN_LIMIT, b as MigrationRunStatus, c as MigrationRunChunkArgs, d as MigrationAppliedState, f as MigrationDefinition, g as MigrationDriftIssue, h as MigrationDocContext, k as detectMigrationDrift, l as MigrationStatusArgs, m as MigrationDoc, o as MigrationCancelArgs, p as MigrationDirection, s as MigrationRunArgs, u as createMigrationHandlers, v as MigrationMigrateOne, w as MigrationTableName, x as MigrationSet, y as MigrationPlan } from "../../capabilities-Bxzoofl4.js";
+import { Ct as migrationCapability, dt as MIGRATION_STORAGE_TABLE_NAMES, ft as injectMigrationStorageTables, lt as MIGRATION_RUN_TABLE, mt as migrationStorageTables, pt as migrationExtension, ut as MIGRATION_STATE_TABLE } from "../../where-clause-compiler-DrV6lQg0.js";
 export { MAX_STATUS_RUN_LIMIT, MIGRATION_RUN_TABLE, MIGRATION_STATE_TABLE, MIGRATION_STORAGE_TABLE_NAMES, type MigrationAppliedState, type MigrationCancelArgs, type MigrationDefinition, type MigrationDirection, type MigrationDoc, type MigrationDocContext, type MigrationDriftIssue, type MigrationManifestEntry, type MigrationMigrateOne, type MigrationPlan, type MigrationRunArgs, type MigrationRunChunkArgs, type MigrationRunStatus, type MigrationSet, type MigrationStateMap, type MigrationStatusArgs, type MigrationStep, type MigrationTableName, type MigrationWriteMode, buildMigrationPlan, createMigrationHandlers, defineMigration, defineMigrationSet, detectMigrationDrift, injectMigrationStorageTables, migrationCapability, migrationExtension, migrationStorageTables };

package/dist/{query-context-D4z1CnDH.js → query-context-DQLv58LH.js}

@@ -671,6 +671,21 @@ function mergedStream(streams, orderByIndexFields) {
 	return new MergedStream(streams, orderByIndexFields);
 }
 /**
+* Read streams over disjoint index ranges one after another, as one stream.
+*
+* Produces the same sequence a `mergedStream` over the whole index key would,
+* for sources that cannot interleave — but a source is only opened once the one
+* before it runs dry, so the fan-out a merge pays up front, one live query per
+* source, never happens. That is what makes a very wide union affordable.
+*
+* The caller owes disjointness and index order. Both are checked as rows come
+* out: a key that goes backwards throws rather than silently returning an
+* unordered stream.
+*/
+function concatStreams(streams) {
+	return new ConcatStreams(...streams);
+}
+/**
 * Marks sources that are already `OrderByStream`s, so `narrow` reuses them
 * instead of adding a redundant delegation layer per call.
 *
@@ -1134,6 +1149,24 @@ function* getOrderingIndexFields(stream) {
 	const streamIndexFields = stream.getIndexFields();
 	for (let i = 0; i <= streamEqualityIndexLength; i++) yield streamIndexFields.slice(i);
 }
+/**
+* Whether `mergedStream(..., orderByIndexFields)` would accept this stream.
+*
+* `MergedStream` wraps every source in an `OrderByStream`, which throws unless
+* the ordering fields are a suffix of the source's index fields past its
+* equality-pinned prefix. A caller that is *choosing* which index a source
+* walks has to know that before it commits to one, so it can fall back instead
+* of turning a working merge into a runtime error.
+*
+* Asks the stream itself rather than re-deriving the rule from an index name,
+* so the answer cannot drift from what `OrderByStream` actually enforces.
+*/
+function streamCanOrderBy(stream, orderByIndexFields) {
+	const normalized = orderByIndexFields.slice();
+	normalizeIndexFields(normalized);
+	for (const orderingIndexFields of getOrderingIndexFields(stream)) if (equalIndexFields(orderingIndexFields, normalized)) return true;
+	return false;
+}
 var OrderByStream = class OrderByStream extends QueryStream {
 	#staticFilter;
 	#stream;
@@ -1351,4 +1384,4 @@ async function getByIdWithOrmQueryFallback(ctx, tableName, id) {
 }
 
 //#endregion
-export { indexKeyWithinBounds as a, streamIndexRange as c, getIndexFields as i, isUnsetToken as l, EmptyStream as n, mergedStream as o, QueryStream as r, stream as s, getByIdWithOrmQueryFallback as t, unsetToken as u };
+export { getIndexFields as a, stream as c, isUnsetToken as d, unsetToken as f, concatStreams as i, streamCanOrderBy as l, EmptyStream as n, indexKeyWithinBounds as o, QueryStream as r, mergedStream as s, getByIdWithOrmQueryFallback as t, streamIndexRange as u };

package/dist/react/index.js

@@ -1479,11 +1479,12 @@ function createCRPCContext(options) {
 			const tokenReady = token === null || decodeJwtExp(token) !== null;
 			const identity = resolveAuthIdentity(token);
 			previousAuthRef.current = {
-				isAuthenticated,
-				identity
+				identity,
+				isAuthenticated
 			};
 			if (!previous) return;
-			if (tokenReady && (previous.identity !== identity || previous.isAuthenticated !== isAuthenticated)) convexQueryClient.resetAuthQueries();
+			const tokenRejected = previous.isAuthenticated && !isAuthenticated;
+			if (tokenReady && previous.identity !== identity || tokenRejected) convexQueryClient.resetAuthQueries();
 		}, [
 			convexQueryClient,
 			isAuthenticated,

package/dist/{schema-Bh7AmJwY.js → schema-BF4P0ZjS.js}

@@ -1313,6 +1313,327 @@ const ensureAggregateAllowedForRls = (tableConfig, rlsMode, methodName) => {
 	assertAggregateAllowedForRls(tableConfig, rlsMode, AGGREGATE_ERROR.RLS_UNSUPPORTED, methodName);
 };
 
+//#endregion
+//#region src/orm/transaction-cache.ts
+/**
+* Per-transaction memo storage for the ORM.
+*
+* The ORM already has isolate-, execution-, statement- and row-scoped memos.
+* A hook needs transaction lifetime: the write barrier is built inside
+* `createOrmDbLifecycle`, which `createOrm` runs at module scope,
+* so a flag in that closure lives as long as the isolate and would leak an
+* answer from one transaction into the next.
+*
+* Deliberately dependency-free, for the same reason as `write-fanout`:
+* `aggregate-index/runtime` is contractually unreachable from `orm/index`
+* (`import-graph.test.ts`), so importing `lifecycle` here to read one symbol
+* would drag the trigger runtime into the aggregate entry's bundle.
+* `Symbol.for` is registry-based, so re-declaring the key resolves to the same
+* symbol `lifecycle` installs.
+*/
+const ORMLIFECYCLE_INNER_DB = Symbol.for("kitcn:OrmLifecycleInnerDB");
+const ORM_TRANSACTION_ANCHOR = Symbol.for("kitcn:OrmTransactionAnchor");
+/**
+* Pins `anchor`'s transaction onto `target`, for a db built from a writer that
+* cannot be resolved back to it.
+*
+* `withoutTriggers` re-roots the ORM on the raw `ctx.db`, which is the one
+* object in the chain that carries no inner-db symbol — so a db derived from it
+* would otherwise stand for a transaction of its own and miss every memo and
+* queued write filed under the real one.
+*/
+const markOrmTransactionAnchor = (target, db) => {
+	const anchor = resolveOrmTransactionAnchor(db);
+	if (!anchor || Object.hasOwn(target, ORM_TRANSACTION_ANCHOR)) return target;
+	Object.defineProperty(target, ORM_TRANSACTION_ANCHOR, {
+		configurable: false,
+		enumerable: false,
+		value: anchor,
+		writable: false
+	});
+	return target;
+};
+/**
+* The object whose identity stands in for "this transaction".
+*
+* Convex builds `ctx.db` fresh on every UDF invocation, so it can never be
+* shared by two transactions. `getOrmLifecycleInnerDb` cannot be used on its
+* own: the lifecycle refuses to wrap readers and returns a no-op wrapper for
+* schemas with no triggers and no aggregate indexes, so the inner-db symbol is
+* absent for every query and for most mutations.
+*
+* Following the symbol to a fixed point, rather than one hop, is what makes the
+* answer canonical: `orm.with(hookCtx)` wraps a writer that is already a hook
+* wrapper, so one hop lands on the intermediate wrapper instead of the raw
+* writer the outer scope filed its work under. A pinned anchor wins outright,
+* because it is the only way a db rooted on the raw writer can name the
+* transaction at all.
+*
+* A nested `ctx.runMutation` shares the transaction but gets its own writer
+* and JS context. It cannot see caller-local memos or queued writes, nor can it
+* invalidate caller snapshots. Callers must flush deferred writes and expire
+* row snapshots before handing control to arbitrary user code.
+*/
+const resolveOrmTransactionAnchor = (db) => {
+	if (typeof db !== "object" || db === null) return;
+	let current = db;
+	const seen = new Set([current]);
+	for (;;) {
+		const pinned = current[ORM_TRANSACTION_ANCHOR];
+		if (typeof pinned === "object" && pinned !== null) return pinned;
+		const inner = current[ORMLIFECYCLE_INNER_DB];
+		if (typeof inner !== "object" || inner === null || seen.has(inner)) return current;
+		seen.add(inner);
+		current = inner;
+	}
+};
+/**
+* One memo namespace with transaction lifetime.
+*
+* The store is a `WeakMap` keyed on the anchor rather than a slot on the db,
+* because `createDatabase` promises not to mutate the `ctx.db` it was handed.
+* Entries die with the transaction's db object.
+*
+* Callers own staleness: only memoize a fact that nothing inside the
+* transaction can invalidate.
+*/
+const createOrmTransactionMemo = () => {
+	const byTransaction = /* @__PURE__ */ new WeakMap();
+	return {
+		get(db, key) {
+			const anchor = resolveOrmTransactionAnchor(db);
+			return anchor ? byTransaction.get(anchor)?.get(key) : void 0;
+		},
+		set(db, key, value) {
+			const anchor = resolveOrmTransactionAnchor(db);
+			if (!anchor) return;
+			const existing = byTransaction.get(anchor);
+			if (existing) {
+				existing.set(key, value);
+				return;
+			}
+			byTransaction.set(anchor, new Map([[key, value]]));
+		}
+	};
+};
+
+//#endregion
+//#region src/orm/write-cache.ts
+const scopes = createOrmTransactionMemo();
+const activeScopes = /* @__PURE__ */ new Set();
+let suspended$1 = 0;
+/** Snapshots may survive ORM-owned work, never a return to arbitrary code. */
+const runInOrmWriteScope = async (db, fn) => {
+	let scope = scopes.get(db, "write");
+	if (!scope) {
+		scope = {
+			depth: 0,
+			entries: /* @__PURE__ */ new Map()
+		};
+		scopes.set(db, "write", scope);
+	}
+	scope.entries.clear();
+	scope.depth += 1;
+	activeScopes.add(scope);
+	try {
+		return await fn();
+	} finally {
+		scope.entries.clear();
+		scope.depth -= 1;
+		if (scope.depth === 0) activeScopes.delete(scope);
+	}
+};
+/**
+* User code can call a nested UDF whose isolated JS context cannot invalidate
+* our snapshots. Suspend every active scope, including reentrant statements,
+* until the callback settles; never restore pre-callback entries.
+*/
+const withoutOrmWriteCache = async (fn) => {
+	for (const scope of activeScopes) scope.entries.clear();
+	suspended$1 += 1;
+	try {
+		return await fn();
+	} finally {
+		suspended$1 -= 1;
+	}
+};
+const createOrmWriteMemo = () => {
+	const namespace = Symbol("orm-write-memo");
+	return {
+		get(db, key) {
+			const scope = scopes.get(db, "write");
+			return !suspended$1 && scope?.depth ? scope.entries.get(namespace)?.get(key) : void 0;
+		},
+		set(db, key, value) {
+			const scope = scopes.get(db, "write");
+			if (suspended$1 || !scope?.depth) return;
+			let entries = scope.entries.get(namespace);
+			if (!entries) {
+				entries = /* @__PURE__ */ new Map();
+				scope.entries.set(namespace, entries);
+			}
+			entries.set(key, value);
+		}
+	};
+};
+
+//#endregion
+//#region src/orm/write-batch.ts
+/**
+* Statement-scoped deferral for the ORM write path.
+*
+* The lifecycle fires its hooks once per written document, so a subsystem that
+* maintains derived storage — aggregate index buckets, today — reconciles one
+* document at a time and rewrites the same storage document once per row. The
+* fold that would collapse those writes exists; what it lacks is a boundary
+* wide enough to fold across. A mutation statement is that boundary: one
+* `update()` / `delete()` / `insert()` is one unit of work whose derived writes
+* nobody can observe half-applied unless they read them, and a reader can be
+* made to drain first.
+*
+* Depends only on the anchor and row-cache lifetime, for the same reason as
+* `write-fanout`: the mutation builders are reachable from `orm/index`, the
+* aggregate runtime contractually is not (`import-graph.test.ts`), and both
+* ends have to name this module.
+*
+* Three invariants make it safe:
+*
+* 1. Every queued write is applied by `flushOrmWriteBatch` and nowhere else.
+*    Deltas are commutative but the writes that apply them are absolute
+*    read-modify-writes, so two of them interleaving is a lost update. Callers
+*    that have no batch open still enqueue and flush immediately rather than
+*    writing around the queue, which makes the drain the single writer and
+*    therefore the serialization point — the role `lifecycle`'s write lock
+*    plays for the documents it wraps.
+* 2. Aggregate readers and user callbacks drain first. Callback execution
+*    suspends deferral because nested UDFs cannot access the caller's queue.
+* 3. A flush callback must never itself drain. It runs inside the drain, and a
+*    drain in progress is awaited rather than skipped, so re-entering it would
+*    deadlock instead of returning stale rows. Keep the read barrier on the
+*    query-path entry points, which no flush callback calls.
+*/
+const batches = /* @__PURE__ */ new WeakMap();
+const activeBatches = /* @__PURE__ */ new Set();
+let suspended = 0;
+const getState = (db) => {
+	const anchor = resolveOrmTransactionAnchor(db);
+	if (!anchor) return;
+	const existing = batches.get(anchor);
+	if (existing) return existing;
+	const created = {
+		depth: 0,
+		flushers: /* @__PURE__ */ new Set(),
+		draining: null
+	};
+	batches.set(anchor, created);
+	return created;
+};
+/**
+* Runs every queued flush callback until none is left.
+*
+* A callback is removed before it runs, so work enqueued while the drain is in
+* flight is picked up by this same loop instead of being dropped or applied
+* twice. `draining` is published before the first callback and cleared in the
+* same synchronous step as the emptiness check that ends the loop, so a
+* caller either sees a drain it can wait for or starts its own — never a
+* window where its work is queued against a drain that has already left.
+*/
+const drain = (state) => {
+	if (state.draining) return state.draining;
+	let settled = false;
+	const running = (async () => {
+		try {
+			for (;;) {
+				const next = state.flushers.values().next();
+				if (next.done) return;
+				state.flushers.delete(next.value);
+				await next.value();
+			}
+		} finally {
+			state.draining = null;
+			settled = true;
+		}
+	})();
+	if (!settled) state.draining = running;
+	return running;
+};
+/**
+* Opens a write batch for the duration of `fn`.
+*
+* Nesting is reference-counted: a cascade that runs another statement inside
+* this one folds into the same batch rather than flushing the outer statement's
+* pending work early. The flush runs whether or not `fn` threw, so rows that
+* landed before a mid-statement throw still get their derived writes.
+*
+* When both throw, `fn`'s error wins and the flush failure rides along as its
+* `cause`. A plain `finally { await drain() }` would report the consequence and
+* swallow the reason — the statement's own failure is what a caller can act on.
+*/
+const runInOrmWriteBatch = async (db, fn) => {
+	const state = getState(db);
+	if (!state) return await fn();
+	state.depth += 1;
+	activeBatches.add(state);
+	let failure;
+	let result;
+	try {
+		result = await fn();
+	} catch (error) {
+		failure = { error };
+	}
+	state.depth -= 1;
+	if (state.depth > 0) {
+		if (failure) throw failure.error;
+		return result;
+	}
+	try {
+		await drain(state);
+	} catch (flushError) {
+		if (!failure) throw flushError;
+		if (failure.error instanceof Error && failure.error.cause === void 0) failure.error.cause = flushError;
+	} finally {
+		if (state.depth === 0) activeBatches.delete(state);
+	}
+	if (failure) throw failure.error;
+	return result;
+};
+/**
+* Queues `flush` for the next drain.
+*
+* Returns `false` only when `db` has no resolvable transaction, which is the
+* caller's signal that this module cannot help and the work has to be done
+* inline.
+*/
+const enqueueOrmWriteBatch = (db, flush) => {
+	const state = getState(db);
+	if (!state) return false;
+	state.flushers.add(flush);
+	return true;
+};
+/** True while a statement scope is holding the queue back. */
+const isOrmWriteBatchOpen = (db) => suspended === 0 && (getState(db)?.depth ?? 0) > 0;
+/** Nested UDFs cannot read or drain queues in the caller's JS context. */
+const runInOrmUserCallback = async (fn) => await withoutOrmWriteCache(async () => {
+	suspended += 1;
+	try {
+		for (const state of activeBatches) await drain(state);
+		return await fn();
+	} finally {
+		suspended -= 1;
+	}
+});
+/**
+* Applies everything queued. Both the read barrier and the only writer.
+*
+* Callers must be outside any flush callback; see this module's header.
+*/
+const flushOrmWriteBatch = async (db) => {
+	const anchor = resolveOrmTransactionAnchor(db);
+	const state = anchor ? batches.get(anchor) : void 0;
+	if (!state || !state.draining && state.flushers.size === 0) return;
+	await drain(state);
+};
+
 //#endregion
 //#region src/orm/aggregate-index/definitions.ts
 const getAggregateIndexDefinitions = (tableConfig) => {
@@ -1426,4 +1747,4 @@ function aggregateExtension() {
 }
 
 //#endregion
-export { patchReferencingRows as $, enforcePolymorphicWrite as A, getForeignKeys as B, collectPrimaryIdLookupRows as C, encodeUndefinedDeep as D, deserializeFilterExpression as E, evaluateCheckConstraintTriState as F, getTableColumns as G, getMutationCollectionLimits as H, evaluateFilter as I, getUniqueIndexes as J, getTableDeleteConfig as K, extractPrimaryIdLookup as L, ensureDefaultColumns as M, ensureNonNullValues as N, enforceCheckConstraints as O, ensureNullableColumns as P, normalizeTemporalComparableValue as Q, getChecks as R, collectMutationRowsBounded as S, decodeUndefinedDeep as T, getMutationExecutionMode as U, getMutationAsyncDelayMs as V, getOrmContext as W, hydrateDateFieldsForRead as X, hardDeleteRow as Y, normalizeDateFieldsForWrite as Z, applyDefaults as _, AGGREGATE_STATE_TABLE as a, splitReturningSelection as at, buildForeignKeyGraph as b, getAggregateIndexDefinitions as c, toConvexFilter as ct, COUNT_ERROR as d, markLifecycleHookedTables as dt, resolveOrmRuntimeDefaults as et, createAggregateError as f, compileConvexFilter as ft, ensureCountAllowedForRls as g, ensureAggregateAllowedForRls as h, mapWithConcurrency as ht, AGGREGATE_RANK_TREE_TABLE as i, softDeleteRow as it, enforceUniqueIndexes as j, enforceForeignKeys as k, getRankIndexDefinitions as l, unsetFieldsOf as lt, createError as m, isConvexEnforceableFilter as mt, AGGREGATE_EXTREMA_TABLE as n, selectReturningRowWithHydration as nt, aggregateExtension as o, stripUnsetFields as ot, createCountError as p, convexAnd as pt, getTableName as q, AGGREGATE_MEMBER_TABLE as r, serializeFilterExpression as rt, rankAggregateName as s, takeRowsWithinByteBudget as st, AGGREGATE_BUCKET_TABLE as t, returningSelectionReadsCreationTime as tt, AGGREGATE_ERROR as u, hasLifecycleHooks as ut, applyIncomingForeignKeyActionsOnDelete as v, createForeignKeyProbeMemo as w, canUsePrimaryIdLookupCursor as x, applyIncomingForeignKeyActionsOnUpdate as y, getColumnName as z };
+export { getOrmContext as $, canUsePrimaryIdLookupCursor as A, enforceUniqueIndexes as B, createError as C, isConvexEnforceableFilter as Ct, applyIncomingForeignKeyActionsOnDelete as D, applyDefaults as E, deserializeFilterExpression as F, evaluateFilter as G, ensureNonNullValues as H, encodeUndefinedDeep as I, getColumnName as J, extractPrimaryIdLookup as K, enforceCheckConstraints as L, collectPrimaryIdLookupRows as M, createForeignKeyProbeMemo as N, applyIncomingForeignKeyActionsOnUpdate as O, decodeUndefinedDeep as P, getMutationExecutionMode as Q, enforceForeignKeys as R, createCountError as S, convexAnd as St, ensureCountAllowedForRls as T, ensureNullableColumns as U, ensureDefaultColumns as V, evaluateCheckConstraintTriState as W, getMutationAsyncDelayMs as X, getForeignKeys as Y, getMutationCollectionLimits as Z, createOrmTransactionMemo as _, toConvexFilter as _t, AGGREGATE_STATE_TABLE as a, hydrateDateFieldsForRead as at, COUNT_ERROR as b, markLifecycleHookedTables as bt, getAggregateIndexDefinitions as c, patchReferencingRows as ct, flushOrmWriteBatch as d, selectReturningRowWithHydration as dt, getTableColumns as et, isOrmWriteBatchOpen as f, serializeFilterExpression as ft, runInOrmWriteScope as g, takeRowsWithinByteBudget as gt, createOrmWriteMemo as h, stripUnsetFields as ht, AGGREGATE_RANK_TREE_TABLE as i, hardDeleteRow as it, collectMutationRowsBounded as j, buildForeignKeyGraph as k, getRankIndexDefinitions as l, resolveOrmRuntimeDefaults as lt, runInOrmWriteBatch as m, splitReturningSelection as mt, AGGREGATE_EXTREMA_TABLE as n, getTableName as nt, aggregateExtension as o, normalizeDateFieldsForWrite as ot, runInOrmUserCallback as p, softDeleteRow as pt, getChecks as q, AGGREGATE_MEMBER_TABLE as r, getUniqueIndexes as rt, rankAggregateName as s, normalizeTemporalComparableValue as st, AGGREGATE_BUCKET_TABLE as t, getTableDeleteConfig as tt, enqueueOrmWriteBatch as u, returningSelectionReadsCreationTime as ut, markOrmTransactionAnchor as v, unsetFieldsOf as vt, ensureAggregateAllowedForRls as w, mapWithConcurrency as wt, createAggregateError as x, compileConvexFilter as xt, AGGREGATE_ERROR as y, hasLifecycleHooks as yt, enforcePolymorphicWrite as z };

package/dist/{where-clause-compiler-Dgf4lrO-.d.ts → where-clause-compiler-DrV6lQg0.d.ts}

@@ -1,4 +1,4 @@
-import { $t as OrmLifecycleChange, A as CreateDatabaseOptions, Ar as $Type, B as getUniqueIndexes, Ct as OrderByClause, F as CascadeMode, Ft as ExtractTablesFromSchema, Gn as Columns, Gt as TablesRelationalConfig, Ht as RelationsBuilderConfigValue, I as DeleteMode, Kn as OrmRuntimeDefaults, L as SerializedFilterExpression, Mr as ColumnBuilder, Mt as VectorSearchProvider, N as OrmReader, Nr as ColumnBuilderBaseConfig, Or as SystemFieldAliases, P as OrmWriter, Pt as AnyRelationsBuilderConfig, Qn as OrmSchemaTriggers, R as getChecks, U as EdgeMetadata, Un as ConvexColumnBuilder, Ur as entityKind, Ut as RelationsConfigWithSchema, Vn as ConvexTextBuilderInitial, Wt as TableRelationalConfig, Xt as ConvexTable, Yn as OrmSchemaExtensionTriggers, Zn as OrmSchemaRelations, Zt as ConvexTableWithColumns, an as RlsPolicy, dt as InferInsertModel, kr as SystemFields, pt as InferSelectModel, qn as OrmSchemaExtensionRelations, r as OrmCapability, rr as FilterExpression$1, x as MigrationSet, z as getForeignKeys, zr as HasDefault, zt as RelationsBuilder } from "./capabilities-BJm_VSDT.js";
+import { $t as OrmLifecycleChange, A as CreateDatabaseOptions, Ar as $Type, B as getUniqueIndexes, Ct as OrderByClause, F as CascadeMode, Ft as ExtractTablesFromSchema, Gn as Columns, Gt as TablesRelationalConfig, Ht as RelationsBuilderConfigValue, I as DeleteMode, Kn as OrmRuntimeDefaults, L as SerializedFilterExpression, Mr as ColumnBuilder, Mt as VectorSearchProvider, N as OrmReader, Nr as ColumnBuilderBaseConfig, Or as SystemFieldAliases, P as OrmWriter, Pt as AnyRelationsBuilderConfig, Qn as OrmSchemaTriggers, R as getChecks, U as EdgeMetadata, Un as ConvexColumnBuilder, Ur as entityKind, Ut as RelationsConfigWithSchema, Vn as ConvexTextBuilderInitial, Wt as TableRelationalConfig, Xt as ConvexTable, Yn as OrmSchemaExtensionTriggers, Zn as OrmSchemaRelations, Zt as ConvexTableWithColumns, an as RlsPolicy, dt as InferInsertModel, kr as SystemFields, pt as InferSelectModel, qn as OrmSchemaExtensionRelations, r as OrmCapability, rr as FilterExpression$1, x as MigrationSet, z as getForeignKeys, zr as HasDefault, zt as RelationsBuilder } from "./capabilities-Bxzoofl4.js";
 import * as convex_values0 from "convex/values";
 import { GenericId, Validator, Value } from "convex/values";
 import { DefineSchemaOptions, GenericDatabaseReader, GenericDatabaseWriter, GenericSchema, SchedulableFunctionReference, Scheduler, SchemaDefinition, internalActionGeneric, internalMutationGeneric, internalQueryGeneric } from "convex/server";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kitcn",
-  "version": "0.32.2",
+  "version": "0.33.0",
   "description": "kitcn - React Query integration and CLI tools for Convex",
   "keywords": [
     "convex",

package/skills/kitcn/references/features/aggregates.md

@@ -58,6 +58,19 @@ const orders = convexTable(
 
 After deploying, CLI runs `aggregateBackfill` automatically. Wait for `aggregateBackfillStatus` (an internal query) to report `READY`.
 
+### Write costs
+
+Bulk ORM statements reuse aggregate bucket/member reads within uninterrupted
+statements: one bucket read per distinct tuple and one membership read per
+document. User hooks, policy callbacks and statement exit end reuse, preserving
+nested-mutation writes. Raw writer calls do not share cached rows.
+
+Shared bucket/extrema writes fold within statements. Aggregate reads (including
+returning relation counts) and user hook/policy entry flush pending writes;
+callbacks suspend batching until they settle so nested functions see stored
+writes. Reads/callbacks can increase flush count. Membership rows remain one
+write per changed document.
+
 ### `count()` — O(1) No-Scan Counts
 
 ```ts

package/skills/kitcn/references/features/orm.md

@@ -598,7 +598,9 @@ Per source:
 
 - `index: { name, range }` anchors that source on its own range. It overrides
   the chain-level `.withIndex(...)`; sources that omit it use the chain index.
-- `where` filters that source's rows after the read.
+- `where` is compiled against the table's indexes like a `findMany` where. It
+  bounds the read when it can be lowered onto the index that source walks;
+  whatever no index covers is filtered after the read.
 
 `interleaveBy` fields must be the trailing fields each source is already ordered
 by, so every field before them has to be pinned with `eq` in that source's
@@ -607,8 +609,18 @@ fields — e.g. `by_author_likes` (authorId, numLikes) with `eq("authorId", ...)
 merges with `numLikesAndType` (type, numLikes) with `eq("type", ...)` under
 `interleaveBy(["numLikes"])`.
 
-Anchor every source. A shared `.withIndex(...)` plus per-source `where` makes
-each source walk the same range and discard the misses after reading them.
+Whether a source `where` bounds the read depends on the index that source ends
+up walking. With no index pinned it picks one, so `{ where: { status: "active" } }`
+reads the `by_status` range. With a pinned index it may only narrow that same
+index: `.withIndex("by_status")` plus `{ where: { status: "active" } }` narrows,
+while `.withIndex("by_name")` plus the same `where` walks `by_name` and discards
+the misses.
+
+A pinned `range` is the source's scope, never a hint: a `where` alongside one
+always filters after the read rather than widening it. Lowering also has to
+preserve the merge, so a `where` is only lowered when the resulting order can
+still supply `interleaveBy`. Anchor a source with `index: { name, range }`
+whenever you need a specific range read.
 
 ### Pre-pagination transforms
 
@@ -630,6 +642,14 @@ const page = await ctx.orm.query.users
   .paginate({ cursor: null, limit: 20 });
 ```
 
+Children are read through an index that leads with the relation's foreign key.
+A stage `where` rides that index when one extends it — `where: { numLikes: { gt: 10 } }`
+on `posts` reads the `by_author_likes` (authorId, numLikes) range instead of
+every post by the author. Children then arrive in that index's order, so a
+lowered range field orders them ahead of creation time. Declare an index whose
+fields are `(...foreign key, ...filtered fields)` for the stage filters you
+page on.
+
 See [Select Composition Limitations](#select-composition-limitations) in API Reference.
 
 ## Pagination Modes
@@ -675,7 +695,7 @@ const page = await ctx.orm.query.users.withIndex("by_status").findMany({
 });
 ```
 
-Falls back to a bounded scan (needs `maxScan`) when the probed index cannot supply the requested `orderBy`, or when the union is wider than 64 ranges.
+Falls back to a bounded scan (needs `maxScan`) when the probed index cannot supply the requested `orderBy`, or when a union wider than 64 ranges is asked for an `orderBy` that sorts across values, such as `createdAt`. Up to 64 ranges are read as one merged stream; a wider union is read one range after another, which keeps it index-bounded at any list length but can only produce the index's own order.
 
 Without an `orderBy`, an index-union page is in the order of the index it walks — grouped by the probed value — not in creation order.