@lossless.org/client 0.1.0

package/ts/nosqldb/classes.doc.ts

@@ -0,0 +1,4928 @@
+import * as plugins from './plugins.js';
+
+import { SmartdataDb } from './classes.db.js';
+import { logger } from './logging.js';
+import { SmartdataDbCursor } from './classes.cursor.js';
+import { runCursorOperation } from './classes.cursoroperation.js';
+import {
+  insertBootstrapRecord, type ISmartdataBootstrapRecordOptions, type ISmartdataBootstrapRecordResult,
+} from './classes.bootstraprecord.js';
+import {
+  validateCollectionPreparationOptions, type ISmartdataCollectionPreparationOptions,
+} from './classes.collectionpreparation.js';
+import { getOrdinaryPersistencePolicy, validateOrdinaryStoredDocument } from './classes.ordinarypersistence.js';
+import {
+  inspectStoredDocuments, inspectStoredDocumentEvidence,
+  type ISmartdataStoredInspectionOptions, type ISmartdataStoredInspection,
+  type ISmartdataStoredEvidenceInspection,
+} from './classes.storedinspection.js';
+import {
+  type IManager,
+  type ISmartdataIndexInfo,
+  SmartdataCollection,
+} from './classes.collection.js';
+import { SmartdataDbWatcher } from './classes.watcher.js';
+import { SmartdataLuceneAdapter } from './classes.lucene.adapter.js';
+import { executeAtomicDelete, executeAtomicDeleteMany } from './classes.atomicdelete.js';
+import { executeAtomicFindOneAndUpdate } from './classes.atomicfindoneandupdate.js';
+import { executeAtomicUpdate, executeAtomicUpdateMany } from './classes.atomicupdate.js';
+import {
+  SmartdataPersistenceError,
+} from './classes.persistence.js';
+import {
+  isOrdinarySessionInTransaction,
+  runWithOrdinarySmartdataSession,
+  type TSmartdataOrdinarySession,
+} from './classes.session.js';
+import {
+  getExpectedCollectionTopologyForModel,
+  inspectCollectionTopologyForModel,
+  type ISmartdataCollectionTopologyInspection,
+  type ISmartdataExpectedCollectionTopology,
+} from './classes.collectiontopology.js';
+/**
+ * Search options for `.search()`:
+ * - filter: additional MongoDB query to AND-merge
+ * - validate: post-fetch validator, return true to keep a doc
+ */
+export interface SearchOptions<T> {
+  /**
+   * Additional MongoDB filter to AND‐merge into the query
+   */
+  filter?: Record<string, any>;
+  /**
+   * Post‐fetch validator; return true to keep each doc
+   */
+  validate?: (doc: T) => Promise<boolean> | boolean;
+  /**
+   * Optional MongoDB session for transactional operations
+   */
+  session?: TSmartdataOrdinarySession;
+}
+
+export type TDocCreation = 'db' | 'new' | 'mixed';
+export type TSmartdataPrimaryId<T> = T extends { _id: infer TId }
+  ? Extract<TId, string | plugins.mongodb.ObjectId>
+  : plugins.mongodb.ObjectId;
+
+const exactPersistencePolicySymbol = Symbol.for(
+  '@push.rocks/smartdata.exactPersistencePolicy',
+);
+
+// Type for decorator metadata - extends TypeScript's built-in DecoratorMetadataObject
+interface ISmartdataDecoratorMetadata extends DecoratorMetadataObject {
+  globalSaveableProperties?: string[];
+  saveableProperties?: string[];
+  uniqueIndexes?: string[];
+  identityValueTypes?: Record<string, TSmartdataIdentityValueType>;
+  regularIndexes?: Array<{field: string, options: IIndexOptions}>;
+  compoundIndexes?: Array<{
+    name: string;
+    key: Record<string, 1 | -1>;
+    options?: Omit<plugins.mongodb.CreateIndexesOptions, 'name'>;
+  }>;
+  searchableFields?: string[];
+  _svDbOptions?: Record<string, SvDbOptions>;
+}
+
+export type TSmartdataIdentityValueType =
+  | 'string'
+  | 'positiveSafeInteger';
+
+export interface IUnIOptions {
+  /**
+   * Runtime value contract for this identity field. The default remains a
+   * non-empty string. Numeric identities require an explicit opt-in.
+   */
+  valueType?: TSmartdataIdentityValueType;
+}
+
+/**
+ * Detects plain object literals only. Anything carrying a custom prototype
+ * (Date, ObjectId, Binary, Buffer, RegExp, Decimal128, class instances, ...) is
+ * deliberately excluded so that BSON types are never rebuilt or otherwise
+ * altered while stripping undefined values.
+ */
+const isPlainObject = (valueArg: unknown): valueArg is Record<string, unknown> => {
+  if (typeof valueArg !== 'object' || valueArg === null) {
+    return false;
+  }
+  const prototype = Object.getPrototypeOf(valueArg);
+  return prototype === Object.prototype || prototype === null;
+};
+
+/**
+ * Recursively drops object properties whose value is `undefined` so MongoDB
+ * stores them as absent rather than as BSON null.
+ *
+ * Notes on the deliberate boundaries of this traversal:
+ * - Array positions are preserved: an `undefined` element stays in place and is
+ *   serialized as null, exactly as `JSON.stringify` does. Removing it would
+ *   shift every following index.
+ * - Only plain objects are recursed into, so BSON types keep their identity.
+ * - On a circular structure the offending value is returned untouched, letting
+ *   BSON raise its usual "Cannot convert circular structure to BSON" error
+ *   instead of overflowing the stack here.
+ */
+const stripUndefinedValues = <T>(valueArg: T, seenArg?: WeakSet<object>): T => {
+  if (typeof valueArg !== 'object' || valueArg === null) {
+    return valueArg;
+  }
+  const isArray = Array.isArray(valueArg);
+  if (!isArray && !isPlainObject(valueArg)) {
+    return valueArg;
+  }
+  const seen = seenArg ?? new WeakSet<object>();
+  if (seen.has(valueArg as object)) {
+    return valueArg;
+  }
+  seen.add(valueArg as object);
+  if (isArray) {
+    return (valueArg as unknown[]).map((entryArg) =>
+      entryArg === undefined ? null : stripUndefinedValues(entryArg, seen),
+    ) as unknown as T;
+  }
+  const strippedObject: Record<string, unknown> = {};
+  for (const keyArg of Object.keys(valueArg as Record<string, unknown>)) {
+    const entry = (valueArg as Record<string, unknown>)[keyArg];
+    if (entry === undefined) {
+      continue;
+    }
+    strippedObject[keyArg] = stripUndefinedValues(entry, seen);
+  }
+  return strippedObject as unknown as T;
+};
+
+export function globalSvDb() {
+  return (value: undefined, context: ClassFieldDecoratorContext) => {
+    if (context.kind !== 'field') {
+      throw new Error('globalSvDb can only decorate fields');
+    }
+
+    // Store metadata at class level using Symbol.metadata
+    const metadata = context.metadata as ISmartdataDecoratorMetadata;
+    if (
+      !Object.prototype.hasOwnProperty.call(
+        metadata,
+        'globalSaveableProperties',
+      )
+    ) {
+      metadata.globalSaveableProperties = [
+        ...(metadata.globalSaveableProperties || []),
+      ];
+    }
+    const propName = String(context.name);
+    if (!metadata.globalSaveableProperties!.includes(propName)) {
+      metadata.globalSaveableProperties!.push(propName);
+    }
+
+    // Use addInitializer to ensure prototype arrays are set up once
+    context.addInitializer(function(this: any) {
+      const proto = this.constructor.prototype;
+      const metadata = this.constructor[Symbol.metadata];
+
+      if (metadata && metadata.globalSaveableProperties && !proto.globalSaveableProperties) {
+        // Initialize prototype array from metadata (runs once per class)
+        proto.globalSaveableProperties = [...metadata.globalSaveableProperties];
+      }
+    });
+  };
+}
+
+/**
+ * Options for custom serialization/deserialization of a field.
+ */
+export interface SvDbOptions {
+  /** Function to serialize the field value before saving to DB */
+  serialize?: (value: any) => any;
+  /** Function to deserialize the field value after reading from DB */
+  deserialize?: (value: any) => any;
+  /**
+   * Explicit relative nested paths that atomic filters and updates may target
+   * below this persisted field.
+   */
+  atomicPaths?: readonly string[];
+  /**
+   * Declares this persisted top-level field as numeric for strict atomic
+   * expression references.
+   */
+  numeric?: boolean;
+}
+
+/**
+ * saveable - saveable decorator to be used on class properties
+ */
+export function svDb(options?: SvDbOptions) {
+  if (options?.numeric !== undefined && typeof options.numeric !== 'boolean') {
+    throw new SmartdataPersistenceError(
+      'invalid_configuration',
+      'svDb numeric must be a boolean.',
+    );
+  }
+  const storedOptions = options
+    ? {
+        ...options,
+        ...(options.atomicPaths !== undefined
+          ? {
+              atomicPaths: Array.isArray(options.atomicPaths)
+                ? [...options.atomicPaths]
+                : options.atomicPaths,
+            }
+          : {}),
+      }
+    : undefined;
+  return (value: undefined, context: ClassFieldDecoratorContext) => {
+    if (context.kind !== 'field') {
+      throw new Error('svDb can only decorate fields');
+    }
+
+    const propName = String(context.name);
+
+    // Store metadata at class level using Symbol.metadata
+    const metadata = context.metadata as ISmartdataDecoratorMetadata;
+    if (!Object.prototype.hasOwnProperty.call(metadata, 'saveableProperties')) {
+      metadata.saveableProperties = [...(metadata.saveableProperties || [])];
+    }
+    if (!metadata.saveableProperties!.includes(propName)) {
+      metadata.saveableProperties!.push(propName);
+    }
+
+    // Store options in metadata
+    if (storedOptions) {
+      if (!Object.prototype.hasOwnProperty.call(metadata, '_svDbOptions')) {
+        metadata._svDbOptions = { ...(metadata._svDbOptions || {}) };
+      }
+      metadata._svDbOptions![propName] = storedOptions;
+    }
+
+    // Use addInitializer to ensure prototype arrays are set up once
+    context.addInitializer(function(this: any) {
+      const proto = this.constructor.prototype;
+      const ctor = this.constructor;
+      const metadata = ctor[Symbol.metadata];
+
+      if (metadata && metadata.saveableProperties && !proto.saveableProperties) {
+        // Initialize prototype array from metadata (runs once per class)
+        proto.saveableProperties = [...metadata.saveableProperties];
+      }
+
+      // Initialize svDbOptions from metadata
+      if (metadata && metadata._svDbOptions && !ctor._svDbOptions) {
+        ctor._svDbOptions = { ...metadata._svDbOptions };
+      }
+    });
+  };
+}
+
+/**
+ * searchable - marks a property as searchable with Lucene query syntax
+ */
+export function searchable() {
+  return (value: undefined, context: ClassFieldDecoratorContext) => {
+    if (context.kind !== 'field') {
+      throw new Error('searchable can only decorate fields');
+    }
+
+    const propName = String(context.name);
+
+    // Store metadata at class level
+    const metadata = context.metadata as ISmartdataDecoratorMetadata;
+    if (!Object.prototype.hasOwnProperty.call(metadata, 'searchableFields')) {
+      metadata.searchableFields = [...(metadata.searchableFields || [])];
+    }
+    if (!metadata.searchableFields!.includes(propName)) {
+      metadata.searchableFields!.push(propName);
+    }
+
+    // Use addInitializer to set up constructor property once
+    context.addInitializer(function(this: any) {
+      const ctor = this.constructor as any;
+      const metadata = ctor[Symbol.metadata];
+
+      if (metadata && metadata.searchableFields && !Array.isArray(ctor.searchableFields)) {
+        // Initialize from metadata (runs once per class)
+        ctor.searchableFields = [...metadata.searchableFields];
+      }
+    });
+  };
+}
+
+// Escape user input for safe use in MongoDB regular expressions
+function escapeForRegex(input: string): string {
+  return input.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * unique index - decorator to mark a unique index
+ */
+export function unI(optionsArg: IUnIOptions = {}) {
+  if (
+    typeof optionsArg !== 'object'
+    || optionsArg === null
+    || Array.isArray(optionsArg)
+    || Object.keys(optionsArg).some((keyArg) => keyArg !== 'valueType')
+  ) {
+    throw new SmartdataPersistenceError(
+      'invalid_configuration',
+      'unI options must be an object containing only valueType.',
+    );
+  }
+  const valueType = optionsArg.valueType ?? 'string';
+  if (valueType !== 'string' && valueType !== 'positiveSafeInteger') {
+    throw new SmartdataPersistenceError(
+      'invalid_configuration',
+      'unI valueType must be "string" or "positiveSafeInteger".',
+    );
+  }
+  return (value: undefined, context: ClassFieldDecoratorContext) => {
+    if (context.kind !== 'field') {
+      throw new Error('unI can only decorate fields');
+    }
+
+    const propName = String(context.name);
+
+    // Store metadata at class level
+    const metadata = context.metadata as ISmartdataDecoratorMetadata;
+    if (!Object.prototype.hasOwnProperty.call(metadata, 'uniqueIndexes')) {
+      metadata.uniqueIndexes = [...(metadata.uniqueIndexes || [])];
+    }
+    if (!metadata.uniqueIndexes!.includes(propName)) {
+      metadata.uniqueIndexes!.push(propName);
+    }
+    if (
+      !Object.prototype.hasOwnProperty.call(metadata, 'identityValueTypes')
+    ) {
+      metadata.identityValueTypes = { ...(metadata.identityValueTypes || {}) };
+    }
+    const existingValueType = metadata.identityValueTypes![propName];
+    if (existingValueType && existingValueType !== valueType) {
+      throw new SmartdataPersistenceError(
+        'invalid_configuration',
+        `Identity field "${propName}" has divergent valueType declarations.`,
+      );
+    }
+    metadata.identityValueTypes![propName] = valueType;
+
+    // Also mark as saveable
+    if (!Object.prototype.hasOwnProperty.call(metadata, 'saveableProperties')) {
+      metadata.saveableProperties = [...(metadata.saveableProperties || [])];
+    }
+    if (!metadata.saveableProperties!.includes(propName)) {
+      metadata.saveableProperties!.push(propName);
+    }
+
+    // Use addInitializer to ensure prototype arrays are set up once
+    context.addInitializer(function(this: any) {
+      const proto = this.constructor.prototype;
+      const metadata = this.constructor[Symbol.metadata];
+
+      if (metadata && metadata.uniqueIndexes && !proto.uniqueIndexes) {
+        proto.uniqueIndexes = [...metadata.uniqueIndexes];
+      }
+
+      if (
+        metadata
+        && metadata.identityValueTypes
+        && !Object.prototype.hasOwnProperty.call(proto, 'identityValueTypes')
+      ) {
+        proto.identityValueTypes = { ...metadata.identityValueTypes };
+      }
+
+      if (metadata && metadata.saveableProperties && !proto.saveableProperties) {
+        proto.saveableProperties = [...metadata.saveableProperties];
+      }
+    });
+  };
+}
+
+/**
+ * Options for MongoDB indexes
+ */
+export interface IIndexOptions {
+  background?: boolean;
+  unique?: boolean;
+  sparse?: boolean;
+  expireAfterSeconds?: number;
+  [key: string]: any;
+}
+
+/**
+ * index - decorator to mark a field for regular indexing
+ */
+export function index(options?: IIndexOptions) {
+  return (value: undefined, context: ClassFieldDecoratorContext) => {
+    if (context.kind !== 'field') {
+      throw new Error('index can only decorate fields');
+    }
+
+    const propName = String(context.name);
+
+    // Store metadata at class level
+    const metadata = context.metadata as ISmartdataDecoratorMetadata;
+    if (!Object.prototype.hasOwnProperty.call(metadata, 'regularIndexes')) {
+      metadata.regularIndexes = [...(metadata.regularIndexes || [])];
+    }
+    metadata.regularIndexes!.push({
+      field: propName,
+      options: { ...(options || {}) }
+    });
+
+    // Also mark as saveable
+    if (!Object.prototype.hasOwnProperty.call(metadata, 'saveableProperties')) {
+      metadata.saveableProperties = [...(metadata.saveableProperties || [])];
+    }
+    if (!metadata.saveableProperties!.includes(propName)) {
+      metadata.saveableProperties!.push(propName);
+    }
+
+    // Use addInitializer to ensure prototype arrays are set up once
+    context.addInitializer(function(this: any) {
+      const proto = this.constructor.prototype;
+      const metadata = this.constructor[Symbol.metadata];
+
+      if (metadata && metadata.regularIndexes && !proto.regularIndexes) {
+        proto.regularIndexes = [...metadata.regularIndexes];
+      }
+
+      if (metadata && metadata.saveableProperties && !proto.saveableProperties) {
+        proto.saveableProperties = [...metadata.saveableProperties];
+      }
+    });
+  };
+}
+
+// Helper type to extract element type from arrays or return T itself
+type ElementOf<T> = T extends ReadonlyArray<infer U> ? U : T;
+
+// Type for $in/$nin values - arrays of the element type
+type InValues<T> = ReadonlyArray<ElementOf<T>>;
+
+// Type that allows MongoDB operators on leaf values while maintaining nested type safety
+export type MongoFilterCondition<T> = T | {
+  $eq?: T;
+  $ne?: T;
+  $gt?: T;
+  $gte?: T;
+  $lt?: T;
+  $lte?: T;
+  $in?: InValues<T>;
+  $nin?: InValues<T>;
+  $exists?: boolean;
+  $type?: string | number;
+  $regex?: string | RegExp;
+  $options?: string;
+  $all?: T extends ReadonlyArray<infer U> ? ReadonlyArray<U> : never;
+  $elemMatch?: T extends ReadonlyArray<infer U> ? MongoFilter<U> : never;
+  $size?: T extends ReadonlyArray<any> ? number : never;
+  $not?: MongoFilterCondition<T>;
+};
+
+export type MongoFilter<T> = {
+  [K in keyof T]?: T[K] extends object 
+    ? T[K] extends any[]
+      ? MongoFilterCondition<T[K]>  // Arrays can have operators
+      : MongoFilter<T[K]> | MongoFilterCondition<T[K]>  // Objects can be nested or have operators
+    : MongoFilterCondition<T[K]>;  // Primitives get operators
+} & {
+  // Logical operators
+  $and?: MongoFilter<T>[];
+  $or?: MongoFilter<T>[];
+  $nor?: MongoFilter<T>[];
+  $not?: MongoFilter<T>;
+  // Allow any string key for dot notation (we lose type safety here but maintain flexibility)
+  [key: string]: any;
+};
+
+export type TSmartdataDocumentPath<T> = keyof T & string;
+
+export type TSmartdataAtomicNestedDocumentPath<T> =
+  `${TSmartdataDocumentPath<T>}.${string}`;
+
+export type TSmartdataAtomicDocumentPath<T> =
+  | TSmartdataDocumentPath<T>
+  | TSmartdataAtomicNestedDocumentPath<T>;
+
+export type TSmartdataProjection<T> = Partial<
+  Record<TSmartdataAtomicDocumentPath<T> | '_id', 0 | 1>
+>;
+
+export type TSmartdataSort<T> = Partial<
+  Record<TSmartdataAtomicDocumentPath<T> | '_id', 1 | -1>
+>;
+
+export interface ISmartdataCursorOptions<T> {
+  projection?: TSmartdataProjection<T>;
+  /**
+   * Callers are responsible for including a unique final tiebreaker when
+   * deterministic pagination across equal values matters.
+   */
+  sort?: TSmartdataSort<T>;
+  batchSize?: number;
+  limit?: number;
+  /** Zero-based offset. Requires an explicit sort and bounded limit. */
+  skip?: number;
+  /** Model-declared index name, or MongoDB's built-in `_id_` index. */
+  hint?: string;
+  maxTimeMS?: number;
+  session?: plugins.mongodb.ClientSession;
+  /**
+   * @deprecated Prefer the structured cursor options. The modifier runs last
+   * for backward compatibility.
+   */
+  modifier?: (
+    cursorArg: plugins.mongodb.FindCursor<
+      plugins.mongodb.WithId<plugins.mongodb.BSON.Document>
+    >,
+  ) => plugins.mongodb.FindCursor<
+    plugins.mongodb.WithId<plugins.mongodb.BSON.Document>
+  >;
+}
+
+export interface ISmartdataCountOptions {
+  limit?: number;
+  /** Model-declared index name, or MongoDB's built-in `_id_` index. */
+  hint?: string;
+  maxTimeMS?: number;
+  /** Client-side operation deadline, including server selection and pool waits. */
+  timeoutMS?: number;
+  signal?: AbortSignal;
+  session?: TSmartdataOrdinarySession;
+}
+
+export interface ISmartdataOffsetPageOptions<T> {
+  skip: number;
+  limit: number;
+  /** Include a unique final tiebreaker to order equal preceding values. */
+  sort: TSmartdataSort<T>;
+  projection?: TSmartdataProjection<T>;
+  hint?: string;
+  maxTimeMS?: number;
+  /** Defaults to 5000ms; maximum 120000ms. Covers the cursor's entire lifetime. */
+  timeoutMS?: number;
+  signal?: AbortSignal;
+  session?: TSmartdataOrdinarySession;
+}
+
+export interface ISmartdataFindOneOptions<T> {
+  projection?: TSmartdataProjection<T>;
+  maxTimeMS?: number;
+  session?: TSmartdataOrdinarySession;
+}
+
+type TSmartdataAtomicSet<T> =
+  & Partial<Pick<T, TSmartdataDocumentPath<T>>>
+  & Partial<Record<TSmartdataAtomicNestedDocumentPath<T>, unknown>>;
+
+type TSmartdataAtomicIncrement<T> =
+  & Partial<
+    Record<
+      {
+        [TKey in TSmartdataDocumentPath<T>]:
+          NonNullable<T[TKey]> extends number ? TKey : never;
+      }[TSmartdataDocumentPath<T>],
+      number
+    >
+  >
+  & Partial<Record<TSmartdataAtomicNestedDocumentPath<T>, number>>;
+
+export type TSmartdataNumericDocumentPath<T> = {
+  [TKey in TSmartdataDocumentPath<T>]:
+    NonNullable<T[TKey]> extends number ? TKey : never;
+}[TSmartdataDocumentPath<T>];
+
+export type TSmartdataAtomicNumericFieldReference<T> =
+  `$${TSmartdataNumericDocumentPath<T>}`;
+
+export type TSmartdataAtomicNumericExpressionOperand<T> =
+  | number
+  | TSmartdataAtomicNumericFieldReference<T>
+  | {
+      $add: readonly [
+        TSmartdataAtomicNumericExpressionOperand<T>,
+        TSmartdataAtomicNumericExpressionOperand<T>,
+        ...TSmartdataAtomicNumericExpressionOperand<T>[],
+      ];
+    };
+
+export interface ISmartdataAtomicNumericExpression<T> {
+  $lte: readonly [
+    TSmartdataAtomicNumericExpressionOperand<T>,
+    TSmartdataAtomicNumericExpressionOperand<T>,
+  ];
+}
+
+export interface ISmartdataGroupedTotalsOptions<T> {
+  /**
+   * One or two declared top-level fields whose distinct value combinations
+   * form the groups.
+   */
+  groupBy: ReadonlyArray<TSmartdataDocumentPath<T>>;
+  /**
+   * Declared numeric top-level fields to sum per group.
+   */
+  sums?: ReadonlyArray<TSmartdataNumericDocumentPath<T>>;
+  filter?: MongoFilter<T>;
+  /**
+   * Required bound on the number of returned groups (1..10000). The group
+   * stage is not sorted, so when more groups exist than the limit the
+   * returned subset is arbitrary. Use `getGroupedTotalsPage()` when the
+   * caller must detect overflow at the 10000-group boundary.
+   */
+  limit: number;
+  maxTimeMS?: number;
+  /** Client-side deadline for the complete aggregation cursor lifetime. */
+  timeoutMS?: number;
+  signal?: AbortSignal;
+  session?: TSmartdataOrdinarySession;
+}
+
+export interface ISmartdataGroupedTotalsRow<T> {
+  /**
+   * The group's key values. Documents missing a group field and documents
+   * holding an explicit null merge into one group reported as null.
+   */
+  group: { [TKey in TSmartdataDocumentPath<T>]?: T[TKey] | null };
+  count: number;
+  sums: Partial<Record<TSmartdataNumericDocumentPath<T>, number>>;
+}
+
+export interface ISmartdataGroupedTotalsPage<T> {
+  rows: Array<ISmartdataGroupedTotalsRow<T>>;
+  hasMore: boolean;
+}
+
+export type TSmartdataAtomicArrayPath<T> = {
+  [TKey in TSmartdataDocumentPath<T>]:
+    NonNullable<T[TKey]> extends ReadonlyArray<unknown> ? TKey : never;
+}[TSmartdataDocumentPath<T>];
+
+type TSmartdataAtomicArrayElement<TValue> =
+  NonNullable<TValue> extends ReadonlyArray<infer TElement> ? TElement : never;
+
+type TSmartdataAtomicArrayOperation<T> = Partial<{
+  [TKey in TSmartdataAtomicArrayPath<T>]: TSmartdataAtomicArrayElement<T[TKey]>;
+}>;
+
+type TSmartdataAtomicPullScalar<TValue> = Extract<
+  TValue,
+  | string
+  | number
+  | boolean
+  | null
+  | Date
+  | plugins.mongodb.ObjectId
+  | plugins.mongodb.Binary
+  | plugins.mongodb.Decimal128
+  | plugins.mongodb.Long
+  | plugins.mongodb.Int32
+  | plugins.mongodb.Double
+  | plugins.mongodb.Timestamp
+>;
+
+type TSmartdataAtomicArrayPullOperation<T> = Partial<{
+  [TKey in TSmartdataAtomicArrayPath<T>]: TSmartdataAtomicPullScalar<
+    TSmartdataAtomicArrayElement<T[TKey]>
+  >;
+}>;
+
+export interface ISmartdataAtomicUpdate<T> {
+  $set?: TSmartdataAtomicSet<T>;
+  $unset?: Partial<
+    Record<TSmartdataAtomicDocumentPath<T>, '' | true | 1>
+  >;
+  $inc?: TSmartdataAtomicIncrement<T>;
+  $setOnInsert?: TSmartdataAtomicSet<T>;
+  /**
+   * Appends one element to a declared top-level array field. Modifier
+   * documents ($each, $position, $slice, $sort) are rejected.
+   */
+  $push?: TSmartdataAtomicArrayOperation<T>;
+  /**
+   * Adds one element to a declared top-level array field unless an equal
+   * element is already present. Modifier documents are rejected.
+   */
+  $addToSet?: TSmartdataAtomicArrayOperation<T>;
+  /**
+   * Removes every element equal to a scalar operand from a declared
+   * top-level array field. Operator documents, plain objects, arrays, and
+   * regular expressions are rejected.
+   */
+  $pull?: TSmartdataAtomicArrayPullOperation<T>;
+}
+
+type TSmartdataAtomicDirectEquality<TValue> =
+  TValue extends ReadonlyArray<infer TEntry>
+    ? ReadonlyArray<TSmartdataAtomicDirectEquality<TEntry>>
+    : TValue extends object
+      ? TValue extends
+        | Date
+        | ArrayBufferView
+        | plugins.mongodb.ObjectId
+        | plugins.mongodb.Binary
+        | plugins.mongodb.Decimal128
+        | plugins.mongodb.Long
+        | plugins.mongodb.Int32
+        | plugins.mongodb.Double
+        | plugins.mongodb.Timestamp
+        | plugins.mongodb.MinKey
+        | plugins.mongodb.MaxKey
+      ? TValue
+      : never
+      : Exclude<TValue, undefined>;
+
+type TSmartdataAtomicInValue<TValue> =
+  TValue extends ReadonlyArray<infer TEntry>
+    ? TSmartdataAtomicDirectEquality<TEntry>
+    : TSmartdataAtomicDirectEquality<TValue>;
+
+export type TSmartdataAtomicFilterCondition<TValue> =
+  | TSmartdataAtomicDirectEquality<TValue>
+  | {
+      $eq?: TValue;
+      $ne?: TSmartdataAtomicDirectEquality<TValue>;
+      $gt?: TSmartdataAtomicDirectEquality<TValue>;
+      $gte?: TSmartdataAtomicDirectEquality<TValue>;
+      $lt?: TSmartdataAtomicDirectEquality<TValue>;
+      $lte?: TSmartdataAtomicDirectEquality<TValue>;
+      $in?: ReadonlyArray<TSmartdataAtomicInValue<TValue>>;
+      $nin?: ReadonlyArray<TSmartdataAtomicInValue<TValue>>;
+      $exists?: boolean;
+      $type?: plugins.mongodb.BSONType | plugins.mongodb.BSONTypeAlias;
+      $regex?: string | RegExp;
+      $options?: string;
+      $not?: TSmartdataAtomicFilterCondition<TValue>;
+    };
+
+type TSmartdataAtomicTopLevelFilter<T> = {
+  [TKey in TSmartdataDocumentPath<T>]?:
+    TSmartdataAtomicFilterCondition<T[TKey]>;
+};
+
+type TSmartdataAtomicNestedFilter<T> = Partial<
+  Record<
+    TSmartdataAtomicNestedDocumentPath<T>,
+    TSmartdataAtomicFilterCondition<unknown>
+  >
+>;
+
+type TSmartdataAtomicFilterBranch<T> =
+  & TSmartdataAtomicTopLevelFilter<T>
+  & TSmartdataAtomicNestedFilter<T>
+  & {
+  $and?: Array<TSmartdataAtomicFilterBranch<T>>;
+  $or?: Array<TSmartdataAtomicFilterBranch<T>>;
+  $nor?: Array<TSmartdataAtomicFilterBranch<T>>;
+};
+
+export type TSmartdataAtomicFilter<T> =
+  & TSmartdataAtomicFilterBranch<T>
+  & {
+      /**
+       * A root-only, fail-closed numeric expression. This predicate never
+       * counts as the equality anchor required by atomic writes.
+       */
+      $expr?: ISmartdataAtomicNumericExpression<T>;
+    };
+
+export interface ISmartdataAtomicUpdateOptions {
+  upsert?: boolean;
+  session?: TSmartdataOrdinarySession;
+}
+
+export interface ISmartdataAtomicUpdateResult {
+  acknowledged: boolean;
+  matchedCount: number;
+  modifiedCount: number;
+  upsertedId: plugins.mongodb.ObjectId | null;
+}
+
+export type TSmartdataAtomicReturnDocument = 'before' | 'after';
+
+export interface ISmartdataAtomicFindOneAndUpdateOptions<
+  TReturnDocument extends TSmartdataAtomicReturnDocument,
+  TModel = any,
+> {
+  returnDocument: TReturnDocument;
+  upsert?: boolean;
+  /**
+   * Optional sort applied before MongoDB selects the single document to
+   * update. Accepts the same paths as cursor sorts: declared top-level fields,
+   * nested paths declared through `@svDb({ atomicPaths })` or a model index,
+   * and `_id`. Callers wanting deterministic claim ordering should include a
+   * unique tiebreaker field.
+   */
+  sort?: TSmartdataSort<TModel>;
+  session?: TSmartdataOrdinarySession;
+}
+
+export type TSmartdataAtomicFindOneAndUpdateResult<
+  T,
+  TReturnDocument extends TSmartdataAtomicReturnDocument,
+> =
+  | { status: 'matched'; document: T }
+  | {
+      status: 'upserted';
+      document: TReturnDocument extends 'after' ? T : null;
+    }
+  | { status: 'not_matched'; document: null };
+
+export interface ISmartdataAtomicDeleteOptions {
+  session?: TSmartdataOrdinarySession;
+  /** Client-side operation deadline, including server selection and pool waits. */
+  timeoutMS?: number;
+}
+
+export interface ISmartdataInsertManyIfAbsentOptions<T> {
+  /** A declared, non-serialized @unI identity field. */
+  identityField: TSmartdataDocumentPath<T>;
+  /** Client-side bulk operation deadline, including server selection and pool waits. */
+  timeoutMS?: number;
+  session?: TSmartdataOrdinarySession;
+}
+
+export interface ISmartdataInsertManyIfAbsentResult {
+  insertedCount: number;
+  matchedCount: number;
+}
+
+export interface ISmartdataAtomicDeleteResult {
+  acknowledged: boolean;
+  deletedCount: number;
+}
+
+export interface ISmartdataAtomicUpdateManyOptions {
+  session?: TSmartdataOrdinarySession;
+}
+
+export interface ISmartdataAtomicUpdateManyResult {
+  acknowledged: boolean;
+  matchedCount: number;
+  modifiedCount: number;
+}
+
+const normalizeAtomicFindOneAndUpdateOptions = <
+  TReturnDocument extends TSmartdataAtomicReturnDocument,
+>(
+  optionsArg: ISmartdataAtomicFindOneAndUpdateOptions<TReturnDocument>,
+): {
+  returnDocument: TReturnDocument;
+  upsert: boolean;
+  sort?: unknown;
+  session?: TSmartdataOrdinarySession;
+} => {
+  if (
+    typeof optionsArg !== 'object'
+    || optionsArg === null
+    || plugins.nodeUtil.types.isProxy(optionsArg)
+    || !isPlainObject(optionsArg)
+  ) {
+    throw new SmartdataPersistenceError(
+      'invalid_argument',
+      'Atomic find-one-and-update options must be an inert plain object.',
+    );
+  }
+  const allowedKeys = new Set(['returnDocument', 'upsert', 'sort', 'session']);
+  const keys = Reflect.ownKeys(optionsArg);
+  for (const key of keys) {
+    if (typeof key !== 'string' || !allowedKeys.has(key)) {
+      throw new SmartdataPersistenceError(
+        'invalid_argument',
+        `Atomic find-one-and-update received unsupported option "${String(key)}".`,
+      );
+    }
+    const descriptor = Object.getOwnPropertyDescriptor(optionsArg, key);
+    if (!descriptor || !('value' in descriptor) || descriptor.enumerable !== true) {
+      throw new SmartdataPersistenceError(
+        'invalid_argument',
+        `Atomic find-one-and-update option "${key}" must be an inert enumerable data property.`,
+      );
+    }
+  }
+  const returnDocumentDescriptor = Object.getOwnPropertyDescriptor(
+    optionsArg,
+    'returnDocument',
+  );
+  if (
+    !returnDocumentDescriptor
+    || !('value' in returnDocumentDescriptor)
+    || (
+      returnDocumentDescriptor.value !== 'before'
+      && returnDocumentDescriptor.value !== 'after'
+    )
+  ) {
+    throw new SmartdataPersistenceError(
+      'invalid_argument',
+      'Atomic find-one-and-update requires returnDocument to be "before" or "after".',
+    );
+  }
+  const upsertDescriptor = Object.getOwnPropertyDescriptor(optionsArg, 'upsert');
+  if (upsertDescriptor && upsertDescriptor.value !== undefined
+    && typeof upsertDescriptor.value !== 'boolean') {
+    throw new SmartdataPersistenceError(
+      'invalid_argument',
+      'Atomic find-one-and-update upsert must be a boolean.',
+    );
+  }
+  const sortDescriptor = Object.getOwnPropertyDescriptor(optionsArg, 'sort');
+  const sessionDescriptor = Object.getOwnPropertyDescriptor(optionsArg, 'session');
+  return {
+    returnDocument: returnDocumentDescriptor.value as TReturnDocument,
+    upsert: upsertDescriptor?.value === true,
+    ...(sortDescriptor?.value !== undefined
+      ? { sort: sortDescriptor.value }
+      : {}),
+    ...(sessionDescriptor?.value !== undefined
+      ? { session: sessionDescriptor.value as TSmartdataOrdinarySession }
+      : {}),
+  };
+};
+
+const normalizeAtomicExpressionUpdateOptions = (
+  optionsArg: ISmartdataAtomicUpdateOptions | undefined,
+): ISmartdataAtomicUpdateOptions | undefined => {
+  if (optionsArg === undefined) {
+    return undefined;
+  }
+  if (
+    typeof optionsArg !== 'object'
+    || optionsArg === null
+    || plugins.nodeUtil.types.isProxy(optionsArg)
+    || Object.getPrototypeOf(optionsArg) !== Object.prototype
+  ) {
+    throw new SmartdataPersistenceError(
+      'invalid_argument',
+      'Atomic update options used with $expr must be an inert ordinary object.',
+    );
+  }
+  const allowedKeys = new Set(['upsert', 'session']);
+  const normalized: ISmartdataAtomicUpdateOptions = {};
+  for (const key of Reflect.ownKeys(optionsArg)) {
+    if (typeof key !== 'string' || !allowedKeys.has(key)) {
+      throw new SmartdataPersistenceError(
+        'invalid_argument',
+        `Atomic update received unsupported option "${String(key)}".`,
+      );
+    }
+    const descriptor = Object.getOwnPropertyDescriptor(optionsArg, key);
+    if (
+      !descriptor
+      || !('value' in descriptor)
+      || descriptor.enumerable !== true
+    ) {
+      throw new SmartdataPersistenceError(
+        'invalid_argument',
+        `Atomic update option "${key}" must be an inert enumerable data property.`,
+      );
+    }
+    if (key === 'upsert') {
+      if (
+        descriptor.value !== undefined
+        && typeof descriptor.value !== 'boolean'
+      ) {
+        throw new SmartdataPersistenceError(
+          'invalid_argument',
+          'Atomic update upsert must be a boolean.',
+        );
+      }
+      if (descriptor.value !== undefined) {
+        normalized.upsert = descriptor.value;
+      }
+    } else if (descriptor.value !== undefined) {
+      normalized.session = descriptor.value as TSmartdataOrdinarySession;
+    }
+  }
+  return normalized;
+};
+
+const reservedOrdinaryPersistenceFields = new Set([
+  '_id',
+  '_createdAt',
+  '_updatedAt',
+  '_smartdataRevision',
+]);
+const stringIdRootSets = new WeakSet<Set<string>>();
+
+const requireBoundedInteger = (
+  valueArg: number | undefined,
+  labelArg: string,
+  maximumArg: number,
+): number | undefined => {
+  if (valueArg === undefined) {
+    return undefined;
+  }
+  if (
+    !Number.isSafeInteger(valueArg) ||
+    valueArg <= 0 ||
+    valueArg > maximumArg
+  ) {
+    throw new SmartdataPersistenceError(
+      'invalid_argument',
+      `${labelArg} must be a positive safe integer no greater than ${maximumArg}.`,
+    );
+  }
+  return valueArg;
+};
+
+const requireDeclaredPath = (
+  pathArg: string,
+  declaredRootsArg: Set<string>,
+  labelArg: string,
+  declaredNestedPathsArg?: Set<string>,
+): string => {
+  const pathSegments = typeof pathArg === 'string'
+    ? pathArg.split('.')
+    : [];
+  if (
+    typeof pathArg !== 'string' ||
+    pathArg.length === 0 ||
+    pathArg.length > 1024 ||
+    pathArg.includes('\0') ||
+    pathArg.startsWith('$') ||
+    pathSegments.length > 32 ||
+    pathSegments.some((segmentArg) => (
+      segmentArg.length === 0
+      || segmentArg.startsWith('$')
+      || segmentArg.includes('\0')
+      || unsafePersistedObjectKeys.has(segmentArg)
+    )) ||
+    (
+      pathSegments.length > 1
+      && !declaredNestedPathsArg?.has(pathArg)
+    )
+  ) {
+    throw new SmartdataPersistenceError(
+      'invalid_argument',
+      `${labelArg} contains invalid persisted path "${pathArg}".`,
+    );
+  }
+  const root = pathSegments[0];
+  if (
+    (reservedOrdinaryPersistenceFields.has(root) &&
+      !(root === '_id' && stringIdRootSets.has(declaredRootsArg))) ||
+    !declaredRootsArg.has(root)
+  ) {
+    throw new SmartdataPersistenceError(
+      'invalid_argument',
+      `${labelArg} references undeclared or reserved persisted path "${pathArg}".`,
+    );
+  }
+  return root;
+};
+
+const unsafePersistedObjectKeys = new Set([
+  '__proto__',
+  'prototype',
+  'constructor',
+]);
+
+const assertSafePersistedValue = (
+  valueArg: unknown,
+  labelArg: string,
+  seenArg = new WeakSet<object>(),
+): void => {
+  if (typeof valueArg !== 'object' || valueArg === null) {
+    return;
+  }
+  if (seenArg.has(valueArg)) {
+    return;
+  }
+  seenArg.add(valueArg);
+  if (Array.isArray(valueArg)) {
+    for (const entryArg of valueArg) {
+      assertSafePersistedValue(entryArg, labelArg, seenArg);
+    }
+    return;
+  }
+  if (!isPlainObject(valueArg)) {
+    return;
+  }
+  for (const [keyArg, entryArg] of Object.entries(valueArg)) {
+    if (
+      unsafePersistedObjectKeys.has(keyArg) ||
+      keyArg.startsWith('$') ||
+      keyArg.includes('.') ||
+      keyArg.includes('\0')
+    ) {
+      throw new SmartdataPersistenceError(
+        'invalid_argument',
+        `${labelArg} contains unsafe object key "${keyArg}".`,
+      );
+    }
+    assertSafePersistedValue(entryArg, labelArg, seenArg);
+  }
+};
+
+const atomicFilterComparisonOperators = new Set([
+  '$eq',
+  '$ne',
+  '$gt',
+  '$gte',
+  '$lt',
+  '$lte',
+]);
+
+const atomicFilterArrayOperators = new Set(['$in', '$nin']);
+
+const atomicFilterOperators = new Set([
+  ...atomicFilterComparisonOperators,
+  ...atomicFilterArrayOperators,
+  '$exists',
+  '$type',
+  '$regex',
+  '$options',
+  '$not',
+]);
+
+const atomicFilterBsonTypes = new Set<unknown>([
+  ...Object.keys(plugins.mongodb.BSONType),
+  ...Object.values(plugins.mongodb.BSONType),
+]);
+
+const atomicBsonScalarPrototypes = new Map<object, string>([
+  [plugins.mongodb.ObjectId.prototype, 'ObjectId'],
+  [plugins.mongodb.Binary.prototype, 'Binary'],
+  [plugins.mongodb.Decimal128.prototype, 'Decimal128'],
+  [plugins.mongodb.Long.prototype, 'Long'],
+  [plugins.mongodb.Int32.prototype, 'Int32'],
+  [plugins.mongodb.Double.prototype, 'Double'],
+  [plugins.mongodb.Timestamp.prototype, 'Timestamp'],
+  [plugins.mongodb.MinKey.prototype, 'MinKey'],
+  [plugins.mongodb.MaxKey.prototype, 'MaxKey'],
+]);
+
+const getTrustedAtomicBsonScalarType = (
+  valueArg: unknown,
+): string | undefined => {
+  if (
+    typeof valueArg !== 'object'
+    || valueArg === null
+    || plugins.nodeUtil.types.isProxy(valueArg)
+  ) {
+    return undefined;
+  }
+  const expectedType = atomicBsonScalarPrototypes.get(
+    Object.getPrototypeOf(valueArg),
+  );
+  if (!expectedType) {
+    return undefined;
+  }
+  const ownBsonTypeDescriptor = Object.getOwnPropertyDescriptor(
+    valueArg,
+    '_bsontype',
+  );
+  if (
+    ownBsonTypeDescriptor
+    && (
+      !('value' in ownBsonTypeDescriptor)
+      || ownBsonTypeDescriptor.value !== expectedType
+    )
+  ) {
+    return undefined;
+  }
+  return expectedType;
+};
+
+const hasAtomicBsonTypeClaim = (valueArg: unknown): boolean => {
+  if (
+    typeof valueArg !== 'object'
+    || valueArg === null
+    || plugins.nodeUtil.types.isProxy(valueArg)
+  ) {
+    return false;
+  }
+  for (
+    let prototype = valueArg as object | null;
+    prototype;
+    prototype = Object.getPrototypeOf(prototype)
+  ) {
+    if (Object.getOwnPropertyDescriptor(prototype, '_bsontype')) {
+      return true;
+    }
+  }
+  return false;
+};
+
+const isAtomicMongoScalar = (valueArg: unknown): boolean => {
+  if (
+    typeof valueArg !== 'object'
+    || valueArg === null
+    || plugins.nodeUtil.types.isProxy(valueArg)
+  ) {
+    return false;
+  }
+  const valuePrototype = Object.getPrototypeOf(valueArg);
+  if (
+    valuePrototype === Date.prototype
+    || valuePrototype === RegExp.prototype
+  ) {
+    return true;
+  }
+  if (ArrayBuffer.isView(valueArg)) {
+    return true;
+  }
+  return getTrustedAtomicBsonScalarType(valueArg) !== undefined;
+};
+
+const allowedAtomicBsonScalarTypes = new Set([
+  'ObjectId',
+  'Binary',
+  'Decimal128',
+  'Long',
+  'Int32',
+  'Double',
+  'Timestamp',
+  'MinKey',
+  'MaxKey',
+]);
+
+const requireSafeAtomicEqualityScalar = (
+  valueArg: unknown,
+  labelArg: string,
+): void => {
+  if (
+    typeof valueArg === 'object'
+    && valueArg !== null
+    && plugins.nodeUtil.types.isProxy(valueArg)
+  ) {
+    throw new SmartdataPersistenceError(
+      'invalid_argument',
+      `${labelArg} may not use a Proxy object.`,
+    );
+  }
+  if (valueArg instanceof RegExp) {
+    throw new SmartdataPersistenceError(
+      'invalid_argument',
+      `${labelArg} may not use a regular expression as an equality value.`,
+    );
+  }
+  if (
+    valueArg instanceof Date &&
+    Object.getPrototypeOf(valueArg) !== Date.prototype
+  ) {
+    throw new SmartdataPersistenceError(
+      'invalid_argument',
+      `${labelArg} may not use a Date subclass with custom BSON behavior.`,
+    );
+  }
+  const bsonType = getTrustedAtomicBsonScalarType(valueArg);
+  if (
+    hasAtomicBsonTypeClaim(valueArg)
+    && (
+      !bsonType
+      || !allowedAtomicBsonScalarTypes.has(bsonType)
+    )
+  ) {
+    throw new SmartdataPersistenceError(
+      'invalid_argument',
+      `${labelArg} uses an unsupported BSON equality scalar.`,
+    );
+  }
+};
+
+const requireUsableIdentityValue = (
+  valueArg: unknown,
+  labelArg: string,
+  valueTypeArg: TSmartdataIdentityValueType,
+): void => {
+  if (valueTypeArg === 'positiveSafeInteger') {
+    if (
+      typeof valueArg === 'number'
+      && Number.isSafeInteger(valueArg)
+      && valueArg > 0
+    ) {
+      return;
+    }
+    throw new SmartdataPersistenceError(
+      'invalid_argument',
+      `${labelArg} must contain a positive safe integer identity value.`,
+    );
+  }
+  if (typeof valueArg !== 'string' || valueArg.trim().length === 0) {
+    throw new SmartdataPersistenceError(
+      'invalid_argument',
+      `${labelArg} must contain a non-empty string identity value.`,
+    );
+  }
+};
+
+const assertUsableIdentityValues = (
+  documentArg: Record<string, unknown>,
+  identityFieldsArg: Iterable<string>,
+  identityValueTypesArg?: Readonly<Record<string, TSmartdataIdentityValueType>>,
+): void => {
+  for (const identityField of identityFieldsArg) {
+    requireUsableIdentityValue(
+      documentArg[identityField],
+      `Identity field "${identityField}"`,
+      identityValueTypesArg?.[identityField] ?? 'string',
+    );
+  }
+};
+
+/**
+ * Validates the explicit `$eq` operand used for whole-object compare-and-set
+ * filters. Direct nested object selectors remain forbidden; the operator is
+ * required so object equality cannot be confused with query structure.
+ */
+const assertOnlyDataProperties = (
+  valueArg: object,
+  labelArg: string,
+  arrayArg: boolean,
+): void => {
+  for (const ownKey of Reflect.ownKeys(valueArg)) {
+    if (typeof ownKey === 'symbol') {
+      throw new SmartdataPersistenceError(
+        'invalid_argument',
+        `${labelArg} may not contain symbol properties.`,
+      );
+    }
+    if (arrayArg && ownKey === 'length') {
+      continue;
+    }
+    const descriptor = Object.getOwnPropertyDescriptor(valueArg, ownKey);
+    if (
+      !descriptor ||
+      !('value' in descriptor) ||
+      typeof descriptor.value === 'function'
+    ) {
+      throw new SmartdataPersistenceError(
+        'invalid_argument',
+        `${labelArg} may contain only inert data properties.`,
+      );
+    }
+    if (!descriptor.enumerable && !arrayArg) {
+      throw new SmartdataPersistenceError(
+        'invalid_argument',
+        `${labelArg} may not contain hidden data properties.`,
+      );
+    }
+  }
+};
+
+const typedArrayPrototype = Object.getPrototypeOf(Uint8Array.prototype);
+const typedArrayBufferGetter = Object.getOwnPropertyDescriptor(
+  typedArrayPrototype,
+  'buffer',
+)?.get;
+const typedArrayByteOffsetGetter = Object.getOwnPropertyDescriptor(
+  typedArrayPrototype,
+  'byteOffset',
+)?.get;
+const typedArrayByteLengthGetter = Object.getOwnPropertyDescriptor(
+  typedArrayPrototype,
+  'byteLength',
+)?.get;
+const dataViewBufferGetter = Object.getOwnPropertyDescriptor(
+  DataView.prototype,
+  'buffer',
+)?.get;
+const dataViewByteOffsetGetter = Object.getOwnPropertyDescriptor(
+  DataView.prototype,
+  'byteOffset',
+)?.get;
+const dataViewByteLengthGetter = Object.getOwnPropertyDescriptor(
+  DataView.prototype,
+  'byteLength',
+)?.get;
+const regExpSourceGetter = Object.getOwnPropertyDescriptor(
+  RegExp.prototype,
+  'source',
+)?.get;
+const regExpFlagGetters = [
+  ['d', 'hasIndices'],
+  ['g', 'global'],
+  ['i', 'ignoreCase'],
+  ['m', 'multiline'],
+  ['s', 'dotAll'],
+  ['u', 'unicode'],
+  ['v', 'unicodeSets'],
+  ['y', 'sticky'],
+].map(([flag, property]) => ({
+  flag,
+  getter: Object.getOwnPropertyDescriptor(
+    RegExp.prototype,
+    property,
+  )?.get,
+}));
+
+const getIntrinsicArrayBufferViewBytes = (
+  valueArg: ArrayBufferView,
+  labelArg: string,
+): Uint8Array => {
+  const readView = (
+    bufferGetterArg: ((this: object) => ArrayBufferLike) | undefined,
+    byteOffsetGetterArg: ((this: object) => number) | undefined,
+    byteLengthGetterArg: ((this: object) => number) | undefined,
+  ): Uint8Array | undefined => {
+    if (
+      !bufferGetterArg
+      || !byteOffsetGetterArg
+      || !byteLengthGetterArg
+    ) {
+      return undefined;
+    }
+    try {
+      const buffer = Reflect.apply(bufferGetterArg, valueArg, []);
+      const byteOffset = Reflect.apply(byteOffsetGetterArg, valueArg, []);
+      const byteLength = Reflect.apply(byteLengthGetterArg, valueArg, []);
+      return new Uint8Array(buffer, byteOffset, byteLength);
+    } catch {
+      return undefined;
+    }
+  };
+  const bytes =
+    readView(
+      typedArrayBufferGetter,
+      typedArrayByteOffsetGetter,
+      typedArrayByteLengthGetter,
+    )
+    || readView(
+      dataViewBufferGetter,
+      dataViewByteOffsetGetter,
+      dataViewByteLengthGetter,
+    );
+  if (!bytes) {
+    throw new SmartdataPersistenceError(
+      'invalid_argument',
+      `${labelArg} contains an invalid ArrayBuffer view.`,
+    );
+  }
+  return bytes;
+};
+
+const createInertAtomicBsonScalarSnapshot = (
+  valueArg: unknown,
+  labelArg: string,
+): unknown => {
+  if (valueArg instanceof Date) {
+    if (
+      Object.getPrototypeOf(valueArg) !== Date.prototype ||
+      Reflect.ownKeys(valueArg).length !== 0
+    ) {
+      throw new SmartdataPersistenceError(
+        'invalid_argument',
+        `${labelArg} may not use a customized Date value.`,
+      );
+    }
+    const snapshot = new Date(valueArg.getTime());
+    Object.defineProperty(snapshot, 'toBSON', {
+      value: undefined,
+      enumerable: false,
+    });
+    return snapshot;
+  }
+  if (ArrayBuffer.isView(valueArg)) {
+    assertOnlyDataProperties(valueArg, labelArg, false);
+    const snapshot = Uint8Array.from(
+      getIntrinsicArrayBufferViewBytes(valueArg, labelArg),
+    );
+    Object.defineProperty(snapshot, 'toBSON', {
+      value: undefined,
+      enumerable: false,
+    });
+    return snapshot;
+  }
+  const originalBsonType = getTrustedAtomicBsonScalarType(valueArg);
+  if (!originalBsonType) {
+    throw new SmartdataPersistenceError(
+      'invalid_argument',
+      `${labelArg} contains an untrusted BSON scalar.`,
+    );
+  }
+  assertOnlyDataProperties(valueArg as object, labelArg, false);
+  for (
+    let prototype = valueArg as object | null;
+    prototype;
+    prototype = Object.getPrototypeOf(prototype)
+  ) {
+    if (Object.getOwnPropertyDescriptor(prototype, 'toBSON')) {
+      throw new SmartdataPersistenceError(
+        'invalid_argument',
+        `${labelArg} may not use a custom BSON encoder.`,
+      );
+    }
+  }
+  try {
+    const snapshotDocument = plugins.mongodb.BSON.deserialize(
+      plugins.mongodb.BSON.serialize({ value: valueArg }),
+      {
+        promoteBuffers: false,
+        promoteValues: false,
+      },
+    );
+    const snapshot = snapshotDocument.value as object;
+    if (getTrustedAtomicBsonScalarType(snapshot) !== originalBsonType) {
+      throw new SmartdataPersistenceError(
+        'invalid_argument',
+        `${labelArg} changed BSON scalar type while being captured.`,
+      );
+    }
+    Object.defineProperty(snapshot, 'toBSON', {
+      value: undefined,
+      enumerable: false,
+    });
+    return snapshot;
+  } catch (cause) {
+    throw new SmartdataPersistenceError(
+      'invalid_argument',
+      `${labelArg} contains an invalid BSON scalar.`,
+      { cause },
+    );
+  }
+};
+
+const createSafeAtomicExactObjectEqualitySnapshot = (
+  valueArg: unknown,
+  labelArg: string,
+  seenArg = new WeakSet<object>(),
+): unknown => {
+  if (valueArg === undefined) {
+    throw new SmartdataPersistenceError(
+      'invalid_argument',
+      `${labelArg} may not contain undefined.`,
+    );
+  }
+  if (
+    typeof valueArg === 'function'
+    || typeof valueArg === 'symbol'
+  ) {
+    throw new SmartdataPersistenceError(
+      'invalid_argument',
+      `${labelArg} contains a value that cannot be encoded as safe BSON.`,
+    );
+  }
+  if (typeof valueArg !== 'object' || valueArg === null) {
+    return valueArg;
+  }
+  if (plugins.nodeUtil.types.isProxy(valueArg)) {
+    throw new SmartdataPersistenceError(
+      'invalid_argument',
+      `${labelArg} may not contain Proxy objects.`,
+    );
+  }
+  if (seenArg.has(valueArg)) {
+    throw new SmartdataPersistenceError(
+      'invalid_argument',
+      `${labelArg} may not contain a circular object graph.`,
+    );
+  }
+  if (isAtomicMongoScalar(valueArg)) {
+    requireSafeAtomicEqualityScalar(valueArg, labelArg);
+    return createInertAtomicBsonScalarSnapshot(valueArg, labelArg);
+  }
+  if (!Array.isArray(valueArg) && !isPlainObject(valueArg)) {
+    throw new SmartdataPersistenceError(
+      'invalid_argument',
+      `${labelArg} contains an object with a custom BSON encoding boundary.`,
+    );
+  }
+  if (
+    Array.isArray(valueArg) &&
+    Object.getPrototypeOf(valueArg) !== Array.prototype
+  ) {
+    throw new SmartdataPersistenceError(
+      'invalid_argument',
+      `${labelArg} may not use an Array subclass.`,
+    );
+  }
+  assertOnlyDataProperties(valueArg, labelArg, Array.isArray(valueArg));
+  seenArg.add(valueArg);
+  if (Array.isArray(valueArg)) {
+    const snapshot: unknown[] = [];
+    for (let index = 0; index < valueArg.length; index++) {
+      if (!Object.prototype.hasOwnProperty.call(valueArg, index)) {
+        throw new SmartdataPersistenceError(
+          'invalid_argument',
+          `${labelArg} may not contain sparse array positions.`,
+        );
+      }
+      snapshot.push(
+        createSafeAtomicExactObjectEqualitySnapshot(
+          valueArg[index],
+          labelArg,
+          seenArg,
+        ),
+      );
+    }
+    seenArg.delete(valueArg);
+    Object.defineProperty(snapshot, 'toBSON', {
+      value: undefined,
+      enumerable: false,
+    });
+    return snapshot;
+  }
+  const snapshot: Record<string, unknown> = {};
+  for (const [keyArg, entryArg] of Object.entries(valueArg)) {
+    if (
+      unsafePersistedObjectKeys.has(keyArg)
+      || keyArg === 'toBSON'
+      || keyArg === '_bsontype'
+      || keyArg.startsWith('$')
+      || keyArg.includes('.')
+      || keyArg.includes('\0')
+    ) {
+      throw new SmartdataPersistenceError(
+        'invalid_argument',
+        `${labelArg} contains unsafe object key "${keyArg}".`,
+      );
+    }
+    Object.defineProperty(snapshot, keyArg, {
+      value: createSafeAtomicExactObjectEqualitySnapshot(
+        entryArg,
+        labelArg,
+        seenArg,
+      ),
+      enumerable: true,
+      writable: false,
+      configurable: false,
+    });
+  }
+  seenArg.delete(valueArg);
+  Object.defineProperty(snapshot, 'toBSON', {
+    value: undefined,
+    enumerable: false,
+  });
+  return snapshot;
+};
+
+const createSafeAtomicFilterValueSnapshot = (
+  valueArg: unknown,
+  labelArg: string,
+): unknown => {
+  if (
+    valueArg === undefined
+    || typeof valueArg === 'function'
+    || typeof valueArg === 'symbol'
+  ) {
+    throw new SmartdataPersistenceError(
+      'invalid_argument',
+      `${labelArg} contains a value that cannot be encoded as safe BSON.`,
+    );
+  }
+  if (
+    typeof valueArg === 'object'
+    && valueArg !== null
+    && plugins.nodeUtil.types.isProxy(valueArg)
+  ) {
+    throw new SmartdataPersistenceError(
+      'invalid_argument',
+      `${labelArg} may not use a Proxy object.`,
+    );
+  }
+  if (Array.isArray(valueArg)) {
+    if (Object.getPrototypeOf(valueArg) !== Array.prototype) {
+      throw new SmartdataPersistenceError(
+        'invalid_argument',
+        `${labelArg} may not use an Array subclass.`,
+      );
+    }
+    assertOnlyDataProperties(valueArg, labelArg, true);
+    const snapshot: unknown[] = [];
+    for (let index = 0; index < valueArg.length; index++) {
+      if (!Object.prototype.hasOwnProperty.call(valueArg, index)) {
+        throw new SmartdataPersistenceError(
+          'invalid_argument',
+          `${labelArg} may not contain sparse array positions.`,
+        );
+      }
+      snapshot.push(
+        createSafeAtomicFilterValueSnapshot(valueArg[index], labelArg),
+      );
+    }
+    return snapshot;
+  }
+  if (typeof valueArg !== 'object' || valueArg === null) {
+    return valueArg;
+  }
+  requireSafeAtomicEqualityScalar(valueArg, labelArg);
+  if (!isAtomicMongoScalar(valueArg)) {
+    throw new SmartdataPersistenceError(
+      'invalid_argument',
+      `${labelArg} must be a scalar BSON value.`,
+    );
+  }
+  return createInertAtomicBsonScalarSnapshot(valueArg, labelArg);
+};
+
+const createSafeAtomicRegExpSnapshot = (
+  valueArg: RegExp,
+  labelArg: string,
+): RegExp => {
+  if (
+    plugins.nodeUtil.types.isProxy(valueArg)
+    || Object.getPrototypeOf(valueArg) !== RegExp.prototype
+    || !regExpSourceGetter
+  ) {
+    throw new SmartdataPersistenceError(
+      'invalid_argument',
+      `${labelArg} may not use a Proxy or RegExp subclass.`,
+    );
+  }
+  const source = Reflect.apply(regExpSourceGetter, valueArg, []);
+  const flags = regExpFlagGetters
+    .filter(
+      ({ getter }) =>
+        getter && Reflect.apply(getter, valueArg, []),
+    )
+    .map(({ flag }) => flag)
+    .join('');
+  return new RegExp(source, flags);
+};
+
+const normalizeAtomicFilterCondition = (
+  valueArg: unknown,
+  labelArg: string,
+  identityValueTypeArg?: TSmartdataIdentityValueType,
+): unknown => {
+  if (valueArg === undefined) {
+    throw new SmartdataPersistenceError(
+      'invalid_argument',
+      `${labelArg} may not contain undefined.`,
+    );
+  }
+  if (
+    typeof valueArg === 'object'
+    && valueArg !== null
+    && plugins.nodeUtil.types.isProxy(valueArg)
+  ) {
+    throw new SmartdataPersistenceError(
+      'invalid_argument',
+      `${labelArg} may not use a Proxy object.`,
+    );
+  }
+  if (!isPlainObject(valueArg) || isAtomicMongoScalar(valueArg)) {
+    requireSafeAtomicEqualityScalar(valueArg, labelArg);
+    if (identityValueTypeArg) {
+      requireUsableIdentityValue(
+        valueArg,
+        labelArg,
+        identityValueTypeArg,
+      );
+    }
+    return createSafeAtomicFilterValueSnapshot(valueArg, labelArg);
+  }
+
+  assertOnlyDataProperties(valueArg, labelArg, false);
+  const entries = Object.entries(valueArg);
+  if (entries.length === 0) {
+    throw new SmartdataPersistenceError(
+      'invalid_argument',
+      `${labelArg} may not be an empty object.`,
+    );
+  }
+  const operatorEntries = entries.filter(([key]) => key.startsWith('$'));
+  if (operatorEntries.length === 0) {
+    throw new SmartdataPersistenceError(
+      'invalid_argument',
+      `${labelArg} must use supported field operators instead of a nested object selector.`,
+    );
+  }
+  if (operatorEntries.length !== entries.length) {
+    throw new SmartdataPersistenceError(
+      'invalid_argument',
+      `${labelArg} may not mix operator and literal object keys.`,
+    );
+  }
+
+  const normalized: Record<string, unknown> = {};
+  for (const [operator, operand] of operatorEntries) {
+    if (!atomicFilterOperators.has(operator)) {
+      throw new SmartdataPersistenceError(
+        'invalid_argument',
+        `${labelArg} uses unsupported operator "${operator}".`,
+      );
+    }
+    if (atomicFilterComparisonOperators.has(operator)) {
+      if (
+        operator === '$eq'
+        && typeof operand === 'object'
+        && operand !== null
+        && !isAtomicMongoScalar(operand)
+      ) {
+        if (identityValueTypeArg) {
+          requireUsableIdentityValue(
+            operand,
+            `${labelArg} ${operator}`,
+            identityValueTypeArg,
+          );
+        }
+        normalized[operator] =
+          createSafeAtomicExactObjectEqualitySnapshot(
+            operand,
+            `${labelArg} ${operator}`,
+          );
+        continue;
+      }
+      if (identityValueTypeArg) {
+        requireUsableIdentityValue(
+          operand,
+          `${labelArg} ${operator}`,
+          identityValueTypeArg,
+        );
+      }
+      normalized[operator] = createSafeAtomicFilterValueSnapshot(
+        operand,
+        `${labelArg} ${operator}`,
+      );
+      continue;
+    }
+    if (atomicFilterArrayOperators.has(operator)) {
+      if (
+        !Array.isArray(operand)
+        || plugins.nodeUtil.types.isProxy(operand)
+        || Object.getPrototypeOf(operand) !== Array.prototype
+      ) {
+        throw new SmartdataPersistenceError(
+          'invalid_argument',
+          `${labelArg} ${operator} must be an ordinary non-empty array.`,
+        );
+      }
+      assertOnlyDataProperties(
+        operand,
+        `${labelArg} ${operator}`,
+        true,
+      );
+      if (operand.length === 0) {
+        throw new SmartdataPersistenceError(
+          'invalid_argument',
+          `${labelArg} ${operator} must be an ordinary non-empty array.`,
+        );
+      }
+      if (identityValueTypeArg) {
+        for (const entry of operand) {
+          requireUsableIdentityValue(
+            entry,
+            `${labelArg} ${operator}`,
+            identityValueTypeArg,
+          );
+        }
+      }
+      normalized[operator] = createSafeAtomicFilterValueSnapshot(
+        operand,
+        `${labelArg} ${operator}`,
+      );
+      continue;
+    }
+    if (operator === '$exists') {
+      if (typeof operand !== 'boolean') {
+        throw new SmartdataPersistenceError(
+          'invalid_argument',
+          `${labelArg} $exists must be a boolean.`,
+        );
+      }
+      normalized[operator] = operand;
+      continue;
+    }
+    if (operator === '$type') {
+      if (!atomicFilterBsonTypes.has(operand)) {
+        throw new SmartdataPersistenceError(
+          'invalid_argument',
+          `${labelArg} $type must use a MongoDB BSON type alias or numeric code.`,
+        );
+      }
+      normalized[operator] = operand;
+      continue;
+    }
+    if (operator === '$regex') {
+      if (typeof operand === 'string' && operand.length > 0) {
+        normalized[operator] = operand;
+        continue;
+      }
+      if (typeof operand !== 'object' || operand === null) {
+        throw new SmartdataPersistenceError(
+          'invalid_argument',
+          `${labelArg} $regex must be a non-empty string or RegExp.`,
+        );
+      }
+      normalized[operator] = createSafeAtomicRegExpSnapshot(
+        operand as RegExp,
+        `${labelArg} ${operator}`,
+      );
+      continue;
+    }
+    if (operator === '$options') {
+      if (
+        typeof operand !== 'string' ||
+        !/^[imsx]*$/.test(operand) ||
+        !('$regex' in valueArg)
+      ) {
+        throw new SmartdataPersistenceError(
+          'invalid_argument',
+          `${labelArg} $options must contain only imsx flags and accompany $regex.`,
+        );
+      }
+      normalized[operator] = operand;
+      continue;
+    }
+    if (operator === '$not') {
+      if (
+        (
+          typeof operand === 'object'
+          && operand !== null
+          && plugins.nodeUtil.types.isProxy(operand)
+        )
+        ||
+        !isPlainObject(operand) ||
+        Object.keys(operand).length === 0 ||
+        Object.keys(operand).some((key) => !key.startsWith('$'))
+      ) {
+        throw new SmartdataPersistenceError(
+          'invalid_argument',
+          `${labelArg} $not must contain a non-empty operator object.`,
+        );
+      }
+      assertOnlyDataProperties(operand, `${labelArg} $not`, false);
+      normalized[operator] = normalizeAtomicFilterCondition(
+        operand,
+        `${labelArg} $not`,
+        identityValueTypeArg,
+      );
+    }
+  }
+  return normalized;
+};
+
+const atomicNumericExpressionMaximumDepth = 8;
+const atomicNumericExpressionMaximumAddOperands = 16;
+const atomicNumericExpressionMaximumLeafOperands = 64;
+
+const getAtomicExpressionProperty = (
+  valueArg: unknown,
+  expectedKeyArg: '$lte' | '$add',
+  labelArg: string,
+): unknown => {
+  if (
+    typeof valueArg !== 'object'
+    || valueArg === null
+    || Array.isArray(valueArg)
+    || plugins.nodeUtil.types.isProxy(valueArg)
+    || Object.getPrototypeOf(valueArg) !== Object.prototype
+  ) {
+    throw new SmartdataPersistenceError(
+      'invalid_argument',
+      `${labelArg} must be an inert ordinary object containing only ${expectedKeyArg}.`,
+    );
+  }
+  const keys = Reflect.ownKeys(valueArg);
+  if (keys.length !== 1 || keys[0] !== expectedKeyArg) {
+    throw new SmartdataPersistenceError(
+      'invalid_argument',
+      `${labelArg} must contain exactly the ${expectedKeyArg} operator.`,
+    );
+  }
+  const descriptor = Object.getOwnPropertyDescriptor(valueArg, expectedKeyArg);
+  if (
+    !descriptor
+    || !('value' in descriptor)
+    || descriptor.enumerable !== true
+  ) {
+    throw new SmartdataPersistenceError(
+      'invalid_argument',
+      `${labelArg} ${expectedKeyArg} must be an inert enumerable data property.`,
+    );
+  }
+  return descriptor.value;
+};
+
+const getAtomicExpressionArrayValues = (
+  valueArg: unknown,
+  minimumLengthArg: number,
+  maximumLengthArg: number,
+  labelArg: string,
+): unknown[] => {
+  if (
+    typeof valueArg !== 'object'
+    || valueArg === null
+    || plugins.nodeUtil.types.isProxy(valueArg)
+    || !Array.isArray(valueArg)
+    || Object.getPrototypeOf(valueArg) !== Array.prototype
+  ) {
+    throw new SmartdataPersistenceError(
+      'invalid_argument',
+      `${labelArg} must be an inert ordinary array.`,
+    );
+  }
+  const lengthDescriptor = Object.getOwnPropertyDescriptor(valueArg, 'length');
+  const length = lengthDescriptor && 'value' in lengthDescriptor
+    ? lengthDescriptor.value
+    : undefined;
+  if (
+    !Number.isSafeInteger(length)
+    || length < minimumLengthArg
+    || length > maximumLengthArg
+  ) {
+    throw new SmartdataPersistenceError(
+      'invalid_argument',
+      `${labelArg} must contain between ${minimumLengthArg} and ${maximumLengthArg} operands.`,
+    );
+  }
+  const ownKeys = Reflect.ownKeys(valueArg);
+  if (ownKeys.length !== length + 1 || !ownKeys.includes('length')) {
+    throw new SmartdataPersistenceError(
+      'invalid_argument',
+      `${labelArg} may not contain sparse positions or extra properties.`,
+    );
+  }
+  const values: unknown[] = [];
+  for (let index = 0; index < length; index++) {
+    const key = String(index);
+    const descriptor = Object.getOwnPropertyDescriptor(valueArg, key);
+    if (
+      !descriptor
+      || !('value' in descriptor)
+      || descriptor.enumerable !== true
+    ) {
+      throw new SmartdataPersistenceError(
+        'invalid_argument',
+        `${labelArg} may contain only dense enumerable data operands.`,
+      );
+    }
+    values.push(descriptor.value);
+  }
+  return values;
+};
+
+interface INormalizedAtomicNumericExpressionOperand {
+  mongoExpression: unknown;
+  referencedFields: Set<string>;
+}
+
+const normalizeAtomicNumericExpression = (
+  expressionArg: unknown,
+  declaredRootsArg: Set<string>,
+  numericRootsArg: Set<string>,
+  serializedRootsArg: Set<string>,
+  operationLabelArg: string,
+): plugins.mongodb.Document => {
+  let leafOperandCount = 0;
+  const normalizeOperand = (
+    operandArg: unknown,
+    depthArg: number,
+  ): INormalizedAtomicNumericExpressionOperand => {
+    if (typeof operandArg === 'number') {
+      leafOperandCount++;
+      if (
+        !Number.isFinite(operandArg)
+        || leafOperandCount > atomicNumericExpressionMaximumLeafOperands
+      ) {
+        throw new SmartdataPersistenceError(
+          'invalid_argument',
+          `${operationLabelArg} $expr requires finite numeric literals and no more than ${atomicNumericExpressionMaximumLeafOperands} leaf operands.`,
+        );
+      }
+      return {
+        mongoExpression: operandArg,
+        referencedFields: new Set(),
+      };
+    }
+    if (typeof operandArg === 'string') {
+      leafOperandCount++;
+      if (leafOperandCount > atomicNumericExpressionMaximumLeafOperands) {
+        throw new SmartdataPersistenceError(
+          'invalid_argument',
+          `${operationLabelArg} $expr may not exceed ${atomicNumericExpressionMaximumLeafOperands} leaf operands.`,
+        );
+      }
+      if (
+        !operandArg.startsWith('$')
+        || operandArg.startsWith('$$')
+        || operandArg.length < 2
+      ) {
+        throw new SmartdataPersistenceError(
+          'invalid_argument',
+          `${operationLabelArg} $expr field references must use exactly one leading $.`,
+        );
+      }
+      const field = operandArg.slice(1);
+      if (field === 'toBSON' || field === '_bsontype') {
+        throw new SmartdataPersistenceError(
+          'invalid_argument',
+          `${operationLabelArg} $expr field "${field}" is reserved.`,
+        );
+      }
+      const root = requireDeclaredPath(
+        field,
+        declaredRootsArg,
+        `${operationLabelArg} $expr`,
+      );
+      if (field !== root) {
+        throw new SmartdataPersistenceError(
+          'invalid_argument',
+          `${operationLabelArg} $expr may reference only declared top-level fields.`,
+        );
+      }
+      if (!numericRootsArg.has(root)) {
+        throw new SmartdataPersistenceError(
+          'invalid_argument',
+          `${operationLabelArg} $expr field "${root}" is not declared numeric.`,
+        );
+      }
+      if (serializedRootsArg.has(root)) {
+        throw new SmartdataPersistenceError(
+          'unsupported_operation',
+          `${operationLabelArg} $expr cannot reference serialized field "${root}".`,
+        );
+      }
+      return {
+        mongoExpression: `$${root}`,
+        referencedFields: new Set([root]),
+      };
+    }
+    if (depthArg >= atomicNumericExpressionMaximumDepth) {
+      throw new SmartdataPersistenceError(
+        'invalid_argument',
+        `${operationLabelArg} $expr exceeds the maximum $add depth of ${atomicNumericExpressionMaximumDepth}.`,
+      );
+    }
+    const rawOperands = getAtomicExpressionArrayValues(
+      getAtomicExpressionProperty(
+        operandArg,
+        '$add',
+        `${operationLabelArg} $expr operand`,
+      ),
+      2,
+      atomicNumericExpressionMaximumAddOperands,
+      `${operationLabelArg} $expr $add`,
+    );
+    const normalizedOperands = rawOperands.map((entryArg) =>
+      normalizeOperand(entryArg, depthArg + 1),
+    );
+    return {
+      mongoExpression: {
+        $add: normalizedOperands.map((entryArg) => entryArg.mongoExpression),
+      },
+      referencedFields: new Set(
+        normalizedOperands.flatMap((entryArg) => [
+          ...entryArg.referencedFields,
+        ]),
+      ),
+    };
+  };
+
+  const lteOperands = getAtomicExpressionArrayValues(
+    getAtomicExpressionProperty(
+      expressionArg,
+      '$lte',
+      `${operationLabelArg} $expr`,
+    ),
+    2,
+    2,
+    `${operationLabelArg} $expr $lte`,
+  );
+  const left = normalizeOperand(lteOperands[0], 0);
+  const right = normalizeOperand(lteOperands[1], 0);
+  const referencedFields = new Set([
+    ...left.referencedFields,
+    ...right.referencedFields,
+  ]);
+  const fieldGuards = [...referencedFields].map((fieldArg) => ({
+    $cond: [
+      { $isNumber: `$${fieldArg}` },
+      {
+        $eq: [
+          { $subtract: [`$${fieldArg}`, `$${fieldArg}`] },
+          0,
+        ],
+      },
+      false,
+    ],
+  }));
+  const guardedComparison = {
+    $let: {
+      vars: {
+        smartdataAtomicExprLeft: left.mongoExpression,
+        smartdataAtomicExprRight: right.mongoExpression,
+      },
+      in: {
+        $cond: [
+          {
+            $and: [
+              { $isNumber: '$$smartdataAtomicExprLeft' },
+              { $isNumber: '$$smartdataAtomicExprRight' },
+              {
+                $eq: [
+                  {
+                    $subtract: [
+                      '$$smartdataAtomicExprLeft',
+                      '$$smartdataAtomicExprLeft',
+                    ],
+                  },
+                  0,
+                ],
+              },
+              {
+                $eq: [
+                  {
+                    $subtract: [
+                      '$$smartdataAtomicExprRight',
+                      '$$smartdataAtomicExprRight',
+                    ],
+                  },
+                  0,
+                ],
+              },
+            ],
+          },
+          {
+            $lte: [
+              '$$smartdataAtomicExprLeft',
+              '$$smartdataAtomicExprRight',
+            ],
+          },
+          false,
+        ],
+      },
+    },
+  };
+  return fieldGuards.length > 0
+    ? {
+        $cond: [
+          { $and: fieldGuards },
+          guardedComparison,
+          false,
+        ],
+      }
+    : guardedComparison;
+};
+
+const normalizeStrictFilter = (
+  filterArg: Record<string, unknown>,
+  declaredRootsArg: Set<string>,
+  declaredNestedPathsArg: Set<string>,
+  identityValueTypesArg: ReadonlyMap<string, TSmartdataIdentityValueType>,
+  numericRootsArg: Set<string>,
+  serializedRootsArg: Set<string>,
+  operationLabelArg:
+    | 'Atomic update'
+    | 'Atomic update-many'
+    | 'Atomic find-one-and-update'
+    | 'Atomic delete'
+    | 'Atomic delete-many',
+  globallyConstrainingKeySetsArg?: ReadonlyArray<ReadonlySet<string>>,
+): plugins.mongodb.Filter<plugins.mongodb.Document> => {
+  if (
+    typeof filterArg !== 'object' ||
+    filterArg === null ||
+    Array.isArray(filterArg) ||
+    plugins.nodeUtil.types.isProxy(filterArg) ||
+    !isPlainObject(filterArg) ||
+    Object.keys(filterArg).length === 0
+  ) {
+    throw new SmartdataPersistenceError(
+      'invalid_argument',
+      `${operationLabelArg} requires a non-empty filter object.`,
+    );
+  }
+  assertOnlyDataProperties(
+    filterArg,
+    `${operationLabelArg} filter`,
+    false,
+  );
+  const requireInertLogicalFilterArray: (
+    valueArg: unknown,
+    labelArg: string,
+  ) => asserts valueArg is Array<Record<string, unknown>> = (
+    valueArg,
+    labelArg,
+  ) => {
+    if (
+      !Array.isArray(valueArg)
+      || plugins.nodeUtil.types.isProxy(valueArg)
+      || Object.getPrototypeOf(valueArg) !== Array.prototype
+      || valueArg.length === 0
+    ) {
+      throw new SmartdataPersistenceError(
+        'invalid_argument',
+        `${labelArg} must be a non-empty ordinary array of filters.`,
+      );
+    }
+    assertOnlyDataProperties(valueArg, labelArg, true);
+    for (let index = 0; index < valueArg.length; index++) {
+      if (!Object.prototype.hasOwnProperty.call(valueArg, index)) {
+        throw new SmartdataPersistenceError(
+          'invalid_argument',
+          `${labelArg} may not contain sparse array positions.`,
+        );
+      }
+      const entry = valueArg[index];
+      if (
+        typeof entry !== 'object'
+        || entry === null
+        || Array.isArray(entry)
+        || plugins.nodeUtil.types.isProxy(entry)
+        || !isPlainObject(entry)
+      ) {
+        throw new SmartdataPersistenceError(
+          'invalid_argument',
+          `${labelArg} entries must be plain filter objects.`,
+        );
+      }
+      assertOnlyDataProperties(entry, `${labelArg} entry`, false);
+    }
+  };
+  const conditionIsEqualityAnchor = (valueArg: unknown): boolean => {
+    if (Array.isArray(valueArg)) {
+      return false;
+    }
+    if (typeof valueArg !== 'object' || valueArg === null) {
+      return (
+        valueArg !== undefined
+        && typeof valueArg !== 'function'
+        && typeof valueArg !== 'symbol'
+      );
+    }
+    if (plugins.nodeUtil.types.isProxy(valueArg)) {
+      throw new SmartdataPersistenceError(
+        'invalid_argument',
+        `${operationLabelArg} filters may not contain Proxy values.`,
+      );
+    }
+    if (isAtomicMongoScalar(valueArg)) {
+      return true;
+    }
+    if (!isPlainObject(valueArg)) {
+      return false;
+    }
+    assertOnlyDataProperties(
+      valueArg,
+      `${operationLabelArg} filter condition`,
+      false,
+    );
+    const entries = Object.entries(valueArg);
+    if (entries.length !== 1 || entries[0][0] !== '$eq') {
+      return false;
+    }
+    const operand = entries[0][1];
+    if (Array.isArray(operand)) {
+      return false;
+    }
+    if (typeof operand !== 'object' || operand === null) {
+      return (
+        operand !== undefined
+        && typeof operand !== 'function'
+        && typeof operand !== 'symbol'
+      );
+    }
+    if (plugins.nodeUtil.types.isProxy(operand)) {
+      throw new SmartdataPersistenceError(
+        'invalid_argument',
+        `${operationLabelArg} filters may not contain Proxy values.`,
+      );
+    }
+    return isAtomicMongoScalar(operand);
+  };
+  const filterHasEqualityAnchor = (
+    filterObjectArg: Record<string, unknown>,
+  ): boolean => {
+    for (const [key, value] of Object.entries(filterObjectArg)) {
+      if (key === '$and' && Array.isArray(value)) {
+        requireInertLogicalFilterArray(value, '$and');
+        if (
+          value.some(
+            (entryArg) =>
+              isPlainObject(entryArg) &&
+              filterHasEqualityAnchor(entryArg),
+          )
+        ) {
+          return true;
+        }
+        continue;
+      }
+      if (key === '$or' && Array.isArray(value)) {
+        requireInertLogicalFilterArray(value, '$or');
+        if (
+          value.length > 0 &&
+          value.every(
+            (entryArg) =>
+              isPlainObject(entryArg) &&
+              filterHasEqualityAnchor(entryArg),
+          )
+        ) {
+          return true;
+        }
+        continue;
+      }
+      if (!key.startsWith('$') && conditionIsEqualityAnchor(value)) {
+        return true;
+      }
+    }
+    return false;
+  };
+  if (!filterHasEqualityAnchor(filterArg)) {
+    throw new SmartdataPersistenceError(
+      'invalid_argument',
+      `${operationLabelArg} filters require at least one top-level equality anchor.`,
+    );
+  }
+  const collectEqualityAnchoredKeys = (
+    filterObjectArg: Record<string, unknown>,
+    anchoredKeysArg: Set<string>,
+  ): void => {
+    for (const [key, value] of Object.entries(filterObjectArg)) {
+      if (key === '$and' && Array.isArray(value)) {
+        requireInertLogicalFilterArray(value, '$and');
+        for (const entryArg of value) {
+          if (isPlainObject(entryArg)) {
+            collectEqualityAnchoredKeys(entryArg, anchoredKeysArg);
+          }
+        }
+        continue;
+      }
+      // $or branches are deliberately excluded: an equality inside one $or
+      // branch does not globally constrain the matched document.
+      if (!key.startsWith('$') && conditionIsEqualityAnchor(value)) {
+        anchoredKeysArg.add(key);
+      }
+    }
+  };
+  if (globallyConstrainingKeySetsArg) {
+    const anchoredKeys = new Set<string>();
+    collectEqualityAnchoredKeys(filterArg, anchoredKeys);
+    const filterIsGloballyConstraining = globallyConstrainingKeySetsArg.some(
+      (keySetArg) =>
+        keySetArg.size > 0 &&
+        [...keySetArg].every((keyArg) => anchoredKeys.has(keyArg)),
+    );
+    if (!filterIsGloballyConstraining) {
+      throw new SmartdataPersistenceError(
+        'invalid_argument',
+        `${operationLabelArg} filters require equality anchors that fully pin an identity field or a declared unqualified unique index.`,
+      );
+    }
+  }
+  const normalizeFilterObject = (
+    filterObjectArg: Record<string, unknown>,
+    rootArg = false,
+  ): Record<string, unknown> => {
+    assertOnlyDataProperties(
+      filterObjectArg,
+      `${operationLabelArg} filter`,
+      false,
+    );
+    const normalized: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(filterObjectArg)) {
+      if (key === '$and' || key === '$or' || key === '$nor') {
+        requireInertLogicalFilterArray(value, key);
+        normalized[key] = value.map((entry) => {
+          if (Object.keys(entry).length === 0) {
+            throw new SmartdataPersistenceError(
+              'invalid_argument',
+              `${key} entries must be non-empty filter objects.`,
+            );
+          }
+          return normalizeFilterObject(entry, false);
+        });
+        continue;
+      }
+      if (key === '$expr') {
+        if (!rootArg) {
+          throw new SmartdataPersistenceError(
+            'invalid_argument',
+            `${operationLabelArg} permits $expr only at the root of the filter.`,
+          );
+        }
+        normalized[key] = normalizeAtomicNumericExpression(
+          value,
+          declaredRootsArg,
+          numericRootsArg,
+          serializedRootsArg,
+          operationLabelArg,
+        );
+        continue;
+      }
+      const root = requireDeclaredPath(
+        key,
+        declaredRootsArg,
+        `${operationLabelArg} filter`,
+        declaredNestedPathsArg,
+      );
+      if (serializedRootsArg.has(root)) {
+        throw new SmartdataPersistenceError(
+          'unsupported_operation',
+          `${operationLabelArg} filters cannot target serialized field "${key}".`,
+        );
+      }
+      if (identityValueTypesArg.has(root) && key !== root) {
+        throw new SmartdataPersistenceError(
+          'invalid_argument',
+          `${operationLabelArg} filters cannot target a nested path below immutable @unI() field "${root}".`,
+        );
+      }
+      normalized[key] = normalizeAtomicFilterCondition(
+        value,
+        `${operationLabelArg} filter path "${key}"`,
+        identityValueTypesArg.get(root),
+      );
+    }
+    return normalized;
+  };
+  return normalizeFilterObject(
+    filterArg,
+    true,
+  ) as plugins.mongodb.Filter<plugins.mongodb.Document>;
+};
+
+const pathsConflict = (leftArg: string, rightArg: string): boolean =>
+  leftArg === rightArg ||
+  leftArg.startsWith(`${rightArg}.`) ||
+  rightArg.startsWith(`${leftArg}.`);
+
+const normalizeAtomicUpdate = <T>(
+  updateArg: ISmartdataAtomicUpdate<T>,
+  declaredRootsArg: Set<string>,
+  declaredNestedPathsArg: Set<string>,
+  uniqueRootsArg: Set<string>,
+  serializedRootsArg: Set<string>,
+): plugins.mongodb.UpdateFilter<plugins.mongodb.Document> => {
+  if (
+    typeof updateArg !== 'object' ||
+    updateArg === null ||
+    Array.isArray(updateArg)
+  ) {
+    throw new SmartdataPersistenceError(
+      'invalid_argument',
+      'Atomic update must be an update object.',
+    );
+  }
+  const allowedOperators = new Set([
+    '$set',
+    '$unset',
+    '$inc',
+    '$setOnInsert',
+    '$push',
+    '$addToSet',
+    '$pull',
+  ]);
+  const arrayOperators = new Set(['$push', '$addToSet', '$pull']);
+  for (const operator of Object.keys(updateArg)) {
+    if (!allowedOperators.has(operator)) {
+      throw new SmartdataPersistenceError(
+        'invalid_argument',
+        `Atomic update operator "${operator}" is not supported.`,
+      );
+    }
+  }
+
+  const normalized: Record<string, Record<string, unknown>> = {};
+  const occupiedPaths: Array<{ path: string; operator: string }> = [];
+  for (const operator of allowedOperators) {
+    const operation = (updateArg as Record<string, unknown>)[operator];
+    if (operation === undefined) {
+      continue;
+    }
+    if (!isPlainObject(operation)) {
+      throw new SmartdataPersistenceError(
+        'invalid_argument',
+        `${operator} must be a plain object.`,
+      );
+    }
+    const entries = Object.entries(operation);
+    if (entries.length === 0) {
+      continue;
+    }
+    const normalizedOperation: Record<string, unknown> = {};
+    for (const [path, value] of entries) {
+      const root = requireDeclaredPath(
+        path,
+        declaredRootsArg,
+        operator,
+        declaredNestedPathsArg,
+      );
+      if (serializedRootsArg.has(root)) {
+        throw new SmartdataPersistenceError(
+          'unsupported_operation',
+          `${operator} cannot target serialized field "${path}".`,
+        );
+      }
+      if (uniqueRootsArg.has(root)) {
+        throw new SmartdataPersistenceError(
+          'invalid_argument',
+          `${operator} may not modify immutable @unI() field "${root}".`,
+        );
+      }
+      const conflict = occupiedPaths.find((occupiedPath) =>
+        pathsConflict(path, occupiedPath.path),
+      );
+      if (conflict) {
+        throw new SmartdataPersistenceError(
+          'invalid_argument',
+          `${operator} path "${path}" conflicts with ${conflict.operator} path "${conflict.path}".`,
+        );
+      }
+      occupiedPaths.push({ path, operator });
+      if (arrayOperators.has(operator)) {
+        if (path !== root) {
+          throw new SmartdataPersistenceError(
+            'invalid_argument',
+            `${operator} may only target declared top-level array fields; "${path}" is a nested path.`,
+          );
+        }
+        if (value === undefined) {
+          throw new SmartdataPersistenceError(
+            'invalid_argument',
+            `${operator} path "${path}" may not be undefined.`,
+          );
+        }
+        if (operator === '$pull') {
+          if (
+            value === null
+            || typeof value === 'string'
+            || typeof value === 'boolean'
+            || (typeof value === 'number' && Number.isFinite(value))
+          ) {
+            normalizedOperation[path] = value;
+            continue;
+          }
+          if (
+            typeof value !== 'object'
+            || Array.isArray(value)
+            || isPlainObject(value)
+            || value instanceof RegExp
+          ) {
+            throw new SmartdataPersistenceError(
+              'invalid_argument',
+              `$pull path "${path}" must use a scalar equality operand.`,
+            );
+          }
+          // Scalar BSON objects are stored as inert snapshots so a custom
+          // toBSON encoder can never rewrite the equality operand into an
+          // operator document at serialization time.
+          normalizedOperation[path] = createInertAtomicBsonScalarSnapshot(
+            value,
+            `$pull path "${path}"`,
+          );
+          continue;
+        }
+        if (
+          typeof value === 'object'
+          && value !== null
+          && !Array.isArray(value)
+          && !isPlainObject(value)
+        ) {
+          // Non-plain element objects (dates, binary views, BSON scalars)
+          // must be inert: a custom toBSON encoder could otherwise smuggle a
+          // modifier document such as $each past validation.
+          normalizedOperation[path] = createInertAtomicBsonScalarSnapshot(
+            value,
+            `${operator} path "${path}"`,
+          );
+          continue;
+        }
+        assertSafePersistedValue(value, `${operator} path "${path}"`);
+        normalizedOperation[path] = stripUndefinedValues(value);
+        continue;
+      }
+      if (operator === '$unset') {
+        if (value !== '' && value !== true && value !== 1) {
+          throw new SmartdataPersistenceError(
+            'invalid_argument',
+            `$unset path "${path}" must use "", true, or 1.`,
+          );
+        }
+        normalizedOperation[path] = '';
+        continue;
+      }
+      if (value === undefined) {
+        throw new SmartdataPersistenceError(
+          'invalid_argument',
+          `${operator} path "${path}" may not be undefined.`,
+        );
+      }
+      if (
+        operator === '$inc' &&
+        (typeof value !== 'number' || !Number.isFinite(value))
+      ) {
+        throw new SmartdataPersistenceError(
+          'invalid_argument',
+          `$inc path "${path}" must be a finite number.`,
+        );
+      }
+      if (operator !== '$inc') {
+        assertSafePersistedValue(value, `${operator} path "${path}"`);
+      }
+      normalizedOperation[path] =
+        operator === '$inc' ? value : stripUndefinedValues(value);
+    }
+    normalized[operator] = normalizedOperation;
+  }
+  if (Object.keys(normalized).length === 0) {
+    throw new SmartdataPersistenceError(
+      'invalid_argument',
+      'Atomic update must contain at least one non-empty operation.',
+    );
+  }
+  return normalized as plugins.mongodb.UpdateFilter<plugins.mongodb.Document>;
+};
+
+const normalizeProjection = <T>(
+  projectionArg: TSmartdataProjection<T> | undefined,
+  declaredRootsArg: Set<string>,
+  declaredNestedPathsArg?: Set<string>,
+): plugins.mongodb.Document | undefined => {
+  if (projectionArg === undefined) {
+    return undefined;
+  }
+  if (!isPlainObject(projectionArg) || Object.keys(projectionArg).length === 0) {
+    throw new SmartdataPersistenceError(
+      'invalid_argument',
+      'Projection must be a non-empty plain object.',
+    );
+  }
+  let inclusionMode: 0 | 1 | undefined;
+  const normalized: Record<string, 0 | 1> = {};
+  for (const [path, value] of Object.entries(projectionArg)) {
+    if (path !== '_id') {
+      requireDeclaredPath(path, declaredRootsArg, 'Projection', declaredNestedPathsArg);
+      if (inclusionMode === undefined) {
+        inclusionMode = value as 0 | 1;
+      } else if (inclusionMode !== value) {
+        throw new SmartdataPersistenceError(
+          'invalid_argument',
+          'Projection may not mix included and excluded fields except for _id.',
+        );
+      }
+    }
+    if (value !== 0 && value !== 1) {
+      throw new SmartdataPersistenceError(
+        'invalid_argument',
+        `Projection path "${path}" must use 0 or 1.`,
+      );
+    }
+    normalized[path] = value;
+  }
+  return normalized;
+};
+
+const normalizeSort = <T>(
+  sortArg: TSmartdataSort<T> | undefined,
+  declaredRootsArg: Set<string>,
+  declaredNestedPathsArg?: Set<string>,
+): plugins.mongodb.Sort | undefined => {
+  if (sortArg === undefined) {
+    return undefined;
+  }
+  if (!isPlainObject(sortArg) || Object.keys(sortArg).length === 0) {
+    throw new SmartdataPersistenceError(
+      'invalid_argument',
+      'Sort must be a non-empty ordered object.',
+    );
+  }
+  const normalized: Record<string, 1 | -1> = {};
+  for (const [path, direction] of Object.entries(sortArg)) {
+    if (path !== '_id') {
+      requireDeclaredPath(path, declaredRootsArg, 'Sort', declaredNestedPathsArg);
+    }
+    if (direction !== 1 && direction !== -1) {
+      throw new SmartdataPersistenceError(
+        'invalid_argument',
+        `Sort path "${path}" must use 1 or -1.`,
+      );
+    }
+    normalized[path] = direction;
+  }
+  return normalized;
+};
+
+const normalizeQueryHint = (
+  hintArg: string | undefined,
+  modelArg: Parameters<typeof getExpectedCollectionTopologyForModel>[0],
+): string | undefined => {
+  if (hintArg === undefined) {
+    return undefined;
+  }
+  if (
+    typeof hintArg !== 'string' ||
+    !getExpectedCollectionTopologyForModel(modelArg).indexes.some(
+      (indexArg) => indexArg.name === hintArg,
+    )
+  ) {
+    throw new SmartdataPersistenceError(
+      'invalid_argument',
+      'Query hint must name an index declared by this model or the built-in _id_ index.',
+    );
+  }
+  return hintArg;
+};
+
+export const convertFilterForMongoDb = (filterArg: { [key: string]: any }) => {
+  // SECURITY: Block $where to prevent server-side JS execution
+  if (filterArg.$where !== undefined) {
+    throw new Error('$where operator is not allowed for security reasons');
+  }
+  
+  // Handle logical operators recursively
+  const logicalOperators = ['$and', '$or', '$nor', '$not'];
+  const processedFilter: { [key: string]: any } = {};
+  
+  for (const key of Object.keys(filterArg)) {
+    if (logicalOperators.includes(key)) {
+      if (key === '$not') {
+        processedFilter[key] = convertFilterForMongoDb(filterArg[key]);
+      } else if (Array.isArray(filterArg[key])) {
+        processedFilter[key] = filterArg[key].map((subFilter: any) => convertFilterForMongoDb(subFilter));
+      }
+    }
+  }
+  
+  // If only logical operators, return them
+  const hasOnlyLogicalOperators = Object.keys(filterArg).every(key => logicalOperators.includes(key));
+  if (hasOnlyLogicalOperators) {
+    return processedFilter;
+  }
+
+  // Original conversion logic for non-MongoDB query objects
+  const convertedFilter: { [key: string]: any } = {};
+  
+  // Helper to merge operator objects
+  const mergeIntoConverted = (path: string, value: any) => {
+    const existing = convertedFilter[path];
+    if (!existing) {
+      convertedFilter[path] = value;
+    } else if (
+      typeof existing === 'object' && !Array.isArray(existing) &&
+      typeof value === 'object' && !Array.isArray(value) &&
+      (Object.keys(existing).some(k => k.startsWith('$')) || Object.keys(value).some(k => k.startsWith('$')))
+    ) {
+      // Both have operators, merge them
+      convertedFilter[path] = { ...existing, ...value };
+    } else {
+      // Otherwise later wins
+      convertedFilter[path] = value;
+    }
+  };
+
+  const isAtomicMongoValue = (valueArg: unknown): boolean => {
+    if (valueArg instanceof Date || valueArg instanceof RegExp) {
+      return true;
+    }
+    if (ArrayBuffer.isView(valueArg)) {
+      return true;
+    }
+    return (
+      typeof valueArg === 'object' &&
+      valueArg !== null &&
+      typeof (valueArg as { _bsontype?: unknown })._bsontype === 'string'
+    );
+  };
+
+  const convertFilterArgument = (keyPathArg2: string, filterArg2: any) => {
+    if (Array.isArray(filterArg2)) {
+      // Arrays are typically used as values for operators like $in or as direct equality matches
+      mergeIntoConverted(keyPathArg2, filterArg2);
+      return;
+    } else if (isAtomicMongoValue(filterArg2)) {
+      // BSON values, dates, regexes, and binary views are scalar query values.
+      // Recursing into them can silently turn an _id filter into an empty filter.
+      mergeIntoConverted(keyPathArg2, filterArg2);
+      return;
+    } else if (typeof filterArg2 === 'object' && filterArg2 !== null) {
+      // Check if this is an object with MongoDB operators
+      const keys = Object.keys(filterArg2);
+      const hasOperators = keys.some(key => key.startsWith('$'));
+      
+      if (hasOperators) {
+        // This object contains MongoDB operators
+        // Validate and pass through allowed operators
+        const allowedOperators = [
+          // Comparison operators
+          '$eq', '$ne', '$gt', '$gte', '$lt', '$lte',
+          // Array operators
+          '$in', '$nin', '$all', '$elemMatch', '$size',
+          // Element operators
+          '$exists', '$type',
+          // Evaluation operators (safe ones only)
+          '$regex', '$options', '$text', '$mod',
+          // Logical operators (nested)
+          '$and', '$or', '$nor', '$not'
+        ];
+        
+        // Check for dangerous operators
+        if (keys.includes('$where')) {
+          throw new Error('$where operator is not allowed for security reasons');
+        }
+        
+        // Validate all operators are in the allowed list
+        const invalidOperators = keys.filter(key => 
+          key.startsWith('$') && !allowedOperators.includes(key)
+        );
+        
+        if (invalidOperators.length > 0) {
+          console.warn(`Warning: Unknown MongoDB operators detected: ${invalidOperators.join(', ')}`);
+        }
+        
+        // For array operators, ensure the values are appropriate
+        if (filterArg2.$in && !Array.isArray(filterArg2.$in)) {
+          throw new Error('$in operator requires an array value');
+        }
+        if (filterArg2.$nin && !Array.isArray(filterArg2.$nin)) {
+          throw new Error('$nin operator requires an array value');
+        }
+        if (filterArg2.$all && !Array.isArray(filterArg2.$all)) {
+          throw new Error('$all operator requires an array value');
+        }
+        if (filterArg2.$size && typeof filterArg2.$size !== 'number') {
+          throw new Error('$size operator requires a numeric value');
+        }
+        
+        // Use merge helper to handle duplicate paths
+        mergeIntoConverted(keyPathArg2, filterArg2);
+        return;
+      }
+      
+      // No operators, check for dots in keys
+      for (const key of keys) {
+        if (key.includes('.')) {
+          throw new Error('keys cannot contain dots');
+        }
+      }
+      
+      // Recursively process nested objects
+      for (const key of keys) {
+        convertFilterArgument(`${keyPathArg2}.${key}`, filterArg2[key]);
+      }
+    } else {
+      // Primitive values
+      mergeIntoConverted(keyPathArg2, filterArg2);
+    }
+  };
+
+  for (const key of Object.keys(filterArg)) {
+    // Skip logical operators, they were already processed
+    if (!logicalOperators.includes(key)) {
+      convertFilterArgument(key, filterArg[key]);
+    }
+  }
+  
+  // Add back processed logical operators
+  Object.assign(convertedFilter, processedFilter);
+  
+  return convertedFilter;
+};
+
+export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends IManager = any> {
+  /**
+   * the collection object an Doc belongs to
+   */
+  public static collection: SmartdataCollection<any>;
+  public static get exact(): unknown {
+    throw new Error('Model is not configured for exact persistence.');
+  }
+  declare public collection: SmartdataCollection<any>;
+  public static defaultManager;
+  public static manager;
+  declare public manager: TManager;
+
+  /**
+   * Helper to get collection with fallback to static for Deno compatibility
+   */
+  private getCollectionSafe(): SmartdataCollection<any> {
+    return this.collection || (this.constructor as any).collection;
+  }
+
+  // STATIC
+  /** Insert a strict primary-only bootstrap record without separate collection/index DDL. */
+  public static async insertBootstrapRecord(
+    dbArg: SmartdataDb,
+    recordArg: unknown,
+    optionsArg?: ISmartdataBootstrapRecordOptions,
+  ): Promise<ISmartdataBootstrapRecordResult> {
+    return insertBootstrapRecord(this, dbArg, recordArg, optionsArg);
+  }
+
+  /** Inspect bounded stored BSON without initializing or hydrating the model. */
+  public static async inspectStoredDocuments(
+    dbArg: SmartdataDb,
+    optionsArg?: ISmartdataStoredInspectionOptions,
+  ): Promise<ISmartdataStoredInspection> {
+    return inspectStoredDocuments(this, dbArg, optionsArg);
+  }
+
+  /** Diagnose stored BSON with explicit ordinary validation evidence, without hydration. */
+  public static async inspectStoredDocumentEvidence(
+    dbArg: SmartdataDb,
+    optionsArg: ISmartdataStoredInspectionOptions = {},
+  ): Promise<ISmartdataStoredEvidenceInspection> {
+    return inspectStoredDocumentEvidence(this, dbArg, optionsArg);
+  }
+
+  public static createInstanceFromMongoDbNativeDoc<T>(
+    this: plugins.tsclass.typeFest.Class<T>,
+    mongoDbNativeDocArg: any,
+  ): T {
+    const policy = getOrdinaryPersistencePolicy(this);
+    if (policy) {
+      mongoDbNativeDocArg = validateOrdinaryStoredDocument(
+        mongoDbNativeDocArg, policy,
+        [...(this as any).getDeclaredPersistedRoots()],
+      );
+    }
+    const newInstance = new this() as T & Record<string, any>;
+    if (policy) {
+      for (const field of (this as any).getDeclaredPersistedRoots() as Set<string>) {
+        if (!Object.prototype.hasOwnProperty.call(mongoDbNativeDocArg, field)) {
+          delete newInstance[field];
+        }
+      }
+    }
+    if (policy?.timestamps === 'none') {
+      delete newInstance['_createdAt'];
+      delete newInstance['_updatedAt'];
+    }
+    (newInstance as any).creationStatus = 'db';
+    for (const key of Object.keys(mongoDbNativeDocArg)) {
+      const rawValue = mongoDbNativeDocArg[key];
+      const optionsMap = (this as any)._svDbOptions || {};
+      const opts = optionsMap[key];
+      (newInstance as any)[key] = opts && typeof opts.deserialize === 'function'
+        ? opts.deserialize(rawValue)
+        : rawValue;
+    }
+    return newInstance;
+  }
+
+  private static getDeclaredPersistedRoots(): Set<string> {
+    const prototype = this.prototype as {
+      globalSaveableProperties?: string[];
+      saveableProperties?: string[];
+    };
+    const roots = new Set([
+      ...(prototype.globalSaveableProperties || []),
+      ...(prototype.saveableProperties || []),
+    ]);
+    if (getOrdinaryPersistencePolicy(this)?.idType === 'string') {
+      roots.add('_id');
+      stringIdRootSets.add(roots);
+    }
+    return roots;
+  }
+
+  private static getDeclaredUniqueRoots(): Set<string> {
+    const prototype = this.prototype as {
+      uniqueIndexes?: string[];
+    };
+    return new Set([
+      ...(prototype.uniqueIndexes || []),
+      ...(getOrdinaryPersistencePolicy(this)?.idType === 'string' ? ['_id'] : []),
+    ]);
+  }
+
+  private static getDeclaredIdentityValueTypes(): Map<
+    string,
+    TSmartdataIdentityValueType
+  > {
+    const prototype = this.prototype as {
+      uniqueIndexes?: string[];
+      identityValueTypes?: Record<string, TSmartdataIdentityValueType>;
+    };
+    return new Map(
+      [...(this as any).getDeclaredUniqueRoots() as Set<string>].map((identityFieldArg) => [
+        identityFieldArg,
+        prototype.identityValueTypes?.[identityFieldArg] ?? 'string',
+      ]),
+    );
+  }
+
+  private static getDeclaredNumericRoots(): Set<string> {
+    const collection: SmartdataCollection<any> = (this as any).collection;
+    return new Set(collection.getBoundModelSchema()?.numericFields || []);
+  }
+
+  /**
+   * Returns every equality key set that globally constrains a single document
+   * of this model: each declared identity field on its own, plus the full key
+   * set of every declared unqualified unique index. Unique indexes that carry
+   * any option beyond `unique` (sparse, partial, or otherwise uninterpretable)
+   * or a non-numeric key direction do not qualify — such indexes do not
+   * guarantee at most one matching document for an equality filter.
+   */
+  private static getGloballyConstrainingKeySets(): ReadonlyArray<
+    ReadonlySet<string>
+  > {
+    const keySets: Array<ReadonlySet<string>> = [];
+    for (const identityField of (this as any).getDeclaredUniqueRoots() as Set<string>) {
+      keySets.push(new Set([identityField]));
+    }
+    const collection: SmartdataCollection<any> = (this as any).collection;
+    const modelSchema = collection.getBoundModelSchema();
+    if (modelSchema) {
+      for (const index of modelSchema.indexes) {
+        if (index.options.unique !== true) {
+          continue;
+        }
+        const hasUnqualifiedOptions = Object.keys(index.options).every(
+          (optionKeyArg) =>
+            optionKeyArg === 'unique' || optionKeyArg === 'background',
+        );
+        if (!hasUnqualifiedOptions) {
+          continue;
+        }
+        if (
+          index.key.length === 0 ||
+          index.key.some(
+            ([, directionArg]) => directionArg !== 1 && directionArg !== -1,
+          )
+        ) {
+          continue;
+        }
+        keySets.push(new Set(index.key.map(([fieldArg]) => fieldArg)));
+      }
+    }
+    return keySets;
+  }
+
+  private static getDeclaredAtomicPaths(): Set<string> {
+    const declaredRoots = (this as any).getDeclaredPersistedRoots() as Set<string>;
+    const uniqueRoots = (this as any).getDeclaredUniqueRoots() as Set<string>;
+    const options = (this as any)._svDbOptions as
+      | Record<string, SvDbOptions>
+      | undefined;
+    const atomicPaths = new Set<string>();
+    for (const [root, fieldOptions] of Object.entries(options || {})) {
+      if (fieldOptions.atomicPaths === undefined) {
+        continue;
+      }
+      if (!Array.isArray(fieldOptions.atomicPaths)) {
+        throw new SmartdataPersistenceError(
+          'invalid_configuration',
+          `Atomic paths for persisted field "${root}" must be an array.`,
+        );
+      }
+      if (
+        typeof fieldOptions.serialize === 'function'
+        || typeof fieldOptions.deserialize === 'function'
+      ) {
+        throw new SmartdataPersistenceError(
+          'invalid_configuration',
+          `Serialized persisted field "${root}" may not declare atomic nested paths.`,
+        );
+      }
+      if (uniqueRoots.has(root)) {
+        throw new SmartdataPersistenceError(
+          'invalid_configuration',
+          `Immutable @unI() field "${root}" may not declare atomic nested paths.`,
+        );
+      }
+      for (const relativePath of fieldOptions.atomicPaths) {
+        if (typeof relativePath !== 'string' || relativePath.length === 0) {
+          throw new SmartdataPersistenceError(
+            'invalid_configuration',
+            `Atomic paths for persisted field "${root}" must be non-empty strings.`,
+          );
+        }
+        const fullPath = `${root}.${relativePath}`;
+        try {
+          requireDeclaredPath(
+            fullPath,
+            declaredRoots,
+            'Atomic path declaration',
+            new Set([fullPath]),
+          );
+        } catch (errorArg) {
+          throw new SmartdataPersistenceError(
+            'invalid_configuration',
+            `Atomic path declaration "${fullPath}" is invalid.`,
+            { cause: errorArg },
+          );
+        }
+        atomicPaths.add(fullPath);
+      }
+    }
+    return atomicPaths;
+  }
+
+  private static getSerializedPersistedRoots(): Set<string> {
+    const options = (this as any)._svDbOptions as
+      | Record<
+          string,
+          {
+            serialize?: unknown;
+            deserialize?: unknown;
+          }
+        >
+      | undefined;
+    return new Set(
+      Object.entries(options || {})
+        .filter(
+          ([, fieldOptions]) =>
+            typeof fieldOptions.serialize === 'function' ||
+            typeof fieldOptions.deserialize === 'function',
+        )
+        .map(([field]) => field),
+    );
+  }
+
+  private static getDeclaredQueryPaths(): Set<string> {
+    return new Set([
+      ...(this as any).getDeclaredAtomicPaths() as Set<string>,
+      ...getExpectedCollectionTopologyForModel(this).indexes.flatMap(
+        (indexArg) => indexArg.keys.map((keyArg) => keyArg.path),
+      ),
+    ]);
+  }
+
+  private static assertHydratedProjection(projectionArg?: unknown, modifierArg?: unknown): void {
+    if (getOrdinaryPersistencePolicy(this) && (projectionArg !== undefined || modifierArg !== undefined)) {
+      throw new SmartdataPersistenceError('unsupported_operation',
+        'Whole-stored-document validation requires an unprojected read without native modifiers.');
+    }
+  }
+
+  /**
+   * Initializes the model collection and all model-owned indexes. Failed
+   * initialization is retryable after the underlying conflict is repaired.
+   */
+  public static async init(): Promise<void> {
+    const collection: SmartdataCollection<any> = (this as any).collection;
+    await collection.init();
+  }
+
+  public static async ensureInitialized(): Promise<void> {
+    await this.init();
+  }
+
+  /** Verify or install the model's exact topology within one explicit deadline. */
+  public static async prepareCollection(opts: ISmartdataCollectionPreparationOptions): Promise<void> {
+    validateCollectionPreparationOptions(opts);
+    const collection: SmartdataCollection<any> = (this as any).collection;
+    await collection.prepareCollection(opts);
+  }
+
+  /**
+   * Returns a sanitized view of the indexes installed for this model.
+   */
+  public static async getIndexInfo(): Promise<ISmartdataIndexInfo[]> {
+    const collection: SmartdataCollection<any> = (this as any).collection;
+    return collection.getIndexInfo();
+  }
+
+  /**
+   * Returns the model's immutable collection and index contract without
+   * resolving a manager, database, or SmartdataCollection.
+   */
+  public static getExpectedCollectionTopology(): ISmartdataExpectedCollectionTopology {
+    return getExpectedCollectionTopologyForModel(this as any);
+  }
+
+  /**
+   * Inspects an explicitly supplied connected database without initializing or
+   * mutating the model collection.
+   */
+  public static async inspectCollectionTopology(
+    dbArg: SmartdataDb,
+  ): Promise<ISmartdataCollectionTopologyInspection> {
+    return inspectCollectionTopologyForModel(this as any, dbArg);
+  }
+
+  /**
+   * Inserts a newly constructed ordinary model through SmartData.
+   */
+  public static async insert<T extends SmartDataDbDoc<any, any>>(
+    this: plugins.tsclass.typeFest.Class<T>,
+    documentArg: T,
+    opts?: { session?: TSmartdataOrdinarySession },
+  ): Promise<plugins.mongodb.InsertOneResult<{ _id: TSmartdataPrimaryId<T> }>> {
+    if ((this as any)[exactPersistencePolicySymbol]) {
+      throw new SmartdataPersistenceError(
+        'unsupported_operation',
+        'Ordinary insert is unavailable for exact-persistence models.',
+      );
+    }
+    if (!(documentArg instanceof this)) {
+      throw new SmartdataPersistenceError(
+        'invalid_argument',
+        `Model insert requires an instance of "${this.name}".`,
+      );
+    }
+    if (documentArg.creationStatus !== 'new') {
+      throw new SmartdataPersistenceError(
+        'invalid_argument',
+        'Model insert requires a newly constructed document.',
+      );
+    }
+    assertUsableIdentityValues(
+      documentArg as unknown as Record<string, unknown>,
+      (this.prototype as { uniqueIndexes?: string[] }).uniqueIndexes || [],
+      (this.prototype as {
+        identityValueTypes?: Record<string, TSmartdataIdentityValueType>;
+      }).identityValueTypes,
+    );
+    const now = new Date().toISOString();
+    if (getOrdinaryPersistencePolicy(this)?.timestamps !== 'none') {
+      documentArg._createdAt = now;
+      documentArg._updatedAt = now;
+    }
+    const collection: SmartdataCollection<T> = (this as any).collection;
+    const result = await collection.insert(documentArg as any, opts);
+    if (!isOrdinarySessionInTransaction(opts?.session)) {
+      documentArg.creationStatus = 'db';
+    }
+    return result as unknown as plugins.mongodb.InsertOneResult<{ _id: TSmartdataPrimaryId<T> }>;
+  }
+
+  /**
+   * Inserts a batch of newly constructed ordinary models through SmartData.
+   * Each document inserts atomically; the batch as a whole is not isolated
+   * unless the caller supplies a transaction session. With ordered semantics
+   * (the default) MongoDB stops at the first failure; documents MongoDB
+   * reports as inserted are marked database-backed even when the batch fails
+   * part-way, so callers can compensate precisely.
+   */
+  public static async insertMany<T extends SmartDataDbDoc<any, any>>(
+    this: plugins.tsclass.typeFest.Class<T>,
+    documentsArg: T[],
+    opts?: { session?: TSmartdataOrdinarySession; ordered?: boolean },
+  ): Promise<plugins.mongodb.InsertManyResult<{ _id: TSmartdataPrimaryId<T> }>> {
+    if ((this as any)[exactPersistencePolicySymbol]) {
+      throw new SmartdataPersistenceError(
+        'unsupported_operation',
+        'Ordinary insertMany is unavailable for exact-persistence models.',
+      );
+    }
+    if (!Array.isArray(documentsArg) || documentsArg.length === 0) {
+      throw new SmartdataPersistenceError(
+        'invalid_argument',
+        'Model insertMany requires a non-empty array of documents.',
+      );
+    }
+    if (
+      opts?.ordered !== undefined
+      && typeof opts.ordered !== 'boolean'
+    ) {
+      throw new SmartdataPersistenceError(
+        'invalid_argument',
+        'Model insertMany ordered must be a boolean.',
+      );
+    }
+    const seenDocuments = new Set<T>();
+    for (const documentArg of documentsArg) {
+      if (!(documentArg instanceof this)) {
+        throw new SmartdataPersistenceError(
+          'invalid_argument',
+          `Model insertMany requires instances of "${this.name}".`,
+        );
+      }
+      if (documentArg.creationStatus !== 'new') {
+        throw new SmartdataPersistenceError(
+          'invalid_argument',
+          'Model insertMany requires newly constructed documents.',
+        );
+      }
+      if (seenDocuments.has(documentArg)) {
+        throw new SmartdataPersistenceError(
+          'invalid_argument',
+          'Model insertMany may not contain the same document instance twice.',
+        );
+      }
+      seenDocuments.add(documentArg);
+      assertUsableIdentityValues(
+        documentArg as unknown as Record<string, unknown>,
+        (this.prototype as { uniqueIndexes?: string[] }).uniqueIndexes || [],
+        (this.prototype as {
+          identityValueTypes?: Record<string, TSmartdataIdentityValueType>;
+        }).identityValueTypes,
+      );
+    }
+    const now = new Date().toISOString();
+    for (const documentArg of documentsArg) {
+      if (getOrdinaryPersistencePolicy(this)?.timestamps !== 'none') {
+        documentArg._createdAt = now;
+        documentArg._updatedAt = now;
+      }
+    }
+    const collection: SmartdataCollection<T> = (this as any).collection;
+    const inTransaction = isOrdinarySessionInTransaction(opts?.session);
+    const markInsertedDocuments = (
+      insertedIdsArg: Record<number, unknown> | undefined,
+    ): void => {
+      if (inTransaction || !insertedIdsArg) {
+        return;
+      }
+      for (const indexKey of Object.keys(insertedIdsArg)) {
+        const insertedDocument = documentsArg[Number(indexKey)];
+        if (insertedDocument) {
+          insertedDocument.creationStatus = 'db';
+        }
+      }
+    };
+    try {
+      const result = await collection.insertMany(documentsArg as any, opts);
+      markInsertedDocuments(
+        result.insertedIds as unknown as Record<number, unknown>,
+      );
+      return result as unknown as plugins.mongodb.InsertManyResult<{ _id: TSmartdataPrimaryId<T> }>;
+    } catch (error) {
+      const bulkError = error instanceof SmartdataPersistenceError
+        ? error.cause
+        : error;
+      if (bulkError instanceof plugins.mongodb.MongoBulkWriteError) {
+        markInsertedDocuments(
+          bulkError.result?.insertedIds as unknown as
+            | Record<number, unknown>
+            | undefined,
+        );
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Inserts absent identities without changing existing documents, including
+   * their timestamps. The unordered batch is bounded to 1000 documents and
+   * 16 MiB of serialized BSON. New-model timestamps are preserved. Inputs stay
+   * new so the same batch can be retried after an ambiguous result; read a
+   * stored instance before updating it because an existing body may differ.
+   */
+  public static async insertManyIfAbsent<T extends SmartDataDbDoc<any, any>>(
+    this: plugins.tsclass.typeFest.Class<T>,
+    documentsArg: T[],
+    opts: ISmartdataInsertManyIfAbsentOptions<T>,
+  ): Promise<ISmartdataInsertManyIfAbsentResult> {
+    if ((this as any)[exactPersistencePolicySymbol]) {
+      throw new SmartdataPersistenceError('unsupported_operation',
+        'insertManyIfAbsent is unavailable for exact-persistence models.');
+    }
+    if (!Array.isArray(documentsArg) || documentsArg.length < 1 || documentsArg.length > 1000) {
+      throw new SmartdataPersistenceError('invalid_argument',
+        'insertManyIfAbsent requires 1 to 1000 newly constructed documents.');
+    }
+    const identityTypes = (this as any).getDeclaredIdentityValueTypes() as Map<string, TSmartdataIdentityValueType>;
+    const serializedRoots = (this as any).getSerializedPersistedRoots() as Set<string>;
+    const identityField = opts?.identityField;
+    if (typeof identityField !== 'string' || !identityTypes.has(identityField) || serializedRoots.has(identityField)) {
+      throw new SmartdataPersistenceError('invalid_argument',
+        'insertManyIfAbsent requires a declared, non-serialized @unI identity field.');
+    }
+    const timeoutMS = requireBoundedInteger(opts?.timeoutMS, 'insertManyIfAbsent timeoutMS', 120_000);
+    const identities = new Set<string | number>();
+    for (const document of documentsArg) {
+      if (!(document instanceof this) || document.creationStatus !== 'new') {
+        throw new SmartdataPersistenceError('invalid_argument',
+          'insertManyIfAbsent requires newly constructed instances of the receiving model.');
+      }
+      assertUsableIdentityValues(document as unknown as Record<string, unknown>,
+        (this.prototype as { uniqueIndexes?: string[] }).uniqueIndexes || [],
+        (this.prototype as { identityValueTypes?: Record<string, TSmartdataIdentityValueType> }).identityValueTypes);
+      const identity = document[identityField] as string | number;
+      if (identities.has(identity)) {
+        throw new SmartdataPersistenceError('invalid_argument',
+          'insertManyIfAbsent may not repeat an identity within one batch.');
+      }
+      identities.add(identity);
+      if (getOrdinaryPersistencePolicy(this)?.timestamps !== 'none') {
+        for (const timestamp of [document._createdAt, document._updatedAt]) {
+          if (typeof timestamp !== 'string' || !Number.isFinite(Date.parse(timestamp))) {
+            throw new SmartdataPersistenceError('invalid_argument',
+              'insertManyIfAbsent requires valid creation and update timestamps.');
+          }
+        }
+      }
+    }
+    const collection: SmartdataCollection<T> = (this as any).collection;
+    return await collection.insertManyIfAbsent(documentsArg as any, identityField, {
+      session: opts.session,
+      timeoutMS,
+    });
+  }
+
+  /**
+   * Atomically updates one ordinary model document using a strict selector
+   * and a bounded set of MongoDB update operators.
+   */
+  public static async atomicUpdate<T>(
+    this: plugins.tsclass.typeFest.Class<T>,
+    filterArg: TSmartdataAtomicFilter<T>,
+    updateArg: ISmartdataAtomicUpdate<T>,
+    opts?: ISmartdataAtomicUpdateOptions,
+  ): Promise<ISmartdataAtomicUpdateResult> {
+    if (getOrdinaryPersistencePolicy(this)) {
+      throw new SmartdataPersistenceError('unsupported_operation',
+        'Validated ordinary models require a transactional postimage update.');
+    }
+    if ((this as any)[exactPersistencePolicySymbol]) {
+      throw new SmartdataPersistenceError(
+        'unsupported_operation',
+        'atomicUpdate is unavailable for exact-persistence models.',
+      );
+    }
+    const declaredRoots = (this as any).getDeclaredPersistedRoots() as Set<string>;
+    const declaredAtomicPaths = (this as any).getDeclaredAtomicPaths() as Set<string>;
+    const identityValueTypes = (this as any).getDeclaredIdentityValueTypes() as Map<
+      string,
+      TSmartdataIdentityValueType
+    >;
+    const numericRoots = (this as any).getDeclaredNumericRoots() as Set<string>;
+    const uniqueRoots = new Set(identityValueTypes.keys());
+    const serializedRoots = (this as any).getSerializedPersistedRoots() as Set<string>;
+    const normalizedFilter = normalizeStrictFilter(
+      filterArg as Record<string, unknown>,
+      declaredRoots,
+      declaredAtomicPaths,
+      identityValueTypes,
+      numericRoots,
+      serializedRoots,
+      'Atomic update',
+    );
+    const normalizedOptions = '$expr' in normalizedFilter
+      ? normalizeAtomicExpressionUpdateOptions(opts)
+      : opts;
+    if (normalizedOptions?.upsert === true && '$expr' in normalizedFilter) {
+      throw new SmartdataPersistenceError(
+        'invalid_argument',
+        'Atomic update does not support upsert when the filter contains $expr.',
+      );
+    }
+    const normalizedUpdate = normalizeAtomicUpdate(
+      updateArg,
+      declaredRoots,
+      declaredAtomicPaths,
+      uniqueRoots,
+      serializedRoots,
+    );
+    const now = new Date().toISOString();
+    normalizedUpdate.$set = {
+      ...(normalizedUpdate.$set || {}),
+      _updatedAt: now,
+    };
+    if (normalizedOptions?.upsert === true) {
+      normalizedUpdate.$setOnInsert = {
+        ...(normalizedUpdate.$setOnInsert || {}),
+        _createdAt: now,
+      };
+    }
+    const collection: SmartdataCollection<T> = (this as any).collection;
+    const result = await executeAtomicUpdate(
+      collection,
+      normalizedFilter,
+      normalizedUpdate,
+      normalizedOptions,
+    );
+    return {
+      acknowledged: result.acknowledged,
+      matchedCount: result.matchedCount,
+      modifiedCount: result.modifiedCount,
+      upsertedId: result.upsertedId as plugins.mongodb.ObjectId | null,
+    };
+  }
+
+  /**
+   * Atomically updates one ordinary model document and returns a hydrated
+   * before or after image with a sanitized persistence outcome.
+   */
+  public static async atomicFindOneAndUpdate<
+    T,
+    TReturnDocument extends TSmartdataAtomicReturnDocument,
+  >(
+    this: plugins.tsclass.typeFest.Class<T>,
+    filterArg: TSmartdataAtomicFilter<T>,
+    updateArg: ISmartdataAtomicUpdate<T>,
+    optionsArg: ISmartdataAtomicFindOneAndUpdateOptions<TReturnDocument, T>,
+  ): Promise<TSmartdataAtomicFindOneAndUpdateResult<T, TReturnDocument>> {
+    if ((this as any)[exactPersistencePolicySymbol]) {
+      throw new SmartdataPersistenceError(
+        'unsupported_operation',
+        'atomicFindOneAndUpdate is unavailable for exact-persistence models.',
+      );
+    }
+    const normalizedOptions = normalizeAtomicFindOneAndUpdateOptions(optionsArg);
+    const policy = getOrdinaryPersistencePolicy(this);
+    const declaredRoots = (this as any).getDeclaredPersistedRoots() as Set<string>;
+    const declaredAtomicPaths = (this as any).getDeclaredAtomicPaths() as Set<string>;
+    const identityValueTypes = (this as any).getDeclaredIdentityValueTypes() as Map<
+      string,
+      TSmartdataIdentityValueType
+    >;
+    const numericRoots = (this as any).getDeclaredNumericRoots() as Set<string>;
+    const uniqueRoots = new Set(identityValueTypes.keys());
+    const serializedRoots = (this as any).getSerializedPersistedRoots() as Set<string>;
+    const normalizedFilter = normalizeStrictFilter(
+      filterArg as Record<string, unknown>,
+      declaredRoots,
+      declaredAtomicPaths,
+      identityValueTypes,
+      numericRoots,
+      serializedRoots,
+      'Atomic find-one-and-update',
+    );
+    if (normalizedOptions.upsert && '$expr' in normalizedFilter) {
+      throw new SmartdataPersistenceError(
+        'invalid_argument',
+        'Atomic find-one-and-update does not support upsert when the filter contains $expr.',
+      );
+    }
+    const normalizedUpdate = normalizeAtomicUpdate(
+      updateArg,
+      declaredRoots,
+      declaredAtomicPaths,
+      uniqueRoots,
+      serializedRoots,
+    );
+    if (policy?.timestamps !== 'none') {
+      const now = new Date().toISOString();
+      normalizedUpdate.$set = { ...(normalizedUpdate.$set || {}), _updatedAt: now };
+      if (normalizedOptions.upsert) {
+        normalizedUpdate.$setOnInsert = { ...(normalizedUpdate.$setOnInsert || {}), _createdAt: now };
+      }
+    }
+    const normalizedSort = normalizeSort(
+      normalizedOptions.sort as TSmartdataSort<T> | undefined,
+      declaredRoots,
+      (this as any).getDeclaredQueryPaths() as Set<string>,
+    );
+    const collection: SmartdataCollection<T> = (this as any).collection;
+    const result = await executeAtomicFindOneAndUpdate(
+      collection,
+      normalizedFilter,
+      normalizedUpdate,
+      {
+        returnDocument: normalizedOptions.returnDocument,
+        upsert: normalizedOptions.upsert,
+        ...(normalizedSort ? { sort: normalizedSort as Record<string, 1 | -1> } : {}),
+        ...(normalizedOptions.session ? { session: normalizedOptions.session } : {}),
+      },
+    );
+    if (result.document === null) {
+      return result as TSmartdataAtomicFindOneAndUpdateResult<T, TReturnDocument>;
+    }
+    return {
+      status: result.status,
+      document: (this as any).createInstanceFromMongoDbNativeDoc(result.document) as T,
+    } as TSmartdataAtomicFindOneAndUpdateResult<T, TReturnDocument>;
+  }
+
+  /**
+   * Atomically deletes one ordinary model document using a strict selector.
+   *
+   * This static operation intentionally does not hydrate an instance or run
+   * instance deletion hooks. Callers that require those hooks must use the
+   * instance `delete()` method instead.
+   */
+  public static async atomicDelete<T>(
+    this: plugins.tsclass.typeFest.Class<T>,
+    filterArg: TSmartdataAtomicFilter<T>,
+    opts?: ISmartdataAtomicDeleteOptions,
+  ): Promise<ISmartdataAtomicDeleteResult> {
+    if ((this as any)[exactPersistencePolicySymbol]) {
+      throw new SmartdataPersistenceError(
+        'unsupported_operation',
+        'atomicDelete is unavailable for exact-persistence models.',
+      );
+    }
+    const declaredRoots = (this as any).getDeclaredPersistedRoots() as Set<string>;
+    const declaredAtomicPaths = (this as any).getDeclaredAtomicPaths() as Set<string>;
+    const identityValueTypes = (this as any).getDeclaredIdentityValueTypes() as Map<
+      string,
+      TSmartdataIdentityValueType
+    >;
+    const numericRoots = (this as any).getDeclaredNumericRoots() as Set<string>;
+    const serializedRoots = (this as any).getSerializedPersistedRoots() as Set<string>;
+    const normalizedFilter = normalizeStrictFilter(
+      filterArg as Record<string, unknown>,
+      declaredRoots,
+      declaredAtomicPaths,
+      identityValueTypes,
+      numericRoots,
+      serializedRoots,
+      'Atomic delete',
+      (this as any).getGloballyConstrainingKeySets(),
+    );
+    const collection: SmartdataCollection<T> = (this as any).collection;
+    const result = await executeAtomicDelete(
+      collection,
+      normalizedFilter,
+      { session: opts?.session, timeoutMS: requireBoundedInteger(opts?.timeoutMS, 'Atomic delete timeoutMS', 120_000) },
+    );
+    return {
+      acknowledged: result.acknowledged,
+      deletedCount: result.deletedCount,
+    };
+  }
+
+  /**
+   * Atomically deletes every ordinary model document matching a strict
+   * selector. Each matched document is deleted atomically; the batch as a
+   * whole is not isolated. Unlike `atomicDelete()`, the filter does not need
+   * to pin a unique index — plural intent is explicit in this API — but it
+   * still requires declared fields and at least one top-level equality
+   * anchor.
+   */
+  public static async atomicDeleteMany<T>(
+    this: plugins.tsclass.typeFest.Class<T>,
+    filterArg: TSmartdataAtomicFilter<T>,
+    opts?: ISmartdataAtomicDeleteOptions,
+  ): Promise<ISmartdataAtomicDeleteResult> {
+    if ((this as any)[exactPersistencePolicySymbol]) {
+      throw new SmartdataPersistenceError(
+        'unsupported_operation',
+        'atomicDeleteMany is unavailable for exact-persistence models.',
+      );
+    }
+    const declaredRoots = (this as any).getDeclaredPersistedRoots() as Set<string>;
+    const declaredAtomicPaths = (this as any).getDeclaredAtomicPaths() as Set<string>;
+    const identityValueTypes = (this as any).getDeclaredIdentityValueTypes() as Map<
+      string,
+      TSmartdataIdentityValueType
+    >;
+    const numericRoots = (this as any).getDeclaredNumericRoots() as Set<string>;
+    const serializedRoots = (this as any).getSerializedPersistedRoots() as Set<string>;
+    const normalizedFilter = normalizeStrictFilter(
+      filterArg as Record<string, unknown>,
+      declaredRoots,
+      declaredAtomicPaths,
+      identityValueTypes,
+      numericRoots,
+      serializedRoots,
+      'Atomic delete-many',
+    );
+    const collection: SmartdataCollection<T> = (this as any).collection;
+    const result = await executeAtomicDeleteMany(
+      collection,
+      normalizedFilter,
+      { session: opts?.session, timeoutMS: requireBoundedInteger(opts?.timeoutMS, 'Atomic delete-many timeoutMS', 120_000) },
+    );
+    return {
+      acknowledged: result.acknowledged,
+      deletedCount: result.deletedCount,
+    };
+  }
+
+  /**
+   * Atomically updates every ordinary model document matching a strict
+   * selector. Each matched document is updated atomically; the batch as a
+   * whole is not isolated. No upsert is possible, so `$setOnInsert` is
+   * rejected.
+   */
+  public static async atomicUpdateMany<T>(
+    this: plugins.tsclass.typeFest.Class<T>,
+    filterArg: TSmartdataAtomicFilter<T>,
+    updateArg: Omit<ISmartdataAtomicUpdate<T>, '$setOnInsert'>,
+    opts?: ISmartdataAtomicUpdateManyOptions,
+  ): Promise<ISmartdataAtomicUpdateManyResult> {
+    if (getOrdinaryPersistencePolicy(this)) {
+      throw new SmartdataPersistenceError('unsupported_operation',
+        'Validated ordinary models require transactional postimage updates.');
+    }
+    if ((this as any)[exactPersistencePolicySymbol]) {
+      throw new SmartdataPersistenceError(
+        'unsupported_operation',
+        'atomicUpdateMany is unavailable for exact-persistence models.',
+      );
+    }
+    if (
+      typeof updateArg === 'object'
+      && updateArg !== null
+      && '$setOnInsert' in updateArg
+    ) {
+      throw new SmartdataPersistenceError(
+        'invalid_argument',
+        'Atomic update-many does not support $setOnInsert.',
+      );
+    }
+    const declaredRoots = (this as any).getDeclaredPersistedRoots() as Set<string>;
+    const declaredAtomicPaths = (this as any).getDeclaredAtomicPaths() as Set<string>;
+    const uniqueRoots = (this as any).getDeclaredUniqueRoots() as Set<string>;
+    const identityValueTypes = (this as any).getDeclaredIdentityValueTypes() as Map<
+      string,
+      TSmartdataIdentityValueType
+    >;
+    const numericRoots = (this as any).getDeclaredNumericRoots() as Set<string>;
+    const serializedRoots = (this as any).getSerializedPersistedRoots() as Set<string>;
+    const normalizedFilter = normalizeStrictFilter(
+      filterArg as Record<string, unknown>,
+      declaredRoots,
+      declaredAtomicPaths,
+      identityValueTypes,
+      numericRoots,
+      serializedRoots,
+      'Atomic update-many',
+    );
+    const normalizedUpdate = normalizeAtomicUpdate(
+      updateArg,
+      declaredRoots,
+      declaredAtomicPaths,
+      uniqueRoots,
+      serializedRoots,
+    );
+    const now = new Date().toISOString();
+    normalizedUpdate.$set = {
+      ...(normalizedUpdate.$set || {}),
+      _updatedAt: now,
+    };
+    const collection: SmartdataCollection<T> = (this as any).collection;
+    const result = await executeAtomicUpdateMany(
+      collection,
+      normalizedFilter,
+      normalizedUpdate,
+      opts,
+    );
+    return {
+      acknowledged: result.acknowledged,
+      matchedCount: result.matchedCount,
+      modifiedCount: result.modifiedCount,
+    };
+  }
+
+  /**
+   * Computes bounded grouped counts and optional numeric sums server-side.
+   * Groups by one or two declared top-level fields, always returns a `count`
+   * per group, and sums only declared numeric fields. The `$limit` follows
+   * the group stage without a sort, so when more groups exist than the limit
+   * the returned subset is arbitrary. Use `getGroupedTotalsPage()` when the
+   * caller must detect overflow. The aggregation cursor never leaves SmartData.
+   */
+  public static async getGroupedTotals<T>(
+    this: plugins.tsclass.typeFest.Class<T>,
+    optionsArg: ISmartdataGroupedTotalsOptions<T>,
+  ): Promise<Array<ISmartdataGroupedTotalsRow<T>>> {
+    const page = await (this as any).getGroupedTotalsPage(optionsArg) as
+      ISmartdataGroupedTotalsPage<T>;
+    return page.rows;
+  }
+
+  /**
+   * Computes the same bounded grouped totals as `getGroupedTotals()` and
+   * reports whether at least one additional group exists beyond the requested
+   * row limit.
+   */
+  public static async getGroupedTotalsPage<T>(
+    this: plugins.tsclass.typeFest.Class<T>,
+    optionsArg: ISmartdataGroupedTotalsOptions<T>,
+  ): Promise<ISmartdataGroupedTotalsPage<T>> {
+    if ((this as any)[exactPersistencePolicySymbol]) {
+      throw new SmartdataPersistenceError(
+        'unsupported_operation',
+        'getGroupedTotals is unavailable for exact-persistence models.',
+      );
+    }
+    if (
+      typeof optionsArg !== 'object'
+      || optionsArg === null
+      || plugins.nodeUtil.types.isProxy(optionsArg)
+      || !isPlainObject(optionsArg)
+    ) {
+      throw new SmartdataPersistenceError(
+        'invalid_argument',
+        'Grouped totals options must be an inert plain object.',
+      );
+    }
+    const allowedKeys = new Set([
+      'groupBy',
+      'sums',
+      'filter',
+      'limit',
+      'maxTimeMS',
+      'timeoutMS',
+      'signal',
+      'session',
+    ]);
+    for (const key of Reflect.ownKeys(optionsArg)) {
+      if (typeof key !== 'string' || !allowedKeys.has(key)) {
+        throw new SmartdataPersistenceError(
+          'invalid_argument',
+          `Grouped totals received unsupported option "${String(key)}".`,
+        );
+      }
+      const descriptor = Object.getOwnPropertyDescriptor(optionsArg, key);
+      if (
+        !descriptor
+        || !('value' in descriptor)
+        || descriptor.enumerable !== true
+      ) {
+        throw new SmartdataPersistenceError(
+          'invalid_argument',
+          `Grouped totals option "${key}" must be an inert enumerable data property.`,
+        );
+      }
+    }
+    const groupByOption = optionsArg.groupBy;
+    const sumsOption = optionsArg.sums;
+    const filterOption = optionsArg.filter;
+    const limitOption = optionsArg.limit;
+    const maxTimeMSOption = optionsArg.maxTimeMS;
+    const timeoutMSOption = optionsArg.timeoutMS;
+    const signalOption = optionsArg.signal;
+    if (signalOption !== undefined && !(signalOption instanceof AbortSignal)) {
+      throw new SmartdataPersistenceError('invalid_argument', 'Grouped totals signal must be an AbortSignal.');
+    }
+    signalOption?.throwIfAborted();
+    const sessionOption = optionsArg.session;
+    const declaredRoots = (this as any).getDeclaredPersistedRoots() as Set<string>;
+    const serializedRoots = (this as any).getSerializedPersistedRoots() as Set<string>;
+    const requireDeclaredGroupField = (
+      fieldArg: unknown,
+      labelArg: string,
+    ): string => {
+      if (typeof fieldArg !== 'string') {
+        throw new SmartdataPersistenceError(
+          'invalid_argument',
+          `${labelArg} must name a declared top-level field.`,
+        );
+      }
+      const root = requireDeclaredPath(fieldArg, declaredRoots, labelArg);
+      if (root !== fieldArg) {
+        throw new SmartdataPersistenceError(
+          'invalid_argument',
+          `${labelArg} must name a declared top-level field, not a nested path.`,
+        );
+      }
+      if (serializedRoots.has(root)) {
+        throw new SmartdataPersistenceError(
+          'unsupported_operation',
+          `${labelArg} cannot target serialized field "${root}".`,
+        );
+      }
+      return root;
+    };
+    if (
+      !Array.isArray(groupByOption)
+      || groupByOption.length < 1
+      || groupByOption.length > 2
+    ) {
+      throw new SmartdataPersistenceError(
+        'invalid_argument',
+        'Grouped totals require one or two groupBy fields.',
+      );
+    }
+    const groupByFields = [...groupByOption].map((fieldArg) =>
+      requireDeclaredGroupField(fieldArg, 'Grouped totals groupBy field'),
+    );
+    if (
+      groupByFields.length < 1
+      || groupByFields.length > 2
+      || new Set(groupByFields).size !== groupByFields.length
+    ) {
+      throw new SmartdataPersistenceError(
+        'invalid_argument',
+        'Grouped totals groupBy fields must be one or two distinct fields.',
+      );
+    }
+    if (sumsOption !== undefined && !Array.isArray(sumsOption)) {
+      throw new SmartdataPersistenceError(
+        'invalid_argument',
+        'Grouped totals sums must be an array of declared numeric fields.',
+      );
+    }
+    const sumFields = [...(sumsOption ?? [])].map((fieldArg) =>
+      requireDeclaredGroupField(fieldArg, 'Grouped totals sum field'),
+    );
+    if (new Set(sumFields).size !== sumFields.length) {
+      throw new SmartdataPersistenceError(
+        'invalid_argument',
+        'Grouped totals sum fields must be distinct.',
+      );
+    }
+    const limit = requireBoundedInteger(
+      limitOption,
+      'Grouped totals limit',
+      10_000,
+    );
+    if (limit === undefined) {
+      throw new SmartdataPersistenceError(
+        'invalid_argument',
+        'Grouped totals require an explicit limit.',
+      );
+    }
+    const maxTimeMS = requireBoundedInteger(
+      maxTimeMSOption,
+      'Grouped totals maxTimeMS',
+      120_000,
+    );
+    const timeoutMS = requireBoundedInteger(timeoutMSOption, 'Grouped totals timeoutMS', 120_000);
+    const groupStage: Record<string, unknown> = {
+      _id: groupByFields.length === 1
+        ? '$' + groupByFields[0]
+        : Object.fromEntries(
+            groupByFields.map((fieldArg) => [fieldArg, '$' + fieldArg]),
+          ),
+      __groupedTotalsCount: { $sum: 1 },
+    };
+    for (const [index, sumField] of sumFields.entries()) {
+      groupStage['__groupedTotalsSum' + index] = { $sum: '$' + sumField };
+    }
+    const collection: SmartdataCollection<T> = (this as any).collection;
+    const rows = await collection.aggregateGroupedTotals(
+      filterOption !== undefined
+        ? convertFilterForMongoDb(filterOption)
+        : undefined,
+      groupStage,
+      limit + 1,
+      {
+        ...(sessionOption ? { session: sessionOption } : {}),
+        ...(maxTimeMS !== undefined ? { maxTimeMS } : {}),
+        ...(timeoutMS !== undefined ? { timeoutMS } : {}),
+        ...(signalOption !== undefined ? { signal: signalOption } : {}),
+      },
+    );
+    const hasMore = rows.length > limit;
+    const returnedRows = rows.slice(0, limit);
+    const requireFiniteNumber = (
+      valueArg: unknown,
+      labelArg: string,
+    ): number => {
+      if (typeof valueArg !== 'number' || !Number.isFinite(valueArg)) {
+        throw new SmartdataPersistenceError(
+          'unsupported_operation',
+          `${labelArg} produced a non-numeric total; store safe-integer values in summed fields.`,
+        );
+      }
+      return valueArg;
+    };
+    const mappedRows = returnedRows.map((rowArg) => {
+      const group: Record<string, unknown> = {};
+      if (groupByFields.length === 1) {
+        group[groupByFields[0]] = rowArg._id ?? null;
+      } else {
+        const compoundKey = (rowArg._id ?? {}) as Record<string, unknown>;
+        for (const fieldArg of groupByFields) {
+          // Missing and explicit-null values merge into one group that is
+          // reported as null in both the single-field and compound shapes.
+          group[fieldArg] = compoundKey[fieldArg] ?? null;
+        }
+      }
+      const sums: Record<string, number> = {};
+      for (const [index, sumField] of sumFields.entries()) {
+        sums[sumField] = requireFiniteNumber(
+          rowArg['__groupedTotalsSum' + index],
+          `Grouped totals sum field "${sumField}"`,
+        );
+      }
+      return {
+        group,
+        count: requireFiniteNumber(
+          rowArg.__groupedTotalsCount,
+          'Grouped totals count',
+        ),
+        sums,
+      } as ISmartdataGroupedTotalsRow<T>;
+    });
+    return {
+      rows: mappedRows,
+      hasMore,
+    };
+  }
+
+  /**
+   * gets all instances as array
+   * @param this
+   * @param filterArg - Type-safe MongoDB filter with nested object support and operators
+   * @returns
+   */
+  public static async getInstances<T>(
+    this: plugins.tsclass.typeFest.Class<T>,
+    filterArg: MongoFilter<T>,
+    opts?: { session?: TSmartdataOrdinarySession }
+  ): Promise<T[]> {
+    // Pass session through to findAll for transactional queries
+    const foundDocs = await (this as any).collection.findAll(
+      convertFilterForMongoDb(filterArg),
+      { session: opts?.session },
+    );
+    const returnArray: T[] = [];
+    for (const foundDoc of foundDocs) {
+      const newInstance: T = (this as any).createInstanceFromMongoDbNativeDoc(foundDoc);
+      returnArray.push(newInstance);
+    }
+    return returnArray;
+  }
+
+  /**
+   * Cursor-paged query with stable seek pagination — the org-standard way to
+   * list unbounded collections. Orders by a comparable (ideally indexed)
+   * sort field with a unique tiebreaker, returns one page plus the cursor
+   * for the next, and never materializes the full result set.
+   * Owned sessions require a prepared model and remain leased through optional
+   * counting, model hydration and cursor cleanup.
+   */
+  public static async getPagedInstances<T>(
+    this: plugins.tsclass.typeFest.Class<T>,
+    optionsArg: {
+      filter?: MongoFilter<T>;
+      /** Comparable, ideally indexed field that orders the pages (e.g. a numeric timestamp). */
+      sortField: string;
+      sortDirection?: 'asc' | 'desc';
+      /** Unique tiebreaker field present on every document. Defaults to 'id'. */
+      uniqueField?: string;
+      /** Page size, default 100, capped at 1000. */
+      limit?: number;
+      /** Seek position returned as nextCursor by the previous page. */
+      cursor?: { sortValue: number | string; uniqueValue: string };
+      /** Also count all filter matches (extra query). */
+      withTotal?: boolean;
+      session?: TSmartdataOrdinarySession;
+    },
+  ): Promise<{
+    documents: T[];
+    nextCursor?: { sortValue: number | string; uniqueValue: string };
+    total?: number;
+  }> {
+    const collection: SmartdataCollection<T> = (this as any).collection;
+    optionsArg = { ...optionsArg, cursor: optionsArg.cursor && { ...optionsArg.cursor } };
+    const sortDirection = optionsArg.sortDirection === 'asc' ? 1 : -1;
+    const uniqueField = optionsArg.uniqueField || 'id';
+    const requestedLimit = Number.isSafeInteger(optionsArg.limit) && optionsArg.limit! > 0
+      ? optionsArg.limit!
+      : 100;
+    const limit = Math.min(requestedLimit, 1000);
+    const baseSelector = convertFilterForMongoDb(optionsArg.filter || {});
+
+    let selector: any = baseSelector;
+    if (optionsArg.cursor) {
+      const seekOperator = sortDirection === 1 ? '$gt' : '$lt';
+      const seekSelector = {
+        $or: [
+          { [optionsArg.sortField]: { [seekOperator]: optionsArg.cursor.sortValue } },
+          {
+            [optionsArg.sortField]: optionsArg.cursor.sortValue,
+            [uniqueField]: { [seekOperator]: optionsArg.cursor.uniqueValue },
+          },
+        ],
+      };
+      selector = Object.keys(baseSelector).length > 0
+        ? { $and: [baseSelector, seekSelector] }
+        : seekSelector;
+    }
+
+    return runWithOrdinarySmartdataSession(optionsArg.session, collection.smartdataDb, {
+      ordinaryWrite: false,
+      prepared: collection.isInitializedForCurrentDatabase(),
+    }, async (rawSessionArg) => {
+      await collection.init();
+      const rawCursor = collection.mongoDbCollection
+        .find(selector, { session: rawSessionArg })
+        .sort({ [optionsArg.sortField]: sortDirection, [uniqueField]: sortDirection })
+        .limit(limit + 1);
+      return runCursorOperation(rawCursor, async (cursorArg) => {
+        const rawDocuments = await cursorArg.toArray();
+        const hasMore = rawDocuments.length > limit;
+        const pageRows = rawDocuments.slice(0, limit);
+        const documents = pageRows.map(
+          (rawDocument: any) => (this as any).createInstanceFromMongoDbNativeDoc(rawDocument) as T,
+        );
+        const lastRow: any = pageRows[pageRows.length - 1];
+        const total = optionsArg.withTotal
+          ? await collection.mongoDbCollection.countDocuments(baseSelector, {
+              session: rawSessionArg,
+            })
+          : undefined;
+        return {
+          documents,
+          ...(hasMore && lastRow
+            ? {
+                nextCursor: {
+                  sortValue: lastRow[optionsArg.sortField],
+                  uniqueValue: lastRow[uniqueField],
+                },
+              }
+            : {}),
+          ...(total !== undefined ? { total } : {}),
+        };
+      });
+    });
+  }
+
+  /**
+   * gets the first matching instance
+   * @param this
+   * @param filterArg
+   * @returns
+   */
+  public static async getInstance<T>(
+    this: plugins.tsclass.typeFest.Class<T>,
+    filterArg: MongoFilter<T>,
+    opts?: ISmartdataFindOneOptions<T>,
+  ): Promise<T> {
+    (this as any).assertHydratedProjection(opts?.projection);
+    const declaredRoots = (this as any).getDeclaredPersistedRoots() as Set<string>;
+    // Retrieve one document, with optional session for transactions
+    const foundDoc = await (this as any).collection.findOne(
+      convertFilterForMongoDb(filterArg),
+      {
+        projection: normalizeProjection(
+          opts?.projection,
+          declaredRoots,
+          (this as any).getDeclaredQueryPaths(),
+        ),
+        maxTimeMS: requireBoundedInteger(
+          opts?.maxTimeMS,
+          'maxTimeMS',
+          120_000,
+        ),
+        session: opts?.session,
+      },
+    );
+    if (foundDoc) {
+      const newInstance: T = (this as any).createInstanceFromMongoDbNativeDoc(foundDoc);
+      return newInstance;
+    } else {
+      return null as any;
+    }
+  }
+
+  public static async exists<T>(
+    this: plugins.tsclass.typeFest.Class<T>,
+    filterArg: MongoFilter<T>,
+    opts?: {
+      maxTimeMS?: number;
+      session?: TSmartdataOrdinarySession;
+    },
+  ): Promise<boolean> {
+    const foundDoc = await (this as any).collection.findOne(
+      convertFilterForMongoDb(filterArg),
+      {
+        projection: { _id: 1 },
+        maxTimeMS: requireBoundedInteger(
+          opts?.maxTimeMS,
+          'maxTimeMS',
+          120_000,
+        ),
+        session: opts?.session,
+      },
+    );
+    return foundDoc !== null;
+  }
+
+  /**
+   * get a unique id prefixed with the class name
+   */
+  public static async getNewId<T = any>(
+    this: plugins.tsclass.typeFest.Class<T>,
+    lengthArg: number = 20,
+  ) {
+    return `${(this as any).className}:${plugins.smartunique.shortId(lengthArg)}`;
+  }
+
+  /**
+   * Stream results using model-declared projections, sorts and index hints.
+   * Offset pages require an explicit sort and limit. Include a unique final
+   * tiebreaker; concurrent writes can still move rows between offset pages.
+   */
+  public static async getCursor<T>(
+    this: plugins.tsclass.typeFest.Class<T>,
+    filterArg: MongoFilter<T>,
+    opts?: ISmartdataCursorOptions<T>,
+  ): Promise<SmartdataDbCursor<T>> {
+    (this as any).assertHydratedProjection(opts?.projection, opts?.modifier);
+    const { session, modifier } = opts || {};
+    const declaredRoots = (this as any).getDeclaredPersistedRoots() as Set<string>;
+    const declaredQueryPaths = (this as any).getDeclaredQueryPaths() as Set<string>;
+    const projection = normalizeProjection(opts?.projection, declaredRoots, declaredQueryPaths);
+    const sort = normalizeSort(opts?.sort, declaredRoots, declaredQueryPaths);
+    const hint = normalizeQueryHint(opts?.hint, this);
+    const batchSize = requireBoundedInteger(
+      opts?.batchSize,
+      'batchSize',
+      10_000,
+    );
+    const limit = requireBoundedInteger(opts?.limit, 'limit', 10_000);
+    const maxTimeMS = requireBoundedInteger(
+      opts?.maxTimeMS,
+      'maxTimeMS',
+      120_000,
+    );
+    const skip = opts?.skip;
+    if (skip !== undefined && (
+      !Number.isSafeInteger(skip) || skip < 0 || skip > 2_147_483_647 ||
+      !sort || limit === undefined
+    )) {
+      throw new SmartdataPersistenceError(
+        'invalid_argument',
+        'Cursor skip must be an integer from 0 through 2147483647 and requires sort and limit.',
+      );
+    }
+    const collection: SmartdataCollection<T> = (this as any).collection;
+    await collection.init();
+    let rawCursor: plugins.mongodb.FindCursor<any> =
+      collection.mongoDbCollection.find(convertFilterForMongoDb(filterArg), {
+        projection,
+        session,
+        hint,
+        skip,
+      });
+    if (sort) {
+      rawCursor = rawCursor.sort(sort);
+    }
+    if (batchSize) {
+      rawCursor = rawCursor.batchSize(batchSize);
+    }
+    if (limit) {
+      rawCursor = rawCursor.limit(limit);
+    }
+    if (maxTimeMS) {
+      rawCursor = rawCursor.maxTimeMS(maxTimeMS);
+    }
+    if (modifier) {
+      const originalCursor = rawCursor;
+      let modifiedCursor: plugins.mongodb.FindCursor<any>;
+      try {
+        modifiedCursor = modifier(originalCursor);
+      } catch (modifierError) {
+        try {
+          await originalCursor.close();
+        } catch {
+          // Preserve the modifier error when best-effort cleanup also fails.
+        }
+        throw modifierError;
+      }
+      if (modifiedCursor !== originalCursor) {
+        try {
+          await originalCursor.close();
+        } catch (originalCursorCloseError) {
+          try {
+            await modifiedCursor.close();
+          } catch {
+            // Preserve the original cursor's cleanup error.
+          }
+          throw originalCursorCloseError;
+        }
+      }
+      rawCursor = modifiedCursor;
+    }
+    return new SmartdataDbCursor<T>(rawCursor, this as any as typeof SmartDataDbDoc);
+  }
+
+  /**
+   * Read a bounded offset page while retaining an owned session through cursor
+   * cleanup. Initialize the model before calling; this operation never creates
+   * collections or indexes. Count separately with the same filter and hint.
+   */
+  public static async getOffsetPage<T>(
+    this: plugins.tsclass.typeFest.Class<T>,
+    filterArg: MongoFilter<T>,
+    opts: ISmartdataOffsetPageOptions<T>,
+  ): Promise<T[]> {
+    const declaredRoots = (this as any).getDeclaredPersistedRoots() as Set<string>;
+    (this as any).assertHydratedProjection(opts?.projection);
+    const declaredQueryPaths = (this as any).getDeclaredQueryPaths() as Set<string>;
+    const projection = normalizeProjection(opts?.projection, declaredRoots, declaredQueryPaths);
+    const sort = normalizeSort(opts?.sort, declaredRoots, declaredQueryPaths);
+    const hint = normalizeQueryHint(opts?.hint, this);
+    const limit = requireBoundedInteger(opts?.limit, 'limit', 10_000);
+    const skip = opts?.skip;
+    if (!sort || limit === undefined || !Number.isSafeInteger(skip) || skip < 0 || skip > 2_147_483_647) {
+      throw new SmartdataPersistenceError(
+        'invalid_argument',
+        'Offset pages require sort, limit and an integer skip from 0 through 2147483647.',
+      );
+    }
+    const timeoutMS = requireBoundedInteger(opts?.timeoutMS === undefined ? 5_000 : opts.timeoutMS, 'timeoutMS', 120_000);
+    const maxTimeMS = requireBoundedInteger(opts?.maxTimeMS, 'maxTimeMS', 120_000);
+    const filter = convertFilterForMongoDb(filterArg);
+    opts.signal?.throwIfAborted();
+    const collection: SmartdataCollection<T> = (this as any).collection;
+    if (!collection.isInitializedForCurrentDatabase()) {
+      throw new SmartdataPersistenceError(
+        'unsupported_operation',
+        'Initialize the model before reading an offset page.',
+      );
+    }
+    return runWithOrdinarySmartdataSession(opts.session, collection.smartdataDb, {
+      ordinaryWrite: false,
+      prepared: true,
+    }, async (rawSessionArg) => {
+      opts.signal?.throwIfAborted();
+      const rawCursor = collection.mongoDbCollection.find(filter, {
+        projection, sort, hint, skip, limit, maxTimeMS, timeoutMS,
+        timeoutMode: 'cursorLifetime', session: rawSessionArg, signal: opts.signal,
+      });
+      return runCursorOperation(rawCursor, async (cursorArg) => {
+        const documents = await cursorArg.toArray();
+        return documents.map((documentArg) =>
+          (this as any).createInstanceFromMongoDbNativeDoc(documentArg) as T,
+        );
+      }, opts.signal);
+    });
+  }
+
+  /**
+   * watch the collection
+   * @param this
+   * @param filterArg
+   * @param forEachFunction
+   */
+  /**
+   * Watch the collection for changes, with optional buffering and change stream options.
+   * @param filterArg MongoDB filter to select which changes to observe
+   * @param opts optional ChangeStreamOptions plus bufferTimeMs
+   */
+  public static async watch<T>(
+    this: plugins.tsclass.typeFest.Class<T>,
+    filterArg: MongoFilter<T>,
+    opts?: plugins.mongodb.ChangeStreamOptions & { bufferTimeMs?: number },
+  ): Promise<SmartdataDbWatcher<T>> {
+    const collection: SmartdataCollection<T> = (this as any).collection;
+    const watcher: SmartdataDbWatcher<T> = await collection.watch(
+      convertFilterForMongoDb(filterArg),
+      opts || {},
+      this as any,
+    );
+    return watcher;
+  }
+
+  /**
+   * run a function for all instances
+   * @returns
+   */
+  public static async forEach<T>(
+    this: plugins.tsclass.typeFest.Class<T>,
+    filterArg: MongoFilter<T>,
+    forEachFunction: (itemArg: T) => Promise<any>,
+  ) {
+    const cursor: SmartdataDbCursor<T> = await (this as any).getCursor(filterArg);
+    await cursor.forEach(forEachFunction);
+  }
+
+  /**
+   * returns a count of the documents in the collection
+   */
+  public static async getCount<T>(
+    this: plugins.tsclass.typeFest.Class<T>,
+    filterArg: MongoFilter<T> = {} as any,
+    opts?: ISmartdataCountOptions,
+  ) {
+    const hint = normalizeQueryHint(opts?.hint, this);
+    const collection: SmartdataCollection<T> = (this as any).collection;
+    return await collection.getCount(convertFilterForMongoDb(filterArg), {
+      hint,
+      limit: requireBoundedInteger(opts?.limit, 'limit', 10_000),
+      maxTimeMS: requireBoundedInteger(
+        opts?.maxTimeMS,
+        'maxTimeMS',
+        120_000,
+      ),
+      timeoutMS: requireBoundedInteger(opts?.timeoutMS, 'timeoutMS', 120_000),
+      signal: opts?.signal,
+      session: opts?.session,
+    });
+  }
+
+  /**
+   * Runs an integrity check on this collection.
+   * Returns a summary with estimated vs actual counts and any duplicate unique fields.
+   */
+  public static async checkCollectionIntegrity<T>(
+    this: plugins.tsclass.typeFest.Class<T>,
+  ) {
+    const collection: SmartdataCollection<T> = (this as any).collection;
+    return await collection.checkCollectionIntegrity();
+  }
+
+  /**
+   * Create a MongoDB filter from a Lucene query string
+   * @param luceneQuery Lucene query string
+   * @returns MongoDB query object
+   */
+  public static createSearchFilter<T>(
+    this: plugins.tsclass.typeFest.Class<T>,
+    luceneQuery: string,
+  ): any {
+    const searchableFields = (this as any).getSearchableFields();
+    if (searchableFields.length === 0) {
+      throw new Error(`No searchable fields defined for class ${this.name}`);
+    }
+    const adapter = new SmartdataLuceneAdapter(searchableFields);
+    return adapter.convert(luceneQuery);
+  }
+  /**
+   * List all searchable fields defined on this class
+   */
+  public static getSearchableFields(): string[] {
+    const ctor = this as any;
+    return Array.isArray(ctor.searchableFields) ? ctor.searchableFields : [];
+  }
+  /**
+   * Execute a query with optional hard filter and post-fetch validation
+   */
+  private static async execQuery<T>(
+    this: plugins.tsclass.typeFest.Class<T>,
+    baseFilter: Record<string, any>,
+    opts?: SearchOptions<T>
+  ): Promise<T[]> {
+    let mongoFilter = baseFilter || {};
+    if (opts?.filter) {
+      mongoFilter = { $and: [mongoFilter, opts.filter] };
+    }
+    // Fetch with optional session for transactions
+    // Fetch within optional session
+    let docs: T[] = await (this as any).getInstances(mongoFilter, { session: opts?.session });
+    if (opts?.validate) {
+      const out: T[] = [];
+      for (const d of docs) {
+        if (await opts.validate(d)) out.push(d);
+      }
+      docs = out;
+    }
+    return docs;
+  }
+
+  /**
+   * Search documents by text or field:value syntax, with safe regex fallback
+   * Supports additional filtering and post-fetch validation via opts
+   * @param query A search term or field:value expression
+   * @param opts Optional filter and validate hooks
+   * @returns Array of matching documents
+   */
+  public static async search<T>(
+    this: plugins.tsclass.typeFest.Class<T>,
+    query: string,
+    opts?: SearchOptions<T>,
+  ): Promise<T[]> {
+    const searchableFields = (this as any).getSearchableFields();
+    if (searchableFields.length === 0) {
+      throw new Error(`No searchable fields defined for class ${this.name}`);
+    }
+    // empty query -> return all
+    const q = query.trim();
+    if (!q) {
+      // empty query: fetch all, apply opts
+      return await (this as any).execQuery({}, opts);
+    }
+    // simple exact field:value (no spaces, no wildcards, no quotes)
+    // simple exact field:value (no spaces, wildcards, quotes)
+    const simpleExact = q.match(/^(\w+):([^"'\*\?\s]+)$/);
+    if (simpleExact) {
+      const field = simpleExact[1];
+      const value = simpleExact[2];
+      if (!searchableFields.includes(field)) {
+        throw new Error(`Field '${field}' is not searchable for class ${this.name}`);
+      }
+      // simple field:value search
+      return await (this as any).execQuery({ [field]: value }, opts);
+    }
+    // quoted phrase across all searchable fields: exact match of phrase
+    const quoted = q.match(/^"(.+)"$|^'(.+)'$/);
+    if (quoted) {
+      const phrase = quoted[1] || quoted[2] || '';
+      const parts = phrase.split(/\s+/).map((t) => escapeForRegex(t));
+      const pattern = parts.join('\\s+');
+      const orConds = searchableFields.map((f) => ({ [f]: { $regex: pattern, $options: 'i' } }));
+      return await (this as any).execQuery({ $or: orConds }, opts);
+    }
+    // wildcard field:value (supports * and ?) -> direct regex on that field
+    const wildcardField = q.match(/^(\w+):(.+[*?].*)$/);
+    if (wildcardField) {
+      const field = wildcardField[1];
+      // Support quoted wildcard patterns: strip surrounding quotes
+      let pattern = wildcardField[2];
+      if ((pattern.startsWith('"') && pattern.endsWith('"')) ||
+          (pattern.startsWith("'") && pattern.endsWith("'"))) {
+        pattern = pattern.slice(1, -1);
+      }
+      if (!searchableFields.includes(field)) {
+        throw new Error(`Field '${field}' is not searchable for class ${this.name}`);
+      }
+      // escape regex special chars except * and ?, then convert wildcards
+      const escaped = pattern.replace(/([.+^${}()|[\\]\\])/g, '\\$1');
+      const regexPattern = escaped.replace(/\*/g, '.*').replace(/\?/g, '.');
+      return await (this as any).execQuery({ [field]: { $regex: regexPattern, $options: 'i' } }, opts);
+    }
+    // wildcard plain term across all fields (supports * and ?)
+    if (!q.includes(':') && (q.includes('*') || q.includes('?'))) {
+      // build wildcard regex pattern: escape all except * and ? then convert
+      const escaped = q.replace(/([.+^${}()|[\\]\\])/g, '\\$1');
+      const pattern = escaped.replace(/\*/g, '.*').replace(/\?/g, '.');
+      const orConds = searchableFields.map((f) => ({ [f]: { $regex: pattern, $options: 'i' } }));
+      return await (this as any).execQuery({ $or: orConds }, opts);
+    }
+    // implicit AND for multiple tokens: free terms, quoted phrases, and field:values
+    {
+      // Split query into tokens, preserving quoted substrings
+      const rawTokens = q.match(/(?:[^\s"']+|"[^"]*"|'[^']*')+/g) || [];
+      // Only apply when more than one token and no boolean operators or grouping
+      if (
+        rawTokens.length > 1 &&
+        !/(\bAND\b|\bOR\b|\bNOT\b|\(|\))/i.test(q) &&
+        !/\[|\]/.test(q)
+      ) {
+        const andConds: any[] = [];
+        for (let token of rawTokens) {
+          // field:value token
+          const fv = token.match(/^(\w+):(.+)$/);
+          if (fv) {
+            const field = fv[1];
+            let value = fv[2];
+            if (!searchableFields.includes(field)) {
+              throw new Error(`Field '${field}' is not searchable for class ${this.name}`);
+            }
+            // Strip surrounding quotes if present
+            if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+              value = value.slice(1, -1);
+            }
+            // Wildcard search?
+            if (value.includes('*') || value.includes('?')) {
+              const escaped = value.replace(/([.+^${}()|[\\]\\])/g, '\\$1');
+              const pattern = escaped.replace(/\*/g, '.*').replace(/\?/g, '.');
+              andConds.push({ [field]: { $regex: pattern, $options: 'i' } });
+            } else {
+              andConds.push({ [field]: value });
+            }
+          } else if ((token.startsWith('"') && token.endsWith('"')) || (token.startsWith("'") && token.endsWith("'"))) {
+            // Quoted free phrase across all fields
+            const phrase = token.slice(1, -1);
+            const parts = phrase.split(/\s+/).map((t) => escapeForRegex(t));
+            const pattern = parts.join('\\s+');
+            andConds.push({ $or: searchableFields.map((f) => ({ [f]: { $regex: pattern, $options: 'i' } })) });
+          } else {
+            // Free term across all fields
+            const esc = escapeForRegex(token);
+            andConds.push({ $or: searchableFields.map((f) => ({ [f]: { $regex: esc, $options: 'i' } })) });
+          }
+        }
+        return await (this as any).execQuery({ $and: andConds }, opts);
+      }
+    }
+    // detect advanced Lucene syntax: field:value, wildcards, boolean, grouping
+    const luceneSyntax = /(\w+:[^\s]+)|\*|\?|\bAND\b|\bOR\b|\bNOT\b|\(|\)/;
+    if (luceneSyntax.test(q)) {
+      const filter = (this as any).createSearchFilter(q);
+      return await (this as any).execQuery(filter, opts);
+    }
+    // multi-term unquoted -> AND of regex across fields for each term
+    const terms = q.split(/\s+/);
+    if (terms.length > 1) {
+      const andConds = terms.map((term) => {
+        const esc = escapeForRegex(term);
+        const ors = searchableFields.map((f) => ({ [f]: { $regex: esc, $options: 'i' } }));
+        return { $or: ors };
+      });
+      return await (this as any).execQuery({ $and: andConds }, opts);
+    }
+    // single term -> regex across all searchable fields
+    const esc = escapeForRegex(q);
+    const orConds = searchableFields.map((f) => ({ [f]: { $regex: esc, $options: 'i' } }));
+    return await (this as any).execQuery({ $or: orConds }, opts);
+  }
+
+
+  // INSTANCE
+
+  // INSTANCE
+
+  /**
+   * how the Doc in memory was created, may prove useful later.
+   */
+  public creationStatus: TDocCreation = 'new';
+
+  /**
+   * updated from db in any case where doc comes from db
+   */
+  @globalSvDb()
+  _createdAt: string = new Date().toISOString();
+
+  /**
+   * will be updated everytime the doc is saved
+   */
+  @globalSvDb()
+  _updatedAt: string = new Date().toISOString();
+
+  /**
+   * an array of saveable properties of ALL doc
+   * Note: Set by decorators on prototype - NOT declared as instance property to avoid shadowing in Deno
+   * Declared with definite assignment assertion to satisfy TypeScript without creating instance property
+   */
+  declare globalSaveableProperties: string[];
+
+  /**
+   * unique indexes
+   * Note: Set by decorators on prototype - NOT declared as instance property to avoid shadowing in Deno
+   */
+  declare uniqueIndexes: string[];
+
+  /** Runtime value contracts for fields declared with @unI(). */
+  declare identityValueTypes: Record<string, TSmartdataIdentityValueType>;
+
+  /**
+   * regular indexes with their options
+   * Note: Set by decorators on prototype - NOT declared as instance property to avoid shadowing in Deno
+   */
+  declare regularIndexes: Array<{field: string, options: IIndexOptions}>;
+
+  /**
+   * named compound indexes declared by @compoundIndex
+   */
+  declare compoundIndexes: Array<{
+    name: string;
+    key: Record<string, 1 | -1>;
+    options?: Omit<plugins.mongodb.CreateIndexesOptions, 'name'>;
+  }>;
+
+  /**
+   * an array of saveable properties of a specific doc
+   * Note: Set by decorators on prototype - NOT declared as instance property to avoid shadowing in Deno
+   */
+  declare saveableProperties: string[];
+
+  /**
+   * name
+   */
+  public name!: string;
+
+  /**
+   * primary id in the database
+   */
+  public dbDocUniqueId!: string;
+
+  /**
+   * class constructor
+   */
+  constructor() {
+    if (getOrdinaryPersistencePolicy(this.constructor)?.timestamps === 'none') {
+      delete (this as any)._createdAt;
+      delete (this as any)._updatedAt;
+    }
+  }
+
+  /**
+   * saves this instance (optionally within a transaction)
+   */
+  public async save(opts?: { session?: plugins.mongodb.ClientSession }) {
+    if (getOrdinaryPersistencePolicy(this.constructor)) {
+      throw new SmartdataPersistenceError('unsupported_operation',
+        'Validated ordinary models use insert() or transactional postimage updates.');
+    }
+    const exactPersistencePolicy = (this.constructor as any)[
+      exactPersistencePolicySymbol
+    ] as { unsupportedSave?: () => Promise<never> } | undefined;
+    if (exactPersistencePolicy) {
+      if (exactPersistencePolicy.unsupportedSave) {
+        return exactPersistencePolicy.unsupportedSave();
+      }
+      throw new Error('save() is unavailable for exact-persistence models.');
+    }
+    // allow hook before saving
+    if (typeof (this as any).beforeSave === 'function') {
+      await (this as any).beforeSave();
+    }
+    assertUsableIdentityValues(
+      this as unknown as Record<string, unknown>,
+      this.uniqueIndexes || [],
+      this.identityValueTypes,
+    );
+    // tslint:disable-next-line: no-this-assignment
+    const self: any = this;
+    let dbResult: any;
+    // update timestamp
+    this._updatedAt = new Date().toISOString();
+    // perform insert or update
+    switch (this.creationStatus) {
+      case 'db':
+        dbResult = await this.getCollectionSafe().update(self, { session: opts?.session });
+        break;
+      case 'new':
+        dbResult = await this.getCollectionSafe().insert(self, { session: opts?.session });
+        this.creationStatus = 'db';
+        break;
+      default:
+        logger.log('error', 'neither new nor in db?');
+    }
+    // allow hook after saving
+    if (typeof (this as any).afterSave === 'function') {
+      await (this as any).afterSave();
+    }
+    return dbResult;
+  }
+
+  /**
+   * deletes a document from the database (optionally within a transaction)
+   */
+  public async delete(opts?: { session?: plugins.mongodb.ClientSession }) {
+    const exactPersistencePolicy = (this.constructor as any)[
+      exactPersistencePolicySymbol
+    ] as { forbiddenDelete?: () => Promise<never> } | undefined;
+    if (exactPersistencePolicy) {
+      if (exactPersistencePolicy.forbiddenDelete) {
+        return exactPersistencePolicy.forbiddenDelete();
+      }
+      throw new Error('delete() is forbidden for exact-persistence models.');
+    }
+    // allow hook before deleting
+    if (typeof (this as any).beforeDelete === 'function') {
+      await (this as any).beforeDelete();
+    }
+    // perform deletion
+    const result = await this.getCollectionSafe().delete(this, { session: opts?.session });
+    // allow hook after delete
+    if (typeof (this as any).afterDelete === 'function') {
+      await (this as any).afterDelete();
+    }
+    return result;
+  }
+
+  /**
+   * also store any referenced objects to DB
+   * better for data consistency
+   */
+  public saveDeep(savedMapArg?: plugins.lik.ObjectMap<SmartDataDbDoc<any, any>>) {
+    if (!savedMapArg) {
+      savedMapArg = new plugins.lik.ObjectMap<SmartDataDbDoc<any, any>>();
+    }
+    savedMapArg.add(this);
+    this.save();
+    for (const propertyKey of Object.keys(this)) {
+      const property: any = this[propertyKey];
+      if (property instanceof SmartDataDbDoc && !savedMapArg.checkForObject(property)) {
+        property.saveDeep(savedMapArg);
+      }
+    }
+  }
+
+  /**
+   * updates an object from db
+   */
+  public async updateFromDb(): Promise<boolean> {
+    const identifiableObject = await this.createIdentifiableObject();
+    if (Object.keys(identifiableObject).length === 0) {
+      throw new SmartdataPersistenceError(
+        'invalid_configuration',
+        'updateFromDb() requires declared identity fields; without them the lookup would read an arbitrary document.',
+      );
+    }
+    const mongoDbNativeDoc = await this.getCollectionSafe().findOne(identifiableObject);
+    if (!mongoDbNativeDoc) {
+      return false; // Document not found in database
+    }
+    if (getOrdinaryPersistencePolicy(this.constructor)) {
+      const hydrated = (this.constructor as any).createInstanceFromMongoDbNativeDoc(mongoDbNativeDoc);
+      for (const field of [...(this.saveableProperties || []), '_id', '_createdAt', '_updatedAt']) {
+        if (!Object.prototype.hasOwnProperty.call(hydrated, field)) delete this[field];
+      }
+      Object.assign(this, hydrated);
+      return true;
+    }
+    for (const key of Object.keys(mongoDbNativeDoc)) {
+      const rawValue = mongoDbNativeDoc[key];
+      const optionsMap = (this.constructor as any)._svDbOptions || {};
+      const opts = optionsMap[key];
+      this[key] = opts && typeof opts.deserialize === 'function'
+        ? opts.deserialize(rawValue)
+        : rawValue;
+    }
+    return true;
+  }
+
+  /**
+   * creates a saveable object so the instance can be persisted as json in the database
+   *
+   * Properties whose value is `undefined` are omitted entirely rather than
+   * written as BSON null, so "absent" stays representable. Explicit `null` is
+   * untouched and remains storable wherever the field type allows it.
+   */
+  public async createSavableObject(): Promise<TImplements> {
+    if (getOrdinaryPersistencePolicy(this.constructor)?.timestamps === 'none' &&
+      (Object.prototype.hasOwnProperty.call(this, '_createdAt') ||
+        Object.prototype.hasOwnProperty.call(this, '_updatedAt'))) {
+      throw new SmartdataPersistenceError('invalid_document',
+        'This ordinary persistence policy forbids managed timestamps.');
+    }
+    assertUsableIdentityValues(
+      this as unknown as Record<string, unknown>,
+      this.uniqueIndexes || [],
+      this.identityValueTypes,
+    );
+    const saveableObject: unknown = {}; // is not exposed to outside, so any is ok here
+    const globalProps = this.globalSaveableProperties || [];
+    const specificProps = this.saveableProperties || [];
+    const policy = getOrdinaryPersistencePolicy(this.constructor);
+    const saveableProperties = [...new Set([
+      ...globalProps, ...specificProps, ...(policy ? ['_id'] : []),
+    ])].filter((fieldArg) => policy?.timestamps !== 'none' ||
+      !['_createdAt', '_updatedAt'].includes(fieldArg));
+    // apply custom serialization if configured
+    const optionsMap = (this.constructor as any)._svDbOptions || {};
+    for (const propertyNameString of saveableProperties) {
+      const rawValue = (this as any)[propertyNameString];
+      const opts = optionsMap[propertyNameString];
+      const serializedValue = opts && typeof opts.serialize === 'function'
+        ? opts.serialize(rawValue)
+        : rawValue;
+      if (serializedValue === undefined) {
+        // an undefined property means "absent" - skip it so the driver cannot
+        // turn it into BSON null during serialization
+        continue;
+      }
+      (saveableObject as any)[propertyNameString] = stripUndefinedValues(serializedValue);
+    }
+    return saveableObject as TImplements;
+  }
+
+  /**
+   * creates an identifiable object for operations that require filtering
+   */
+  public async createIdentifiableObject() {
+    assertUsableIdentityValues(
+      this as unknown as Record<string, unknown>,
+      this.uniqueIndexes || [],
+      this.identityValueTypes,
+    );
+    const identifiableObject: any = {}; // is not exposed to outside, so any is ok here
+    for (const propertyNameString of this.uniqueIndexes || []) {
+      identifiableObject[propertyNameString] = this[propertyNameString];
+    }
+    if (getOrdinaryPersistencePolicy(this.constructor)?.idType === 'string') {
+      const id = (this as any)._id;
+      if (typeof id !== 'string' || id.trim().length === 0) {
+        throw new SmartdataPersistenceError('invalid_argument', 'String primary ID is required.');
+      }
+      identifiableObject._id = id;
+    }
+    return identifiableObject;
+  }
+}