@atscript/db 0.1.145 → 0.1.147

package/dist/{column-diff-Q9UmWn5x.d.mts → fk-diff-BtOmL4OW.d.mts}

@@ -1,4 +1,4 @@
-import { B as TDbFieldMeta, Gt as AtscriptDbView, O as TColumnDiff, Q as TDbStorageType, Qt as AtscriptQueryNode, R as TDbDefaultValue, Zt as AtscriptQueryFieldRef, dt as TExistingTableOption, lt as TExistingColumn, sn as AtscriptDbReadable, st as TDerivedColumn } from "./buckets-DRycmhOW.mjs";
+import { $ as TDbStorageType, H as TDbForeignKey, Jt as AtscriptDbView, O as TColumnDiff, V as TDbFieldMeta, ct as TDerivedColumn, ft as TExistingTableOption, nn as AtscriptQueryFieldRef, pn as AtscriptDbReadable, rn as AtscriptQueryNode, ut as TExistingColumn, z as TDbDefaultValue } from "./buckets-DYopfd2Y.mjs";
 
 //#region src/schema/schema-hash.d.ts
 interface TFieldSnapshot {
@@ -66,6 +66,11 @@ interface TViewJoinSnapshot {
   condition: string;
   /** Emitted only for `"left"` — an inner join (the default) carries no key. @since 0.1.136 */
   kind?: "inner" | "left";
+  /**
+   * First-row joins only: canonical JSON `[["<scope>.<column>", 1 | -1], …]`
+   * of the ordering, the appended primary key included. @since 0.1.147
+   */
+  order?: string;
 }
 /**
  * One column of a managed view as stored in its snapshot — the PHYSICAL
@@ -84,6 +89,12 @@ interface TViewColumnSnapshot {
   aggField?: string;
   /** Canonical JSON of a conditional aggregate's predicate. */
   aggFilter?: string;
+  /**
+   * Computed columns only: canonical JSON of the `@db.compute` expression —
+   * leaves `{c: "<viewColumn>"}`, literals `{n: x}`, nodes `{op, a: [...]}`.
+   * @since 0.1.147
+   */
+  expr?: string;
 }
 interface TViewSnapshot {
   tableName: string;
@@ -208,4 +219,39 @@ declare function computeColumnDiff(desired: readonly TDbFieldMeta[], existing: T
   snapshot?: TTableSnapshot | null;
 }): TColumnDiff;
 //#endregion
-export { TTableSnapshot as a, TViewSnapshot as c, computeTableHash as d, computeTableSnapshot as f, snapshotToExistingTableOptions as h, TForeignKeySnapshot as i, canonicalizeQueryNode as l, snapshotToExistingColumns as m, isColumnTypeChanged as n, TViewColumnSnapshot as o, computeViewSnapshot as p, TFieldSnapshot as r, TViewJoinSnapshot as s, computeColumnDiff as t, computeSchemaHash as u };
+//#region src/schema/fk-diff.d.ts
+/**
+ * Desired FKs are keyed and compared by their PHYSICAL columns
+ * ({@link fkColumns}) — the snapshot side is physical too.
+ */
+interface TForeignKeyDiff {
+  /** FKs present in desired but not in stored snapshot (new). */
+  added: TDbForeignKey[];
+  /** FKs present in stored snapshot but not in desired (removed). */
+  removed: TForeignKeySnapshot[];
+  /** FKs where fields match but target, onDelete, or onUpdate differ. */
+  changed: Array<{
+    desired: TDbForeignKey;
+    existing: TForeignKeySnapshot;
+  }>;
+}
+/** Canonical key for an FK: sorted local field names, comma-joined. */
+declare function fkKey(fields: readonly string[]): string;
+/**
+ * Physical local / target column names of a desired FK (`@db.column` renames
+ * applied) — what DDL, constraint sync, the FK diff and the snapshot compare.
+ */
+declare function fkColumns(fk: TDbForeignKey): {
+  fields: string[];
+  targetFields: string[];
+};
+/**
+ * Compares desired FK constraints against stored snapshot to detect
+ * additions, removals, and property changes (target table, target fields,
+ * onDelete, onUpdate).
+ */
+declare function computeForeignKeyDiff(desired: ReadonlyMap<string, TDbForeignKey>, existingSnapshot: readonly TForeignKeySnapshot[]): TForeignKeyDiff;
+/** Whether the FK diff contains any changes. */
+declare function hasForeignKeyChanges(diff: TForeignKeyDiff): boolean;
+//#endregion
+export { computeTableSnapshot as _, hasForeignKeyChanges as a, snapshotToExistingTableOptions as b, TFieldSnapshot as c, TViewColumnSnapshot as d, TViewJoinSnapshot as f, computeTableHash as g, computeSchemaHash as h, fkKey as i, TForeignKeySnapshot as l, canonicalizeQueryNode as m, computeForeignKeyDiff as n, computeColumnDiff as o, TViewSnapshot as p, fkColumns as r, isColumnTypeChanged as s, TForeignKeyDiff as t, TTableSnapshot as u, computeViewSnapshot as v, snapshotToExistingColumns as y };

package/dist/{column-diff-w-Mym_3w.d.cts → fk-diff-DLqwVkKG.d.cts}

@@ -1,4 +1,4 @@
-import { B as TDbFieldMeta, Gt as AtscriptDbView, O as TColumnDiff, Q as TDbStorageType, Qt as AtscriptQueryNode, R as TDbDefaultValue, Zt as AtscriptQueryFieldRef, dt as TExistingTableOption, lt as TExistingColumn, sn as AtscriptDbReadable, st as TDerivedColumn } from "./buckets-DYFu0eZ8.cjs";
+import { $ as TDbStorageType, H as TDbForeignKey, Jt as AtscriptDbView, O as TColumnDiff, V as TDbFieldMeta, ct as TDerivedColumn, ft as TExistingTableOption, nn as AtscriptQueryFieldRef, pn as AtscriptDbReadable, rn as AtscriptQueryNode, ut as TExistingColumn, z as TDbDefaultValue } from "./buckets-CjdPipCC.cjs";
 
 //#region src/schema/schema-hash.d.ts
 interface TFieldSnapshot {
@@ -66,6 +66,11 @@ interface TViewJoinSnapshot {
   condition: string;
   /** Emitted only for `"left"` — an inner join (the default) carries no key. @since 0.1.136 */
   kind?: "inner" | "left";
+  /**
+   * First-row joins only: canonical JSON `[["<scope>.<column>", 1 | -1], …]`
+   * of the ordering, the appended primary key included. @since 0.1.147
+   */
+  order?: string;
 }
 /**
  * One column of a managed view as stored in its snapshot — the PHYSICAL
@@ -84,6 +89,12 @@ interface TViewColumnSnapshot {
   aggField?: string;
   /** Canonical JSON of a conditional aggregate's predicate. */
   aggFilter?: string;
+  /**
+   * Computed columns only: canonical JSON of the `@db.compute` expression —
+   * leaves `{c: "<viewColumn>"}`, literals `{n: x}`, nodes `{op, a: [...]}`.
+   * @since 0.1.147
+   */
+  expr?: string;
 }
 interface TViewSnapshot {
   tableName: string;
@@ -208,4 +219,39 @@ declare function computeColumnDiff(desired: readonly TDbFieldMeta[], existing: T
   snapshot?: TTableSnapshot | null;
 }): TColumnDiff;
 //#endregion
-export { TTableSnapshot as a, TViewSnapshot as c, computeTableHash as d, computeTableSnapshot as f, snapshotToExistingTableOptions as h, TForeignKeySnapshot as i, canonicalizeQueryNode as l, snapshotToExistingColumns as m, isColumnTypeChanged as n, TViewColumnSnapshot as o, computeViewSnapshot as p, TFieldSnapshot as r, TViewJoinSnapshot as s, computeColumnDiff as t, computeSchemaHash as u };
+//#region src/schema/fk-diff.d.ts
+/**
+ * Desired FKs are keyed and compared by their PHYSICAL columns
+ * ({@link fkColumns}) — the snapshot side is physical too.
+ */
+interface TForeignKeyDiff {
+  /** FKs present in desired but not in stored snapshot (new). */
+  added: TDbForeignKey[];
+  /** FKs present in stored snapshot but not in desired (removed). */
+  removed: TForeignKeySnapshot[];
+  /** FKs where fields match but target, onDelete, or onUpdate differ. */
+  changed: Array<{
+    desired: TDbForeignKey;
+    existing: TForeignKeySnapshot;
+  }>;
+}
+/** Canonical key for an FK: sorted local field names, comma-joined. */
+declare function fkKey(fields: readonly string[]): string;
+/**
+ * Physical local / target column names of a desired FK (`@db.column` renames
+ * applied) — what DDL, constraint sync, the FK diff and the snapshot compare.
+ */
+declare function fkColumns(fk: TDbForeignKey): {
+  fields: string[];
+  targetFields: string[];
+};
+/**
+ * Compares desired FK constraints against stored snapshot to detect
+ * additions, removals, and property changes (target table, target fields,
+ * onDelete, onUpdate).
+ */
+declare function computeForeignKeyDiff(desired: ReadonlyMap<string, TDbForeignKey>, existingSnapshot: readonly TForeignKeySnapshot[]): TForeignKeyDiff;
+/** Whether the FK diff contains any changes. */
+declare function hasForeignKeyChanges(diff: TForeignKeyDiff): boolean;
+//#endregion
+export { computeTableSnapshot as _, hasForeignKeyChanges as a, snapshotToExistingTableOptions as b, TFieldSnapshot as c, TViewColumnSnapshot as d, TViewJoinSnapshot as f, computeTableHash as g, computeSchemaHash as h, fkKey as i, TForeignKeySnapshot as l, canonicalizeQueryNode as m, computeForeignKeyDiff as n, computeColumnDiff as o, TViewSnapshot as p, fkColumns as r, isColumnTypeChanged as s, TForeignKeyDiff as t, TTableSnapshot as u, computeViewSnapshot as v, snapshotToExistingColumns as y };

