kitcn 0.29.0 → 0.30.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # kitcn
 
+## 0.30.0
+
+### Minor Changes
+
+- [#422](https://github.com/udecode/kitcn/pull/422) [`f677251`](https://github.com/udecode/kitcn/commit/f6772514d2525104ac6878c0eeb7334a84af981b) Thanks [@MikeyZhang75](https://github.com/MikeyZhang75)! - ## Patches
+
+  - Fix soft cascade delete re-reading every child it had already processed. New scheduled campaigns require and resume through an exact foreign-key index, keeping reads linear without allowing mutable trailing index fields to strand a child. Queued jobs reselect a newly available exact index or drain through the legacy replay path.
+
 ## 0.29.0
 
 ### Minor Changes

package/dist/aggregate/index.d.ts

@@ -1,5 +1,5 @@
 import { Vn as ConvexTextBuilderInitial, Zt as ConvexTableWithColumns } from "../capabilities-6PZBmvc8.js";
-import { C as ConvexNumberBuilderInitial, E as ConvexIdBuilderInitial, N as ConvexCustomBuilderInitial } from "../where-clause-compiler-CX5-0M5p.js";
+import { C as ConvexNumberBuilderInitial, E as ConvexIdBuilderInitial, N as ConvexCustomBuilderInitial } from "../where-clause-compiler-DvYSTJXe.js";
 import * as convex_values0 from "convex/values";
 import { GenericId, Infer, Value } from "convex/values";
 import { DocumentByName, GenericDataModel, GenericDatabaseReader, GenericDatabaseWriter, TableNamesInDataModel } from "convex/server";

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

@@ -1,6 +1,6 @@
 import { t as DirectAggregate } from "../../runtime-CcOvOf4K.js";
 import { a as Columns } from "../../table-CX2lnX7e.js";
-import { Dt as usesSystemCreatedAtAlias, Et as PUBLIC_CREATED_AT_FIELD, Q as normalizeTemporalComparableValue, Tt as INTERNAL_CREATION_TIME_FIELD, a as AGGREGATE_STATE_TABLE, c as getAggregateIndexDefinitions, d as COUNT_ERROR, ht as mapWithConcurrency, i as AGGREGATE_RANK_TREE_TABLE, l as getRankIndexDefinitions, m as createError, n as AGGREGATE_EXTREMA_TABLE, r as AGGREGATE_MEMBER_TABLE, s as rankAggregateName, t as AGGREGATE_BUCKET_TABLE, u as AGGREGATE_ERROR } from "../../schema-CzdjX7nx.js";
+import { Dt as PUBLIC_CREATED_AT_FIELD, Et as INTERNAL_CREATION_TIME_FIELD, Ot as usesSystemCreatedAtAlias, Q as normalizeTemporalComparableValue, a as AGGREGATE_STATE_TABLE, c as getAggregateIndexDefinitions, d as COUNT_ERROR, ht as mapWithConcurrency, i as AGGREGATE_RANK_TREE_TABLE, l as getRankIndexDefinitions, m as createError, n as AGGREGATE_EXTREMA_TABLE, r as AGGREGATE_MEMBER_TABLE, s as rankAggregateName, t as AGGREGATE_BUCKET_TABLE, u as AGGREGATE_ERROR } from "../../schema-D8ZZMSKd.js";
 
 //#region src/orm/transaction-cache.ts
 /**

package/dist/orm/index.d.ts

@@ -1,5 +1,5 @@
 import { $n as TableName, $t as OrmLifecycleChange, An as ConvexCheckBuilder, At as UpdateSet, Bn as ConvexTextBuilder, Br as IsPrimaryKey, Bt as RelationsBuilderColumnBase, C as MigrationStep, Cn as ConvexVectorIndexConfig, Cr as not, Ct as OrderByClause, D as defineMigration, Dn as searchIndex, Dr as startsWith, Dt as ReturningAll, E as buildMigrationPlan, En as rankIndex, Er as or, Et as PredicateWhereIndexConfig, Fn as ConvexUniqueConstraintBuilderOn, Fr as ColumnBuilderTypeConfig, Ft as ExtractTablesFromSchema, Gn as Columns, Gt as TablesRelationalConfig, H as RlsMode, Hn as text, Hr as NotNull, In as ConvexUniqueConstraintConfig, Ir as ColumnBuilderWithTableName, It as ExtractTablesWithRelations, Jn as OrmSchemaExtensionTables, Jt as ConvexDeletionBuilder, Kt as defineRelations, Ln as check, Lr as ColumnDataType, Lt as ManyConfig, M as DatabaseWithQuery, Mn as ConvexForeignKeyBuilder, Mr as ColumnBuilder, Mt as VectorSearchProvider, N as OrmReader$1, Nn as ConvexForeignKeyConfig, Nr as ColumnBuilderBaseConfig, Nt as unsetToken, O as defineMigrationSet, On as uniqueIndex, Ot as ReturningResult, P as OrmWriter$1, Pn as ConvexUniqueConstraintBuilder, Pr as ColumnBuilderRuntimeConfig, Qn as OrmSchemaTriggers, Qt as DiscriminatorBuilderConfig, Rn as foreignKey, Rr as DrizzleEntity, Rt as OneConfig, S as MigrationStateMap, Sn as ConvexVectorIndexBuilderOn, Sr as ne, St as MutationRunMode, T as MigrationWriteMode, Tn as index, Tr as notInArray, Tt as PaginatedResult, U as EdgeMetadata, V as RlsContext, Vn as ConvexTextBuilderInitial, Vr as IsUnique, Vt as RelationsBuilderColumnConfig, W as extractRelationsConfig, Wn as Brand, Wt as TableRelationalConfig, Xn as OrmSchemaExtensions, Xt as ConvexTable, Yt as ConvexDeletionConfig, Zn as OrmSchemaRelations, Zt as ConvexTableWithColumns, _ as MigrationManifestEntry, _n as ConvexRankIndexBuilderOn, _r as isNotNull, _t as MutationExecutionMode, an as RlsPolicy, ar as UnaryExpression, at as BuildRelationResult, b as MigrationRunStatus, bn as ConvexSearchIndexConfig, br as lt, bt as MutationResult, cn as rlsPolicy, cr as contains, ct as DBQueryConfig, d as MigrationAppliedState, dn as rlsRole, dr as fieldRef, dt as InferInsertModel, en as OrmLifecycleOperation, er as BinaryExpression, f as MigrationDefinition, fn as ConvexAggregateIndexBuilder, fr as gt, ft as InferModelFromColumns, g as MigrationDriftIssue, gn as ConvexRankIndexBuilder, gr as isFieldReference, gt as MutationExecuteResult, h as MigrationDocContext, hn as ConvexIndexBuilderOn, hr as inArray, ht as MutationExecuteConfig, i as OrmMigrationCapability, in as discriminator, ir as LogicalExpression, it as BuildQueryResult, j as DatabaseWithMutations, jn as ConvexCheckConfig, jr as AnyColumn, jt as VectorQueryConfig, k as detectMigrationDrift, kn as vectorIndex, kr as SystemFields, kt as ReturningSelection, ln as RlsRole, lr as endsWith, lt as FilterOperators, m as MigrationDoc, mn as ConvexIndexBuilder, mr as ilike, mt as InsertValue, n as OrmCapabilities, nn as convexTable, nr as FieldReference, nt as AggregateFieldValue, on as RlsPolicyConfig, or as and, ot as CountConfig, p as MigrationDirection, pn as ConvexAggregateIndexBuilderOn, pr as gte, pt as InferSelectModel, qt as defineRelationsPart, r as OrmCapability, rn as deletion, rr as FilterExpression, rt as AggregateResult, sn as RlsPolicyToOption, sr as between, st as CountResult, t as OrmAggregateCapability, tn as TableConfig, tr as ExpressionVisitor, tt as AggregateConfig, un as RlsRoleConfig, ur as eq, ut as GetColumnData, v as MigrationMigrateOne, vn as ConvexSearchIndexBuilder, vr as isNull, vt as MutationPaginateConfig, w as MigrationTableName, wn as aggregateIndex, wr as notBetween, wt as OrderDirection, x as MigrationSet, xn as ConvexVectorIndexBuilder, xr as lte, xt as MutationReturning, y as MigrationPlan, yn as ConvexSearchIndexBuilderOn, yr as like, yt as MutationPaginatedResult, zn as unique, zr as HasDefault, zt as RelationsBuilder } from "../capabilities-6PZBmvc8.js";
-import { $ as OrmClientWithApi$1, A as ConvexDateMode, B as ConvexBytesBuilderInitial, C as ConvexNumberBuilderInitial, D as id, E as ConvexIdBuilderInitial, F as custom, G as ConvexBigIntBuilder, H as ConvexBooleanBuilder, I as json, J as CreateOrmOptions, K as ConvexBigIntBuilderInitial, L as objectOf, M as ConvexCustomBuilder, N as ConvexCustomBuilderInitial, O as ConvexDateBuilder, P as arrayOf, Q as OrmClientBase$1, R as unionOf, S as ConvexNumberBuilder, St as defineTriggers, T as ConvexIdBuilder, U as ConvexBooleanBuilderInitial, V as bytes, W as boolean, X as GenericOrmCtx$1, Y as GenericOrm$1, Z as OrmApiResult, _ as ConvexTimestampMode, _t as OrmBeforeResult, a as requireSchemaRelations, at as ScheduledMutationBatchArgs, b as ConvexTextEnumBuilderInitial, bt as OrmTriggerContext, c as TableConfigResult, ct as scheduledDeleteFactory, d as OrmNotFoundError, et as OrmFunctions, f as ConvexVectorBuilder, g as ConvexTimestampBuilderInitial, gt as defineSchemaExtension, h as ConvexTimestampBuilder, ht as SchemaExtension, i as getSchemaTriggers, it as createOrm, j as date, k as ConvexDateBuilderInitial, l as getTableColumns, m as vector, n as defineSchema, nt as OrmWriterCtx, o as asc, ot as scheduledMutationBatchFactory, p as ConvexVectorBuilderInitial, q as bigint, r as getSchemaRelations, rt as ResolveOrmSchema, s as desc, st as ScheduledDeleteArgs, t as WhereClauseResult, tt as OrmReaderCtx, u as getTableConfig, v as timestamp, vt as OrmTableTriggers, w as integer, x as textEnum, xt as OrmTriggers, y as ConvexTextEnumBuilder, yt as OrmTriggerChange, z as ConvexBytesBuilder } from "../where-clause-compiler-CX5-0M5p.js";
+import { $ as OrmClientWithApi$1, A as ConvexDateMode, B as ConvexBytesBuilderInitial, C as ConvexNumberBuilderInitial, D as id, E as ConvexIdBuilderInitial, F as custom, G as ConvexBigIntBuilder, H as ConvexBooleanBuilder, I as json, J as CreateOrmOptions, K as ConvexBigIntBuilderInitial, L as objectOf, M as ConvexCustomBuilder, N as ConvexCustomBuilderInitial, O as ConvexDateBuilder, P as arrayOf, Q as OrmClientBase$1, R as unionOf, S as ConvexNumberBuilder, St as defineTriggers, T as ConvexIdBuilder, U as ConvexBooleanBuilderInitial, V as bytes, W as boolean, X as GenericOrmCtx$1, Y as GenericOrm$1, Z as OrmApiResult, _ as ConvexTimestampMode, _t as OrmBeforeResult, a as requireSchemaRelations, at as ScheduledMutationBatchArgs, b as ConvexTextEnumBuilderInitial, bt as OrmTriggerContext, c as TableConfigResult, ct as scheduledDeleteFactory, d as OrmNotFoundError, et as OrmFunctions, f as ConvexVectorBuilder, g as ConvexTimestampBuilderInitial, gt as defineSchemaExtension, h as ConvexTimestampBuilder, ht as SchemaExtension, i as getSchemaTriggers, it as createOrm, j as date, k as ConvexDateBuilderInitial, l as getTableColumns, m as vector, n as defineSchema, nt as OrmWriterCtx, o as asc, ot as scheduledMutationBatchFactory, p as ConvexVectorBuilderInitial, q as bigint, r as getSchemaRelations, rt as ResolveOrmSchema, s as desc, st as ScheduledDeleteArgs, t as WhereClauseResult, tt as OrmReaderCtx, u as getTableConfig, v as timestamp, vt as OrmTableTriggers, w as integer, x as textEnum, xt as OrmTriggers, y as ConvexTextEnumBuilder, yt as OrmTriggerChange, z as ConvexBytesBuilder } from "../where-clause-compiler-DvYSTJXe.js";
 import { i as pretendRequired, n as deprecated, r as pretend } from "../validators-wOIjhkfN.js";
 import { a as QueryCtxWithPreferredOrmQueryTable, i as QueryCtxWithOrmQueryTable, n as LookupByIdResultByCtx, o as getByIdWithOrmQueryFallback, r as QueryCtxWithOptionalOrmQueryTable, t as DocByCtx } from "../query-context-DJONf8X5.js";
 import { DefineSchemaOptions, GenericDatabaseReader, GenericDatabaseWriter, GenericSchema, SchemaDefinition } from "convex/server";

package/dist/orm/index.js

@@ -4,7 +4,7 @@ import { a as pretendRequired, i as pretend, n as deprecated } from "../validato
 import { t as id } from "../id-CuSfWa5q.js";
 import { A as or, C as matchLikePattern, D as notIlike, E as notBetween, O as notInArray, S as lte, T as not, _ as isFieldReference, a as between, b as like, c as endsWith, d as filterValueInList, f as filterValuesEqual, g as inArray, h as ilike, i as arrayOverlaps, j as startsWith, k as notLike, l as eq, m as gte, n as arrayContained, o as column, p as gt, r as arrayContains, s as contains, t as and, u as fieldRef, v as isNotNull, w as ne, x as lt, y as isNull } from "../filter-expression-Dydt8wS0.js";
 import { a as indexKeyWithinBounds, c as streamIndexRange, i as getIndexFields, l as isUnsetToken, n as EmptyStream, o as mergedStream, r as QueryStream, s as stream, t as getByIdWithOrmQueryFallback, u as unsetToken } from "../query-context-DOm5Xm3H.js";
-import { $ as patchReferencingRows, A as enforcePolymorphicWrite, B as getForeignKeys, C as collectPrimaryIdLookupRows, Ct as resolveIndexOrderPushdown, D as encodeUndefinedDeep, Dt as usesSystemCreatedAtAlias, E as deserializeFilterExpression, Et as PUBLIC_CREATED_AT_FIELD, F as evaluateCheckConstraintTriState, G as getTableColumns$2, H as getMutationCollectionLimits, I as evaluateFilter, J as getUniqueIndexes, K as getTableDeleteConfig, L as extractPrimaryIdLookup, M as ensureDefaultColumns, N as ensureNonNullValues, O as enforceCheckConstraints, P as ensureNullableColumns, Q as normalizeTemporalComparableValue, R as getChecks, S as collectMutationRowsBounded, St as getRankIndexes, T as decodeUndefinedDeep, Tt as INTERNAL_CREATION_TIME_FIELD, U as getMutationExecutionMode, V as getMutationAsyncDelayMs, W as getOrmContext, X as hydrateDateFieldsForRead, Y as hardDeleteRow, Z as normalizeDateFieldsForWrite, _ as applyDefaults, _t as findRelationIndex, at as splitReturningSelection, b as buildForeignKeyGraph, bt as getAggregateIndexes, c as getAggregateIndexDefinitions, ct as toConvexFilter, d as COUNT_ERROR, dt as markLifecycleHookedTables, et as resolveOrmRuntimeDefaults, f as createAggregateError, ft as compileConvexFilter, g as ensureCountAllowedForRls, gt as findIndexForColumns, h as ensureAggregateAllowedForRls, ht as mapWithConcurrency, it as softDeleteRow, j as enforceUniqueIndexes, k as enforceForeignKeys, l as getRankIndexDefinitions, lt as unsetFieldsOf, mt as isConvexEnforceableFilter, nt as selectReturningRowWithHydration, o as aggregateExtension, ot as stripUnsetFields, p as createCountError, pt as convexAnd, q as getTableName, rt as serializeFilterExpression, st as takeRowsWithinByteBudget, tt as returningSelectionReadsCreationTime, u as AGGREGATE_ERROR, ut as hasLifecycleHooks, v as applyIncomingForeignKeyActionsOnDelete, vt as findSearchIndexByName, w as createForeignKeyProbeMemo, wt as CREATED_AT_MIGRATION_MESSAGE, x as canUsePrimaryIdLookupCursor, xt as getIndexes, y as applyIncomingForeignKeyActionsOnUpdate, yt as findVectorIndexByName, z as getColumnName$1 } from "../schema-CzdjX7nx.js";
+import { $ as patchReferencingRows, A as enforcePolymorphicWrite, B as getForeignKeys, C as collectPrimaryIdLookupRows, Ct as getRankIndexes, D as encodeUndefinedDeep, Dt as PUBLIC_CREATED_AT_FIELD, E as deserializeFilterExpression, Et as INTERNAL_CREATION_TIME_FIELD, F as evaluateCheckConstraintTriState, G as getTableColumns$2, H as getMutationCollectionLimits, I as evaluateFilter, J as getUniqueIndexes, K as getTableDeleteConfig, L as extractPrimaryIdLookup, M as ensureDefaultColumns, N as ensureNonNullValues, O as enforceCheckConstraints, Ot as usesSystemCreatedAtAlias, P as ensureNullableColumns, Q as normalizeTemporalComparableValue, R as getChecks, S as collectMutationRowsBounded, St as getIndexes, T as decodeUndefinedDeep, Tt as CREATED_AT_MIGRATION_MESSAGE, U as getMutationExecutionMode, V as getMutationAsyncDelayMs, W as getOrmContext, X as hydrateDateFieldsForRead, Y as hardDeleteRow, Z as normalizeDateFieldsForWrite, _ as applyDefaults, _t as findIndexForColumns, at as splitReturningSelection, b as buildForeignKeyGraph, bt as findVectorIndexByName, c as getAggregateIndexDefinitions, ct as toConvexFilter, d as COUNT_ERROR, dt as markLifecycleHookedTables, et as resolveOrmRuntimeDefaults, f as createAggregateError, ft as compileConvexFilter, g as ensureCountAllowedForRls, gt as findExactIndexForColumns, h as ensureAggregateAllowedForRls, ht as mapWithConcurrency, it as softDeleteRow, j as enforceUniqueIndexes, k as enforceForeignKeys, l as getRankIndexDefinitions, lt as unsetFieldsOf, mt as isConvexEnforceableFilter, nt as selectReturningRowWithHydration, o as aggregateExtension, ot as stripUnsetFields, p as createCountError, pt as convexAnd, q as getTableName, rt as serializeFilterExpression, st as takeRowsWithinByteBudget, tt as returningSelectionReadsCreationTime, u as AGGREGATE_ERROR, ut as hasLifecycleHooks, v as applyIncomingForeignKeyActionsOnDelete, vt as findRelationIndex, w as createForeignKeyProbeMemo, wt as resolveIndexOrderPushdown, x as canUsePrimaryIdLookupCursor, xt as getAggregateIndexes, y as applyIncomingForeignKeyActionsOnUpdate, yt as findSearchIndexByName, z as getColumnName$1 } from "../schema-D8ZZMSKd.js";
 import { t as defineSchemaExtension } from "../extensions-Blzsyekm.js";
 import { compareValues, convexToJson, jsonToConvex, v } from "convex/values";
 import { defineSchema as defineSchema$1, internalActionGeneric, internalMutationGeneric, internalQueryGeneric } from "convex/server";
@@ -7360,6 +7360,7 @@ function scheduledDeleteFactory(schema, edgeMetadata, scheduledMutationBatch) {
 //#region src/orm/scheduled-mutation-batch.ts
 /** Column stamped by `softDeleteRow`; see mutation-utils.ts. */
 const DELETION_TIME_FIELD = "deletionTime";
+const isPending = (row) => row[DELETION_TIME_FIELD] === void 0 || row[DELETION_TIME_FIELD] === null;
 const isRecord = (value) => !!value && typeof value === "object" && !Array.isArray(value);
 function scheduledMutationBatchFactory(schema, edgeMetadata, scheduledMutationBatch) {
 	const tableByName = /* @__PURE__ */ new Map();
@@ -7424,23 +7425,30 @@ function scheduledMutationBatchFactory(schema, edgeMetadata, scheduledMutationBa
 		if (!targetValues || !Array.isArray(targetValues)) throw new Error("scheduledMutationBatch: targetValues are required for cascade work.");
 		if (!args.foreignIndexName) throw new Error("scheduledMutationBatch: foreignIndexName is required for cascade work.");
 		const action = args.foreignAction ?? "no action";
-		const skipSoftDeletedRows = workType === "cascade-delete" && action === "cascade" && (args.cascadeMode ?? "hard") === "soft";
+		const isSoftCascade = workType === "cascade-delete" && action === "cascade" && (args.cascadeMode ?? "hard") === "soft";
+		const exactIndexName = findExactIndexForColumns(getIndexes(table), sourceColumns);
+		if (isSoftCascade && args.softCascadeCursorVersion === 1 && !exactIndexName) throw new Error(`scheduledMutationBatch: async soft cascade on '${args.table}' requires an exact foreign-key index on (${sourceColumns.join(", ")}).`);
+		const effectiveIndexName = isSoftCascade && exactIndexName ? exactIndexName : args.foreignIndexName;
+		const recoversQueuedJob = isSoftCascade && exactIndexName !== null && (args.softCascadeCursorVersion !== 1 || args.foreignIndexName !== exactIndexName);
+		const pageStartCursor = isSoftCascade && exactIndexName ? recoversQueuedJob ? null : args.cursor : null;
+		const replaysQueuedPrefixJob = isSoftCascade && !exactIndexName;
 		const queryWithIndex = () => {
-			const indexed = ctx.db.query(args.table).withIndex(args.foreignIndexName, (q) => {
+			const indexed = ctx.db.query(args.table).withIndex(effectiveIndexName, (q) => {
 				let builder = q.eq(sourceColumns[0], targetValues[0]);
 				for (let i = 1; i < sourceColumns.length; i += 1) builder = builder.eq(sourceColumns[i], targetValues[i]);
 				return builder;
 			});
-			if (!skipSoftDeletedRows) return indexed;
+			if (!replaysQueuedPrefixJob) return indexed;
 			return indexed.filter((q) => q.or(q.eq(q.field(DELETION_TIME_FIELD), void 0), q.eq(q.field(DELETION_TIME_FIELD), null)));
 		};
 		const paged = await queryWithIndex().paginate({
-			cursor: null,
+			cursor: pageStartCursor,
 			numItems: args.batchSize
 		});
 		const resolvedMaxBytesPerBatch = args.maxBytesPerBatch ?? maxBytesPerBatch;
 		const bounded = takeRowsWithinByteBudget(paged.page, resolvedMaxBytesPerBatch);
-		const rows = bounded.rows;
+		const consumedRows = bounded.rows;
+		const rows = isSoftCascade ? consumedRows.filter(isPending) : consumedRows;
 		const hitByteLimit = bounded.hitLimit;
 		const scheduleState = {
 			remainingCalls: scheduleCallCap,
@@ -7498,6 +7506,29 @@ function scheduledMutationBatchFactory(schema, edgeMetadata, scheduledMutationBa
 				await patchReferencingRows(ctx.db, args.table, rows, patchValues);
 			}
 		}
+		if (isSoftCascade && exactIndexName) {
+			if (hitByteLimit) {
+				await ctx.scheduler.runAfter(args.delayMs, scheduledMutationBatch, {
+					...args,
+					workType,
+					foreignIndexName: exactIndexName,
+					softCascadeCursorVersion: 1,
+					cursor: pageStartCursor,
+					batchSize: consumedRows.length,
+					maxBytesPerBatch: resolvedMaxBytesPerBatch
+				});
+				return;
+			}
+			if (!paged.isDone && paged.continueCursor !== null) await ctx.scheduler.runAfter(args.delayMs, scheduledMutationBatch, {
+				...args,
+				workType,
+				foreignIndexName: exactIndexName,
+				softCascadeCursorVersion: 1,
+				cursor: paged.continueCursor,
+				maxBytesPerBatch: resolvedMaxBytesPerBatch
+			});
+			return;
+		}
 		if (await queryWithIndex().first() !== null || hitByteLimit) await ctx.scheduler.runAfter(args.delayMs, scheduledMutationBatch, {
 			...args,
 			workType,

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-6PZBmvc8.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-CX5-0M5p.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-DvYSTJXe.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/{schema-CzdjX7nx.js → schema-D8ZZMSKd.js}

@@ -47,6 +47,9 @@ function findIndexForColumns(indexes, columns) {
 	for (const index of indexes) if (hasColumnPrefix(index, columns)) return index.name;
 	return null;
 }
+function findExactIndexForColumns(indexes, columns) {
+	return indexes.find((candidate) => candidate.fields.length === columns.length && candidate.fields.every((field, position) => field === columns[position]))?.name ?? null;
+}
 const hasColumnPrefix = (index, columns) => {
 	if (index.fields.length < columns.length) return false;
 	for (let i = 0; i < columns.length; i += 1) if (index.fields[i] !== columns[i]) return false;
@@ -880,8 +883,9 @@ async function enforceForeignKeys(db, table, candidate, options) {
 		}).first()) throw new Error(`Foreign key violation on '${tableName}': missing document in '${foreignKey.foreignTableName}'.`);
 	}
 }
-function getIndexForForeignKey(foreignKey) {
-	return findIndexForColumns(getIndexes(foreignKey.sourceTable), foreignKey.sourceColumns);
+function getIndexForForeignKey(foreignKey, exact = false) {
+	const indexes = getIndexes(foreignKey.sourceTable);
+	return exact ? findExactIndexForColumns(indexes, foreignKey.sourceColumns) : findIndexForColumns(indexes, foreignKey.sourceColumns);
 }
 function foreignKeyIndexError(foreignKey) {
 	return /* @__PURE__ */ new Error(`Foreign key on '${foreignKey.sourceTableName}' requires index on '${foreignKey.sourceTableName}(${foreignKey.sourceColumns.join(", ")})' for cascading actions.`);
@@ -969,7 +973,9 @@ async function applyIncomingForeignKeyActionsOnDelete(db, table, row, options) {
 		const action = foreignKey.onDelete ?? "no action";
 		const targetValues = foreignKey.targetColumns.map((column) => row[column]);
 		if (targetValues.some((value) => value === void 0 || value === null)) continue;
-		const indexName = getIndexForForeignKey(foreignKey);
+		const requiresExactIndex = options.executionMode === "async" && options.cascadeMode === "soft" && action === "cascade";
+		const indexName = getIndexForForeignKey(foreignKey, requiresExactIndex);
+		if (requiresExactIndex && !indexName) throw new Error(`Async soft cascade on '${foreignKey.sourceTableName}' requires an exact foreign-key index on (${foreignKey.sourceColumns.join(", ")}). Prefix indexes with trailing fields cannot provide stable scheduled continuation.`);
 		if (action === "restrict" || action === "no action") {
 			if (!indexName && !options.allowFullScan) throw foreignKeyIndexError(foreignKey);
 			if (!indexName && options.strict) console.warn(`Foreign key check running without index (allowFullScan: true) on '${foreignKey.sourceTableName}'.`);
@@ -1001,6 +1007,7 @@ async function applyIncomingForeignKeyActionsOnDelete(db, table, row, options) {
 					foreignAction: action,
 					deleteMode: options.deleteMode,
 					cascadeMode: options.cascadeMode,
+					softCascadeCursorVersion: requiresExactIndex ? 1 : void 0,
 					cursor: null,
 					batchSize: asyncBatchSize,
 					maxBytesPerBatch: options.maxBytesPerBatch,
@@ -1526,4 +1533,4 @@ function aggregateExtension() {
 }
 
 //#endregion
-export { patchReferencingRows as $, enforcePolymorphicWrite as A, getForeignKeys as B, collectPrimaryIdLookupRows as C, resolveIndexOrderPushdown as Ct, encodeUndefinedDeep as D, usesSystemCreatedAtAlias as Dt, deserializeFilterExpression as E, PUBLIC_CREATED_AT_FIELD as Et, 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, getRankIndexes as St, decodeUndefinedDeep as T, INTERNAL_CREATION_TIME_FIELD as Tt, getMutationExecutionMode as U, getMutationAsyncDelayMs as V, getOrmContext as W, hydrateDateFieldsForRead as X, hardDeleteRow as Y, normalizeDateFieldsForWrite as Z, applyDefaults as _, findRelationIndex as _t, AGGREGATE_STATE_TABLE as a, splitReturningSelection as at, buildForeignKeyGraph as b, getAggregateIndexes as bt, 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, findIndexForColumns as gt, 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, findSearchIndexByName as vt, createForeignKeyProbeMemo as w, CREATED_AT_MIGRATION_MESSAGE as wt, canUsePrimaryIdLookupCursor as x, getIndexes as xt, applyIncomingForeignKeyActionsOnUpdate as y, findVectorIndexByName as yt, getColumnName as z };
+export { patchReferencingRows as $, enforcePolymorphicWrite as A, getForeignKeys as B, collectPrimaryIdLookupRows as C, getRankIndexes as Ct, encodeUndefinedDeep as D, PUBLIC_CREATED_AT_FIELD as Dt, deserializeFilterExpression as E, INTERNAL_CREATION_TIME_FIELD as Et, 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, usesSystemCreatedAtAlias as Ot, ensureNullableColumns as P, normalizeTemporalComparableValue as Q, getChecks as R, collectMutationRowsBounded as S, getIndexes as St, decodeUndefinedDeep as T, CREATED_AT_MIGRATION_MESSAGE as Tt, getMutationExecutionMode as U, getMutationAsyncDelayMs as V, getOrmContext as W, hydrateDateFieldsForRead as X, hardDeleteRow as Y, normalizeDateFieldsForWrite as Z, applyDefaults as _, findIndexForColumns as _t, AGGREGATE_STATE_TABLE as a, splitReturningSelection as at, buildForeignKeyGraph as b, findVectorIndexByName as bt, 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, findExactIndexForColumns as gt, 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, findRelationIndex as vt, createForeignKeyProbeMemo as w, resolveIndexOrderPushdown as wt, canUsePrimaryIdLookupCursor as x, getAggregateIndexes as xt, applyIncomingForeignKeyActionsOnUpdate as y, findSearchIndexByName as yt, getColumnName as z };

package/dist/{where-clause-compiler-CX5-0M5p.d.ts → where-clause-compiler-DvYSTJXe.d.ts}

@@ -427,6 +427,7 @@ type ScheduledMutationBatchArgs = {
   update?: Record<string, unknown>;
   deleteMode?: DeleteMode;
   cascadeMode?: CascadeMode;
+  softCascadeCursorVersion?: 1;
   foreignIndexName?: string;
   foreignSourceColumns?: string[];
   targetValues?: unknown;
@@ -1023,7 +1024,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
           fieldName: "updatedAt";
         };
       };
-      count: ConvexNumberBuilderInitial<""> & {
+      indexName: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1033,7 +1034,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "count";
+          fieldName: "indexName";
         };
       };
       tableKey: ConvexTextBuilderInitial<""> & {
@@ -1049,7 +1050,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
           fieldName: "tableKey";
         };
       };
-      indexName: ConvexTextBuilderInitial<""> & {
+      count: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1059,7 +1060,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "indexName";
+          fieldName: "count";
         };
       };
       keyHash: ConvexTextBuilderInitial<""> & {
@@ -1161,7 +1162,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
           fieldName: "updatedAt";
         };
       };
-      tableKey: ConvexTextBuilderInitial<""> & {
+      indexName: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1171,10 +1172,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "tableKey";
+          fieldName: "indexName";
         };
       };
-      indexName: ConvexTextBuilderInitial<""> & {
+      tableKey: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1184,7 +1185,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "indexName";
+          fieldName: "tableKey";
         };
       };
       keyHash: ConvexTextBuilderInitial<""> & {
@@ -1355,7 +1356,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
           fieldName: "updatedAt";
         };
       };
-      count: ConvexNumberBuilderInitial<""> & {
+      indexName: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1365,7 +1366,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "count";
+          fieldName: "indexName";
         };
       };
       tableKey: ConvexTextBuilderInitial<""> & {
@@ -1381,7 +1382,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
           fieldName: "tableKey";
         };
       };
