@atscript/db 0.1.154 → 0.1.156

package/dist/{fk-diff-BIJ8l_hF.d.mts → fk-diff-5gX42hBt.d.mts}

@@ -1,4 +1,4 @@
-import { A as TColumnDiff, Cn as AtscriptDbReadable, U as TDbFieldMeta, V as TDbDefaultValue, W as TDbForeignKey, _t as TExistingColumn, at as TDbStorageType, dn as AtscriptQueryFieldRef, fn as AtscriptQueryNode, ht as TDerivedColumn, nn as AtscriptDbView, yt as TExistingTableOption, z as TDbCollation } from "./buckets-CBKL_ZWE.mjs";
+import { A as TColumnDiff, B as TDbDefaultFn, En as AtscriptDbReadable, U as TDbFieldMeta, V as TDbDefaultValue, W as TDbForeignKey, _t as TExistingColumn, an as AtscriptDbView, at as TDbStorageType, hn as AtscriptQueryNode, ht as TDerivedColumn, mn as AtscriptQueryFieldRef, yt as TExistingTableOption, z as TDbCollation } from "./buckets-8mG67Mtw.mjs";
 
 //#region src/schema/schema-hash.d.ts
 interface TFieldSnapshot {
@@ -225,6 +225,7 @@ declare function isColumnTypeChanged(existingType: string, expectedType: string)
  */
 declare function computeColumnDiff(desired: readonly TDbFieldMeta[], existing: TExistingColumn[], typeMapper?: (field: TDbFieldMeta) => string, opts?: {
   snapshot?: TTableSnapshot | null;
+  nativeDefaultFns?: ReadonlySet<TDbDefaultFn>;
 }): TColumnDiff;
 //#endregion
 //#region src/schema/fk-diff.d.ts

package/dist/{fk-diff-D1mrLMjU.d.cts → fk-diff-BWdQ7kRZ.d.cts}

@@ -1,4 +1,4 @@
-import { A as TColumnDiff, Cn as AtscriptDbReadable, U as TDbFieldMeta, V as TDbDefaultValue, W as TDbForeignKey, _t as TExistingColumn, at as TDbStorageType, dn as AtscriptQueryFieldRef, fn as AtscriptQueryNode, ht as TDerivedColumn, nn as AtscriptDbView, yt as TExistingTableOption, z as TDbCollation } from "./buckets-jy8BfswO.cjs";
+import { A as TColumnDiff, B as TDbDefaultFn, En as AtscriptDbReadable, U as TDbFieldMeta, V as TDbDefaultValue, W as TDbForeignKey, _t as TExistingColumn, an as AtscriptDbView, at as TDbStorageType, hn as AtscriptQueryNode, ht as TDerivedColumn, mn as AtscriptQueryFieldRef, yt as TExistingTableOption, z as TDbCollation } from "./buckets-B4T_alUe.cjs";
 
 //#region src/schema/schema-hash.d.ts
 interface TFieldSnapshot {
@@ -225,6 +225,7 @@ declare function isColumnTypeChanged(existingType: string, expectedType: string)
  */
 declare function computeColumnDiff(desired: readonly TDbFieldMeta[], existing: TExistingColumn[], typeMapper?: (field: TDbFieldMeta) => string, opts?: {
   snapshot?: TTableSnapshot | null;
+  nativeDefaultFns?: ReadonlySet<TDbDefaultFn>;
 }): TColumnDiff;
 //#endregion
 //#region src/schema/fk-diff.d.ts

package/dist/index.cjs

@@ -1,13 +1,13 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_db_error = require("./db-error-JcfJqqpk.cjs");
-const require_column_diff = require("./column-diff-qnzx1o3c.cjs");
+const require_column_diff = require("./column-diff-DpeUbhEI.cjs");
 const require_aggregate_fns = require("./aggregate-fns-DFtKAv7Q.cjs");
 const require_nested_writer = require("./nested-writer-Bl1SZS7x.cjs");
-const require_search_fields = require("./search-fields-DwrsJUC1.cjs");
+const require_validator = require("./validator-B4YDLUkj.cjs");
+const require_search_fields = require("./search-fields-CT_UZ9fg.cjs");
 const require_object = require("./object-Djg28csK.cjs");
 const require_consts = require("./consts-BzRfCcH2.cjs");
 const require_ops = require("./ops.cjs");
-const require_validator = require("./validator-BxWwh3wf.cjs");
 let _atscript_typescript_utils = require("@atscript/typescript/utils");
 let _uniqu_core = require("@uniqu/core");
 let node_crypto = require("node:crypto");

package/dist/index.d.cts

@@ -1,11 +1,11 @@
-import { $ as TDbInsertResult, $t as DbSpace, A as TColumnDiff, An as TRelationFilterJunction, At as TReferencingForeignKey, B as TDbDefaultFn, Bn as TDbEncryptionOptions, Bt as TWriteOptions, C as NavPropsOf, Cn as AtscriptDbReadable, Ct as TIdDescriptor, D as PrimaryKeyOf, Dn as REL_FILTER_MAX_NODES, Dt as TMetaResponse, E as OwnPropsOf, En as REL_FILTER_MAX_DEPTH, Et as TInsertOptions, F as TDbActionLevel, Fn as forEachResolvedRelation, Ft as TTableOptionDiff, G as TDbIndex, Gn as TGenericLogger, Gt as WithRelation, H as TDbDeleteResult, Hn as FieldMappingStrategy, Ht as TypedWithRelation, I as TDbActionProcessor, In as hasRelationOp, It as TTableResolver, J as TDbInsertIgnoreOptions, Jn as TRowOrderKey, Jt as isGeoPointType, K as TDbIndexField, Kn as TExprAggregate, Kt as TableMetadata, L as TDbActionTargetSummary, Ln as isResolvedRelationFilter, Lt as TTouchManyOptions, M as TCrudPermissions, Mn as TRelationStaticFilter, Mt as TRowResolveOptions, N as TDbActionInfo, Nn as andFilters, Nt as TSearchIndexInfo, O as TCascadeResolver, On as ResolvedRelationFilter, Ot as TMetadataOverrides, P as TDbActionIntent, Pn as containsRelationFilter, Pt as TSyncColumnResult, Q as TDbInsertManyResult, Qt as TViewCapability, R as TDbAvailableActions, Rn as relationStaticFilter, Rt as TValueFormatterPair, S as FlatOf, Sn as TCascadePin, St as TFkLookupTarget, T as NullsPlacement, Tn as resolveDesignType, Tt as TIdentification, U as TDbFieldMeta, Un as TReadControls, Ut as Uniquery, V as TDbDefaultValue, Vn as DocumentFieldMapper, Vt as TWriteTableResolver, W as TDbForeignKey, Wn as NoopLogger, Wt as UniqueryControls, X as TDbInsertIgnoreSlot, Xt as ALL_VIEW_CAPABILITIES, Y as TDbInsertIgnoreResult, Yn as UniquSelect, Yt as ALL_BUCKET_UNITS, Z as TDbInsertManyIgnoreResult, Zt as BaseDbAdapter, _ as DbPatch, _n as isFieldRef, _t as TExistingColumn, a as isJsonValueField, an as isViewType, at as TDbStorageType, b as FieldOpsFor, bn as IntegrityStrategy, bt as TFieldMeta, c as resolveCalendarBuckets, cn as AtscriptExprNode, ct as TDbWriteAction, d as AggregateFn, dn as AtscriptQueryFieldRef, dt as TDbWriteGuard, en as TAdapterFactory, et as TDbObjectKind, f as AggregateQuery, fn as AtscriptQueryNode, ft as TDbWriteGuardContext, g as DbControls, gn as evaluateExpr, gt as TEnsureTableOptions, h as AtscriptDbWritable, hn as TViewPlan, ht as TDerivedColumn, i as isBucketableField, in as isAtscriptDbView, it as TDbRemoveGuardContext, j as TCrudOp, jn as TRelationFilterTable, jt as TRelationInfo, k as TCascadeTarget, kn as TRelGuardState, kt as TPrimaryKeyChange, l as AggregateControls, ln as AtscriptOrderItem, lt as TDbWriteCheck, mn as TViewJoin, mt as TDerivedChangeReason, n as TComputedSelect, nn as AtscriptDbView, nt as TDbRelation, o as jsonValueAncestor, on as TViewReadPlan, ot as TDbUpdateOptions, p as AggregateResult, pn as AtscriptRef, pt as TDeleteOptions, q as TDbIndexType, qn as TFirstLast, qt as isGeoIndexableType, r as TResolvedBucket, rn as TViewColumnMapping, rt as TDbRemoveGuard, s as normalizeComputedSelect, sn as aliasTargetOf, st as TDbUpdateResult, t as TBucketFieldSource, tn as TDbSpaceOptions, tt as TDbReferentialAction, u as AggregateExpr, un as AtscriptQueryComparison, ut as TDbWriteCheckContext, v as DbQuery, vn as translateQueryTree, vt as TExistingForeignKey, w as NullableOptional, wn as DbResponse, wt as TIdResolveOptions, x as FilterExpr, xn as NativeIntegrity, xt as TFkLookupResolver, y as DbRow, yn as AtscriptDbTable, yt as TExistingTableOption, z as TDbCollation, zn as DbEncryption, zt as TViewJsonType } from "./buckets-jy8BfswO.cjs";
+import { $ as TDbInsertResult, $t as ALL_VIEW_CAPABILITIES, A as TColumnDiff, An as REL_FILTER_MAX_NODES, At as TPrimaryKeyChange, B as TDbDefaultFn, Bn as isResolvedRelationFilter, Bt as TValueFormatterPair, C as NavPropsOf, Cn as IntegrityStrategy, Ct as TIdDescriptor, D as PrimaryKeyOf, Dn as DbResponse, Dt as TJsonCopyTarget, E as OwnPropsOf, En as AtscriptDbReadable, Et as TInsertOptions, F as TDbActionLevel, Fn as TRelationStaticFilter, Ft as TSyncColumnResult, G as TDbIndex, Gn as FieldMappingStrategy, Gt as Uniquery, H as TDbDeleteResult, Hn as DbEncryption, Ht as TWriteOptions, I as TDbActionProcessor, In as andFilters, It as TSyncIndexesOptions, J as TDbInsertIgnoreOptions, Jn as TGenericLogger, Jt as TableMetadata, K as TDbIndexField, Kn as TReadControls, Kt as UniqueryControls, L as TDbActionTargetSummary, Ln as containsRelationFilter, Lt as TTableOptionDiff, M as TCrudPermissions, Mn as TRelGuardState, Mt as TRelationInfo, N as TDbActionInfo, Nn as TRelationFilterJunction, Nt as TRowResolveOptions, O as TCascadeResolver, On as resolveDesignType, Ot as TMetaResponse, P as TDbActionIntent, Pn as TRelationFilterTable, Pt as TSearchIndexInfo, Q as TDbInsertManyResult, Qn as UniquSelect, Qt as ALL_BUCKET_UNITS, R as TDbAvailableActions, Rn as forEachResolvedRelation, Rt as TTableResolver, S as FlatOf, Sn as AtscriptDbTable, St as TFkLookupTarget, T as NullsPlacement, Tn as TCascadePin, Tt as TIdentification, U as TDbFieldMeta, Un as TDbEncryptionOptions, Ut as TWriteTableResolver, V as TDbDefaultValue, Vn as relationStaticFilter, Vt as TViewJsonType, W as TDbForeignKey, Wn as DocumentFieldMapper, Wt as TypedWithRelation, X as TDbInsertIgnoreSlot, Xn as TFirstLast, Xt as isGeoPointType, Y as TDbInsertIgnoreResult, Yn as TExprAggregate, Yt as isGeoIndexableType, Z as TDbInsertManyIgnoreResult, Zn as TRowOrderKey, Zt as TPathPresence, _ as DbPatch, _n as TViewJoin, _t as TExistingColumn, a as isJsonValueField, an as AtscriptDbView, at as TDbStorageType, b as FieldOpsFor, bn as isFieldRef, bt as TFieldMeta, c as resolveCalendarBuckets, cn as isViewType, ct as TDbWriteAction, d as AggregateFn, dn as AtscriptExprNode, dt as TDbWriteGuard, en as BaseDbAdapter, et as TDbObjectKind, f as AggregateQuery, fn as AtscriptOrderItem, ft as TDbWriteGuardContext, g as DbControls, gn as AtscriptRef, gt as TEnsureTableOptions, h as AtscriptDbWritable, hn as AtscriptQueryNode, ht as TDerivedColumn, i as isBucketableField, in as TDbSpaceOptions, it as TDbRemoveGuardContext, j as TCrudOp, jn as ResolvedRelationFilter, jt as TReferencingForeignKey, k as TCascadeTarget, kn as REL_FILTER_MAX_DEPTH, kt as TMetadataOverrides, l as AggregateControls, ln as TViewReadPlan, lt as TDbWriteCheck, mn as AtscriptQueryFieldRef, mt as TDerivedChangeReason, n as TComputedSelect, nn as DbSpace, nt as TDbRelation, o as jsonValueAncestor, on as TViewColumnMapping, ot as TDbUpdateOptions, p as AggregateResult, pn as AtscriptQueryComparison, pt as TDeleteOptions, q as TDbIndexType, qn as NoopLogger, qt as WithRelation, r as TResolvedBucket, rn as TAdapterFactory, rt as TDbRemoveGuard, s as normalizeComputedSelect, sn as isAtscriptDbView, st as TDbUpdateResult, t as TBucketFieldSource, tn as TViewCapability, tt as TDbReferentialAction, u as AggregateExpr, un as aliasTargetOf, ut as TDbWriteCheckContext, v as DbQuery, vn as TViewPlan, vt as TExistingForeignKey, w as NullableOptional, wn as NativeIntegrity, wt as TIdResolveOptions, x as FilterExpr, xn as translateQueryTree, xt as TFkLookupResolver, y as DbRow, yn as evaluateExpr, yt as TExistingTableOption, z as TDbCollation, zn as hasRelationOp, zt as TTouchManyOptions } from "./buckets-B4T_alUe.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-42CSpGDR.cjs";
 import { _ as aggregateFailure, a as buildValidationContext, b as isRetryableDbError, c as isNavRelation, d as getKeyProps, f as CasExhaustedError, g as aggregateExpressionsNotSupported, 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, v as bucketTimeZoneUnavailable, y as isConflict } from "./validator-B3xlbrWf.cjs";
 import { n as createDbValidatorPlugin, t as DbValidationContext } from "./db-validator-plugin-BWy60OvG.cjs";
-import { r as fkColumns, s as isColumnTypeChanged } from "./fk-diff-D1mrLMjU.cjs";
-import { i as tableNameOf } from "./relation-helpers-D_8bydc2.cjs";
+import { r as fkColumns, s as isColumnTypeChanged } from "./fk-diff-BWdQ7kRZ.cjs";
+import { i as tableNameOf } from "./relation-helpers-BLBrLQYi.cjs";
 import { AggregateQuery as AggregateQuery$1, FilterExpr as FilterExpr$1, FilterVisitor, RELATION_OPS, RelationOp, RelationOp as RelationOp$1, ResolvedRowOrderKey, ResolvedSelectExpr, Uniquery as Uniquery$1, computeInsights, isPrimitive, isRelationOp, walkFilter } from "@uniqu/core";
 import { AtscriptExprNode as AtscriptExprNode$1, TAtscriptAnnotatedType } from "@atscript/typescript/utils";
 
@@ -177,6 +177,11 @@ type TFilterPredicate = "compare" | "geo" | "exists" | "relation";
 interface TFilterRef {
   path: string;
   predicate: TFilterPredicate;
+  /**
+   * The entry only tests presence (`null`, `$eq` / `$ne: null`, `$exists`)
+   * — the one filter a stored object accepts (since 0.1.155).
+   */
+  nullTest?: boolean;
   /**
    * `relation` entries: each operator with its operand (a filter on the
    * related table, not walked here). @since 0.1.147
@@ -386,7 +391,7 @@ declare function classifyQueryPath(source: TQueryPathSource, path: string): {
  * `FieldCapabilityIndex`, with `$with` hints and leaf lists) is what clients
  * see and is authoritative — the HTTP gate always answers first.
  */
-declare function guardPath(meta: TableMetadata, adapter: BaseDbAdapter, path: string, op: TQueryPathOp, predicate?: TFilterPredicate): void;
+declare function guardPath(meta: TableMetadata, adapter: BaseDbAdapter, path: string, op: TQueryPathOp, predicate?: TFilterPredicate, nullTest?: boolean): void;
 /**
  * Core backstop for every read / aggregate / mutation-filter entry point:
  * each referenced path (see {@link collectQueryPaths}) must exist on THIS
@@ -636,10 +641,11 @@ declare function assertNoVersionWrites(data: Record<string, unknown>, versionCol
  * Whether a logical (pre-decomposition) patch writes ONLY version-exempt
  * fields (`@db.column.version.exempt`). `data` has nav fields, filter keys and
  * derived fields removed and `$cas` separated. Mirrors `flattenPatchPayload`
- * (keep the two side by side): PK keys are skipped; an exempt path (or one
- * under an exempt ancestor) is covered whatever its value (scalar, field op,
- * array ops, object); a non-exempt merge-strategy object recurses (only the
- * supplied children are written); anything else is a non-exempt write.
+ * (keep the two side by side): PK keys and `@db.onUpdate.now` fields are
+ * skipped; an exempt path (or one under an exempt ancestor) is covered
+ * whatever its value (scalar, field op, array ops, object); a non-exempt
+ * merge-strategy object recurses (only the supplied children are written);
+ * anything else is a non-exempt write.
  * True iff at least one key is covered and none is not.
  * @since 0.1.150
  */
@@ -686,4 +692,4 @@ declare function createFailureCollector(what: string): {
  */
 declare function numericOperandProblem(fd: TDbFieldMeta): string | undefined;
 //#endregion
-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, INTEGER_REGEX_OP, IntegrityStrategy, NativeIntegrity, type NavPropsOf, NoopLogger, type NullableOptional, type NullsPlacement, 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 TDbInsertIgnoreOptions, type TDbInsertIgnoreResult, type TDbInsertIgnoreSlot, type TDbInsertManyIgnoreResult, type TDbInsertManyResult, type TDbInsertResult, type TDbObjectKind, type TDbPatch, type TDbReferentialAction, type TDbRelation, type TDbRemoveGuard, type TDbRemoveGuardContext, type TDbSpaceOptions, type TDbStorageType, type TDbUpdateOptions, 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 TExprAggregate, type TFieldMeta, type TFieldOps, type TFilterPredicate, type TFilterRef, type TFirstLast, type TFkLookupResolver, type TFkLookupTarget, type TGenericLogger, type TGroupSourceVerdict, type TGuardedQuery, type TIdDescriptor, type TIdResolveOptions, type TIdentification, type TInsertOptions, type TMetaResponse, type TMetadataOverrides, type TPrimaryKeyChange, type TQueryPathKind, type TQueryPathOp, type TQueryPathRefs, type TQueryPathSource, type TReadColumnsKind, type TReadControls, type TReferencingForeignKey, type TRelationFilterJunction, type TRelationFilterTable, type TRelationInfo, type TRelationStaticFilter, type TResolvedBucket, type TRowOrderKey, type TRowResolveOptions, type TSearchIndexInfo, type TSearchMemberKind, type TSyncColumnResult, type TTableOptionDiff, type TTableResolver, type TTouchManyOptions, type TValueFormatterPair, type TViewCapability, type TViewColumnMapping, type TViewJoin, type TViewJsonType, type TViewPlan, type TViewReadPlan, type TWriteOptions, type TWriteTableResolver, TableMetadata, type TypedWithRelation, UniquSelect, type Uniquery, type UniqueryControls, type ValidationContext, type ValidatorMode, type WeekStart, type WithOptimisticRetryOptions, type WithRelation, acceptedOperatorsHint, aggregateExpressionsNotSupported, aggregateFailure, aliasTargetOf, andFilters, assertGeoPoint, assertNoVersionWrites, bucketSourceVerdict, bucketTimeZoneUnavailable, buildDbValidator, buildValidationContext, canFilterLeaf, checkHavingKeys, classifyQueryPath, collectQueryPaths, computeInsights, containsRelationFilter, createDbValidatorPlugin, createFailureCollector, decomposePatch, defaultFulltextIndex, deletePath, describeFulltext, evaluateExpr, findAncestorInSet, fkColumns, forEachResolvedRelation, forceNavNonOptional, geoIndexNotFoundMessage, getDbFieldOp, getKeyProps, getPath, groupSourceVerdict, guardAggregate, guardFilter, guardPath, guardPaths, guardQuery, hasRelationOp, isAtscriptDbView, isBucketableField, isColumnTypeChanged, isConflict, isDbEntityType, isDbFieldOp, isEmptyObject, isFieldRef, isGeoIndexableType, isGeoPointType, isJsonValueField, isNavRelation, isPlainObject, isPrimitive, isRelationOp, isResolvedRelationFilter, isRetryableDbError, isVersionExemptPatch, isViewType, jsonValueAncestor, narrowerFilterOps, normalizeComputedSelect, numericOperandProblem, queryReadColumns, reconcileCas, relationStaticFilter, resolveCalendarBuckets, resolveDesignType, searchIndexNotFoundMessage, searchMemberKind, searchTermInteger, selfOrAncestor, separateCas, separateFieldOps, sortFieldNames, splitFulltextFields, tableNameOf, translateQueryTree, uniqueKeyTuple, 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, INTEGER_REGEX_OP, IntegrityStrategy, NativeIntegrity, type NavPropsOf, NoopLogger, type NullableOptional, type NullsPlacement, 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 TDbInsertIgnoreOptions, type TDbInsertIgnoreResult, type TDbInsertIgnoreSlot, type TDbInsertManyIgnoreResult, type TDbInsertManyResult, type TDbInsertResult, type TDbObjectKind, type TDbPatch, type TDbReferentialAction, type TDbRelation, type TDbRemoveGuard, type TDbRemoveGuardContext, type TDbSpaceOptions, type TDbStorageType, type TDbUpdateOptions, 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 TExprAggregate, type TFieldMeta, type TFieldOps, type TFilterPredicate, type TFilterRef, type TFirstLast, type TFkLookupResolver, type TFkLookupTarget, type TGenericLogger, type TGroupSourceVerdict, type TGuardedQuery, type TIdDescriptor, type TIdResolveOptions, type TIdentification, type TInsertOptions, type TJsonCopyTarget, type TMetaResponse, type TMetadataOverrides, type TPathPresence, type TPrimaryKeyChange, type TQueryPathKind, type TQueryPathOp, type TQueryPathRefs, type TQueryPathSource, type TReadColumnsKind, type TReadControls, type TReferencingForeignKey, type TRelationFilterJunction, type TRelationFilterTable, type TRelationInfo, type TRelationStaticFilter, type TResolvedBucket, type TRowOrderKey, type TRowResolveOptions, type TSearchIndexInfo, type TSearchMemberKind, type TSyncColumnResult, type TSyncIndexesOptions, type TTableOptionDiff, type TTableResolver, type TTouchManyOptions, type TValueFormatterPair, type TViewCapability, type TViewColumnMapping, type TViewJoin, type TViewJsonType, type TViewPlan, type TViewReadPlan, type TWriteOptions, type TWriteTableResolver, TableMetadata, type TypedWithRelation, UniquSelect, type Uniquery, type UniqueryControls, type ValidationContext, type ValidatorMode, type WeekStart, type WithOptimisticRetryOptions, type WithRelation, acceptedOperatorsHint, aggregateExpressionsNotSupported, aggregateFailure, aliasTargetOf, andFilters, assertGeoPoint, assertNoVersionWrites, bucketSourceVerdict, bucketTimeZoneUnavailable, buildDbValidator, buildValidationContext, canFilterLeaf, checkHavingKeys, classifyQueryPath, collectQueryPaths, computeInsights, containsRelationFilter, createDbValidatorPlugin, createFailureCollector, decomposePatch, defaultFulltextIndex, deletePath, describeFulltext, evaluateExpr, findAncestorInSet, fkColumns, forEachResolvedRelation, forceNavNonOptional, geoIndexNotFoundMessage, getDbFieldOp, getKeyProps, getPath, groupSourceVerdict, guardAggregate, guardFilter, guardPath, guardPaths, guardQuery, hasRelationOp, isAtscriptDbView, isBucketableField, isColumnTypeChanged, isConflict, isDbEntityType, isDbFieldOp, isEmptyObject, isFieldRef, isGeoIndexableType, isGeoPointType, isJsonValueField, isNavRelation, isPlainObject, isPrimitive, isRelationOp, isResolvedRelationFilter, isRetryableDbError, isVersionExemptPatch, isViewType, jsonValueAncestor, narrowerFilterOps, normalizeComputedSelect, numericOperandProblem, queryReadColumns, reconcileCas, relationStaticFilter, resolveCalendarBuckets, resolveDesignType, searchIndexNotFoundMessage, searchMemberKind, searchTermInteger, selfOrAncestor, separateCas, separateFieldOps, sortFieldNames, splitFulltextFields, tableNameOf, translateQueryTree, uniqueKeyTuple, unsupportedOperatorMessage, vectorIndexNotFoundMessage, walkFilter, withOptimisticRetry };

package/dist/index.d.mts

@@ -1,11 +1,11 @@
-import { $ as TDbInsertResult, $t as DbSpace, A as TColumnDiff, An as TRelationFilterJunction, At as TReferencingForeignKey, B as TDbDefaultFn, Bn as TDbEncryptionOptions, Bt as TWriteOptions, C as NavPropsOf, Cn as AtscriptDbReadable, Ct as TIdDescriptor, D as PrimaryKeyOf, Dn as REL_FILTER_MAX_NODES, Dt as TMetaResponse, E as OwnPropsOf, En as REL_FILTER_MAX_DEPTH, Et as TInsertOptions, F as TDbActionLevel, Fn as forEachResolvedRelation, Ft as TTableOptionDiff, G as TDbIndex, Gn as TGenericLogger, Gt as WithRelation, H as TDbDeleteResult, Hn as FieldMappingStrategy, Ht as TypedWithRelation, I as TDbActionProcessor, In as hasRelationOp, It as TTableResolver, J as TDbInsertIgnoreOptions, Jn as TRowOrderKey, Jt as isGeoPointType, K as TDbIndexField, Kn as TExprAggregate, Kt as TableMetadata, L as TDbActionTargetSummary, Ln as isResolvedRelationFilter, Lt as TTouchManyOptions, M as TCrudPermissions, Mn as TRelationStaticFilter, Mt as TRowResolveOptions, N as TDbActionInfo, Nn as andFilters, Nt as TSearchIndexInfo, O as TCascadeResolver, On as ResolvedRelationFilter, Ot as TMetadataOverrides, P as TDbActionIntent, Pn as containsRelationFilter, Pt as TSyncColumnResult, Q as TDbInsertManyResult, Qt as TViewCapability, R as TDbAvailableActions, Rn as relationStaticFilter, Rt as TValueFormatterPair, S as FlatOf, Sn as TCascadePin, St as TFkLookupTarget, T as NullsPlacement, Tn as resolveDesignType, Tt as TIdentification, U as TDbFieldMeta, Un as TReadControls, Ut as Uniquery, V as TDbDefaultValue, Vn as DocumentFieldMapper, Vt as TWriteTableResolver, W as TDbForeignKey, Wn as NoopLogger, Wt as UniqueryControls, X as TDbInsertIgnoreSlot, Xt as ALL_VIEW_CAPABILITIES, Y as TDbInsertIgnoreResult, Yn as UniquSelect, Yt as ALL_BUCKET_UNITS, Z as TDbInsertManyIgnoreResult, Zt as BaseDbAdapter, _ as DbPatch, _n as isFieldRef, _t as TExistingColumn, a as isJsonValueField, an as isViewType, at as TDbStorageType, b as FieldOpsFor, bn as IntegrityStrategy, bt as TFieldMeta, c as resolveCalendarBuckets, cn as AtscriptExprNode, ct as TDbWriteAction, d as AggregateFn, dn as AtscriptQueryFieldRef, dt as TDbWriteGuard, en as TAdapterFactory, et as TDbObjectKind, f as AggregateQuery, fn as AtscriptQueryNode, ft as TDbWriteGuardContext, g as DbControls, gn as evaluateExpr, gt as TEnsureTableOptions, h as AtscriptDbWritable, hn as TViewPlan, ht as TDerivedColumn, i as isBucketableField, in as isAtscriptDbView, it as TDbRemoveGuardContext, j as TCrudOp, jn as TRelationFilterTable, jt as TRelationInfo, k as TCascadeTarget, kn as TRelGuardState, kt as TPrimaryKeyChange, l as AggregateControls, ln as AtscriptOrderItem, lt as TDbWriteCheck, mn as TViewJoin, mt as TDerivedChangeReason, n as TComputedSelect, nn as AtscriptDbView, nt as TDbRelation, o as jsonValueAncestor, on as TViewReadPlan, ot as TDbUpdateOptions, p as AggregateResult, pn as AtscriptRef, pt as TDeleteOptions, q as TDbIndexType, qn as TFirstLast, qt as isGeoIndexableType, r as TResolvedBucket, rn as TViewColumnMapping, rt as TDbRemoveGuard, s as normalizeComputedSelect, sn as aliasTargetOf, st as TDbUpdateResult, t as TBucketFieldSource, tn as TDbSpaceOptions, tt as TDbReferentialAction, u as AggregateExpr, un as AtscriptQueryComparison, ut as TDbWriteCheckContext, v as DbQuery, vn as translateQueryTree, vt as TExistingForeignKey, w as NullableOptional, wn as DbResponse, wt as TIdResolveOptions, x as FilterExpr, xn as NativeIntegrity, xt as TFkLookupResolver, y as DbRow, yn as AtscriptDbTable, yt as TExistingTableOption, z as TDbCollation, zn as DbEncryption, zt as TViewJsonType } from "./buckets-CBKL_ZWE.mjs";
+import { $ as TDbInsertResult, $t as ALL_VIEW_CAPABILITIES, A as TColumnDiff, An as REL_FILTER_MAX_NODES, At as TPrimaryKeyChange, B as TDbDefaultFn, Bn as isResolvedRelationFilter, Bt as TValueFormatterPair, C as NavPropsOf, Cn as IntegrityStrategy, Ct as TIdDescriptor, D as PrimaryKeyOf, Dn as DbResponse, Dt as TJsonCopyTarget, E as OwnPropsOf, En as AtscriptDbReadable, Et as TInsertOptions, F as TDbActionLevel, Fn as TRelationStaticFilter, Ft as TSyncColumnResult, G as TDbIndex, Gn as FieldMappingStrategy, Gt as Uniquery, H as TDbDeleteResult, Hn as DbEncryption, Ht as TWriteOptions, I as TDbActionProcessor, In as andFilters, It as TSyncIndexesOptions, J as TDbInsertIgnoreOptions, Jn as TGenericLogger, Jt as TableMetadata, K as TDbIndexField, Kn as TReadControls, Kt as UniqueryControls, L as TDbActionTargetSummary, Ln as containsRelationFilter, Lt as TTableOptionDiff, M as TCrudPermissions, Mn as TRelGuardState, Mt as TRelationInfo, N as TDbActionInfo, Nn as TRelationFilterJunction, Nt as TRowResolveOptions, O as TCascadeResolver, On as resolveDesignType, Ot as TMetaResponse, P as TDbActionIntent, Pn as TRelationFilterTable, Pt as TSearchIndexInfo, Q as TDbInsertManyResult, Qn as UniquSelect, Qt as ALL_BUCKET_UNITS, R as TDbAvailableActions, Rn as forEachResolvedRelation, Rt as TTableResolver, S as FlatOf, Sn as AtscriptDbTable, St as TFkLookupTarget, T as NullsPlacement, Tn as TCascadePin, Tt as TIdentification, U as TDbFieldMeta, Un as TDbEncryptionOptions, Ut as TWriteTableResolver, V as TDbDefaultValue, Vn as relationStaticFilter, Vt as TViewJsonType, W as TDbForeignKey, Wn as DocumentFieldMapper, Wt as TypedWithRelation, X as TDbInsertIgnoreSlot, Xn as TFirstLast, Xt as isGeoPointType, Y as TDbInsertIgnoreResult, Yn as TExprAggregate, Yt as isGeoIndexableType, Z as TDbInsertManyIgnoreResult, Zn as TRowOrderKey, Zt as TPathPresence, _ as DbPatch, _n as TViewJoin, _t as TExistingColumn, a as isJsonValueField, an as AtscriptDbView, at as TDbStorageType, b as FieldOpsFor, bn as isFieldRef, bt as TFieldMeta, c as resolveCalendarBuckets, cn as isViewType, ct as TDbWriteAction, d as AggregateFn, dn as AtscriptExprNode, dt as TDbWriteGuard, en as BaseDbAdapter, et as TDbObjectKind, f as AggregateQuery, fn as AtscriptOrderItem, ft as TDbWriteGuardContext, g as DbControls, gn as AtscriptRef, gt as TEnsureTableOptions, h as AtscriptDbWritable, hn as AtscriptQueryNode, ht as TDerivedColumn, i as isBucketableField, in as TDbSpaceOptions, it as TDbRemoveGuardContext, j as TCrudOp, jn as ResolvedRelationFilter, jt as TReferencingForeignKey, k as TCascadeTarget, kn as REL_FILTER_MAX_DEPTH, kt as TMetadataOverrides, l as AggregateControls, ln as TViewReadPlan, lt as TDbWriteCheck, mn as AtscriptQueryFieldRef, mt as TDerivedChangeReason, n as TComputedSelect, nn as DbSpace, nt as TDbRelation, o as jsonValueAncestor, on as TViewColumnMapping, ot as TDbUpdateOptions, p as AggregateResult, pn as AtscriptQueryComparison, pt as TDeleteOptions, q as TDbIndexType, qn as NoopLogger, qt as WithRelation, r as TResolvedBucket, rn as TAdapterFactory, rt as TDbRemoveGuard, s as normalizeComputedSelect, sn as isAtscriptDbView, st as TDbUpdateResult, t as TBucketFieldSource, tn as TViewCapability, tt as TDbReferentialAction, u as AggregateExpr, un as aliasTargetOf, ut as TDbWriteCheckContext, v as DbQuery, vn as TViewPlan, vt as TExistingForeignKey, w as NullableOptional, wn as NativeIntegrity, wt as TIdResolveOptions, x as FilterExpr, xn as translateQueryTree, xt as TFkLookupResolver, y as DbRow, yn as evaluateExpr, yt as TExistingTableOption, z as TDbCollation, zn as hasRelationOp, zt as TTouchManyOptions } from "./buckets-8mG67Mtw.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-Wo-smrYV.mjs";
 import { _ as aggregateFailure, a as buildValidationContext, b as isRetryableDbError, c as isNavRelation, d as getKeyProps, f as CasExhaustedError, g as aggregateExpressionsNotSupported, 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, v as bucketTimeZoneUnavailable, y as isConflict } from "./validator-B3xlbrWf.mjs";
 import { n as createDbValidatorPlugin, t as DbValidationContext } from "./db-validator-plugin-BWy60OvG.mjs";
-import { r as fkColumns, s as isColumnTypeChanged } from "./fk-diff-BIJ8l_hF.mjs";
-import { i as tableNameOf } from "./relation-helpers-BUsxNNGU.mjs";
+import { r as fkColumns, s as isColumnTypeChanged } from "./fk-diff-5gX42hBt.mjs";
+import { i as tableNameOf } from "./relation-helpers-17_2f5hX.mjs";
 import { AtscriptExprNode as AtscriptExprNode$1, TAtscriptAnnotatedType } from "@atscript/typescript/utils";
 import { AggregateQuery as AggregateQuery$1, FilterExpr as FilterExpr$1, FilterVisitor, RELATION_OPS, RelationOp, RelationOp as RelationOp$1, ResolvedRowOrderKey, ResolvedSelectExpr, Uniquery as Uniquery$1, computeInsights, isPrimitive, isRelationOp, walkFilter } from "@uniqu/core";
 
@@ -177,6 +177,11 @@ type TFilterPredicate = "compare" | "geo" | "exists" | "relation";
 interface TFilterRef {
   path: string;
   predicate: TFilterPredicate;
+  /**
+   * The entry only tests presence (`null`, `$eq` / `$ne: null`, `$exists`)
+   * — the one filter a stored object accepts (since 0.1.155).
+   */
+  nullTest?: boolean;
   /**
    * `relation` entries: each operator with its operand (a filter on the
    * related table, not walked here). @since 0.1.147
@@ -386,7 +391,7 @@ declare function classifyQueryPath(source: TQueryPathSource, path: string): {
  * `FieldCapabilityIndex`, with `$with` hints and leaf lists) is what clients
  * see and is authoritative — the HTTP gate always answers first.
  */
-declare function guardPath(meta: TableMetadata, adapter: BaseDbAdapter, path: string, op: TQueryPathOp, predicate?: TFilterPredicate): void;
+declare function guardPath(meta: TableMetadata, adapter: BaseDbAdapter, path: string, op: TQueryPathOp, predicate?: TFilterPredicate, nullTest?: boolean): void;
 /**
  * Core backstop for every read / aggregate / mutation-filter entry point:
  * each referenced path (see {@link collectQueryPaths}) must exist on THIS
@@ -636,10 +641,11 @@ declare function assertNoVersionWrites(data: Record<string, unknown>, versionCol
  * Whether a logical (pre-decomposition) patch writes ONLY version-exempt
  * fields (`@db.column.version.exempt`). `data` has nav fields, filter keys and
  * derived fields removed and `$cas` separated. Mirrors `flattenPatchPayload`
- * (keep the two side by side): PK keys are skipped; an exempt path (or one
- * under an exempt ancestor) is covered whatever its value (scalar, field op,
- * array ops, object); a non-exempt merge-strategy object recurses (only the
- * supplied children are written); anything else is a non-exempt write.
+ * (keep the two side by side): PK keys and `@db.onUpdate.now` fields are
+ * skipped; an exempt path (or one under an exempt ancestor) is covered
+ * whatever its value (scalar, field op, array ops, object); a non-exempt
+ * merge-strategy object recurses (only the supplied children are written);
+ * anything else is a non-exempt write.
  * True iff at least one key is covered and none is not.
  * @since 0.1.150
  */
@@ -686,4 +692,4 @@ declare function createFailureCollector(what: string): {
  */
 declare function numericOperandProblem(fd: TDbFieldMeta): string | undefined;
 //#endregion
-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, INTEGER_REGEX_OP, IntegrityStrategy, NativeIntegrity, type NavPropsOf, NoopLogger, type NullableOptional, type NullsPlacement, 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 TDbInsertIgnoreOptions, type TDbInsertIgnoreResult, type TDbInsertIgnoreSlot, type TDbInsertManyIgnoreResult, type TDbInsertManyResult, type TDbInsertResult, type TDbObjectKind, type TDbPatch, type TDbReferentialAction, type TDbRelation, type TDbRemoveGuard, type TDbRemoveGuardContext, type TDbSpaceOptions, type TDbStorageType, type TDbUpdateOptions, 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 TExprAggregate, type TFieldMeta, type TFieldOps, type TFilterPredicate, type TFilterRef, type TFirstLast, type TFkLookupResolver, type TFkLookupTarget, type TGenericLogger, type TGroupSourceVerdict, type TGuardedQuery, type TIdDescriptor, type TIdResolveOptions, type TIdentification, type TInsertOptions, type TMetaResponse, type TMetadataOverrides, type TPrimaryKeyChange, type TQueryPathKind, type TQueryPathOp, type TQueryPathRefs, type TQueryPathSource, type TReadColumnsKind, type TReadControls, type TReferencingForeignKey, type TRelationFilterJunction, type TRelationFilterTable, type TRelationInfo, type TRelationStaticFilter, type TResolvedBucket, type TRowOrderKey, type TRowResolveOptions, type TSearchIndexInfo, type TSearchMemberKind, type TSyncColumnResult, type TTableOptionDiff, type TTableResolver, type TTouchManyOptions, type TValueFormatterPair, type TViewCapability, type TViewColumnMapping, type TViewJoin, type TViewJsonType, type TViewPlan, type TViewReadPlan, type TWriteOptions, type TWriteTableResolver, TableMetadata, type TypedWithRelation, UniquSelect, type Uniquery, type UniqueryControls, type ValidationContext, type ValidatorMode, type WeekStart, type WithOptimisticRetryOptions, type WithRelation, acceptedOperatorsHint, aggregateExpressionsNotSupported, aggregateFailure, aliasTargetOf, andFilters, assertGeoPoint, assertNoVersionWrites, bucketSourceVerdict, bucketTimeZoneUnavailable, buildDbValidator, buildValidationContext, canFilterLeaf, checkHavingKeys, classifyQueryPath, collectQueryPaths, computeInsights, containsRelationFilter, createDbValidatorPlugin, createFailureCollector, decomposePatch, defaultFulltextIndex, deletePath, describeFulltext, evaluateExpr, findAncestorInSet, fkColumns, forEachResolvedRelation, forceNavNonOptional, geoIndexNotFoundMessage, getDbFieldOp, getKeyProps, getPath, groupSourceVerdict, guardAggregate, guardFilter, guardPath, guardPaths, guardQuery, hasRelationOp, isAtscriptDbView, isBucketableField, isColumnTypeChanged, isConflict, isDbEntityType, isDbFieldOp, isEmptyObject, isFieldRef, isGeoIndexableType, isGeoPointType, isJsonValueField, isNavRelation, isPlainObject, isPrimitive, isRelationOp, isResolvedRelationFilter, isRetryableDbError, isVersionExemptPatch, isViewType, jsonValueAncestor, narrowerFilterOps, normalizeComputedSelect, numericOperandProblem, queryReadColumns, reconcileCas, relationStaticFilter, resolveCalendarBuckets, resolveDesignType, searchIndexNotFoundMessage, searchMemberKind, searchTermInteger, selfOrAncestor, separateCas, separateFieldOps, sortFieldNames, splitFulltextFields, tableNameOf, translateQueryTree, uniqueKeyTuple, 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, INTEGER_REGEX_OP, IntegrityStrategy, NativeIntegrity, type NavPropsOf, NoopLogger, type NullableOptional, type NullsPlacement, 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 TDbInsertIgnoreOptions, type TDbInsertIgnoreResult, type TDbInsertIgnoreSlot, type TDbInsertManyIgnoreResult, type TDbInsertManyResult, type TDbInsertResult, type TDbObjectKind, type TDbPatch, type TDbReferentialAction, type TDbRelation, type TDbRemoveGuard, type TDbRemoveGuardContext, type TDbSpaceOptions, type TDbStorageType, type TDbUpdateOptions, 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 TExprAggregate, type TFieldMeta, type TFieldOps, type TFilterPredicate, type TFilterRef, type TFirstLast, type TFkLookupResolver, type TFkLookupTarget, type TGenericLogger, type TGroupSourceVerdict, type TGuardedQuery, type TIdDescriptor, type TIdResolveOptions, type TIdentification, type TInsertOptions, type TJsonCopyTarget, type TMetaResponse, type TMetadataOverrides, type TPathPresence, type TPrimaryKeyChange, type TQueryPathKind, type TQueryPathOp, type TQueryPathRefs, type TQueryPathSource, type TReadColumnsKind, type TReadControls, type TReferencingForeignKey, type TRelationFilterJunction, type TRelationFilterTable, type TRelationInfo, type TRelationStaticFilter, type TResolvedBucket, type TRowOrderKey, type TRowResolveOptions, type TSearchIndexInfo, type TSearchMemberKind, type TSyncColumnResult, type TSyncIndexesOptions, type TTableOptionDiff, type TTableResolver, type TTouchManyOptions, type TValueFormatterPair, type TViewCapability, type TViewColumnMapping, type TViewJoin, type TViewJsonType, type TViewPlan, type TViewReadPlan, type TWriteOptions, type TWriteTableResolver, TableMetadata, type TypedWithRelation, UniquSelect, type Uniquery, type UniqueryControls, type ValidationContext, type ValidatorMode, type WeekStart, type WithOptimisticRetryOptions, type WithRelation, acceptedOperatorsHint, aggregateExpressionsNotSupported, aggregateFailure, aliasTargetOf, andFilters, assertGeoPoint, assertNoVersionWrites, bucketSourceVerdict, bucketTimeZoneUnavailable, buildDbValidator, buildValidationContext, canFilterLeaf, checkHavingKeys, classifyQueryPath, collectQueryPaths, computeInsights, containsRelationFilter, createDbValidatorPlugin, createFailureCollector, decomposePatch, defaultFulltextIndex, deletePath, describeFulltext, evaluateExpr, findAncestorInSet, fkColumns, forEachResolvedRelation, forceNavNonOptional, geoIndexNotFoundMessage, getDbFieldOp, getKeyProps, getPath, groupSourceVerdict, guardAggregate, guardFilter, guardPath, guardPaths, guardQuery, hasRelationOp, isAtscriptDbView, isBucketableField, isColumnTypeChanged, isConflict, isDbEntityType, isDbFieldOp, isEmptyObject, isFieldRef, isGeoIndexableType, isGeoPointType, isJsonValueField, isNavRelation, isPlainObject, isPrimitive, isRelationOp, isResolvedRelationFilter, isRetryableDbError, isVersionExemptPatch, isViewType, jsonValueAncestor, narrowerFilterOps, normalizeComputedSelect, numericOperandProblem, queryReadColumns, reconcileCas, relationStaticFilter, resolveCalendarBuckets, resolveDesignType, searchIndexNotFoundMessage, searchMemberKind, searchTermInteger, selfOrAncestor, separateCas, separateFieldOps, sortFieldNames, splitFulltextFields, tableNameOf, translateQueryTree, uniqueKeyTuple, unsupportedOperatorMessage, vectorIndexNotFoundMessage, walkFilter, withOptimisticRetry };

package/dist/index.mjs

@@ -1,12 +1,12 @@
 import { a as aggregateExpressionsNotSupported, c as isConflict, l as isRetryableDbError, n as CasMismatchError, o as aggregateFailure, r as DbError, s as bucketTimeZoneUnavailable, t as CasExhaustedError, u as spaceClosedError } from "./db-error-eSsQX7rt.mjs";
-import { $ as DocumentFieldMapper, A as resolveDesignType, B as checkHavingKeys, C as ALL_BUCKET_UNITS, D as IntegrityStrategy, E as createFailureCollector, F as ENCRYPTED_REASON, G as guardFilter, H as collectQueryPaths, I as acceptedOperatorsHint, J as guardQuery, K as guardPath, L as assertGeoPoint, M as searchIndexNotFoundMessage, N as vectorIndexNotFoundMessage, O as NativeIntegrity, P as ADAPTER_FILTER_REASON, Q as RelationalFieldMapper, R as bucketSourceVerdict, S as ApplicationIntegrity, T as BaseDbAdapter, U as groupSourceVerdict, V as classifyQueryPath, W as guardAggregate, X as sortFieldNames, Y as narrowerFilterOps, Z as unsupportedOperatorMessage, _ as isViewType, _t as NoopLogger, at as describeFulltext, b as assertNoVersionWrites, ct as TableMetadata, dt as aliasTargetOf, et as FieldMappingStrategy, f as fkColumns, ft as isBucketableField, g as isAtscriptDbView, gt as resolveCalendarBuckets, h as AtscriptDbView, ht as normalizeComputedSelect, it as defaultFulltextIndex, j as geoIndexNotFoundMessage, k as AtscriptDbReadable, lt as isGeoIndexableType, mt as jsonValueAncestor, n as isColumnTypeChanged, nt as numericOperandProblem, ot as searchTermInteger, pt as isJsonValueField, q as guardPaths, rt as INTEGER_REGEX_OP, st as splitFulltextFields, tt as UniquSelect, ut as isGeoPointType, v as AtscriptDbTable, w as ALL_VIEW_CAPABILITIES, x as decomposePatch, y as isVersionExemptPatch, z as canFilterLeaf } from "./column-diff-DAIAq6XR.mjs";
+import { $ as RelationalFieldMapper, A as AtscriptDbReadable, B as canFilterLeaf, C as ApplicationIntegrity, D as createFailureCollector, E as BaseDbAdapter, F as ADAPTER_FILTER_REASON, G as guardAggregate, H as classifyQueryPath, I as ENCRYPTED_REASON, J as guardPaths, K as guardFilter, L as acceptedOperatorsHint, M as geoIndexNotFoundMessage, N as searchIndexNotFoundMessage, O as IntegrityStrategy, P as vectorIndexNotFoundMessage, Q as unsupportedOperatorMessage, R as assertGeoPoint, S as decomposePatch, T as ALL_VIEW_CAPABILITIES, U as collectQueryPaths, V as checkHavingKeys, W as groupSourceVerdict, X as narrowerFilterOps, Y as guardQuery, Z as sortFieldNames, _ as isAtscriptDbView, _t as normalizeComputedSelect, at as defaultFulltextIndex, b as isVersionExemptPatch, ct as splitFulltextFields, dt as isGeoPointType, et as DocumentFieldMapper, g as AtscriptDbView, gt as jsonValueAncestor, ht as isJsonValueField, it as INTEGER_REGEX_OP, j as resolveDesignType, k as NativeIntegrity, lt as TableMetadata, mt as isBucketableField, n as isColumnTypeChanged, nt as UniquSelect, ot as describeFulltext, p as fkColumns, pt as aliasTargetOf, q as guardPath, rt as numericOperandProblem, st as searchTermInteger, tt as FieldMappingStrategy, ut as isGeoIndexableType, v as isViewType, vt as resolveCalendarBuckets, w as ALL_BUCKET_UNITS, x as assertNoVersionWrites, y as AtscriptDbTable, yt as NoopLogger, z as bucketSourceVerdict } from "./column-diff-DR1glykD.mjs";
 import { n as ALL_AGGREGATE_FNS } from "./aggregate-fns-B_sgl4mB.mjs";
 import { A as hasRelationOp, C as REL_FILTER_MAX_DEPTH, D as containsRelationFilter, E as andFilters, G as evaluateExpr, H as tableNameOf, K as isFieldRef, P as relationStaticFilter, S as uniqueKeyTuple, T as ResolvedRelationFilter, j as isResolvedRelationFilter, k as forEachResolvedRelation, q as translateQueryTree, w as REL_FILTER_MAX_NODES } from "./nested-writer-BOj_c_lI.mjs";
-import { i as DB_ENTITY_ANNOTATIONS, n as searchMemberKind } from "./search-fields-DBIZKwyb.mjs";
+import { a as forceNavNonOptional, c as getKeyProps, o as isNavRelation, r as buildValidationContext, s as createDbValidatorPlugin, t as buildDbValidator } from "./validator-B3fPJjS1.mjs";
+import { i as DB_ENTITY_ANNOTATIONS, n as searchMemberKind } from "./search-fields-CE8cmj9X.mjs";
 import { a as isPlainObject, i as isEmptyObject, n as findAncestorInSet, o as selfOrAncestor, r as getPath, t as deletePath } from "./object-TkiJQ-Dp.mjs";
 import { t as DEFAULT_DB_SPACE } from "./consts-C_-5_pFq.mjs";
 import { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, getDbFieldOp, isDbFieldOp, reconcileCas, separateCas, separateFieldOps } from "./ops.mjs";
-import { a as forceNavNonOptional, c as getKeyProps, o as isNavRelation, r as buildValidationContext, s as createDbValidatorPlugin, t as buildDbValidator } from "./validator-BACewoRj.mjs";
 import { isAnnotatedType } from "@atscript/typescript/utils";
 import { RELATION_OPS, computeInsights, isPrimitive, isRelationOp, walkFilter } from "@uniqu/core";
 import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";

package/dist/plugin.cjs

@@ -34,9 +34,9 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 }) : target, mod));
 //#endregion
 const require_aggregate_fns = require("./aggregate-fns-DFtKAv7Q.cjs");