package/dist/index.cjs

@@ -1,8 +1,8 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_db_error = require("./db-error-DTkkeu5b.cjs");
-const require_column_diff = require("./column-diff-D_Kyuh0S.cjs");
-const require_aggregate_fns = require("./aggregate-fns-CGBv3E8S.cjs");
-const require_nested_writer = require("./nested-writer-xfQwxplL.cjs");
+const require_column_diff = require("./column-diff-Dt7EDJsA.cjs");
+const require_aggregate_fns = require("./aggregate-fns-CtsRbZn9.cjs");
+const require_nested_writer = require("./nested-writer-SqtYJHF0.cjs");
 const require_derived_rules = require("./derived-rules-YstgIxG-.cjs");
 const require_object = require("./object-Djg28csK.cjs");
 const require_consts = require("./consts-BzRfCcH2.cjs");
@@ -377,34 +377,6 @@ var DbSpace = class {
 	}
 };
 //#endregion
-//#region src/query/query-tree.ts
-/**
-* `true` when a query-tree operand is a field reference (`{ field, type? }`)
-* rather than a literal — e.g. the right side of a field-to-field comparison.
-* @since 0.1.136
-*/
-function isFieldRef(value) {
-	return value !== null && typeof value === "object" && "field" in value;
-}
-/**
-* Translates a JS-emitted query tree into a FilterExpr.
-* Resolves field references (type + field path) to physical column names
-* via the provided resolver function.
-*/
-function translateQueryTree(node, resolveField) {
-	if ("$and" in node) return { $and: node.$and.map((n) => translateQueryTree(n, resolveField)) };
-	if ("$or" in node) return { $or: node.$or.map((n) => translateQueryTree(n, resolveField)) };
-	if ("$not" in node) return { $not: translateQueryTree(node.$not, resolveField) };
-	const comp = node;
-	const leftField = resolveField(comp.left);
-	if (isFieldRef(comp.right)) {
-		const rightField = resolveField(comp.right);
-		return { [leftField]: { [comp.op]: { $field: rightField } } };
-	}
-	if (comp.op === "$exists") return { [leftField]: { $exists: comp.right !== false } };
-	return { [leftField]: { [comp.op]: comp.right } };
-}
-//#endregion
 //#region src/table/db-entity.ts
 /**
 * Whether `value` is a compiled type a `DbSpace` accepts: an annotated type
@@ -435,6 +407,7 @@ exports.$upsert = require_ops.$upsert;
 exports.ADAPTER_FILTER_REASON = require_column_diff.ADAPTER_FILTER_REASON;
 exports.ALL_AGGREGATE_FNS = require_aggregate_fns.ALL_AGGREGATE_FNS;
 exports.ALL_BUCKET_UNITS = require_column_diff.ALL_BUCKET_UNITS;
+exports.ALL_VIEW_CAPABILITIES = require_column_diff.ALL_VIEW_CAPABILITIES;
 exports.ApplicationIntegrity = require_column_diff.ApplicationIntegrity;
 exports.AtscriptDbReadable = require_column_diff.AtscriptDbReadable;
 exports.AtscriptDbTable = require_column_diff.AtscriptDbTable;
@@ -452,11 +425,21 @@ exports.FieldMappingStrategy = require_column_diff.FieldMappingStrategy;
 exports.IntegrityStrategy = require_column_diff.IntegrityStrategy;
 exports.NativeIntegrity = require_column_diff.NativeIntegrity;
 exports.NoopLogger = require_column_diff.NoopLogger;
+Object.defineProperty(exports, "RELATION_OPS", {
+	enumerable: true,
+	get: function() {
+		return _uniqu_core.RELATION_OPS;
+	}
+});
+exports.REL_FILTER_MAX_DEPTH = require_nested_writer.REL_FILTER_MAX_DEPTH;
+exports.REL_FILTER_MAX_NODES = require_nested_writer.REL_FILTER_MAX_NODES;
 exports.RelationalFieldMapper = require_column_diff.RelationalFieldMapper;
+exports.ResolvedRelationFilter = require_nested_writer.ResolvedRelationFilter;
 exports.TableMetadata = require_column_diff.TableMetadata;
 exports.UniquSelect = require_column_diff.UniquSelect;
 exports.acceptedOperatorsHint = require_column_diff.acceptedOperatorsHint;
 exports.aliasTargetOf = require_column_diff.aliasTargetOf;
+exports.andFilters = require_nested_writer.andFilters;
 exports.assertGeoPoint = require_column_diff.assertGeoPoint;
 exports.assertNoVersionWrites = require_column_diff.assertNoVersionWrites;
 exports.bucketSourceVerdict = require_column_diff.bucketSourceVerdict;
@@ -473,11 +456,14 @@ Object.defineProperty(exports, "computeInsights", {
 		return _uniqu_core.computeInsights;
 	}
 });
+exports.containsRelationFilter = require_nested_writer.containsRelationFilter;
 exports.createDbValidatorPlugin = require_validator.createDbValidatorPlugin;
 exports.createFailureCollector = require_column_diff.createFailureCollector;
 exports.decomposePatch = require_column_diff.decomposePatch;
 exports.deletePath = require_object.deletePath;
 exports.findAncestorInSet = require_object.findAncestorInSet;
+exports.fkColumns = require_column_diff.fkColumns;
+exports.forEachResolvedRelation = require_nested_writer.forEachResolvedRelation;
 exports.forceNavNonOptional = require_validator.forceNavNonOptional;
 exports.geoIndexNotFoundMessage = require_column_diff.geoIndexNotFoundMessage;
 exports.getDbFieldOp = require_ops.getDbFieldOp;
@@ -488,13 +474,14 @@ exports.guardFilter = require_column_diff.guardFilter;
 exports.guardPath = require_column_diff.guardPath;
 exports.guardPaths = require_column_diff.guardPaths;
 exports.guardQuery = require_column_diff.guardQuery;
+exports.hasRelationOp = require_nested_writer.hasRelationOp;
 exports.isAtscriptDbView = require_column_diff.isAtscriptDbView;
 exports.isBucketableField = require_column_diff.isBucketableField;
 exports.isColumnTypeChanged = require_column_diff.isColumnTypeChanged;
 exports.isDbEntityType = isDbEntityType;
 exports.isDbFieldOp = require_ops.isDbFieldOp;
 exports.isEmptyObject = require_object.isEmptyObject;
-exports.isFieldRef = isFieldRef;
+exports.isFieldRef = require_nested_writer.isFieldRef;
 exports.isGeoIndexableType = require_column_diff.isGeoIndexableType;
 exports.isGeoPointType = require_column_diff.isGeoPointType;
 exports.isJsonValueField = require_column_diff.isJsonValueField;
@@ -506,11 +493,19 @@ Object.defineProperty(exports, "isPrimitive", {
 		return _uniqu_core.isPrimitive;
 	}
 });
+Object.defineProperty(exports, "isRelationOp", {
+	enumerable: true,
+	get: function() {
+		return _uniqu_core.isRelationOp;
+	}
+});
+exports.isResolvedRelationFilter = require_nested_writer.isResolvedRelationFilter;
 exports.isViewType = require_column_diff.isViewType;
 exports.jsonValueAncestor = require_column_diff.jsonValueAncestor;
 exports.narrowerFilterOps = require_column_diff.narrowerFilterOps;
 exports.normalizeComputedSelect = require_column_diff.normalizeComputedSelect;
 exports.reconcileCas = require_ops.reconcileCas;
+exports.relationStaticFilter = require_nested_writer.relationStaticFilter;
 exports.resolveCalendarBuckets = require_column_diff.resolveCalendarBuckets;
 exports.resolveDesignType = require_column_diff.resolveDesignType;
 exports.searchIndexNotFoundMessage = require_column_diff.searchIndexNotFoundMessage;
@@ -519,7 +514,7 @@ exports.separateCas = require_ops.separateCas;
 exports.separateFieldOps = require_ops.separateFieldOps;
 exports.sortFieldNames = require_column_diff.sortFieldNames;
 exports.tableNameOf = require_nested_writer.tableNameOf;
-exports.translateQueryTree = translateQueryTree;
+exports.translateQueryTree = require_nested_writer.translateQueryTree;
 exports.unsupportedOperatorMessage = require_column_diff.unsupportedOperatorMessage;
 exports.vectorIndexNotFoundMessage = require_column_diff.vectorIndexNotFoundMessage;
 Object.defineProperty(exports, "walkFilter", {

package/dist/index.d.cts

@@ -1,12 +1,12 @@
-import { $ as TDbUpdateResult, $t as AtscriptRef, A as TCrudPermissions, At as TViewJsonType, B as TDbFieldMeta, Bt as ALL_BUCKET_UNITS, C as NullableOptional, Ct as TRowResolveOptions, D as TCascadeTarget, Dt as TTableResolver, E as TCascadeResolver, Et as TTableOptionDiff, F as TDbAvailableActions, Ft as UniqueryControls, G as TDbInsertManyResult, Gt as AtscriptDbView, H as TDbIndex, Ht as DbSpace, I as TDbCollation, It as WithRelation, J as TDbReferentialAction, Jt as isViewType, K as TDbInsertResult, Kt as TViewColumnMapping, L as TDbDefaultFn, Lt as TableMetadata, M as TDbActionIntent, Mt as TWriteTableResolver, N as TDbActionLevel, Nt as TypedWithRelation, O as TColumnDiff, Ot as TTouchManyOptions, P as TDbActionProcessor, Pt as Uniquery, Q as TDbStorageType, Qt as AtscriptQueryNode, R as TDbDefaultValue, Rt as isGeoIndexableType, S as NavPropsOf, St as TRelationInfo, T as PrimaryKeyOf, Tt as TSyncColumnResult, U as TDbIndexField, Ut as TAdapterFactory, V as TDbForeignKey, Vt as BaseDbAdapter, W as TDbIndexType, Wt as TDbSpaceOptions, X as TDbRemoveGuard, Xt as AtscriptQueryComparison, Y as TDbRelation, Yt as aliasTargetOf, Z as TDbRemoveGuardContext, Zt as AtscriptQueryFieldRef, _ as DbQuery, _n as UniquSelect, _t as TIdentification, a as jsonValueAncestor, an as IntegrityStrategy, at as TDeleteOptions, b as FilterExpr, bt as TPrimaryKeyChange, c as AggregateControls, cn as DbResponse, ct as TEnsureTableOptions, d as AggregateQuery, dn as TDbEncryptionOptions, dt as TExistingTableOption, en as TViewJoin, et as TDbWriteAction, f as AggregateResult, fn as DocumentFieldMapper, ft as TFieldMeta, g as DbPatch, gn as TGenericLogger, gt as TIdResolveOptions, h as DbControls, hn as NoopLogger, ht as TIdDescriptor, i as isJsonValueField, in as AtscriptDbTable, it as TDbWriteGuardContext, j as TDbActionInfo, jt as TWriteOptions, k as TCrudOp, kt as TValueFormatterPair, l as AggregateExpr, ln as resolveDesignType, lt as TExistingColumn, m as AtscriptDbWritable, mn as TReadControls, mt as TFkLookupTarget, n as TResolvedBucket, nn as isFieldRef, nt as TDbWriteCheckContext, o as normalizeComputedSelect, on as NativeIntegrity, ot as TDerivedChangeReason, pn as FieldMappingStrategy, pt as TFkLookupResolver, q as TDbObjectKind, qt as isAtscriptDbView, r as isBucketableField, rn as translateQueryTree, rt as TDbWriteGuard, s as resolveCalendarBuckets, sn as AtscriptDbReadable, st as TDerivedColumn, t as TBucketFieldSource, tn as TViewPlan, tt as TDbWriteCheck, u as AggregateFn, un as DbEncryption, ut as TExistingForeignKey, v as DbRow, vt as TMetaResponse, w as OwnPropsOf, wt as TSearchIndexInfo, x as FlatOf, xt as TReferencingForeignKey, y as FieldOpsFor, yt as TMetadataOverrides, z as TDbDeleteResult, zt as isGeoPointType } from "./buckets-DYFu0eZ8.cjs";
+import { $ as TDbStorageType, $t as AtscriptExprNode, A as TCrudPermissions, An as TDbEncryptionOptions, At as TValueFormatterPair, B as TDbDeleteResult, Bt as isGeoPointType, C as NullableOptional, Cn as andFilters, Ct as TRelationInfo, D as TCascadeTarget, Dn as isResolvedRelationFilter, Dt as TTableOptionDiff, E as TCascadeResolver, En as hasRelationOp, Et as TSyncColumnResult, F as TDbActionTargetSummary, Fn as TGenericLogger, Ft as Uniquery, G as TDbIndexType, Gt as DbSpace, H as TDbForeignKey, Ht as ALL_VIEW_CAPABILITIES, I as TDbAvailableActions, In as UniquSelect, It as UniqueryControls, J as TDbObjectKind, Jt as AtscriptDbView, K as TDbInsertManyResult, Kt as TAdapterFactory, L as TDbCollation, Lt as WithRelation, M as TDbActionIntent, Mn as FieldMappingStrategy, Mt as TWriteOptions, N as TDbActionLevel, Nn as TReadControls, Nt as TWriteTableResolver, O as TColumnDiff, On as relationStaticFilter, Ot as TTableResolver, P as TDbActionProcessor, Pn as NoopLogger, Pt as TypedWithRelation, Q as TDbRemoveGuardContext, Qt as aliasTargetOf, R as TDbDefaultFn, Rt as TableMetadata, S as NavPropsOf, Sn as TRelationStaticFilter, St as TReferencingForeignKey, T as PrimaryKeyOf, Tn as forEachResolvedRelation, Tt as TSearchIndexInfo, U as TDbIndex, Ut as BaseDbAdapter, V as TDbFieldMeta, Vt as ALL_BUCKET_UNITS, W as TDbIndexField, Wt as TViewCapability, X as TDbRelation, Xt as isAtscriptDbView, Y as TDbReferentialAction, Yt as TViewColumnMapping, Z as TDbRemoveGuard, Zt as isViewType, _ as DbQuery, _n as REL_FILTER_MAX_NODES, _t as TIdResolveOptions, a as jsonValueAncestor, an as TViewJoin, at as TDbWriteGuardContext, b as FilterExpr, bn as TRelationFilterJunction, bt as TMetadataOverrides, c as AggregateControls, cn as translateQueryTree, ct as TDerivedColumn, d as AggregateQuery, dn as NativeIntegrity, dt as TExistingForeignKey, en as AtscriptOrderItem, et as TDbUpdateResult, f as AggregateResult, fn as TCascadePin, ft as TExistingTableOption, g as DbPatch, gn as REL_FILTER_MAX_DEPTH, gt as TIdDescriptor, h as DbControls, hn as resolveDesignType, ht as TFkLookupTarget, i as isJsonValueField, in as AtscriptRef, it as TDbWriteGuard, j as TDbActionInfo, jn as DocumentFieldMapper, jt as TViewJsonType, k as TCrudOp, kn as DbEncryption, kt as TTouchManyOptions, l as AggregateExpr, ln as AtscriptDbTable, lt as TEnsureTableOptions, m as AtscriptDbWritable, mn as DbResponse, mt as TFkLookupResolver, n as TResolvedBucket, nn as AtscriptQueryFieldRef, nt as TDbWriteCheck, o as normalizeComputedSelect, on as TViewPlan, ot as TDeleteOptions, pn as AtscriptDbReadable, pt as TFieldMeta, q as TDbInsertResult, qt as TDbSpaceOptions, r as isBucketableField, rn as AtscriptQueryNode, rt as TDbWriteCheckContext, s as resolveCalendarBuckets, sn as isFieldRef, st as TDerivedChangeReason, t as TBucketFieldSource, tn as AtscriptQueryComparison, tt as TDbWriteAction, u as AggregateFn, un as IntegrityStrategy, ut as TExistingColumn, v as DbRow, vn as ResolvedRelationFilter, vt as TIdentification, w as OwnPropsOf, wn as containsRelationFilter, wt as TRowResolveOptions, x as FlatOf, xn as TRelationFilterTable, xt as TPrimaryKeyChange, y as FieldOpsFor, yn as TRelGuardState, yt as TMetaResponse, z as TDbDefaultValue, zt as isGeoIndexableType } from "./buckets-CjdPipCC.cjs";
 import { _ as separateFieldOps, a as $mul, c as $update, d as TDbFieldOp, f as TFieldOps, g as separateCas, h as reconcileCas, i as $insert, l as $upsert, m as isDbFieldOp, n as $dec, o as $remove, p as getDbFieldOp, r as $inc, s as $replace, t as $cas, u as TDbCas } from "./ops-AqhV7s9o.cjs";
 import { a as isPlainObject, i as isEmptyObject, n as findAncestorInSet, o as selfOrAncestor, r as getPath, t as deletePath } from "./object-CtPYTIvy.cjs";
 import { c as CalendarBucketLabel, d as WeekStart, g as ALL_AGGREGATE_FNS, l as ComputedExpr, o as BucketExpr, s as BucketUnit, u as ResolvedBucket } from "./agg-CV7y8nC6.cjs";
-import { a as buildValidationContext, c as isNavRelation, d as getKeyProps, f as CasExhaustedError, g as bucketTimeZoneUnavailable, h as DbErrorCode, l as TArrayPatch, m as DbError, n as ValidatorMode, p as CasMismatchError, r as buildDbValidator, s as forceNavNonOptional, t as ValidationContext, u as TDbPatch } from "./validator-Bw6ks9Hy.cjs";
+import { a as buildValidationContext, c as isNavRelation, d as getKeyProps, f as CasExhaustedError, g as bucketTimeZoneUnavailable, h as DbErrorCode, l as TArrayPatch, m as DbError, n as ValidatorMode, p as CasMismatchError, r as buildDbValidator, s as forceNavNonOptional, t as ValidationContext, u as TDbPatch } from "./validator-CMnTI6r7.cjs";
 import { n as createDbValidatorPlugin, t as DbValidationContext } from "./db-validator-plugin-BWy60OvG.cjs";
-import { n as isColumnTypeChanged } from "./column-diff-w-Mym_3w.cjs";
-import { i as tableNameOf } from "./relation-helpers-BOMm_HUI.cjs";
-import { AggregateQuery as AggregateQuery$1, FilterExpr as FilterExpr$1, FilterVisitor, ResolvedBucket as ResolvedBucket$1, Uniquery as Uniquery$1, computeInsights, isPrimitive, walkFilter } from "@uniqu/core";
+import { r as fkColumns, s as isColumnTypeChanged } from "./fk-diff-DLqwVkKG.cjs";
+import { i as tableNameOf } from "./relation-helpers-DH3LvwLV.cjs";
+import { AggregateQuery as AggregateQuery$1, FilterExpr as FilterExpr$1, FilterVisitor, RELATION_OPS, RelationOp, RelationOp as RelationOp$1, ResolvedBucket as ResolvedBucket$1, Uniquery as Uniquery$1, computeInsights, isPrimitive, isRelationOp, walkFilter } from "@uniqu/core";
 import { TAtscriptAnnotatedType } from "@atscript/typescript/utils";
 
 //#region src/shared/consts.d.ts
@@ -30,14 +30,16 @@ declare class RelationalFieldMapper extends FieldMappingStrategy {
   /** The flattened column of a logical path (`contact.email` → `contact__email`). */
   protected physicalPath(logical: string, meta: TableMetadata): string;
   /**
-   * Overrides the base `translateFilter` to use `leafByLogical` for key resolution
+   * Overrides the base `translateResolvedFilter` to use `leafByLogical` for key resolution
    * (handles flattened nested paths like `contact.email` → `contact__email`).
    */