-      indexName: ConvexTextBuilderInitial<""> & {
+      count: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1391,7 +1392,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "indexName";
+          fieldName: "count";
         };
       };
       keyHash: ConvexTextBuilderInitial<""> & {
@@ -1670,7 +1671,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
           fieldName: "lastError";
         };
       };
-      tableKey: ConvexTextBuilderInitial<""> & {
+      indexName: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1680,10 +1681,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "tableKey";
+          fieldName: "indexName";
         };
       };
-      indexName: ConvexTextBuilderInitial<""> & {
+      keyDefinitionHash: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1693,10 +1694,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "indexName";
+          fieldName: "keyDefinitionHash";
         };
       };
-      keyDefinitionHash: ConvexTextBuilderInitial<""> & {
+      metricDefinitionHash: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1706,10 +1707,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "keyDefinitionHash";
+          fieldName: "metricDefinitionHash";
         };
       };
-      metricDefinitionHash: ConvexTextBuilderInitial<""> & {
+      tableKey: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1719,7 +1720,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "metricDefinitionHash";
+          fieldName: "tableKey";
         };
       };
     };

package/package.json

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

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

@@ -89,6 +89,11 @@ import { foreignKey } from "kitcn/orm";
 (t) => [foreignKey({ columns: [t.userSlug], foreignColumns: [users.slug] })];
 ```
 
+Delta from parity: async soft cascade requires an exact child index on the
+referencing columns. `index("by_author").on(t.authorId)` qualifies;
+`index("by_author_rank").on(t.authorId, t.rank)` does not, because a mutable
+trailing field cannot provide stable continuation across scheduled mutations.
+
 ### Check Constraints
 
 ```ts