-const require_search_fields = require("./search-fields-DwrsJUC1.cjs");
+const require_search_fields = require("./search-fields-CT_UZ9fg.cjs");
 require("./consts-BzRfCcH2.cjs");
-const require_validation_utils = require("./validation-utils-debIYpq0.cjs");
+const require_validation_utils = require("./validation-utils-CtLNlBtB.cjs");
 let node_path = require("node:path");
 node_path = __toESM(node_path, 1);
 let node_url = require("node:url");
@@ -873,6 +873,21 @@ const dbColumnAnnotations = {
 			}
 		})
 	},
+	onUpdate: { now: new _atscript_core.AnnotationSpec({
+		description: "Sets the field to the current time (epoch ms) on every update: patches (`updateOne`, `bulkUpdate`, `updateMany`, HTTP `PATCH`) and replaces (`replaceOne`, `bulkReplace`, `replaceMany`, HTTP `PUT`). The value is written by the SDK in the same statement on every adapter and overrides a value the payload carries. Inserts are not affected — combine with `@db.default.now` (`number.timestamp.updated` applies both). Writes outside the SDK (raw SQL) do not set it.\n\n**Example:**\n```atscript\n@db.default.now\n@db.onUpdate.now\nupdatedAt: number.timestamp\n```\n",
+		nodeType: ["prop"],
+		passedWhenReferred: false,
+		validate(token, args, doc) {
+			const errors = require_validation_utils.validateFieldBaseType(token, doc, "@db.onUpdate.now", "number");
+			const field = token.parentNode;
+			for (const [name, why] of [["meta.id", "the primary key identifies the row and is never updated"], ["db.column.version", "the version column is adapter-managed"]]) if (field.countAnnotations(name) > 0) errors.push({
+				message: `@db.onUpdate.now cannot coexist with @${name} — ${why}`,
+				severity: 1,
+				range: token.range
+			});
+			return errors;
+		}
+	}) },
 	json: new _atscript_core.AnnotationSpec({
 		description: "Forces a field to be stored as a single JSON column instead of being flattened into separate columns. Use on nested object fields that should remain as JSON in the database.\n\n**Example:**\n```atscript\n@db.json\nmetadata: { key: string, value: string }\n```\n",
 		nodeType: ["prop"],
@@ -925,6 +940,7 @@ const dbColumnAnnotations = {
 				["db.column.version", "the OCC filter needs cleartext equality"],
 				["db.default.increment", "engine-side defaults bypass the encryption transform"],
 				["db.default.now", "engine-side defaults bypass the encryption transform"],
+				["db.onUpdate.now", "the update time is set after the encryption transform"],
 				["db.mongo.search.text", "Atlas Search over ciphertext is impossible"],
 				["db.mongo.search.autocomplete", "Atlas Search over ciphertext is impossible"]
 			]) if (field.countAnnotations(name) > 0) errors.push({
@@ -1701,7 +1717,7 @@ const dbSearchAnnotations = { search: {
 * read sorts by it without a `$nulls` entry for it.
 */
 const dbSortAnnotations = { sort: { nulls: new _atscript_core.AnnotationSpec({
-	description: "Default **NULL placement** when a read sorts by this field and the request names none (`$nulls` control, URL suffix `$sort=-closedAt:last`).\n\n- **`'first'`** — rows where the field is NULL (or missing) come before every value, in both sort directions\n- **`'last'`** — they come after every value, in both directions\n\nWithout it (and without `$nulls`) NULL placement is the database's own: first in ascending order on SQLite, MySQL, MongoDB and the in-memory adapter, last on PostgreSQL. Applies to `$sort` and to the `$rowOrder` of `first()` / `last()`. Only optional fields can be NULL — on a required table field it has no effect. On PostgreSQL, MySQL and MongoDB a placement the engine does not produce natively costs the index its ORDER BY (a sort step instead).\n\n**Example:**\n```atscript\n@db.sort.nulls 'last'\nclosedAt?: number.timestamp\n```\n",
+	description: "Default **NULL placement** when a read sorts by this field and the request names none (`$nulls` control, URL suffix `$sort=-closedAt:last`).\n\n- **`'first'`** — rows where the field is NULL (or missing) come before every value, in both sort directions\n- **`'last'`** — they come after every value, in both directions\n\nWithout it (and without `$nulls`) NULL placement is the database's own: first in ascending order on SQLite, MySQL, MongoDB and the in-memory adapter, last on PostgreSQL. Applies to `$sort` and to the `$rowOrder` of `first()` / `last()`. Only optional and `| null` fields can be NULL — on another required table field it has no effect. On PostgreSQL, MySQL and MongoDB a placement the engine does not produce natively costs the index its ORDER BY (a sort step instead).\n\n**Example:**\n```atscript\n@db.sort.nulls 'last'\nclosedAt?: number.timestamp\n```\n",
 	nodeType: ["prop"],
 	passedWhenReferred: false,
 	multiple: false,
@@ -1736,7 +1752,7 @@ const dbSortAnnotations = { sort: { nulls: new _atscript_core.AnnotationSpec({
 			return errors;
 		}
 		const owner = require_validation_utils.getDbTableOwner(token);
-		if (!field.has("optional") && owner && owner.countAnnotations("db.table") > 0 && field.ownerNode?.ownerNode === owner) fail("@db.sort.nulls on a required field has no effect — the field is never NULL; make it optional (field?: …) or remove the annotation", 2);
+		if (!field.has("optional") && !require_validation_utils.isNullableUnion(def, doc) && owner && owner.countAnnotations("db.table") > 0 && field.ownerNode?.ownerNode === owner) fail("@db.sort.nulls on a required field has no effect — the field is never NULL; make it optional (field?: …) or remove the annotation", 2);
 		return errors;
 	}
 }) } };
@@ -2319,6 +2335,7 @@ const dbPlugin = (options) => ({
 				index: dbIndexAnnotations.index,
 				column: dbColumnAnnotations.column,
 				default: dbColumnAnnotations.default,
+				onUpdate: dbColumnAnnotations.onUpdate,
 				json: dbColumnAnnotations.json,
 				ignore: dbColumnAnnotations.ignore,
 				encrypted: dbColumnAnnotations.encrypted,

package/dist/plugin.mjs

@@ -1,7 +1,7 @@
 import { i as NULL_WHEN_EMPTY_AGGREGATE_FNS, o as SUPPORTED_AGGREGATE_FNS, t as AGG_ANNOTATIONS } from "./aggregate-fns-B_sgl4mB.mjs";
-import { a as DERIVED_INCOMPATIBLE, i as DB_ENTITY_ANNOTATIONS, o as JSON_LEAF_TYPES, r as numericTypeProblem } from "./search-fields-DBIZKwyb.mjs";
+import { a as DERIVED_INCOMPATIBLE, i as DB_ENTITY_ANNOTATIONS, o as JSON_LEAF_TYPES, r as numericTypeProblem } from "./search-fields-CE8cmj9X.mjs";
 import "./consts-C_-5_pFq.mjs";
-import { C as validateFieldBaseType, S as validateExclusiveWith, _ as getParentTypeName, a as hasAnyViewAnnotation, b as refActionAnnotation, d as viewJoins, f as viewScopeTypes, g as getParentStruct, h as getNavTargetTypeName, i as forEachFieldRef, l as validateQueryScope, m as getDbTableOwner, n as findFKFieldsPointingTo, o as isAliasDecl, p as getAnnotationAlias, r as findViewCycle, s as isDbSourceDecl, t as earlierJoinTargets, u as validateRefArgument, v as integerMemberIndexProblem, w as validateSiblingStringField, x as searchFieldVerdict, y as primitiveBaseType } from "./validation-utils-DqZAH6aT.mjs";
+import { C as validateExclusiveWith, S as searchFieldVerdict, T as validateSiblingStringField, _ as getParentTypeName, a as hasAnyViewAnnotation, b as primitiveBaseType, d as viewJoins, f as viewScopeTypes, g as getParentStruct, h as getNavTargetTypeName, i as forEachFieldRef, l as validateQueryScope, m as getDbTableOwner, n as findFKFieldsPointingTo, o as isAliasDecl, p as getAnnotationAlias, r as findViewCycle, s as isDbSourceDecl, t as earlierJoinTargets, u as validateRefArgument, v as integerMemberIndexProblem, w as validateFieldBaseType, x as refActionAnnotation, y as isNullableUnion } from "./validation-utils-BGjqc2jU.mjs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { AnnotationSpec, DEFAULT_FORMAT, getFieldsForType, isArray, isInterface, isPrimitive, isProp, isQueryComparison, isQueryLogical, isRef, isStructure } from "@atscript/core";
@@ -837,6 +837,21 @@ const dbColumnAnnotations = {
 			}
 		})
 	},
+	onUpdate: { now: new AnnotationSpec({
+		description: "Sets the field to the current time (epoch ms) on every update: patches (`updateOne`, `bulkUpdate`, `updateMany`, HTTP `PATCH`) and replaces (`replaceOne`, `bulkReplace`, `replaceMany`, HTTP `PUT`). The value is written by the SDK in the same statement on every adapter and overrides a value the payload carries. Inserts are not affected — combine with `@db.default.now` (`number.timestamp.updated` applies both). Writes outside the SDK (raw SQL) do not set it.\n\n**Example:**\n```atscript\n@db.default.now\n@db.onUpdate.now\nupdatedAt: number.timestamp\n```\n",
+		nodeType: ["prop"],
+		passedWhenReferred: false,
+		validate(token, args, doc) {
+			const errors = validateFieldBaseType(token, doc, "@db.onUpdate.now", "number");
+			const field = token.parentNode;
+			for (const [name, why] of [["meta.id", "the primary key identifies the row and is never updated"], ["db.column.version", "the version column is adapter-managed"]]) if (field.countAnnotations(name) > 0) errors.push({
+				message: `@db.onUpdate.now cannot coexist with @${name} — ${why}`,
+				severity: 1,
+				range: token.range
+			});
+			return errors;
+		}
+	}) },
 	json: new AnnotationSpec({
 		description: "Forces a field to be stored as a single JSON column instead of being flattened into separate columns. Use on nested object fields that should remain as JSON in the database.\n\n**Example:**\n```atscript\n@db.json\nmetadata: { key: string, value: string }\n```\n",
 		nodeType: ["prop"],
@@ -889,6 +904,7 @@ const dbColumnAnnotations = {
 				["db.column.version", "the OCC filter needs cleartext equality"],
 				["db.default.increment", "engine-side defaults bypass the encryption transform"],
 				["db.default.now", "engine-side defaults bypass the encryption transform"],
+				["db.onUpdate.now", "the update time is set after the encryption transform"],
 				["db.mongo.search.text", "Atlas Search over ciphertext is impossible"],
 				["db.mongo.search.autocomplete", "Atlas Search over ciphertext is impossible"]
 			]) if (field.countAnnotations(name) > 0) errors.push({
@@ -1665,7 +1681,7 @@ const dbSearchAnnotations = { search: {
 * read sorts by it without a `$nulls` entry for it.
 */
 const dbSortAnnotations = { sort: { nulls: new AnnotationSpec({
-	description: "Default **NULL placement** when a read sorts by this field and the request names none (`$nulls` control, URL suffix `$sort=-closedAt:last`).\n\n- **`'first'`** — rows where the field is NULL (or missing) come before every value, in both sort directions\n- **`'last'`** — they come after every value, in both directions\n\nWithout it (and without `$nulls`) NULL placement is the database's own: first in ascending order on SQLite, MySQL, MongoDB and the in-memory adapter, last on PostgreSQL. Applies to `$sort` and to the `$rowOrder` of `first()` / `last()`. Only optional fields can be NULL — on a required table field it has no effect. On PostgreSQL, MySQL and MongoDB a placement the engine does not produce natively costs the index its ORDER BY (a sort step instead).\n\n**Example:**\n```atscript\n@db.sort.nulls 'last'\nclosedAt?: number.timestamp\n```\n",
+	description: "Default **NULL placement** when a read sorts by this field and the request names none (`$nulls` control, URL suffix `$sort=-closedAt:last`).\n\n- **`'first'`** — rows where the field is NULL (or missing) come before every value, in both sort directions\n- **`'last'`** — they come after every value, in both directions\n\nWithout it (and without `$nulls`) NULL placement is the database's own: first in ascending order on SQLite, MySQL, MongoDB and the in-memory adapter, last on PostgreSQL. Applies to `$sort` and to the `$rowOrder` of `first()` / `last()`. Only optional and `| null` fields can be NULL — on another required table field it has no effect. On PostgreSQL, MySQL and MongoDB a placement the engine does not produce natively costs the index its ORDER BY (a sort step instead).\n\n**Example:**\n```atscript\n@db.sort.nulls 'last'\nclosedAt?: number.timestamp\n```\n",
 	nodeType: ["prop"],
 	passedWhenReferred: false,
 	multiple: false,
@@ -1700,7 +1716,7 @@ const dbSortAnnotations = { sort: { nulls: new AnnotationSpec({
 			return errors;
 		}
 		const owner = getDbTableOwner(token);
-		if (!field.has("optional") && owner && owner.countAnnotations("db.table") > 0 && field.ownerNode?.ownerNode === owner) fail("@db.sort.nulls on a required field has no effect — the field is never NULL; make it optional (field?: …) or remove the annotation", 2);
+		if (!field.has("optional") && !isNullableUnion(def, doc) && owner && owner.countAnnotations("db.table") > 0 && field.ownerNode?.ownerNode === owner) fail("@db.sort.nulls on a required field has no effect — the field is never NULL; make it optional (field?: …) or remove the annotation", 2);
 		return errors;
 	}
 }) } };
@@ -2283,6 +2299,7 @@ const dbPlugin = (options) => ({
 				index: dbIndexAnnotations.index,
 				column: dbColumnAnnotations.column,
 				default: dbColumnAnnotations.default,
+				onUpdate: dbColumnAnnotations.onUpdate,
 				json: dbColumnAnnotations.json,
 				ignore: dbColumnAnnotations.ignore,
 				encrypted: dbColumnAnnotations.encrypted,

package/dist/rel.d.cts

@@ -1,6 +1,6 @@
-import { Gn as TGenericLogger, It as TTableResolver, Kt as TableMetadata, Vt as TWriteTableResolver, W as TDbForeignKey, Zt as BaseDbAdapter, h as AtscriptDbWritable, m as AtscriptDbTableLike, nt as TDbRelation } from "./buckets-jy8BfswO.cjs";
+import { Jn as TGenericLogger, Jt as TableMetadata, Rt as TTableResolver, Ut as TWriteTableResolver, W as TDbForeignKey, en as BaseDbAdapter, h as AtscriptDbWritable, m as AtscriptDbTableLike, nt as TDbRelation } from "./buckets-B4T_alUe.cjs";
 import { t as DbValidationContext } from "./db-validator-plugin-BWy60OvG.cjs";
-import { n as findRemoteFK, r as resolveRelationTargetTable, t as findFKForRelation } from "./relation-helpers-D_8bydc2.cjs";
+import { n as findRemoteFK, r as resolveRelationTargetTable, t as findFKForRelation } from "./relation-helpers-BLBrLQYi.cjs";
 import { FilterExpr, WithRelation } from "@uniqu/core";
 import { Validator } from "@atscript/typescript/utils";
 

package/dist/rel.d.mts

@@ -1,6 +1,6 @@
-import { Gn as TGenericLogger, It as TTableResolver, Kt as TableMetadata, Vt as TWriteTableResolver, W as TDbForeignKey, Zt as BaseDbAdapter, h as AtscriptDbWritable, m as AtscriptDbTableLike, nt as TDbRelation } from "./buckets-CBKL_ZWE.mjs";
+import { Jn as TGenericLogger, Jt as TableMetadata, Rt as TTableResolver, Ut as TWriteTableResolver, W as TDbForeignKey, en as BaseDbAdapter, h as AtscriptDbWritable, m as AtscriptDbTableLike, nt as TDbRelation } from "./buckets-8mG67Mtw.mjs";
 import { t as DbValidationContext } from "./db-validator-plugin-BWy60OvG.mjs";
-import { n as findRemoteFK, r as resolveRelationTargetTable, t as findFKForRelation } from "./relation-helpers-BUsxNNGU.mjs";
+import { n as findRemoteFK, r as resolveRelationTargetTable, t as findFKForRelation } from "./relation-helpers-17_2f5hX.mjs";
 import { Validator } from "@atscript/typescript/utils";
 import { FilterExpr, WithRelation } from "@uniqu/core";
 

package/dist/{relation-helpers-BUsxNNGU.d.mts → relation-helpers-17_2f5hX.d.mts}

@@ -1,4 +1,4 @@
-import { W as TDbForeignKey, nt as TDbRelation } from "./buckets-CBKL_ZWE.mjs";
+import { W as TDbForeignKey, nt as TDbRelation } from "./buckets-8mG67Mtw.mjs";
 import { TAtscriptAnnotatedType } from "@atscript/typescript/utils";
 
 //#region src/rel/relation-helpers.d.ts

package/dist/{relation-helpers-D_8bydc2.d.cts → relation-helpers-BLBrLQYi.d.cts}

@@ -1,4 +1,4 @@
-import { W as TDbForeignKey, nt as TDbRelation } from "./buckets-jy8BfswO.cjs";
+import { W as TDbForeignKey, nt as TDbRelation } from "./buckets-B4T_alUe.cjs";
 import { TAtscriptAnnotatedType } from "@atscript/typescript/utils";
 
 //#region src/rel/relation-helpers.d.ts

package/dist/{search-fields-DBIZKwyb.mjs → search-fields-CE8cmj9X.mjs}

@@ -29,6 +29,7 @@ const DERIVED_INCOMPATIBLE = [
 	["db.default.increment", "the value is computed, never defaulted"],
 	["db.default.uuid", "the value is computed, never defaulted"],
 	["db.default.now", "the value is computed, never defaulted"],
+	["db.onUpdate.now", "a derived column is never written"],
 	["db.column.version", "the version column is adapter-managed"],
 	["db.column.version.exempt", "a derived column is never written"],
 	["db.encrypted", "the value is a cleartext extraction of its source"],

package/dist/{search-fields-DwrsJUC1.cjs → search-fields-CT_UZ9fg.cjs}

@@ -29,6 +29,7 @@ const DERIVED_INCOMPATIBLE = [
 	["db.default.increment", "the value is computed, never defaulted"],
 	["db.default.uuid", "the value is computed, never defaulted"],
 	["db.default.now", "the value is computed, never defaulted"],
+	["db.onUpdate.now", "a derived column is never written"],
 	["db.column.version", "the version column is adapter-managed"],
 	["db.column.version.exempt", "a derived column is never written"],
 	["db.encrypted", "the value is a cleartext extraction of its source"],

package/dist/shared.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_aggregate_rules = require("./aggregate-rules-D_bsCpUI.cjs");
-const require_validation_utils = require("./validation-utils-debIYpq0.cjs");
+const require_validation_utils = require("./validation-utils-CtLNlBtB.cjs");
 exports.NOT_DIMENSION_REASON = require_aggregate_rules.NOT_DIMENSION_REASON;
 exports.earlierJoinTargets = require_validation_utils.earlierJoinTargets;
 exports.findFKFieldsPointingTo = require_validation_utils.findFKFieldsPointingTo;
@@ -15,6 +15,7 @@ exports.hasAnyViewAnnotation = require_validation_utils.hasAnyViewAnnotation;
 exports.integerMemberIndexProblem = require_validation_utils.integerMemberIndexProblem;
 exports.isAliasDecl = require_validation_utils.isAliasDecl;
 exports.isDbSourceDecl = require_validation_utils.isDbSourceDecl;
+exports.isNullableUnion = require_validation_utils.isNullableUnion;
 exports.isStrictAggregateStruct = require_aggregate_rules.isStrictAggregateStruct;
 exports.joinTargets = require_validation_utils.joinTargets;
 exports.primitiveBaseType = require_validation_utils.primitiveBaseType;

package/dist/shared.d.cts

@@ -8,6 +8,12 @@ declare function validateExclusiveWith(token: Token, selfName: string, others: A
 }>): TMessages;
 /** Primitive base type (`string`, `number`, `decimal`, …) of a resolved definition, if it is a primitive. */
 declare function primitiveBaseType(def: SemanticNode | undefined): string | undefined;
+/**
+ * Whether a definition is a union with a `null` member — `T | null`, or a
+ * ref to an alias of one (compile-time mirror of the runtime nullable union,
+ * since 0.1.155).
+ */
+declare function isNullableUnion(def: SemanticNode | undefined, doc: AtscriptDoc, depth?: number): boolean;
 /**
  * Whether a prop takes part in `$search` as text or as an integer, or why it
  * cannot (compile-time mirror of the runtime `searchMemberKind`). Anything
@@ -22,8 +28,9 @@ declare function searchFieldVerdict(field: SemanticNode, doc: AtscriptDoc): {
 /**
  * Why an integer fulltext member is not index-backed (its exact-number match
  * would scan — or fail on MongoDB next to `$text`), or `undefined`. Backed:
- * `_id`, the first `@meta.id` of the type, or the first field (in declaration
- * order) of a `@db.index.plain` / `@db.index.unique` group.
+ * `_id` or the first `@meta.id` of an interface's own fields (an inline
+ * nested object's are no key of the row, like at runtime), or the first field
+ * (in declaration order) of a `@db.index.plain` / `@db.index.unique` group.
  */
 declare function integerMemberIndexProblem(token: Token): string | undefined;
 /** Asserts `args[0]` names a sibling property whose primitive base type is `string`. */
@@ -157,4 +164,4 @@ declare const NOT_DIMENSION_REASON = "not a dimension";
  */
 declare function isStrictAggregateStruct(struct: SemanticStructureNode): boolean;
 //#endregion
-export { NOT_DIMENSION_REASON, TFKFieldMatch, TRefArgumentOptions, earlierJoinTargets, findFKFieldsPointingTo, findViewCycle, forEachFieldRef, getAnnotationAlias, getDbTableOwner, getNavTargetTypeName, getParentStruct, getParentTypeName, hasAnyViewAnnotation, integerMemberIndexProblem, isAliasDecl, isDbSourceDecl, isStrictAggregateStruct, joinTargets, primitiveBaseType, refActionAnnotation, searchFieldVerdict, validateExclusiveWith, validateFieldBaseType, validateQueryScope, validateRefArgument, validateSiblingStringField, viewJoins, viewScopeTypes };
+export { NOT_DIMENSION_REASON, TFKFieldMatch, TRefArgumentOptions, earlierJoinTargets, findFKFieldsPointingTo, findViewCycle, forEachFieldRef, getAnnotationAlias, getDbTableOwner, getNavTargetTypeName, getParentStruct, getParentTypeName, hasAnyViewAnnotation, integerMemberIndexProblem, isAliasDecl, isDbSourceDecl, isNullableUnion, isStrictAggregateStruct, joinTargets, primitiveBaseType, refActionAnnotation, searchFieldVerdict, validateExclusiveWith, validateFieldBaseType, validateQueryScope, validateRefArgument, validateSiblingStringField, viewJoins, viewScopeTypes };

package/dist/shared.d.mts

@@ -8,6 +8,12 @@ declare function validateExclusiveWith(token: Token, selfName: string, others: A
 }>): TMessages;
 /** Primitive base type (`string`, `number`, `decimal`, …) of a resolved definition, if it is a primitive. */
 declare function primitiveBaseType(def: SemanticNode | undefined): string | undefined;
+/**
+ * Whether a definition is a union with a `null` member — `T | null`, or a
+ * ref to an alias of one (compile-time mirror of the runtime nullable union,
+ * since 0.1.155).
+ */
+declare function isNullableUnion(def: SemanticNode | undefined, doc: AtscriptDoc, depth?: number): boolean;
 /**
  * Whether a prop takes part in `$search` as text or as an integer, or why it
  * cannot (compile-time mirror of the runtime `searchMemberKind`). Anything
@@ -22,8 +28,9 @@ declare function searchFieldVerdict(field: SemanticNode, doc: AtscriptDoc): {
 /**
  * Why an integer fulltext member is not index-backed (its exact-number match
  * would scan — or fail on MongoDB next to `$text`), or `undefined`. Backed:
- * `_id`, the first `@meta.id` of the type, or the first field (in declaration
- * order) of a `@db.index.plain` / `@db.index.unique` group.
+ * `_id` or the first `@meta.id` of an interface's own fields (an inline
+ * nested object's are no key of the row, like at runtime), or the first field
+ * (in declaration order) of a `@db.index.plain` / `@db.index.unique` group.
  */
 declare function integerMemberIndexProblem(token: Token): string | undefined;
 /** Asserts `args[0]` names a sibling property whose primitive base type is `string`. */
@@ -157,4 +164,4 @@ declare const NOT_DIMENSION_REASON = "not a dimension";
  */
 declare function isStrictAggregateStruct(struct: SemanticStructureNode): boolean;
 //#endregion
-export { NOT_DIMENSION_REASON, TFKFieldMatch, TRefArgumentOptions, earlierJoinTargets, findFKFieldsPointingTo, findViewCycle, forEachFieldRef, getAnnotationAlias, getDbTableOwner, getNavTargetTypeName, getParentStruct, getParentTypeName, hasAnyViewAnnotation, integerMemberIndexProblem, isAliasDecl, isDbSourceDecl, isStrictAggregateStruct, joinTargets, primitiveBaseType, refActionAnnotation, searchFieldVerdict, validateExclusiveWith, validateFieldBaseType, validateQueryScope, validateRefArgument, validateSiblingStringField, viewJoins, viewScopeTypes };
+export { NOT_DIMENSION_REASON, TFKFieldMatch, TRefArgumentOptions, earlierJoinTargets, findFKFieldsPointingTo, findViewCycle, forEachFieldRef, getAnnotationAlias, getDbTableOwner, getNavTargetTypeName, getParentStruct, getParentTypeName, hasAnyViewAnnotation, integerMemberIndexProblem, isAliasDecl, isDbSourceDecl, isNullableUnion, isStrictAggregateStruct, joinTargets, primitiveBaseType, refActionAnnotation, searchFieldVerdict, validateExclusiveWith, validateFieldBaseType, validateQueryScope, validateRefArgument, validateSiblingStringField, viewJoins, viewScopeTypes };

package/dist/shared.mjs

@@ -1,3 +1,3 @@
 import { n as isStrictAggregateStruct, t as NOT_DIMENSION_REASON } from "./aggregate-rules-jdPrxqWa.mjs";
-import { C as validateFieldBaseType, S as validateExclusiveWith, _ as getParentTypeName, a as hasAnyViewAnnotation, b as refActionAnnotation, c as joinTargets, d as viewJoins, f as viewScopeTypes, g as getParentStruct, h as getNavTargetTypeName, i as forEachFieldRef, l as validateQueryScope, m as getDbTableOwner, n as findFKFieldsPointingTo, o as isAliasDecl, p as getAnnotationAlias, r as findViewCycle, s as isDbSourceDecl, t as earlierJoinTargets, u as validateRefArgument, v as integerMemberIndexProblem, w as validateSiblingStringField, x as searchFieldVerdict, y as primitiveBaseType } from "./validation-utils-DqZAH6aT.mjs";
-export { NOT_DIMENSION_REASON, earlierJoinTargets, findFKFieldsPointingTo, findViewCycle, forEachFieldRef, getAnnotationAlias, getDbTableOwner, getNavTargetTypeName, getParentStruct, getParentTypeName, hasAnyViewAnnotation, integerMemberIndexProblem, isAliasDecl, isDbSourceDecl, isStrictAggregateStruct, joinTargets, primitiveBaseType, refActionAnnotation, searchFieldVerdict, validateExclusiveWith, validateFieldBaseType, validateQueryScope, validateRefArgument, validateSiblingStringField, viewJoins, viewScopeTypes };
+import { C as validateExclusiveWith, S as searchFieldVerdict, T as validateSiblingStringField, _ as getParentTypeName, a as hasAnyViewAnnotation, b as primitiveBaseType, c as joinTargets, d as viewJoins, f as viewScopeTypes, g as getParentStruct, h as getNavTargetTypeName, i as forEachFieldRef, l as validateQueryScope, m as getDbTableOwner, n as findFKFieldsPointingTo, o as isAliasDecl, p as getAnnotationAlias, r as findViewCycle, s as isDbSourceDecl, t as earlierJoinTargets, u as validateRefArgument, v as integerMemberIndexProblem, w as validateFieldBaseType, x as refActionAnnotation, y as isNullableUnion } from "./validation-utils-BGjqc2jU.mjs";
+export { NOT_DIMENSION_REASON, earlierJoinTargets, findFKFieldsPointingTo, findViewCycle, forEachFieldRef, getAnnotationAlias, getDbTableOwner, getNavTargetTypeName, getParentStruct, getParentTypeName, hasAnyViewAnnotation, integerMemberIndexProblem, isAliasDecl, isDbSourceDecl, isNullableUnion, isStrictAggregateStruct, joinTargets, primitiveBaseType, refActionAnnotation, searchFieldVerdict, validateExclusiveWith, validateFieldBaseType, validateQueryScope, validateRefArgument, validateSiblingStringField, viewJoins, viewScopeTypes };