-  translateFilter(filter: FilterExpr$1, meta: TableMetadata): FilterExpr$1;
+  protected translateResolvedFilter(filter: FilterExpr$1, meta: TableMetadata): FilterExpr$1;
   /**
    * Translates filter with key renaming from logical to physical names.
    * Used by the relational query path where field paths must be mapped
-   * to `__`-separated column names.
+   * to `__`-separated column names. Relational predicates must already be
+   * resolved (`translateFilter` / `translateQuery` do it); a resolved
+   * predicate passes through under its navigation-field key.
    */
   translateFilterWithRename(filter: FilterExpr$1, meta: TableMetadata): FilterExpr$1;
   prepareForWrite(payload: Record<string, unknown>, meta: TableMetadata, adapter: BaseDbAdapter): Record<string, unknown>;
@@ -83,8 +85,14 @@ declare class ApplicationIntegrity extends IntegrityStrategy {
    * - `restrict`: throws if any children exist
    * - `cascade`: recursively deletes child records
    * - `setNull`: sets FK fields to null
+   *
+   * When `filter` holds a relational predicate, returns the matched rows
+   * PINNED by primary key (see {@link TCascadePin}): the caller deletes those
+   * rows, never re-evaluating `filter` on data the cascade just changed (a
+   * `$some` over a cascaded child relation would otherwise stop matching and
+   * leave the parent behind). Any other filter → `undefined`.
    */
-  cascadeBeforeDelete(filter: FilterExpr$1, tableName: string, meta: TableMetadata, cascadeResolver: TCascadeResolver, translateFilter: (f: FilterExpr$1) => FilterExpr$1, adapter: BaseDbAdapter): Promise<void>;
+  cascadeBeforeDelete(filter: FilterExpr$1, tableName: string, meta: TableMetadata, cascadeResolver: TCascadeResolver, translateFilter: (f: FilterExpr$1) => FilterExpr$1, adapter: BaseDbAdapter): Promise<TCascadePin>;
   needsCascade(cascadeResolver: TCascadeResolver | undefined): boolean;
   private recordKey;
   /**
@@ -119,6 +127,9 @@ declare class ApplicationIntegrity extends IntegrityStrategy {
  *   {@link canFilterLeaf}) needs → `INVALID_QUERY` (see {@link guardPaths}).
  *   Runs after the checks above so `ENC_*` codes keep firing first for
  *   encrypted subtrees.
+ * - every filter / `$having` comparison value must be able to denote its
+ *   field's declared type (`?n='x'` on a number) → `INVALID_QUERY`, after
+ *   the path guard (see `guardFilterValues`, since 0.1.147).
  */
 /** Validates a `[lng, lat]` tuple (GeoJSON coordinate order). */
 declare function assertGeoPoint(point: unknown, path: string): asserts point is [number, number];
@@ -156,13 +167,23 @@ declare function sortFieldNames(sort: unknown): string[];
  * The operator class a filter entry needs from its field (since 0.1.132):
  * - `compare` — value comparison (bare values, `$eq`, `$gt`, `$in`, `$regex`, any mix);
  * - `geo` — a `$geoWithin` entry;
- * - `exists` — an entry whose sole operator is `$exists`.
+ * - `exists` — an entry whose sole operator is `$exists`;
+ * - `relation` — a relational predicate (`$some` / `$none` only) on a
+ *   navigation field (since 0.1.147).
  */
-type TFilterPredicate = "compare" | "geo" | "exists";
+type TFilterPredicate = "compare" | "geo" | "exists" | "relation";
 /** One filter entry, collected per occurrence: its key and the predicate class its operators need. */
 interface TFilterRef {
   path: string;
   predicate: TFilterPredicate;
+  /**
+   * `relation` entries: each operator with its operand (a filter on the
+   * related table, not walked here). @since 0.1.147
+   */
+  relation?: Array<{
+    op: RelationOp$1;
+    filter: FilterExpr$1;
+  }>;
 }
 /**
  * The reason clause for a leaf the adapter cannot filter (value comparison).
@@ -357,16 +378,20 @@ declare function guardPath(meta: TableMetadata, adapter: BaseDbAdapter, path: st
  * `bucket`), `$groupBy` fields are checked, and computed aliases (`$as` or
  * the default) are exempt in `$sort` / `$having`.
  *
+ * Then every filter comparison value must be able to denote its field's
+ * declared type (`guardFilterValues`, since 0.1.147) — after the paths, so
+ * an unknown or unfilterable field keeps its own rejection.
+ *
  * Returns the collected refs so callers can run further structural rules
  * (see {@link checkHavingKeys}) without walking the query again.
  */
-declare function guardPaths(meta: TableMetadata, adapter: BaseDbAdapter, query: TGuardedQuery | undefined, aggregate?: boolean): TQueryPathRefs | undefined;
+declare function guardPaths(meta: TableMetadata, adapter: BaseDbAdapter, query: TGuardedQuery | undefined, aggregate?: boolean, state?: TRelGuardState): TQueryPathRefs | undefined;
 /**
  * Shared read-path guard: filter + $sort encryption checks, the `$select`
  * normalizer (a calendar bucket is invalid outside a grouped query), then
  * the path guard.
  */
-declare function guardQuery(meta: TableMetadata, adapter: BaseDbAdapter, query: TGuardedQuery | undefined): void;
+declare function guardQuery(meta: TableMetadata, adapter: BaseDbAdapter, query: TGuardedQuery | undefined, state?: TRelGuardState): void;
 /**
  * `$having` is a post-aggregation filter, so a key is either a computed
  * alias (aggregate or calendar bucket — already exempt in
@@ -387,7 +412,7 @@ declare function checkHavingKeys(refs: TQueryPathRefs): {
  * (`AGG_FN_NOT_SUPPORTED`) and calendar-bucket units
  * (`BUCKET_NOT_SUPPORTED`), then the `$having` key rule
  * ({@link checkHavingKeys} — after the path guard so an unknown key still
- * reads `Unknown field`).
+ * reads `Unknown field`), then the `$having` values (`guardHavingValues`).
  *
  * `buckets` are the query's resolved calendar buckets when the caller already
  * ran `normalizeComputedSelect` (resolved here otherwise).
@@ -531,4 +556,4 @@ declare function createFailureCollector(what: string): {
   throwIfAny: () => void;
 };
 //#endregion
-export { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, ADAPTER_FILTER_REASON, ALL_AGGREGATE_FNS, ALL_BUCKET_UNITS, type AggregateControls, type AggregateExpr, type AggregateFn, type AggregateQuery, type AggregateResult, ApplicationIntegrity, AtscriptDbReadable, AtscriptDbTable, AtscriptDbView, type AtscriptDbWritable, type AtscriptQueryComparison, type AtscriptQueryFieldRef, type AtscriptQueryNode, type AtscriptRef, BaseDbAdapter, type BucketExpr, type BucketUnit, type CalendarBucketLabel, CasExhaustedError, CasMismatchError, type ComputedExpr, DEFAULT_DB_SPACE, type DbControls, DbEncryption, DbError, type DbErrorCode, type DbPatch, type DbQuery, type DbResponse, type DbRow, DbSpace, type DbValidationContext, DocumentFieldMapper, ENCRYPTED_REASON, FieldMappingStrategy, type FieldOpsFor, type FilterExpr, type FilterVisitor, type FlatOf, IntegrityStrategy, NativeIntegrity, type NavPropsOf, NoopLogger, type NullableOptional, type OwnPropsOf, type PrimaryKeyOf, RelationalFieldMapper, type ResolvedBucket, type TAdapterFactory, type TArrayPatch, type TBucketFieldSource, type TBucketSourceTable, type TBucketSourceVerdict, type TCascadeResolver, type TCascadeTarget, type TColumnDiff, type TCrudOp, type TCrudPermissions, type TDbActionInfo, type TDbActionIntent, type TDbActionLevel, type TDbActionProcessor, type TDbAvailableActions, type TDbCas, type TDbCollation, type TDbDefaultFn, type TDbDefaultValue, type TDbDeleteResult, type TDbEncryptionOptions, type TDbFieldMeta, type TDbFieldOp, type TDbForeignKey, type TDbIndex, type TDbIndexField, type TDbIndexType, type TDbInsertManyResult, type TDbInsertResult, type TDbObjectKind, type TDbPatch, type TDbReferentialAction, type TDbRelation, type TDbRemoveGuard, type TDbRemoveGuardContext, type TDbSpaceOptions, type TDbStorageType, type TDbUpdateResult, type TDbWriteAction, type TDbWriteCheck, type TDbWriteCheckContext, type TDbWriteGuard, type TDbWriteGuardContext, type TDeleteOptions, type TDerivedChangeReason, type TDerivedColumn, type TEnsureTableOptions, type TExistingColumn, type TExistingForeignKey, type TExistingTableOption, type TFieldMeta, type TFieldOps, type TFilterPredicate, type TFilterRef, type TFkLookupResolver, type TFkLookupTarget, type TGenericLogger, type TGuardedQuery, type TIdDescriptor, type TIdResolveOptions, type TIdentification, type TMetaResponse, type TMetadataOverrides, type TPrimaryKeyChange, type TQueryPathKind, type TQueryPathOp, type TQueryPathRefs, type TQueryPathSource, type TReadControls, type TReferencingForeignKey, type TRelationInfo, type TResolvedBucket, type TRowResolveOptions, type TSearchIndexInfo, type TSyncColumnResult, type TTableOptionDiff, type TTableResolver, type TTouchManyOptions, type TValueFormatterPair, type TViewColumnMapping, type TViewJoin, type TViewJsonType, type TViewPlan, type TWriteOptions, type TWriteTableResolver, TableMetadata, type TypedWithRelation, UniquSelect, type Uniquery, type UniqueryControls, type ValidationContext, type ValidatorMode, type WeekStart, type WithOptimisticRetryOptions, type WithRelation, acceptedOperatorsHint, aliasTargetOf, assertGeoPoint, assertNoVersionWrites, bucketSourceVerdict, bucketTimeZoneUnavailable, buildDbValidator, buildValidationContext, canFilterLeaf, checkHavingKeys, classifyQueryPath, collectQueryPaths, computeInsights, createDbValidatorPlugin, createFailureCollector, decomposePatch, deletePath, findAncestorInSet, forceNavNonOptional, geoIndexNotFoundMessage, getDbFieldOp, getKeyProps, getPath, guardAggregate, guardFilter, guardPath, guardPaths, guardQuery, isAtscriptDbView, isBucketableField, isColumnTypeChanged, isDbEntityType, isDbFieldOp, isEmptyObject, isFieldRef, isGeoIndexableType, isGeoPointType, isJsonValueField, isNavRelation, isPlainObject, isPrimitive, isViewType, jsonValueAncestor, narrowerFilterOps, normalizeComputedSelect, reconcileCas, resolveCalendarBuckets, resolveDesignType, searchIndexNotFoundMessage, selfOrAncestor, separateCas, separateFieldOps, sortFieldNames, tableNameOf, translateQueryTree, unsupportedOperatorMessage, vectorIndexNotFoundMessage, walkFilter, withOptimisticRetry };
+export { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, ADAPTER_FILTER_REASON, ALL_AGGREGATE_FNS, ALL_BUCKET_UNITS, ALL_VIEW_CAPABILITIES, type AggregateControls, type AggregateExpr, type AggregateFn, type AggregateQuery, type AggregateResult, ApplicationIntegrity, AtscriptDbReadable, AtscriptDbTable, AtscriptDbView, type AtscriptDbWritable, type AtscriptExprNode, type AtscriptOrderItem, type AtscriptQueryComparison, type AtscriptQueryFieldRef, type AtscriptQueryNode, type AtscriptRef, BaseDbAdapter, type BucketExpr, type BucketUnit, type CalendarBucketLabel, CasExhaustedError, CasMismatchError, type ComputedExpr, DEFAULT_DB_SPACE, type DbControls, DbEncryption, DbError, type DbErrorCode, type DbPatch, type DbQuery, type DbResponse, type DbRow, DbSpace, type DbValidationContext, DocumentFieldMapper, ENCRYPTED_REASON, FieldMappingStrategy, type FieldOpsFor, type FilterExpr, type FilterVisitor, type FlatOf, IntegrityStrategy, NativeIntegrity, type NavPropsOf, NoopLogger, type NullableOptional, type OwnPropsOf, type PrimaryKeyOf, RELATION_OPS, REL_FILTER_MAX_DEPTH, REL_FILTER_MAX_NODES, type RelationOp, RelationalFieldMapper, type ResolvedBucket, ResolvedRelationFilter, type TAdapterFactory, type TArrayPatch, type TBucketFieldSource, type TBucketSourceTable, type TBucketSourceVerdict, type TCascadeResolver, type TCascadeTarget, type TColumnDiff, type TCrudOp, type TCrudPermissions, type TDbActionInfo, type TDbActionIntent, type TDbActionLevel, type TDbActionProcessor, type TDbActionTargetSummary, type TDbAvailableActions, type TDbCas, type TDbCollation, type TDbDefaultFn, type TDbDefaultValue, type TDbDeleteResult, type TDbEncryptionOptions, type TDbFieldMeta, type TDbFieldOp, type TDbForeignKey, type TDbIndex, type TDbIndexField, type TDbIndexType, type TDbInsertManyResult, type TDbInsertResult, type TDbObjectKind, type TDbPatch, type TDbReferentialAction, type TDbRelation, type TDbRemoveGuard, type TDbRemoveGuardContext, type TDbSpaceOptions, type TDbStorageType, type TDbUpdateResult, type TDbWriteAction, type TDbWriteCheck, type TDbWriteCheckContext, type TDbWriteGuard, type TDbWriteGuardContext, type TDeleteOptions, type TDerivedChangeReason, type TDerivedColumn, type TEnsureTableOptions, type TExistingColumn, type TExistingForeignKey, type TExistingTableOption, type TFieldMeta, type TFieldOps, type TFilterPredicate, type TFilterRef, type TFkLookupResolver, type TFkLookupTarget, type TGenericLogger, type TGuardedQuery, type TIdDescriptor, type TIdResolveOptions, type TIdentification, type TMetaResponse, type TMetadataOverrides, type TPrimaryKeyChange, type TQueryPathKind, type TQueryPathOp, type TQueryPathRefs, type TQueryPathSource, type TReadControls, type TReferencingForeignKey, type TRelationFilterJunction, type TRelationFilterTable, type TRelationInfo, type TRelationStaticFilter, type TResolvedBucket, type TRowResolveOptions, type TSearchIndexInfo, type TSyncColumnResult, type TTableOptionDiff, type TTableResolver, type TTouchManyOptions, type TValueFormatterPair, type TViewCapability, type TViewColumnMapping, type TViewJoin, type TViewJsonType, type TViewPlan, type TWriteOptions, type TWriteTableResolver, TableMetadata, type TypedWithRelation, UniquSelect, type Uniquery, type UniqueryControls, type ValidationContext, type ValidatorMode, type WeekStart, type WithOptimisticRetryOptions, type WithRelation, acceptedOperatorsHint, aliasTargetOf, andFilters, assertGeoPoint, assertNoVersionWrites, bucketSourceVerdict, bucketTimeZoneUnavailable, buildDbValidator, buildValidationContext, canFilterLeaf, checkHavingKeys, classifyQueryPath, collectQueryPaths, computeInsights, containsRelationFilter, createDbValidatorPlugin, createFailureCollector, decomposePatch, deletePath, findAncestorInSet, fkColumns, forEachResolvedRelation, forceNavNonOptional, geoIndexNotFoundMessage, getDbFieldOp, getKeyProps, getPath, guardAggregate, guardFilter, guardPath, guardPaths, guardQuery, hasRelationOp, isAtscriptDbView, isBucketableField, isColumnTypeChanged, isDbEntityType, isDbFieldOp, isEmptyObject, isFieldRef, isGeoIndexableType, isGeoPointType, isJsonValueField, isNavRelation, isPlainObject, isPrimitive, isRelationOp, isResolvedRelationFilter, isViewType, jsonValueAncestor, narrowerFilterOps, normalizeComputedSelect, reconcileCas, relationStaticFilter, resolveCalendarBuckets, resolveDesignType, searchIndexNotFoundMessage, selfOrAncestor, separateCas, separateFieldOps, sortFieldNames, tableNameOf, translateQueryTree, unsupportedOperatorMessage, vectorIndexNotFoundMessage, walkFilter, withOptimisticRetry };

package/dist/index.d.mts

@@ -1,13 +1,13 @@
-import { $ as TDbUpdateResult, $t as AtscriptRef, A as TCrudPermissions, At as TViewJsonType, B as TDbFieldMeta, Bt as ALL_BUCKET_UNITS, C as NullableOptional, Ct as TRowResolveOptions, D as TCascadeTarget, Dt as TTableResolver, E as TCascadeResolver, Et as TTableOptionDiff, F as TDbAvailableActions, Ft as UniqueryControls, G as TDbInsertManyResult, Gt as AtscriptDbView, H as TDbIndex, Ht as DbSpace, I as TDbCollation, It as WithRelation, J as TDbReferentialAction, Jt as isViewType, K as TDbInsertResult, Kt as TViewColumnMapping, L as TDbDefaultFn, Lt as TableMetadata, M as TDbActionIntent, Mt as TWriteTableResolver, N as TDbActionLevel, Nt as TypedWithRelation, O as TColumnDiff, Ot as TTouchManyOptions, P as TDbActionProcessor, Pt as Uniquery, Q as TDbStorageType, Qt as AtscriptQueryNode, R as TDbDefaultValue, Rt as isGeoIndexableType, S as NavPropsOf, St as TRelationInfo, T as PrimaryKeyOf, Tt as TSyncColumnResult, U as TDbIndexField, Ut as TAdapterFactory, V as TDbForeignKey, Vt as BaseDbAdapter, W as TDbIndexType, Wt as TDbSpaceOptions, X as TDbRemoveGuard, Xt as AtscriptQueryComparison, Y as TDbRelation, Yt as aliasTargetOf, Z as TDbRemoveGuardContext, Zt as AtscriptQueryFieldRef, _ as DbQuery, _n as UniquSelect, _t as TIdentification, a as jsonValueAncestor, an as IntegrityStrategy, at as TDeleteOptions, b as FilterExpr, bt as TPrimaryKeyChange, c as AggregateControls, cn as DbResponse, ct as TEnsureTableOptions, d as AggregateQuery, dn as TDbEncryptionOptions, dt as TExistingTableOption, en as TViewJoin, et as TDbWriteAction, f as AggregateResult, fn as DocumentFieldMapper, ft as TFieldMeta, g as DbPatch, gn as TGenericLogger, gt as TIdResolveOptions, h as DbControls, hn as NoopLogger, ht as TIdDescriptor, i as isJsonValueField, in as AtscriptDbTable, it as TDbWriteGuardContext, j as TDbActionInfo, jt as TWriteOptions, k as TCrudOp, kt as TValueFormatterPair, l as AggregateExpr, ln as resolveDesignType, lt as TExistingColumn, m as AtscriptDbWritable, mn as TReadControls, mt as TFkLookupTarget, n as TResolvedBucket, nn as isFieldRef, nt as TDbWriteCheckContext, o as normalizeComputedSelect, on as NativeIntegrity, ot as TDerivedChangeReason, pn as FieldMappingStrategy, pt as TFkLookupResolver, q as TDbObjectKind, qt as isAtscriptDbView, r as isBucketableField, rn as translateQueryTree, rt as TDbWriteGuard, s as resolveCalendarBuckets, sn as AtscriptDbReadable, st as TDerivedColumn, t as TBucketFieldSource, tn as TViewPlan, tt as TDbWriteCheck, u as AggregateFn, un as DbEncryption, ut as TExistingForeignKey, v as DbRow, vt as TMetaResponse, w as OwnPropsOf, wt as TSearchIndexInfo, x as FlatOf, xt as TReferencingForeignKey, y as FieldOpsFor, yt as TMetadataOverrides, z as TDbDeleteResult, zt as isGeoPointType } from "./buckets-DRycmhOW.mjs";
+import { $ as TDbStorageType, $t as AtscriptExprNode, A as TCrudPermissions, An as TDbEncryptionOptions, At as TValueFormatterPair, B as TDbDeleteResult, Bt as isGeoPointType, C as NullableOptional, Cn as andFilters, Ct as TRelationInfo, D as TCascadeTarget, Dn as isResolvedRelationFilter, Dt as TTableOptionDiff, E as TCascadeResolver, En as hasRelationOp, Et as TSyncColumnResult, F as TDbActionTargetSummary, Fn as TGenericLogger, Ft as Uniquery, G as TDbIndexType, Gt as DbSpace, H as TDbForeignKey, Ht as ALL_VIEW_CAPABILITIES, I as TDbAvailableActions, In as UniquSelect, It as UniqueryControls, J as TDbObjectKind, Jt as AtscriptDbView, K as TDbInsertManyResult, Kt as TAdapterFactory, L as TDbCollation, Lt as WithRelation, M as TDbActionIntent, Mn as FieldMappingStrategy, Mt as TWriteOptions, N as TDbActionLevel, Nn as TReadControls, Nt as TWriteTableResolver, O as TColumnDiff, On as relationStaticFilter, Ot as TTableResolver, P as TDbActionProcessor, Pn as NoopLogger, Pt as TypedWithRelation, Q as TDbRemoveGuardContext, Qt as aliasTargetOf, R as TDbDefaultFn, Rt as TableMetadata, S as NavPropsOf, Sn as TRelationStaticFilter, St as TReferencingForeignKey, T as PrimaryKeyOf, Tn as forEachResolvedRelation, Tt as TSearchIndexInfo, U as TDbIndex, Ut as BaseDbAdapter, V as TDbFieldMeta, Vt as ALL_BUCKET_UNITS, W as TDbIndexField, Wt as TViewCapability, X as TDbRelation, Xt as isAtscriptDbView, Y as TDbReferentialAction, Yt as TViewColumnMapping, Z as TDbRemoveGuard, Zt as isViewType, _ as DbQuery, _n as REL_FILTER_MAX_NODES, _t as TIdResolveOptions, a as jsonValueAncestor, an as TViewJoin, at as TDbWriteGuardContext, b as FilterExpr, bn as TRelationFilterJunction, bt as TMetadataOverrides, c as AggregateControls, cn as translateQueryTree, ct as TDerivedColumn, d as AggregateQuery, dn as NativeIntegrity, dt as TExistingForeignKey, en as AtscriptOrderItem, et as TDbUpdateResult, f as AggregateResult, fn as TCascadePin, ft as TExistingTableOption, g as DbPatch, gn as REL_FILTER_MAX_DEPTH, gt as TIdDescriptor, h as DbControls, hn as resolveDesignType, ht as TFkLookupTarget, i as isJsonValueField, in as AtscriptRef, it as TDbWriteGuard, j as TDbActionInfo, jn as DocumentFieldMapper, jt as TViewJsonType, k as TCrudOp, kn as DbEncryption, kt as TTouchManyOptions, l as AggregateExpr, ln as AtscriptDbTable, lt as TEnsureTableOptions, m as AtscriptDbWritable, mn as DbResponse, mt as TFkLookupResolver, n as TResolvedBucket, nn as AtscriptQueryFieldRef, nt as TDbWriteCheck, o as normalizeComputedSelect, on as TViewPlan, ot as TDeleteOptions, pn as AtscriptDbReadable, pt as TFieldMeta, q as TDbInsertResult, qt as TDbSpaceOptions, r as isBucketableField, rn as AtscriptQueryNode, rt as TDbWriteCheckContext, s as resolveCalendarBuckets, sn as isFieldRef, st as TDerivedChangeReason, t as TBucketFieldSource, tn as AtscriptQueryComparison, tt as TDbWriteAction, u as AggregateFn, un as IntegrityStrategy, ut as TExistingColumn, v as DbRow, vn as ResolvedRelationFilter, vt as TIdentification, w as OwnPropsOf, wn as containsRelationFilter, wt as TRowResolveOptions, x as FlatOf, xn as TRelationFilterTable, xt as TPrimaryKeyChange, y as FieldOpsFor, yn as TRelGuardState, yt as TMetaResponse, z as TDbDefaultValue, zt as isGeoIndexableType } from "./buckets-DYopfd2Y.mjs";
 import { _ as separateFieldOps, a as $mul, c as $update, d as TDbFieldOp, f as TFieldOps, g as separateCas, h as reconcileCas, i as $insert, l as $upsert, m as isDbFieldOp, n as $dec, o as $remove, p as getDbFieldOp, r as $inc, s as $replace, t as $cas, u as TDbCas } from "./ops-AqhV7s9o.mjs";
 import { a as isPlainObject, i as isEmptyObject, n as findAncestorInSet, o as selfOrAncestor, r as getPath, t as deletePath } from "./object-CtPYTIvy.mjs";
 import { c as CalendarBucketLabel, d as WeekStart, g as ALL_AGGREGATE_FNS, l as ComputedExpr, o as BucketExpr, s as BucketUnit, u as ResolvedBucket } from "./agg-D5DHsAby.mjs";
-import { a as buildValidationContext, c as isNavRelation, d as getKeyProps, f as CasExhaustedError, g as bucketTimeZoneUnavailable, h as DbErrorCode, l as TArrayPatch, m as DbError, n as ValidatorMode, p as CasMismatchError, r as buildDbValidator, s as forceNavNonOptional, t as ValidationContext, u as TDbPatch } from "./validator-Bw6ks9Hy.mjs";
+import { a as buildValidationContext, c as isNavRelation, d as getKeyProps, f as CasExhaustedError, g as bucketTimeZoneUnavailable, h as DbErrorCode, l as TArrayPatch, m as DbError, n as ValidatorMode, p as CasMismatchError, r as buildDbValidator, s as forceNavNonOptional, t as ValidationContext, u as TDbPatch } from "./validator-CMnTI6r7.mjs";
 import { n as createDbValidatorPlugin, t as DbValidationContext } from "./db-validator-plugin-BWy60OvG.mjs";
-import { n as isColumnTypeChanged } from "./column-diff-Q9UmWn5x.mjs";
-import { i as tableNameOf } from "./relation-helpers-B-0NRKat.mjs";
+import { r as fkColumns, s as isColumnTypeChanged } from "./fk-diff-BtOmL4OW.mjs";
+import { i as tableNameOf } from "./relation-helpers-C2bLtE-t.mjs";
 import { TAtscriptAnnotatedType } from "@atscript/typescript/utils";
-import { AggregateQuery as AggregateQuery$1, FilterExpr as FilterExpr$1, FilterVisitor, ResolvedBucket as ResolvedBucket$1, Uniquery as Uniquery$1, computeInsights, isPrimitive, walkFilter } from "@uniqu/core";
+import { AggregateQuery as AggregateQuery$1, FilterExpr as FilterExpr$1, FilterVisitor, RELATION_OPS, RelationOp, RelationOp as RelationOp$1, ResolvedBucket as ResolvedBucket$1, Uniquery as Uniquery$1, computeInsights, isPrimitive, isRelationOp, walkFilter } from "@uniqu/core";
 
 //#region src/shared/consts.d.ts
 /**
@@ -30,14 +30,16 @@ declare class RelationalFieldMapper extends FieldMappingStrategy {
   /** The flattened column of a logical path (`contact.email` → `contact__email`). */
   protected physicalPath(logical: string, meta: TableMetadata): string;
   /**
-   * Overrides the base `translateFilter` to use `leafByLogical` for key resolution
+   * Overrides the base `translateResolvedFilter` to use `leafByLogical` for key resolution
    * (handles flattened nested paths like `contact.email` → `contact__email`).
    */
-  translateFilter(filter: FilterExpr$1, meta: TableMetadata): FilterExpr$1;
+  protected translateResolvedFilter(filter: FilterExpr$1, meta: TableMetadata): FilterExpr$1;
   /**
    * Translates filter with key renaming from logical to physical names.
    * Used by the relational query path where field paths must be mapped
-   * to `__`-separated column names.
+   * to `__`-separated column names. Relational predicates must already be
+   * resolved (`translateFilter` / `translateQuery` do it); a resolved
+   * predicate passes through under its navigation-field key.
    */
   translateFilterWithRename(filter: FilterExpr$1, meta: TableMetadata): FilterExpr$1;
   prepareForWrite(payload: Record<string, unknown>, meta: TableMetadata, adapter: BaseDbAdapter): Record<string, unknown>;
@@ -83,8 +85,14 @@ declare class ApplicationIntegrity extends IntegrityStrategy {
    * - `restrict`: throws if any children exist
    * - `cascade`: recursively deletes child records
    * - `setNull`: sets FK fields to null
+   *
+   * When `filter` holds a relational predicate, returns the matched rows
+   * PINNED by primary key (see {@link TCascadePin}): the caller deletes those
+   * rows, never re-evaluating `filter` on data the cascade just changed (a
+   * `$some` over a cascaded child relation would otherwise stop matching and
+   * leave the parent behind). Any other filter → `undefined`.
    */
-  cascadeBeforeDelete(filter: FilterExpr$1, tableName: string, meta: TableMetadata, cascadeResolver: TCascadeResolver, translateFilter: (f: FilterExpr$1) => FilterExpr$1, adapter: BaseDbAdapter): Promise<void>;
+  cascadeBeforeDelete(filter: FilterExpr$1, tableName: string, meta: TableMetadata, cascadeResolver: TCascadeResolver, translateFilter: (f: FilterExpr$1) => FilterExpr$1, adapter: BaseDbAdapter): Promise<TCascadePin>;
   needsCascade(cascadeResolver: TCascadeResolver | undefined): boolean;
   private recordKey;
   /**
@@ -119,6 +127,9 @@ declare class ApplicationIntegrity extends IntegrityStrategy {
  *   {@link canFilterLeaf}) needs → `INVALID_QUERY` (see {@link guardPaths}).
  *   Runs after the checks above so `ENC_*` codes keep firing first for
  *   encrypted subtrees.
+ * - every filter / `$having` comparison value must be able to denote its
+ *   field's declared type (`?n='x'` on a number) → `INVALID_QUERY`, after
+ *   the path guard (see `guardFilterValues`, since 0.1.147).
  */
 /** Validates a `[lng, lat]` tuple (GeoJSON coordinate order). */
 declare function assertGeoPoint(point: unknown, path: string): asserts point is [number, number];
@@ -156,13 +167,23 @@ declare function sortFieldNames(sort: unknown): string[];
  * The operator class a filter entry needs from its field (since 0.1.132):
  * - `compare` — value comparison (bare values, `$eq`, `$gt`, `$in`, `$regex`, any mix);
  * - `geo` — a `$geoWithin` entry;
- * - `exists` — an entry whose sole operator is `$exists`.
+ * - `exists` — an entry whose sole operator is `$exists`;
+ * - `relation` — a relational predicate (`$some` / `$none` only) on a
+ *   navigation field (since 0.1.147).
  */
-type TFilterPredicate = "compare" | "geo" | "exists";
+type TFilterPredicate = "compare" | "geo" | "exists" | "relation";
 /** One filter entry, collected per occurrence: its key and the predicate class its operators need. */
 interface TFilterRef {
   path: string;
   predicate: TFilterPredicate;
+  /**
+   * `relation` entries: each operator with its operand (a filter on the
+   * related table, not walked here). @since 0.1.147
+   */
+  relation?: Array<{
+    op: RelationOp$1;
+    filter: FilterExpr$1;
+  }>;
 }
 /**
  * The reason clause for a leaf the adapter cannot filter (value comparison).
@@ -357,16 +378,20 @@ declare function guardPath(meta: TableMetadata, adapter: BaseDbAdapter, path: st
  * `bucket`), `$groupBy` fields are checked, and computed aliases (`$as` or
  * the default) are exempt in `$sort` / `$having`.
  *
+ * Then every filter comparison value must be able to denote its field's
+ * declared type (`guardFilterValues`, since 0.1.147) — after the paths, so
+ * an unknown or unfilterable field keeps its own rejection.
+ *
  * Returns the collected refs so callers can run further structural rules
  * (see {@link checkHavingKeys}) without walking the query again.
  */
-declare function guardPaths(meta: TableMetadata, adapter: BaseDbAdapter, query: TGuardedQuery | undefined, aggregate?: boolean): TQueryPathRefs | undefined;
+declare function guardPaths(meta: TableMetadata, adapter: BaseDbAdapter, query: TGuardedQuery | undefined, aggregate?: boolean, state?: TRelGuardState): TQueryPathRefs | undefined;
 /**
  * Shared read-path guard: filter + $sort encryption checks, the `$select`
  * normalizer (a calendar bucket is invalid outside a grouped query), then
  * the path guard.
  */
-declare function guardQuery(meta: TableMetadata, adapter: BaseDbAdapter, query: TGuardedQuery | undefined): void;
+declare function guardQuery(meta: TableMetadata, adapter: BaseDbAdapter, query: TGuardedQuery | undefined, state?: TRelGuardState): void;
 /**
  * `$having` is a post-aggregation filter, so a key is either a computed
  * alias (aggregate or calendar bucket — already exempt in
@@ -387,7 +412,7 @@ declare function checkHavingKeys(refs: TQueryPathRefs): {
  * (`AGG_FN_NOT_SUPPORTED`) and calendar-bucket units
  * (`BUCKET_NOT_SUPPORTED`), then the `$having` key rule
  * ({@link checkHavingKeys} — after the path guard so an unknown key still
- * reads `Unknown field`).
+ * reads `Unknown field`), then the `$having` values (`guardHavingValues`).
  *
  * `buckets` are the query's resolved calendar buckets when the caller already
  * ran `normalizeComputedSelect` (resolved here otherwise).
@@ -531,4 +556,4 @@ declare function createFailureCollector(what: string): {
   throwIfAny: () => void;
 };
 //#endregion
-export { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, ADAPTER_FILTER_REASON, ALL_AGGREGATE_FNS, ALL_BUCKET_UNITS, type AggregateControls, type AggregateExpr, type AggregateFn, type AggregateQuery, type AggregateResult, ApplicationIntegrity, AtscriptDbReadable, AtscriptDbTable, AtscriptDbView, type AtscriptDbWritable, type AtscriptQueryComparison, type AtscriptQueryFieldRef, type AtscriptQueryNode, type AtscriptRef, BaseDbAdapter, type BucketExpr, type BucketUnit, type CalendarBucketLabel, CasExhaustedError, CasMismatchError, type ComputedExpr, DEFAULT_DB_SPACE, type DbControls, DbEncryption, DbError, type DbErrorCode, type DbPatch, type DbQuery, type DbResponse, type DbRow, DbSpace, type DbValidationContext, DocumentFieldMapper, ENCRYPTED_REASON, FieldMappingStrategy, type FieldOpsFor, type FilterExpr, type FilterVisitor, type FlatOf, IntegrityStrategy, NativeIntegrity, type NavPropsOf, NoopLogger, type NullableOptional, type OwnPropsOf, type PrimaryKeyOf, RelationalFieldMapper, type ResolvedBucket, type TAdapterFactory, type TArrayPatch, type TBucketFieldSource, type TBucketSourceTable, type TBucketSourceVerdict, type TCascadeResolver, type TCascadeTarget, type TColumnDiff, type TCrudOp, type TCrudPermissions, type TDbActionInfo, type TDbActionIntent, type TDbActionLevel, type TDbActionProcessor, type TDbAvailableActions, type TDbCas, type TDbCollation, type TDbDefaultFn, type TDbDefaultValue, type TDbDeleteResult, type TDbEncryptionOptions, type TDbFieldMeta, type TDbFieldOp, type TDbForeignKey, type TDbIndex, type TDbIndexField, type TDbIndexType, type TDbInsertManyResult, type TDbInsertResult, type TDbObjectKind, type TDbPatch, type TDbReferentialAction, type TDbRelation, type TDbRemoveGuard, type TDbRemoveGuardContext, type TDbSpaceOptions, type TDbStorageType, type TDbUpdateResult, type TDbWriteAction, type TDbWriteCheck, type TDbWriteCheckContext, type TDbWriteGuard, type TDbWriteGuardContext, type TDeleteOptions, type TDerivedChangeReason, type TDerivedColumn, type TEnsureTableOptions, type TExistingColumn, type TExistingForeignKey, type TExistingTableOption, type TFieldMeta, type TFieldOps, type TFilterPredicate, type TFilterRef, type TFkLookupResolver, type TFkLookupTarget, type TGenericLogger, type TGuardedQuery, type TIdDescriptor, type TIdResolveOptions, type TIdentification, type TMetaResponse, type TMetadataOverrides, type TPrimaryKeyChange, type TQueryPathKind, type TQueryPathOp, type TQueryPathRefs, type TQueryPathSource, type TReadControls, type TReferencingForeignKey, type TRelationInfo, type TResolvedBucket, type TRowResolveOptions, type TSearchIndexInfo, type TSyncColumnResult, type TTableOptionDiff, type TTableResolver, type TTouchManyOptions, type TValueFormatterPair, type TViewColumnMapping, type TViewJoin, type TViewJsonType, type TViewPlan, type TWriteOptions, type TWriteTableResolver, TableMetadata, type TypedWithRelation, UniquSelect, type Uniquery, type UniqueryControls, type ValidationContext, type ValidatorMode, type WeekStart, type WithOptimisticRetryOptions, type WithRelation, acceptedOperatorsHint, aliasTargetOf, assertGeoPoint, assertNoVersionWrites, bucketSourceVerdict, bucketTimeZoneUnavailable, buildDbValidator, buildValidationContext, canFilterLeaf, checkHavingKeys, classifyQueryPath, collectQueryPaths, computeInsights, createDbValidatorPlugin, createFailureCollector, decomposePatch, deletePath, findAncestorInSet, forceNavNonOptional, geoIndexNotFoundMessage, getDbFieldOp, getKeyProps, getPath, guardAggregate, guardFilter, guardPath, guardPaths, guardQuery, isAtscriptDbView, isBucketableField, isColumnTypeChanged, isDbEntityType, isDbFieldOp, isEmptyObject, isFieldRef, isGeoIndexableType, isGeoPointType, isJsonValueField, isNavRelation, isPlainObject, isPrimitive, isViewType, jsonValueAncestor, narrowerFilterOps, normalizeComputedSelect, reconcileCas, resolveCalendarBuckets, resolveDesignType, searchIndexNotFoundMessage, selfOrAncestor, separateCas, separateFieldOps, sortFieldNames, tableNameOf, translateQueryTree, unsupportedOperatorMessage, vectorIndexNotFoundMessage, walkFilter, withOptimisticRetry };
+export { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, ADAPTER_FILTER_REASON, ALL_AGGREGATE_FNS, ALL_BUCKET_UNITS, ALL_VIEW_CAPABILITIES, type AggregateControls, type AggregateExpr, type AggregateFn, type AggregateQuery, type AggregateResult, ApplicationIntegrity, AtscriptDbReadable, AtscriptDbTable, AtscriptDbView, type AtscriptDbWritable, type AtscriptExprNode, type AtscriptOrderItem, type AtscriptQueryComparison, type AtscriptQueryFieldRef, type AtscriptQueryNode, type AtscriptRef, BaseDbAdapter, type BucketExpr, type BucketUnit, type CalendarBucketLabel, CasExhaustedError, CasMismatchError, type ComputedExpr, DEFAULT_DB_SPACE, type DbControls, DbEncryption, DbError, type DbErrorCode, type DbPatch, type DbQuery, type DbResponse, type DbRow, DbSpace, type DbValidationContext, DocumentFieldMapper, ENCRYPTED_REASON, FieldMappingStrategy, type FieldOpsFor, type FilterExpr, type FilterVisitor, type FlatOf, IntegrityStrategy, NativeIntegrity, type NavPropsOf, NoopLogger, type NullableOptional, type OwnPropsOf, type PrimaryKeyOf, RELATION_OPS, REL_FILTER_MAX_DEPTH, REL_FILTER_MAX_NODES, type RelationOp, RelationalFieldMapper, type ResolvedBucket, ResolvedRelationFilter, type TAdapterFactory, type TArrayPatch, type TBucketFieldSource, type TBucketSourceTable, type TBucketSourceVerdict, type TCascadeResolver, type TCascadeTarget, type TColumnDiff, type TCrudOp, type TCrudPermissions, type TDbActionInfo, type TDbActionIntent, type TDbActionLevel, type TDbActionProcessor, type TDbActionTargetSummary, type TDbAvailableActions, type TDbCas, type TDbCollation, type TDbDefaultFn, type TDbDefaultValue, type TDbDeleteResult, type TDbEncryptionOptions, type TDbFieldMeta, type TDbFieldOp, type TDbForeignKey, type TDbIndex, type TDbIndexField, type TDbIndexType, type TDbInsertManyResult, type TDbInsertResult, type TDbObjectKind, type TDbPatch, type TDbReferentialAction, type TDbRelation, type TDbRemoveGuard, type TDbRemoveGuardContext, type TDbSpaceOptions, type TDbStorageType, type TDbUpdateResult, type TDbWriteAction, type TDbWriteCheck, type TDbWriteCheckContext, type TDbWriteGuard, type TDbWriteGuardContext, type TDeleteOptions, type TDerivedChangeReason, type TDerivedColumn, type TEnsureTableOptions, type TExistingColumn, type TExistingForeignKey, type TExistingTableOption, type TFieldMeta, type TFieldOps, type TFilterPredicate, type TFilterRef, type TFkLookupResolver, type TFkLookupTarget, type TGenericLogger, type TGuardedQuery, type TIdDescriptor, type TIdResolveOptions, type TIdentification, type TMetaResponse, type TMetadataOverrides, type TPrimaryKeyChange, type TQueryPathKind, type TQueryPathOp, type TQueryPathRefs, type TQueryPathSource, type TReadControls, type TReferencingForeignKey, type TRelationFilterJunction, type TRelationFilterTable, type TRelationInfo, type TRelationStaticFilter, type TResolvedBucket, type TRowResolveOptions, type TSearchIndexInfo, type TSyncColumnResult, type TTableOptionDiff, type TTableResolver, type TTouchManyOptions, type TValueFormatterPair, type TViewCapability, type TViewColumnMapping, type TViewJoin, type TViewJsonType, type TViewPlan, type TWriteOptions, type TWriteTableResolver, TableMetadata, type TypedWithRelation, UniquSelect, type Uniquery, type UniqueryControls, type ValidationContext, type ValidatorMode, type WeekStart, type WithOptimisticRetryOptions, type WithRelation, acceptedOperatorsHint, aliasTargetOf, andFilters, assertGeoPoint, assertNoVersionWrites, bucketSourceVerdict, bucketTimeZoneUnavailable, buildDbValidator, buildValidationContext, canFilterLeaf, checkHavingKeys, classifyQueryPath, collectQueryPaths, computeInsights, containsRelationFilter, createDbValidatorPlugin, createFailureCollector, decomposePatch, deletePath, findAncestorInSet, fkColumns, forEachResolvedRelation, forceNavNonOptional, geoIndexNotFoundMessage, getDbFieldOp, getKeyProps, getPath, guardAggregate, guardFilter, guardPath, guardPaths, guardQuery, hasRelationOp, isAtscriptDbView, isBucketableField, isColumnTypeChanged, isDbEntityType, isDbFieldOp, isEmptyObject, isFieldRef, isGeoIndexableType, isGeoPointType, isJsonValueField, isNavRelation, isPlainObject, isPrimitive, isRelationOp, isResolvedRelationFilter, isViewType, jsonValueAncestor, narrowerFilterOps, normalizeComputedSelect, reconcileCas, relationStaticFilter, resolveCalendarBuckets, resolveDesignType, searchIndexNotFoundMessage, selfOrAncestor, separateCas, separateFieldOps, sortFieldNames, tableNameOf, translateQueryTree, unsupportedOperatorMessage, vectorIndexNotFoundMessage, walkFilter, withOptimisticRetry };