@lossless.org/client 1.2.0 → 1.3.0

package/ts/nosqldb/classes.doc.ts

@@ -25,7 +25,9 @@ import {
 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 {
+  executeAtomicFindOneAndReplace, executeAtomicFindOneAndUpdate,
+} from './classes.atomicfindoneandupdate.js';
 import {
   executeAtomicUpdate, executeAtomicUpdateMany, executeAtomicUpsertMany,
 } from './classes.atomicupdate.js';
@@ -34,6 +36,7 @@ import {
 } from './classes.persistence.js';
 import {
   isOrdinarySessionInTransaction,
+  leaseOrdinarySmartdataSession,
   runWithOrdinarySmartdataSession,
   type TSmartdataOrdinarySession,
 } from './classes.session.js';
@@ -219,6 +222,20 @@ export interface SvDbOptions {
    * expression references.
    */
   numeric?: boolean;
+  /**
+   * Declares a persisted field that only atomic operations may overwrite.
+   *
+   * The field stays a declared persisted root — atomic filters, updates and
+   * `$expr` references, projections, sorts and hydration all accept it. Every
+   * operation that creates a document stores it, so a created document is
+   * complete: `insert()`, `insertMany()`, `insertManyIfAbsent()`, a `save()`
+   * on a new instance, and the upsert branch of a `save()` whose row is gone,
+   * which seeds it through `$setOnInsert`. A `save()` that matches a stored
+   * document never writes it, so a stale instance can never overwrite a
+   * counter, quota or lease that concurrent atomic writers own. Combine with
+   * `numeric` for `$expr` references.
+   */
+  atomicOnly?: boolean;
 }
 
 /**
@@ -231,6 +248,29 @@ export function svDb(options?: SvDbOptions) {
       'svDb numeric must be a boolean.',
     );
   }
+  if (
+    options?.atomicOnly !== undefined
+    && typeof options.atomicOnly !== 'boolean'
+  ) {
+    throw new SmartdataPersistenceError(
+      'invalid_configuration',
+      'svDb atomicOnly must be a boolean.',
+    );
+  }
+  if (
+    options?.atomicOnly === true
+    && (
+      typeof options.serialize === 'function'
+      || typeof options.deserialize === 'function'
+    )
+  ) {
+    // Atomic operations refuse serialized roots outright, so an atomic-only
+    // serialized field could never be written at all.
+    throw new SmartdataPersistenceError(
+      'invalid_configuration',
+      'svDb atomicOnly cannot be combined with custom serialization.',
+    );
+  }
   const storedOptions = options
     ? {
         ...options,
@@ -505,13 +545,24 @@ export function index(options?: IIndexOptions) {
 // Helper type to extract element type from arrays or return T itself
 type ElementOf<T> = T extends ReadonlyArray<infer U> ? U : T;
 
+/**
+ * Explicit BSON null is a legitimate predicate for a field the model declares
+ * optional. MongoDB answers `{ field: null }` with the documents that store an
+ * explicit null *and* the documents where the field is absent, so it is the
+ * only predicate that addresses a value an earlier writer stored as null. The
+ * runtime filters have always accepted it; the declared type admits it wherever
+ * the field type contains `undefined`.
+ */
+export type TSmartdataOptionalNullPredicate<TValue> =
+  undefined extends TValue ? null : never;
+
 // Type for $in/$nin values - arrays of the element type
-type InValues<T> = ReadonlyArray<ElementOf<T>>;
+type InValues<T> = ReadonlyArray<ElementOf<T> | TSmartdataOptionalNullPredicate<T>>;
 
 // Type that allows MongoDB operators on leaf values while maintaining nested type safety
-export type MongoFilterCondition<T> = T | {
-  $eq?: T;
-  $ne?: T;
+export type MongoFilterCondition<T> = T | TSmartdataOptionalNullPredicate<T> | {
+  $eq?: T | TSmartdataOptionalNullPredicate<T>;
+  $ne?: T | TSmartdataOptionalNullPredicate<T>;
   $gt?: T;
   $gte?: T;
   $lt?: T;
@@ -575,7 +626,12 @@ export interface ISmartdataCursorOptions<T> {
   /** Model-declared index name, or MongoDB's built-in `_id_` index. */
   hint?: string;
   maxTimeMS?: number;
-  session?: plugins.mongodb.ClientSession;
+  /**
+   * An owned session from `db.createSession()` stays leased until the cursor
+   * is closed, so the cursor and the session's next operation can never run in
+   * parallel. A raw `ClientSession` keeps its unmanaged pass-through behavior.
+   */
+  session?: TSmartdataOrdinarySession;
   /**
    * @deprecated Prefer the structured cursor options. The modifier runs last
    * for backward compatibility.
@@ -661,9 +717,20 @@ type TSmartdataAtomicMonotonic<T> =
 export type TSmartdataAtomicNumericFieldReference<T> =
   `$${TSmartdataNumericDocumentPath<T>}`;
 
+/**
+ * Reads a declared numeric field, substituting a finite literal when the field
+ * is absent or stored as null. A document written before the field existed
+ * therefore takes the declared default instead of failing the comparison, while
+ * a present non-numeric value still fails closed.
+ */
+export interface ISmartdataAtomicNumericIfNull<T> {
+  $ifNull: readonly [TSmartdataAtomicNumericFieldReference<T>, number];
+}
+
 export type TSmartdataAtomicNumericExpressionOperand<T> =
   | number
   | TSmartdataAtomicNumericFieldReference<T>
+  | ISmartdataAtomicNumericIfNull<T>
   | {
       $add: readonly [
         TSmartdataAtomicNumericExpressionOperand<T>,
@@ -817,15 +884,24 @@ type TSmartdataAtomicInValue<TValue> =
 
 export type TSmartdataAtomicFilterCondition<TValue> =
   | TSmartdataAtomicDirectEquality<TValue>
+  | TSmartdataOptionalNullPredicate<TValue>
   | {
-      $eq?: TValue;
-      $ne?: TSmartdataAtomicDirectEquality<TValue>;
+      $eq?: TValue | TSmartdataOptionalNullPredicate<TValue>;
+      $ne?:
+        | TSmartdataAtomicDirectEquality<TValue>
+        | TSmartdataOptionalNullPredicate<TValue>;
       $gt?: TSmartdataAtomicDirectEquality<TValue>;
       $gte?: TSmartdataAtomicDirectEquality<TValue>;
       $lt?: TSmartdataAtomicDirectEquality<TValue>;
       $lte?: TSmartdataAtomicDirectEquality<TValue>;
-      $in?: ReadonlyArray<TSmartdataAtomicInValue<TValue>>;
-      $nin?: ReadonlyArray<TSmartdataAtomicInValue<TValue>>;
+      $in?: ReadonlyArray<
+        | TSmartdataAtomicInValue<TValue>
+        | TSmartdataOptionalNullPredicate<TValue>
+      >;
+      $nin?: ReadonlyArray<
+        | TSmartdataAtomicInValue<TValue>
+        | TSmartdataOptionalNullPredicate<TValue>
+      >;
       $exists?: boolean;
       $type?: plugins.mongodb.BSONType | plugins.mongodb.BSONTypeAlias;
       $regex?: string | RegExp;
@@ -906,6 +982,15 @@ export type TSmartdataAtomicFindOneAndUpdateResult<
     }
   | { status: 'not_matched'; document: null };
 
+export interface ISmartdataAtomicFindOneAndReplaceOptions {
+  /**
+   * Which image to return: the stored replacement (`'after'`, the default) or
+   * the document it ousted (`'before'`).
+   */
+  returnDocument?: TSmartdataAtomicReturnDocument;
+  session?: TSmartdataOrdinarySession;
+}
+
 export interface ISmartdataAtomicDeleteOptions {
   session?: TSmartdataOrdinarySession;
   /** Client-side operation deadline, including server selection and pool waits. */
@@ -964,6 +1049,87 @@ export interface ISmartdataAtomicUpsertManyResult {
   upsertedCount: number;
 }
 
+/**
+ * How a fenced save treats a declared persisted field the instance holds as
+ * `undefined`. `'ignore'` leaves whatever the document stores for it, which is
+ * what an instance that never loaded the field needs; `'unset'` removes it from
+ * the stored document, which is what an instance that deliberately cleared the
+ * field needs.
+ */
+export type TSmartdataAbsentDeclaredFields = 'ignore' | 'unset';
+
+export interface ISmartdataSaveIfOptions {
+  session?: TSmartdataOrdinarySession;
+  /** Defaults to `'ignore'`. */
+  absentDeclaredFields?: TSmartdataAbsentDeclaredFields;
+}
+
+export interface ISmartdataSaveIfResult {
+  acknowledged: boolean;
+  /** `0` means the fence did not match, so nothing was written. */
+  matchedCount: number;
+  modifiedCount: number;
+}
+
+const normalizeSaveIfOptions = (
+  optionsArg: ISmartdataSaveIfOptions | undefined,
+): {
+  session?: TSmartdataOrdinarySession;
+  absentDeclaredFields: TSmartdataAbsentDeclaredFields;
+} => {
+  if (optionsArg === undefined) {
+    return { absentDeclaredFields: 'ignore' };
+  }
+  if (
+    typeof optionsArg !== 'object'
+    || optionsArg === null
+    || plugins.nodeUtil.types.isProxy(optionsArg)
+    || !isPlainObject(optionsArg)
+  ) {
+    throw new SmartdataPersistenceError(
+      'invalid_argument',
+      'Fenced save options must be an inert plain object.',
+    );
+  }
+  const allowedKeys = new Set(['session', 'absentDeclaredFields']);
+  for (const key of Reflect.ownKeys(optionsArg)) {
+    if (typeof key !== 'string' || !allowedKeys.has(key)) {
+      throw new SmartdataPersistenceError(
+        'invalid_argument',
+        `Fenced save received unsupported option "${String(key)}".`,
+      );
+    }
+    const descriptor = Object.getOwnPropertyDescriptor(optionsArg, key);
+    if (!descriptor || !('value' in descriptor) || descriptor.enumerable !== true) {
+      throw new SmartdataPersistenceError(
+        'invalid_argument',
+        `Fenced save option "${key}" must be an inert enumerable data property.`,
+      );
+    }
+  }
+  const absentDeclaredFields = Object.getOwnPropertyDescriptor(
+    optionsArg,
+    'absentDeclaredFields',
+  )?.value as TSmartdataAbsentDeclaredFields | undefined;
+  if (
+    absentDeclaredFields !== undefined
+    && absentDeclaredFields !== 'ignore'
+    && absentDeclaredFields !== 'unset'
+  ) {
+    throw new SmartdataPersistenceError(
+      'invalid_argument',
+      'Fenced save absentDeclaredFields must be "ignore" or "unset".',
+    );
+  }
+  const session = Object.getOwnPropertyDescriptor(optionsArg, 'session')?.value as
+    | TSmartdataOrdinarySession
+    | undefined;
+  return {
+    ...(session !== undefined ? { session } : {}),
+    absentDeclaredFields: absentDeclaredFields ?? 'ignore',
+  };
+};
+
 const normalizeAtomicFindOneAndUpdateOptions = <
   TReturnDocument extends TSmartdataAtomicReturnDocument,
 >(
@@ -1041,6 +1207,63 @@ const normalizeAtomicFindOneAndUpdateOptions = <
   };
 };
 
+const normalizeAtomicFindOneAndReplaceOptions = (
+  optionsArg: ISmartdataAtomicFindOneAndReplaceOptions | undefined,
+): {
+  returnDocument: TSmartdataAtomicReturnDocument;
+  session?: TSmartdataOrdinarySession;
+} => {
+  if (optionsArg === undefined) {
+    return { returnDocument: 'after' };
+  }
+  if (
+    typeof optionsArg !== 'object'
+    || optionsArg === null
+    || plugins.nodeUtil.types.isProxy(optionsArg)
+    || !isPlainObject(optionsArg)
+  ) {
+    throw new SmartdataPersistenceError(
+      'invalid_argument',
+      'Atomic find-one-and-replace options must be an inert plain object.',
+    );
+  }
+  const allowedKeys = new Set(['returnDocument', 'session']);
+  for (const key of Reflect.ownKeys(optionsArg)) {
+    if (typeof key !== 'string' || !allowedKeys.has(key)) {
+      throw new SmartdataPersistenceError(
+        'invalid_argument',
+        `Atomic find-one-and-replace 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-replace option "${key}" must be an inert enumerable data property.`,
+      );
+    }
+  }
+  const returnDocument = Object.getOwnPropertyDescriptor(optionsArg, 'returnDocument')
+    ?.value as TSmartdataAtomicReturnDocument | undefined;
+  if (
+    returnDocument !== undefined
+    && returnDocument !== 'before'
+    && returnDocument !== 'after'
+  ) {
+    throw new SmartdataPersistenceError(
+      'invalid_argument',
+      'Atomic find-one-and-replace returnDocument must be "before" or "after".',
+    );
+  }
+  const session = Object.getOwnPropertyDescriptor(optionsArg, 'session')?.value as
+    | TSmartdataOrdinarySession
+    | undefined;
+  return {
+    returnDocument: returnDocument ?? 'after',
+    ...(session !== undefined ? { session } : {}),
+  };
+};
+
 const normalizeAtomicExpressionUpdateOptions = (
   optionsArg: ISmartdataAtomicUpdateOptions | undefined,
 ): ISmartdataAtomicUpdateOptions | undefined => {
@@ -2052,7 +2275,7 @@ const atomicNumericExpressionMaximumLeafOperands = 64;
 
 const getAtomicExpressionProperty = (
   valueArg: unknown,
-  expectedKeyArg: '$lte' | '$add',
+  expectedKeyArg: '$lte' | '$add' | '$ifNull',
   labelArg: string,
 ): unknown => {
   if (
@@ -2148,9 +2371,27 @@ const getAtomicExpressionArrayValues = (
 
 interface INormalizedAtomicNumericExpressionOperand {
   mongoExpression: unknown;
+  /** Fields the expression reads directly and that must be numeric to match. */
   referencedFields: Set<string>;
+  /** Fields read through `$ifNull`, where absent or null takes the literal. */
+  nullableFields: Set<string>;
 }
 
+/** Detects the inert `{ $ifNull: [...] }` operand shape before validating it. */
+const isAtomicIfNullOperand = (operandArg: unknown): boolean => {
+  if (
+    typeof operandArg !== 'object'
+    || operandArg === null
+    || Array.isArray(operandArg)
+    || plugins.nodeUtil.types.isProxy(operandArg)
+    || Object.getPrototypeOf(operandArg) !== Object.prototype
+  ) {
+    return false;
+  }
+  const keys = Reflect.ownKeys(operandArg);
+  return keys.length === 1 && keys[0] === '$ifNull';
+};
+
 const normalizeAtomicNumericExpression = (
   expressionArg: unknown,
   declaredRootsArg: Set<string>,
@@ -2159,77 +2400,88 @@ const normalizeAtomicNumericExpression = (
   operationLabelArg: string,
 ): plugins.mongodb.Document => {
   let leafOperandCount = 0;
+  const normalizeNumericLiteral = (literalArg: unknown): number => {
+    leafOperandCount++;
+    if (
+      typeof literalArg !== 'number'
+      || !Number.isFinite(literalArg)
+      || leafOperandCount > atomicNumericExpressionMaximumLeafOperands
+    ) {
+      throw new SmartdataPersistenceError(
+        'invalid_argument',
+        `${operationLabelArg} $expr requires finite numeric literals and no more than ${atomicNumericExpressionMaximumLeafOperands} leaf operands.`,
+      );
+    }
+    return literalArg;
+  };
+  const normalizeFieldReference = (referenceArg: unknown): string => {
+    leafOperandCount++;
+    if (leafOperandCount > atomicNumericExpressionMaximumLeafOperands) {
+      throw new SmartdataPersistenceError(
+        'invalid_argument',
+        `${operationLabelArg} $expr may not exceed ${atomicNumericExpressionMaximumLeafOperands} leaf operands.`,
+      );
+    }
+    if (
+      typeof referenceArg !== 'string'
+      || !referenceArg.startsWith('$')
+      || referenceArg.startsWith('$$')
+      || referenceArg.length < 2
+    ) {
+      throw new SmartdataPersistenceError(
+        'invalid_argument',
+        `${operationLabelArg} $expr field references must use exactly one leading $.`,
+      );
+    }
+    const field = referenceArg.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 root;
+  };
   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,
+        mongoExpression: normalizeNumericLiteral(operandArg),
         referencedFields: new Set(),
+        nullableFields: 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}".`,
-        );
-      }
+      const root = normalizeFieldReference(operandArg);
       return {
         mongoExpression: `$${root}`,
         referencedFields: new Set([root]),
+        nullableFields: new Set(),
       };
     }
     if (depthArg >= atomicNumericExpressionMaximumDepth) {
@@ -2238,6 +2490,28 @@ const normalizeAtomicNumericExpression = (
         `${operationLabelArg} $expr exceeds the maximum $add depth of ${atomicNumericExpressionMaximumDepth}.`,
       );
     }
+    if (isAtomicIfNullOperand(operandArg)) {
+      const ifNullOperands = getAtomicExpressionArrayValues(
+        getAtomicExpressionProperty(
+          operandArg,
+          '$ifNull',
+          `${operationLabelArg} $expr operand`,
+        ),
+        2,
+        2,
+        `${operationLabelArg} $expr $ifNull`,
+      );
+      const root = normalizeFieldReference(ifNullOperands[0]);
+      const fallback = normalizeNumericLiteral(ifNullOperands[1]);
+      return {
+        // A field that is absent or stored as null takes the literal; any other
+        // stored value flows into the guarded comparison unchanged, so a
+        // non-numeric value still fails closed.
+        mongoExpression: { $ifNull: [`$${root}`, fallback] },
+        referencedFields: new Set(),
+        nullableFields: new Set([root]),
+      };
+    }
     const rawOperands = getAtomicExpressionArrayValues(
       getAtomicExpressionProperty(
         operandArg,
@@ -2260,6 +2534,11 @@ const normalizeAtomicNumericExpression = (
           ...entryArg.referencedFields,
         ]),
       ),
+      nullableFields: new Set(
+        normalizedOperands.flatMap((entryArg) => [
+          ...entryArg.nullableFields,
+        ]),
+      ),
     };
   };
 
@@ -2279,7 +2558,14 @@ const normalizeAtomicNumericExpression = (
     ...left.referencedFields,
     ...right.referencedFields,
   ]);
-  const fieldGuards = [...referencedFields].map((fieldArg) => ({
+  // A field read both directly and through $ifNull must still be numeric: the
+  // direct read has no fallback, so the stricter guard wins.
+  const nullableFields = new Set(
+    [...left.nullableFields, ...right.nullableFields].filter(
+      (fieldArg) => !referencedFields.has(fieldArg),
+    ),
+  );
+  const requireStoredNumber = (fieldArg: string) => ({
     $cond: [
       { $isNumber: `$${fieldArg}` },
       {
@@ -2290,7 +2576,20 @@ const normalizeAtomicNumericExpression = (
       },
       false,
     ],
-  }));
+  });
+  const fieldGuards = [
+    ...[...referencedFields].map((fieldArg) => requireStoredNumber(fieldArg)),
+    // An absent or null field takes the $ifNull literal, which validation
+    // already proved finite. Every other stored value must still be a finite
+    // number, so a present non-numeric value fails closed exactly as before.
+    ...[...nullableFields].map((fieldArg) => ({
+      $cond: [
+        { $in: [{ $type: `$${fieldArg}` }, ['missing', 'null']] },
+        true,
+        requireStoredNumber(fieldArg),
+      ],
+    })),
+  ];
   const guardedComparison = {
     $let: {
       vars: {
@@ -2361,8 +2660,10 @@ const normalizeStrictFilter = (
     | 'Atomic update-many'
     | 'Atomic upsert-many'
     | 'Atomic find-one-and-update'
+    | 'Atomic find-one-and-replace'
     | 'Atomic delete'
-    | 'Atomic delete-many',
+    | 'Atomic delete-many'
+    | 'Fenced save',
   globallyConstrainingKeySetsArg?: ReadonlyArray<ReadonlySet<string>>,
 ): plugins.mongodb.Filter<plugins.mongodb.Document> => {
   if (
@@ -2425,7 +2726,19 @@ const normalizeStrictFilter = (
       assertOnlyDataProperties(entry, `${labelArg} entry`, false);
     }
   };
-  const conditionIsEqualityAnchor = (valueArg: unknown): boolean => {
+  /**
+   * Plural intent is explicit in the plural method names, so an explicitly
+   * enumerated, non-empty `$in` over equality scalars anchors those filters as
+   * well. A regular expression is a pattern rather than an enumerated value, so
+   * it never anchors. The singular operations keep requiring an equality that
+   * can address exactly one document, and the unique-index check below never
+   * accepts `$in`.
+   */
+  const pluralEqualityAnchors =
+    operationLabelArg === 'Atomic update-many'
+    || operationLabelArg === 'Atomic delete-many'
+    || operationLabelArg === 'Atomic upsert-many';
+  const valueIsEqualityScalar = (valueArg: unknown): boolean => {
     if (Array.isArray(valueArg)) {
       return false;
     }
@@ -2442,6 +2755,24 @@ const normalizeStrictFilter = (
         `${operationLabelArg} filters may not contain Proxy values.`,
       );
     }
+    return isAtomicMongoScalar(valueArg);
+  };
+  const conditionIsEqualityAnchor = (
+    valueArg: unknown,
+    allowBoundedInArg: boolean = pluralEqualityAnchors,
+  ): boolean => {
+    if (Array.isArray(valueArg)) {
+      return false;
+    }
+    if (typeof valueArg !== 'object' || valueArg === null) {
+      return valueIsEqualityScalar(valueArg);
+    }
+    if (plugins.nodeUtil.types.isProxy(valueArg)) {
+      throw new SmartdataPersistenceError(
+        'invalid_argument',
+        `${operationLabelArg} filters may not contain Proxy values.`,
+      );
+    }
     if (isAtomicMongoScalar(valueArg)) {
       return true;
     }
@@ -2454,27 +2785,30 @@ const normalizeStrictFilter = (
       false,
     );
     const entries = Object.entries(valueArg);
-    if (entries.length !== 1 || entries[0][0] !== '$eq') {
+    if (entries.length !== 1) {
       return false;
     }
-    const operand = entries[0][1];
-    if (Array.isArray(operand)) {
-      return false;
+    const [operator, operand] = entries[0];
+    if (operator === '$eq') {
+      return valueIsEqualityScalar(operand);
     }
-    if (typeof operand !== 'object' || operand === null) {
+    if (operator === '$in' && allowBoundedInArg) {
+      // An empty or exotic array is refused by the condition normalizer; it
+      // never becomes an anchor here either. A regular expression entry states
+      // a pattern instead of enumerating documents, so it does not bound the
+      // write and the filter stays unanchored.
       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.`,
+        Array.isArray(operand)
+        && !plugins.nodeUtil.types.isProxy(operand)
+        && Object.getPrototypeOf(operand) === Array.prototype
+        && operand.length > 0
+        && operand.every(
+          (entryArg) =>
+            !(entryArg instanceof RegExp) && valueIsEqualityScalar(entryArg),
+        )
       );
     }
-    return isAtomicMongoScalar(operand);
+    return false;
   };
   const filterHasEqualityAnchor = (
     filterObjectArg: Record<string, unknown>,
@@ -2534,8 +2868,10 @@ const normalizeStrictFilter = (
         continue;
       }
       // $or branches are deliberately excluded: an equality inside one $or
-      // branch does not globally constrain the matched document.
-      if (!key.startsWith('$') && conditionIsEqualityAnchor(value)) {
+      // branch does not globally constrain the matched document. A bounded
+      // `$in` is excluded for the same reason: it selects a set, so it never
+      // pins a unique index to one document.
+      if (!key.startsWith('$') && conditionIsEqualityAnchor(value, false)) {
         anchoredKeysArg.add(key);
       }
     }
@@ -4021,6 +4357,137 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
     } as TSmartdataAtomicFindOneAndUpdateResult<T, TReturnDocument>;
   }
 
+  /**
+   * Atomically replaces one ordinary model document with a new one, including
+   * its declared identity.
+   *
+   * This is the one operation that moves an `@unI()` identity: the matched
+   * document ceases to exist and the replacement takes its `_id` slot in a
+   * single compare-and-swap, which is what a model whose identity is the
+   * additional-authenticated-data of an encrypted field needs when it rotates.
+   * Every other write keeps identities immutable.
+   *
+   * `replacementArg` is a newly constructed instance that was never stored.
+   * Its `createSavableObject()` body is written whole, so a field the matched
+   * document carried and the replacement does not is gone afterwards — replace
+   * semantics, not `$set` — and atomic-only fields are seeded from the
+   * instance exactly as `insert()` seeds them. The body never carries an
+   * `_id`: keeping the matched document's primary key is the point of the
+   * operation, so a model whose declared identity *is* the `_id`
+   * (`identityAsDocumentId`) cannot rotate and is refused before any write.
+   *
+   * The filter follows the singular rule of `atomicUpdate()` and
+   * `atomicFindOneAndUpdate()`: declared paths and at least one top-level
+   * equality anchor. It does not have to pin a unique index — the caller
+   * usually searches by the owning field precisely because it does not know
+   * which identity is stored — so a filter matching several documents replaces
+   * one of them, as with every singular atomic operation.
+   *
+   * Like `insert()` and the other static atomic operations, this one runs no
+   * instance hooks; `beforeSave()`-style normalization belongs before the
+   * call. On a match the replacement becomes a stored instance, exactly as
+   * `insert()` marks it, and the returned instance is hydrated from the image
+   * named by `returnDocument`. Without a match nothing is written, `null` is
+   * returned, and the replacement stays untouched.
+   */
+  public static async atomicFindOneAndReplace<T>(
+    this: plugins.tsclass.typeFest.Class<T>,
+    filterArg: TSmartdataAtomicFilter<T>,
+    replacementArg: T,
+    opts?: ISmartdataAtomicFindOneAndReplaceOptions,
+  ): Promise<T | null> {
+    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',
+        'atomicFindOneAndReplace is unavailable for exact-persistence models.',
+      );
+    }
+    const normalizedOptions = normalizeAtomicFindOneAndReplaceOptions(opts);
+    if (!(replacementArg instanceof this)) {
+      throw new SmartdataPersistenceError(
+        'invalid_argument',
+        `Atomic find-one-and-replace requires a replacement instance of "${this.name}".`,
+      );
+    }
+    const replacement = replacementArg as T & SmartDataDbDoc<any, any>;
+    if (replacement.creationStatus !== 'new') {
+      // A stored instance already owns a document. Writing its body into a
+      // second one would leave two documents claiming one identity until the
+      // unique index refuses the loser.
+      throw new SmartdataPersistenceError(
+        'invalid_argument',
+        'Atomic find-one-and-replace requires a newly constructed replacement; a stored instance already owns a document.',
+      );
+    }
+    const identityDocumentIdField = (this as any).getIdentityDocumentIdField() as
+      | string
+      | undefined;
+    if (identityDocumentIdField) {
+      throw new SmartdataPersistenceError(
+        'invalid_argument',
+        `Identity field "${identityDocumentIdField}" owns the document _id, which a replacement cannot move; rotate such an identity by inserting the new document and deleting the old one.`,
+      );
+    }
+    assertUsableIdentityValues(
+      replacement as unknown as Record<string, unknown>,
+      (this.prototype as { uniqueIndexes?: string[] }).uniqueIndexes || [],
+      (this.prototype as {
+        identityValueTypes?: Record<string, TSmartdataIdentityValueType>;
+      }).identityValueTypes,
+    );
+    const normalizedFilter = normalizeStrictFilter(
+      filterArg as Record<string, unknown>,
+      (this as any).getDeclaredPersistedRoots() as Set<string>,
+      (this as any).getDeclaredAtomicPaths() as Set<string>,
+      (this as any).getDeclaredIdentityValueTypes() as Map<
+        string,
+        TSmartdataIdentityValueType
+      >,
+      (this as any).getDeclaredNumericRoots() as Set<string>,
+      (this as any).getSerializedPersistedRoots() as Set<string>,
+      'Atomic find-one-and-replace',
+    );
+    // The replacement is a document of its own, so it carries the timestamps
+    // an insert would give it rather than the matched document's.
+    const previousCreatedAt = replacement._createdAt;
+    const previousUpdatedAt = replacement._updatedAt;
+    const now = new Date().toISOString();
+    replacement._createdAt = now;
+    replacement._updatedAt = now;
+    const body = await replacement.createSavableObject() as Record<string, unknown>;
+    if (Object.prototype.hasOwnProperty.call(body, '_id')) {
+      throw new SmartdataPersistenceError(
+        'invalid_argument',
+        'Atomic find-one-and-replace cannot carry a stored document _id; the matched document keeps its own.',
+      );
+    }
+    const collection: SmartdataCollection<T> = (this as any).collection;
+    const result = await executeAtomicFindOneAndReplace(
+      collection,
+      normalizedFilter,
+      body,
+      {
+        returnDocument: normalizedOptions.returnDocument,
+        ...(normalizedOptions.session ? { session: normalizedOptions.session } : {}),
+      },
+    );
+    if (result.status === 'not_matched') {
+      replacement._createdAt = previousCreatedAt;
+      replacement._updatedAt = previousUpdatedAt;
+      return null;
+    }
+    if (!isOrdinarySessionInTransaction(normalizedOptions.session)) {
+      // A transaction may still abort, so the instance counts as stored only
+      // once the write is outside one, exactly as insert() decides it.
+      replacement.creationStatus = 'db';
+    }
+    return (this as any).createInstanceFromMongoDbNativeDoc(result.document) as T;
+  }
+
   /**
    * Atomically deletes one ordinary model document using a strict selector.
    *
@@ -4691,6 +5158,7 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
     return runWithOrdinarySmartdataSession(optionsArg.session, collection.smartdataDb, {
       ordinaryWrite: false,
       prepared: collection.isInitializedForCurrentDatabase(),
+      collectionName: collection.collectionName,
     }, async (rawSessionArg) => {
       await collection.init();
       const rawCursor = collection.mongoDbCollection
@@ -4836,54 +5304,69 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
       );
     }
     const collection: SmartdataCollection<T> = (this as any).collection;
-    await collection.init();
-    let rawCursor: plugins.mongodb.FindCursor<any> =
-      collection.mongoDbCollection.find((this as any).normalizeReadFilter(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;
+    // The cursor outlives this call, so an owned session stays leased until the
+    // cursor is closed. Every failure below releases it before rethrowing.
+    const lease = leaseOrdinarySmartdataSession(session, collection.smartdataDb, {
+      prepared: collection.isInitializedForCurrentDatabase(),
+      collectionName: collection.collectionName,
+    });
+    try {
+      await collection.init();
+      let rawCursor: plugins.mongodb.FindCursor<any> =
+        collection.mongoDbCollection.find((this as any).normalizeReadFilter(filterArg), {
+          projection,
+          session: lease.rawSession,
+          hint,
+          skip,
+        });
+      if (sort) {
+        rawCursor = rawCursor.sort(sort);
+      }
+      if (batchSize) {
+        rawCursor = rawCursor.batchSize(batchSize);
+      }
+      if (limit) {
+        rawCursor = rawCursor.limit(limit);
       }
-      if (modifiedCursor !== originalCursor) {
+      if (maxTimeMS) {
+        rawCursor = rawCursor.maxTimeMS(maxTimeMS);
+      }
+      if (modifier) {
+        const originalCursor = rawCursor;
+        let modifiedCursor: plugins.mongodb.FindCursor<any>;
         try {
-          await originalCursor.close();
-        } catch (originalCursorCloseError) {
+          modifiedCursor = modifier(originalCursor);
+        } catch (modifierError) {
           try {
-            await modifiedCursor.close();
+            await originalCursor.close();
           } catch {
-            // Preserve the original cursor's cleanup error.
+            // 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;
           }
-          throw originalCursorCloseError;
         }
+        rawCursor = modifiedCursor;
       }
-      rawCursor = modifiedCursor;
+      return new SmartdataDbCursor<T>(
+        rawCursor,
+        this as any as typeof SmartDataDbDoc,
+        lease.release,
+      );
+    } catch (cursorCreationError) {
+      lease.release();
+      throw cursorCreationError;
     }
-    return new SmartdataDbCursor<T>(rawCursor, this as any as typeof SmartDataDbDoc);
   }
 
   /**
@@ -5327,6 +5810,162 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
     return dbResult;
   }
 
+  /**
+   * Saves this instance only while the stored document still matches `fence`.
+   *
+   * The write is one `updateOne` that never upserts: the instance's identity
+   * addresses the document, the fence adds the condition the caller depends on
+   * — a status, a revision, a lease owner — and the update applies only if the
+   * server still sees that condition. `matchedCount === 0` means another writer
+   * moved the document first; nothing was written and this instance is exactly
+   * as it was before the call, so the caller can reload and decide.
+   *
+   * The stored document receives the same fields an ordinary `save()` writes,
+   * minus the ones no `save()` may write: declared identities are immutable and
+   * already pinned by the filter, and atomic-only fields belong to concurrent
+   * atomic writers — a fenced save never creates a document, so it has nothing
+   * to seed either. Declared fields this instance holds as `undefined` follow
+   * `absentDeclaredFields`.
+   *
+   * `beforeSave()` runs before the write, as with `save()`; `afterSave()` runs
+   * only when the fence matched, because a fence that missed saved nothing.
+   */
+  public async saveIf(
+    fenceArg: TSmartdataAtomicFilter<T>,
+    optsArg?: ISmartdataSaveIfOptions,
+  ): Promise<ISmartdataSaveIfResult> {
+    if (getOrdinaryPersistencePolicy(this.constructor)) {
+      throw new SmartdataPersistenceError('unsupported_operation',
+        'Validated ordinary models use insert() or transactional postimage updates.');
+    }
+    if ((this.constructor as any)[exactPersistencePolicySymbol]) {
+      throw new SmartdataPersistenceError('unsupported_operation',
+        'saveIf() is unavailable for exact-persistence models.');
+    }
+    const options = normalizeSaveIfOptions(optsArg);
+    if (this.creationStatus !== 'db') {
+      // A fence states what the stored document must still look like. An
+      // instance that was never stored has no such document, so the call is a
+      // programming error rather than a miss the caller could retry.
+      throw new SmartdataPersistenceError('invalid_argument',
+        'saveIf() requires an instance read from the database; use save() to create a document.');
+    }
+    const identityFields = this.uniqueIndexes || [];
+    if (identityFields.length === 0) {
+      throw new SmartdataPersistenceError('invalid_configuration',
+        'saveIf() requires declared identity fields; without them the fence would address an arbitrary document.');
+    }
+    if (
+      typeof fenceArg !== 'object'
+      || fenceArg === null
+      || Array.isArray(fenceArg)
+      || plugins.nodeUtil.types.isProxy(fenceArg)
+      || !isPlainObject(fenceArg)
+      || Object.keys(fenceArg).length === 0
+    ) {
+      throw new SmartdataPersistenceError('invalid_argument',
+        'saveIf() requires a non-empty fence object; an unfenced save is save().');
+    }
+    assertOnlyDataProperties(fenceArg, 'Fenced save fence', false);
+    for (const identityField of identityFields) {
+      if (Object.prototype.hasOwnProperty.call(fenceArg, identityField)) {
+        // The instance's own identity addresses the document. A second
+        // top-level condition on it would silently redirect the write.
+        throw new SmartdataPersistenceError('invalid_argument',
+          `Fenced save may not fence on identity field "${identityField}"; the instance already addresses its document.`);
+      }
+    }
+    const modelConstructor: any = this.constructor;
+    // Numeric and atomic-only declarations live on the bound collection, so a
+    // @managed instance answers for the collection it was read through.
+    const collection = this.getCollectionSafe();
+    const modelSchema = collection.getBoundModelSchema();
+    const identityFilter: Record<string, unknown> = {};
+    for (const identityField of identityFields) {
+      identityFilter[identityField] = (this as any)[identityField];
+    }
+    const normalizedFilter = normalizeStrictFilter(
+      { ...identityFilter, ...(fenceArg as Record<string, unknown>) },
+      modelConstructor.getDeclaredPersistedRoots() as Set<string>,
+      modelConstructor.getDeclaredAtomicPaths() as Set<string>,
+      modelConstructor.getDeclaredIdentityValueTypes() as Map<
+        string,
+        TSmartdataIdentityValueType
+      >,
+      new Set(modelSchema?.numericFields || []),
+      modelConstructor.getSerializedPersistedRoots() as Set<string>,
+      'Fenced save',
+    );
+    if (typeof (this as any).beforeSave === 'function') {
+      await (this as any).beforeSave();
+    }
+    assertUsableIdentityValues(
+      this as unknown as Record<string, unknown>,
+      identityFields,
+      this.identityValueTypes,
+    );
+    const previousUpdatedAt = this._updatedAt;
+    this._updatedAt = new Date().toISOString();
+    const saveableObject = await this.createSavableObject() as Record<string, unknown>;
+    const atomicOnlyRoots = new Set(modelSchema?.atomicOnlyFields || []);
+    const isWritableField = (fieldArg: string): boolean =>
+      !identityFields.includes(fieldArg) && !atomicOnlyRoots.has(fieldArg);
+    const setObject: Record<string, unknown> = {};
+    for (const key of Object.keys(saveableObject)) {
+      if (isWritableField(key)) {
+        setObject[key] = saveableObject[key];
+      }
+    }
+    const unsetObject: Record<string, unknown> = {};
+    if (options.absentDeclaredFields === 'unset') {
+      // createSavableObject() omits every field the instance holds as
+      // undefined, so a declared field missing from it is exactly a field this
+      // instance states as absent.
+      const declaredSavableFields = new Set([
+        ...(this.globalSaveableProperties || []),
+        ...(this.saveableProperties || []),
+      ]);
+      for (const field of declaredSavableFields) {
+        if (
+          isWritableField(field)
+          && !Object.prototype.hasOwnProperty.call(saveableObject, field)
+        ) {
+          unsetObject[field] = '';
+        }
+      }
+    }
+    const result = await executeAtomicUpdate(
+      collection,
+      mapIdentityFilterToDocumentId(
+        normalizedFilter,
+        getIdentityDocumentIdField(this.constructor),
+      ),
+      {
+        $set: setObject,
+        ...(Object.keys(unsetObject).length > 0 ? { $unset: unsetObject } : {}),
+      },
+      { session: options.session },
+    );
+    if (result.matchedCount === 0) {
+      // Nothing was written, so the instance keeps the update timestamp the
+      // stored document still carries.
+      this._updatedAt = previousUpdatedAt;
+      return {
+        acknowledged: result.acknowledged,
+        matchedCount: 0,
+        modifiedCount: result.modifiedCount,
+      };
+    }
+    if (typeof (this as any).afterSave === 'function') {
+      await (this as any).afterSave();
+    }
+    return {
+      acknowledged: result.acknowledged,
+      matchedCount: result.matchedCount,
+      modifiedCount: result.modifiedCount,
+    };
+  }
+
   /**
    * deletes a document from the database (optionally within a transaction)
    */