@lossless.org/client 1.0.0 → 1.2.0

package/ts/nosqldb/classes.doc.ts

@@ -17,6 +17,7 @@ import {
   type ISmartdataStoredEvidenceInspection,
 } from './classes.storedinspection.js';
 import {
+  getIdentityDocumentIdField,
   type IManager,
   type ISmartdataIndexInfo,
   SmartdataCollection,
@@ -25,7 +26,9 @@ 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 {
+  executeAtomicUpdate, executeAtomicUpdateMany, executeAtomicUpsertMany,
+} from './classes.atomicupdate.js';
 import {
   SmartdataPersistenceError,
 } from './classes.persistence.js';
@@ -75,6 +78,7 @@ interface ISmartdataDecoratorMetadata extends DecoratorMetadataObject {
   saveableProperties?: string[];
   uniqueIndexes?: string[];
   identityValueTypes?: Record<string, TSmartdataIdentityValueType>;
+  identityIndexNames?: Record<string, string>;
   regularIndexes?: Array<{field: string, options: IIndexOptions}>;
   compoundIndexes?: Array<{
     name: string;
@@ -95,6 +99,14 @@ export interface IUnIOptions {
    * non-empty string. Numeric identities require an explicit opt-in.
    */
   valueType?: TSmartdataIdentityValueType;
+  /**
+   * Name of the single-field ascending unique index that backs this identity.
+   * Defaults to `<field>_1`. A collection whose unique index was created by a
+   * migration under another name declares that name here: MongoDB refuses a
+   * second index over the same key, so without it the identity could not be
+   * declared at all.
+   */
+  indexName?: string;
 }
 
 /**
@@ -320,11 +332,13 @@ export function unI(optionsArg: IUnIOptions = {}) {
     typeof optionsArg !== 'object'
     || optionsArg === null
     || Array.isArray(optionsArg)
-    || Object.keys(optionsArg).some((keyArg) => keyArg !== 'valueType')
+    || Object.keys(optionsArg).some(
+      (keyArg) => keyArg !== 'valueType' && keyArg !== 'indexName',
+    )
   ) {
     throw new SmartdataPersistenceError(
       'invalid_configuration',
-      'unI options must be an object containing only valueType.',
+      'unI options must be an object containing only valueType and indexName.',
     );
   }
   const valueType = optionsArg.valueType ?? 'string';
@@ -334,6 +348,25 @@ export function unI(optionsArg: IUnIOptions = {}) {
       'unI valueType must be "string" or "positiveSafeInteger".',
     );
   }
+  const indexName = optionsArg.indexName;
+  if (indexName !== undefined) {
+    if (
+      typeof indexName !== 'string'
+      || indexName.trim().length === 0
+      || indexName.includes('\0')
+    ) {
+      throw new SmartdataPersistenceError(
+        'invalid_configuration',
+        'unI indexName must be a non-empty index name.',
+      );
+    }
+    if (indexName === '_id_') {
+      throw new SmartdataPersistenceError(
+        'invalid_configuration',
+        'unI indexName "_id_" is reserved for MongoDB.',
+      );
+    }
+  }
   return (value: undefined, context: ClassFieldDecoratorContext) => {
     if (context.kind !== 'field') {
       throw new Error('unI can only decorate fields');
@@ -362,6 +395,24 @@ export function unI(optionsArg: IUnIOptions = {}) {
       );
     }
     metadata.identityValueTypes![propName] = valueType;
+    // An unnamed declaration writes no entry, so a subclass that redeclares
+    // the identity without a name keeps the index the base class named. Only
+    // a second, different name is a contradiction worth refusing.
+    if (indexName !== undefined) {
+      if (
+        !Object.prototype.hasOwnProperty.call(metadata, 'identityIndexNames')
+      ) {
+        metadata.identityIndexNames = { ...(metadata.identityIndexNames || {}) };
+      }
+      const existingIndexName = metadata.identityIndexNames![propName];
+      if (existingIndexName && existingIndexName !== indexName) {
+        throw new SmartdataPersistenceError(
+          'invalid_configuration',
+          `Identity field "${propName}" has divergent indexName declarations.`,
+        );
+      }
+      metadata.identityIndexNames![propName] = indexName;
+    }
 
     // Also mark as saveable
     if (!Object.prototype.hasOwnProperty.call(metadata, 'saveableProperties')) {
@@ -590,6 +641,23 @@ export type TSmartdataNumericDocumentPath<T> = {
     NonNullable<T[TKey]> extends number ? TKey : never;
 }[TSmartdataDocumentPath<T>];
 
+/** Declared top-level fields that carry a monotonic ordering: numbers and dates. */
+export type TSmartdataMonotonicDocumentPath<T> = {
+  [TKey in TSmartdataDocumentPath<T>]:
+    NonNullable<T[TKey]> extends number
+      ? TKey
+      : NonNullable<T[TKey]> extends Date
+        ? TKey
+        : never;
+}[TSmartdataDocumentPath<T>];
+
+type TSmartdataAtomicMonotonic<T> =
+  & Partial<{
+    [TKey in TSmartdataMonotonicDocumentPath<T>]:
+      NonNullable<T[TKey]> extends Date ? Date : number;
+  }>
+  & Partial<Record<TSmartdataAtomicNestedDocumentPath<T>, number | Date>>;
+
 export type TSmartdataAtomicNumericFieldReference<T> =
   `$${TSmartdataNumericDocumentPath<T>}`;
 
@@ -691,6 +759,18 @@ export interface ISmartdataAtomicUpdate<T> {
     Record<TSmartdataAtomicDocumentPath<T>, '' | true | 1>
   >;
   $inc?: TSmartdataAtomicIncrement<T>;
+  /**
+   * Monotonic ceiling for a declared numeric or date field: one server-side
+   * compare-and-write that never lowers the stored value, so a retried or
+   * out-of-order writer cannot regress a counter. With `upsert: true` a
+   * missing field is inserted with the operand.
+   */
+  $max?: TSmartdataAtomicMonotonic<T>;
+  /**
+   * Monotonic floor for a declared numeric or date field: the mirror of
+   * `$max`, never raising the stored value.
+   */
+  $min?: TSmartdataAtomicMonotonic<T>;
   $setOnInsert?: TSmartdataAtomicSet<T>;
   /**
    * Appends one element to a declared top-level array field. Modifier
@@ -860,6 +940,30 @@ export interface ISmartdataAtomicUpdateManyResult {
   modifiedCount: number;
 }
 
+/** One strict selector and its update, both validated before any write. */
+export interface ISmartdataAtomicUpsertManyOperation<T> {
+  filter: TSmartdataAtomicFilter<T>;
+  update: ISmartdataAtomicUpdate<T>;
+}
+
+export interface ISmartdataAtomicUpsertManyOptions {
+  session?: TSmartdataOrdinarySession;
+  /** Client-side bulk operation deadline, including server selection and pool waits. */
+  timeoutMS?: number;
+  /**
+   * Only `false`. The batch is always unordered, so one conflicting entry
+   * never hides the outcome of the entries behind it.
+   */
+  ordered?: false;
+}
+
+export interface ISmartdataAtomicUpsertManyResult {
+  acknowledged: boolean;
+  matchedCount: number;
+  modifiedCount: number;
+  upsertedCount: number;
+}
+
 const normalizeAtomicFindOneAndUpdateOptions = <
   TReturnDocument extends TSmartdataAtomicReturnDocument,
 >(
@@ -2255,6 +2359,7 @@ const normalizeStrictFilter = (
   operationLabelArg:
     | 'Atomic update'
     | 'Atomic update-many'
+    | 'Atomic upsert-many'
     | 'Atomic find-one-and-update'
     | 'Atomic delete'
     | 'Atomic delete-many',
@@ -2533,6 +2638,15 @@ const normalizeAtomicUpdate = <T>(
   declaredNestedPathsArg: Set<string>,
   uniqueRootsArg: Set<string>,
   serializedRootsArg: Set<string>,
+  /**
+   * Supplied only by upserting operations. Its presence allows `$setOnInsert`
+   * to seed declared identity roots on the insert branch; identities stay
+   * immutable on the update branch because MongoDB never applies
+   * `$setOnInsert` to an existing document.
+   */
+  identitySeedingArg?: {
+    identityValueTypes: ReadonlyMap<string, TSmartdataIdentityValueType>;
+  },
 ): plugins.mongodb.UpdateFilter<plugins.mongodb.Document> => {
   if (
     typeof updateArg !== 'object' ||
@@ -2552,8 +2666,11 @@ const normalizeAtomicUpdate = <T>(
     '$push',
     '$addToSet',
     '$pull',
+    '$max',
+    '$min',
   ]);
   const arrayOperators = new Set(['$push', '$addToSet', '$pull']);
+  const monotonicOperators = new Set(['$max', '$min']);
   for (const operator of Object.keys(updateArg)) {
     if (!allowedOperators.has(operator)) {
       throw new SmartdataPersistenceError(
@@ -2595,9 +2712,30 @@ const normalizeAtomicUpdate = <T>(
         );
       }
       if (uniqueRootsArg.has(root)) {
-        throw new SmartdataPersistenceError(
-          'invalid_argument',
-          `${operator} may not modify immutable @unI() field "${root}".`,
+        if (operator !== '$setOnInsert') {
+          throw new SmartdataPersistenceError(
+            'invalid_argument',
+            `${operator} may not modify immutable @unI() field "${root}".`,
+          );
+        }
+        if (!identitySeedingArg) {
+          throw new SmartdataPersistenceError(
+            'invalid_argument',
+            `$setOnInsert may not seed immutable @unI() field "${root}" without upsert: true.`,
+          );
+        }
+        if (path !== root) {
+          throw new SmartdataPersistenceError(
+            'invalid_argument',
+            `$setOnInsert may not target a nested path below immutable @unI() field "${root}".`,
+          );
+        }
+        // The insert branch must create a complete, addressable document, so
+        // the seeded value passes the same identity validation an insert does.
+        requireUsableIdentityValue(
+          value,
+          `$setOnInsert identity field "${root}"`,
+          identitySeedingArg.identityValueTypes.get(root) ?? 'string',
         );
       }
       const conflict = occupiedPaths.find((occupiedPath) =>
@@ -2688,6 +2826,34 @@ const normalizeAtomicUpdate = <T>(
           `${operator} path "${path}" may not be undefined.`,
         );
       }
+      if (monotonicOperators.has(operator)) {
+        if (typeof value === 'number') {
+          if (!Number.isFinite(value)) {
+            throw new SmartdataPersistenceError(
+              'invalid_argument',
+              `${operator} path "${path}" must be a finite number or a Date.`,
+            );
+          }
+          normalizedOperation[path] = value;
+          continue;
+        }
+        if (
+          !(value instanceof Date)
+          || !Number.isFinite(value.getTime())
+        ) {
+          throw new SmartdataPersistenceError(
+            'invalid_argument',
+            `${operator} path "${path}" must be a finite number or a Date.`,
+          );
+        }
+        // A custom encoder could otherwise rewrite the comparison operand at
+        // serialization time, so the date is captured as an inert snapshot.
+        normalizedOperation[path] = createInertAtomicBsonScalarSnapshot(
+          value,
+          `${operator} path "${path}"`,
+        );
+        continue;
+      }
       if (
         operator === '$inc' &&
         (typeof value !== 'number' || !Number.isFinite(value))
@@ -2714,6 +2880,151 @@ const normalizeAtomicUpdate = <T>(
   return normalized as plugins.mongodb.UpdateFilter<plugins.mongodb.Document>;
 };
 
+/**
+ * Reads a globally constraining equality value for one declared path from an
+ * already normalized filter. `$or` branches are excluded because an equality
+ * inside a single branch does not pin the matched document.
+ */
+const readNormalizedFilterEquality = (
+  filterArg: Record<string, unknown>,
+  pathArg: string,
+): { found: boolean; value?: unknown } => {
+  for (const [key, value] of Object.entries(filterArg)) {
+    if (key === '$and' && Array.isArray(value)) {
+      for (const entry of value) {
+        if (isPlainObject(entry)) {
+          const nested = readNormalizedFilterEquality(
+            entry as Record<string, unknown>,
+            pathArg,
+          );
+          if (nested.found) {
+            return nested;
+          }
+        }
+      }
+      continue;
+    }
+    if (key !== pathArg) {
+      continue;
+    }
+    if (isPlainObject(value)) {
+      const entries = Object.entries(value as Record<string, unknown>);
+      if (entries.length === 1 && entries[0][0] === '$eq') {
+        return { found: true, value: entries[0][1] };
+      }
+      continue;
+    }
+    return { found: true, value };
+  }
+  return { found: false };
+};
+
+/**
+ * An upsert seeds its inserted document from the filter's equality conditions
+ * and from `$setOnInsert`. When both name the same identity they must agree,
+ * otherwise the insert branch would create a document its own selector can
+ * never match again.
+ */
+const assertSeededIdentitiesMatchFilter = (
+  normalizedFilterArg: Record<string, unknown>,
+  normalizedUpdateArg: Record<string, unknown>,
+  uniqueRootsArg: Set<string>,
+  operationLabelArg: string,
+): void => {
+  const seeded = normalizedUpdateArg.$setOnInsert;
+  if (!isPlainObject(seeded)) {
+    return;
+  }
+  for (const [path, value] of Object.entries(seeded as Record<string, unknown>)) {
+    if (!uniqueRootsArg.has(path)) {
+      continue;
+    }
+    const anchored = readNormalizedFilterEquality(normalizedFilterArg, path);
+    if (anchored.found && anchored.value !== value) {
+      throw new SmartdataPersistenceError(
+        'invalid_argument',
+        `${operationLabelArg} $setOnInsert identity "${path}" must equal the filter's equality anchor for "${path}".`,
+      );
+    }
+  }
+};
+
+/**
+ * An upsert on a model whose identity owns the document `_id` must pin that
+ * identity by equality: MongoDB derives the inserted primary key from the
+ * filter, so an unpinned upsert would create a document with a generated `_id`
+ * that contradicts the declared mapping. Returns the pinned identity value so
+ * the caller can seed the stored identity field exactly as an unmapped upsert
+ * would have done.
+ */
+const requirePinnedDocumentIdentity = (
+  normalizedFilterArg: Record<string, unknown>,
+  identityFieldArg: string,
+  operationLabelArg: string,
+): unknown => {
+  const anchored = readNormalizedFilterEquality(
+    normalizedFilterArg,
+    identityFieldArg,
+  );
+  if (!anchored.found) {
+    throw new SmartdataPersistenceError(
+      'invalid_argument',
+      `${operationLabelArg} upsert requires an equality anchor on "${identityFieldArg}", which owns the document _id.`,
+    );
+  }
+  return anchored.value;
+};
+
+/**
+ * Rewrites equality and operator conditions on a model's `identityAsDocumentId`
+ * field onto `_id`, so the primary key index answers the query instead of a
+ * collection scan. The stored identity field keeps its own value, but every
+ * identity-filtered access is answered through `_id`, so a document written
+ * before the option was declared resolves only if `_id` already equals it.
+ */
+const mapIdentityFilterToDocumentId = (
+  filterArg: Record<string, unknown>,
+  identityFieldArg: string | undefined,
+): Record<string, unknown> => {
+  if (!identityFieldArg || !isPlainObject(filterArg)) {
+    return filterArg;
+  }
+  const carriesExplicitDocumentId = Object.prototype.hasOwnProperty.call(
+    filterArg,
+    '_id',
+  );
+  const mapped: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(filterArg)) {
+    if (
+      (key === '$and' || key === '$or' || key === '$nor')
+      && Array.isArray(value)
+    ) {
+      mapped[key] = value.map((entryArg) =>
+        isPlainObject(entryArg)
+          ? mapIdentityFilterToDocumentId(
+            entryArg as Record<string, unknown>,
+            identityFieldArg,
+          )
+          : entryArg,
+      );
+      continue;
+    }
+    if (key === '$not' && isPlainObject(value)) {
+      mapped[key] = mapIdentityFilterToDocumentId(
+        value as Record<string, unknown>,
+        identityFieldArg,
+      );
+      continue;
+    }
+    if (key === identityFieldArg && !carriesExplicitDocumentId) {
+      mapped._id = value;
+      continue;
+    }
+    mapped[key] = value;
+  }
+  return mapped;
+};
+
 const normalizeProjection = <T>(
   projectionArg: TSmartdataProjection<T> | undefined,
   declaredRootsArg: Set<string>,
@@ -3087,6 +3398,27 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
     return new Set(collection.getBoundModelSchema()?.numericFields || []);
   }
 
+  /**
+   * Returns the declared identity field this model stores as the document
+   * `_id`, or undefined when SmartData owns the primary key.
+   */
+  private static getIdentityDocumentIdField(): string | undefined {
+    return getIdentityDocumentIdField(this);
+  }
+
+  /**
+   * Converts an ordinary read filter and routes a declared document-id
+   * identity onto `_id`, so reads use the primary key index.
+   */
+  private static normalizeReadFilter(
+    filterArg: Record<string, any>,
+  ): plugins.mongodb.Filter<plugins.mongodb.Document> {
+    return mapIdentityFilterToDocumentId(
+      convertFilterForMongoDb(filterArg),
+      (this as any).getIdentityDocumentIdField() as string | undefined,
+    ) as plugins.mongodb.Filter<plugins.mongodb.Document>;
+  }
+
   /**
    * 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
@@ -3531,20 +3863,40 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
         'Atomic update does not support upsert when the filter contains $expr.',
       );
     }
+    const upserting = normalizedOptions?.upsert === true;
     const normalizedUpdate = normalizeAtomicUpdate(
       updateArg,
       declaredRoots,
       declaredAtomicPaths,
       uniqueRoots,
       serializedRoots,
+      upserting ? { identityValueTypes } : undefined,
+    );
+    assertSeededIdentitiesMatchFilter(
+      normalizedFilter,
+      normalizedUpdate,
+      uniqueRoots,
+      'Atomic update',
     );
     const now = new Date().toISOString();
     normalizedUpdate.$set = {
       ...(normalizedUpdate.$set || {}),
       _updatedAt: now,
     };
-    if (normalizedOptions?.upsert === true) {
+    const identityDocumentIdField = (this as any).getIdentityDocumentIdField() as
+      | string
+      | undefined;
+    if (upserting) {
       normalizedUpdate.$setOnInsert = {
+        ...(identityDocumentIdField
+          ? {
+            [identityDocumentIdField]: requirePinnedDocumentIdentity(
+              normalizedFilter,
+              identityDocumentIdField,
+              'Atomic update',
+            ),
+          }
+          : {}),
         ...(normalizedUpdate.$setOnInsert || {}),
         _createdAt: now,
       };
@@ -3552,7 +3904,7 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
     const collection: SmartdataCollection<T> = (this as any).collection;
     const result = await executeAtomicUpdate(
       collection,
-      normalizedFilter,
+      mapIdentityFilterToDocumentId(normalizedFilter, identityDocumentIdField),
       normalizedUpdate,
       normalizedOptions,
     );
@@ -3615,6 +3967,13 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
       declaredAtomicPaths,
       uniqueRoots,
       serializedRoots,
+      normalizedOptions.upsert ? { identityValueTypes } : undefined,
+    );
+    assertSeededIdentitiesMatchFilter(
+      normalizedFilter,
+      normalizedUpdate,
+      uniqueRoots,
+      'Atomic find-one-and-update',
     );
     if (policy?.timestamps !== 'none') {
       const now = new Date().toISOString();
@@ -3623,6 +3982,19 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
         normalizedUpdate.$setOnInsert = { ...(normalizedUpdate.$setOnInsert || {}), _createdAt: now };
       }
     }
+    const identityDocumentIdField = (this as any).getIdentityDocumentIdField() as
+      | string
+      | undefined;
+    if (normalizedOptions.upsert && identityDocumentIdField) {
+      normalizedUpdate.$setOnInsert = {
+        [identityDocumentIdField]: requirePinnedDocumentIdentity(
+          normalizedFilter,
+          identityDocumentIdField,
+          'Atomic find-one-and-update',
+        ),
+        ...(normalizedUpdate.$setOnInsert || {}),
+      };
+    }
     const normalizedSort = normalizeSort(
       normalizedOptions.sort as TSmartdataSort<T> | undefined,
       declaredRoots,
@@ -3631,7 +4003,7 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
     const collection: SmartdataCollection<T> = (this as any).collection;
     const result = await executeAtomicFindOneAndUpdate(
       collection,
-      normalizedFilter,
+      mapIdentityFilterToDocumentId(normalizedFilter, identityDocumentIdField),
       normalizedUpdate,
       {
         returnDocument: normalizedOptions.returnDocument,
@@ -3688,7 +4060,10 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
     const collection: SmartdataCollection<T> = (this as any).collection;
     const result = await executeAtomicDelete(
       collection,
-      normalizedFilter,
+      mapIdentityFilterToDocumentId(
+        normalizedFilter,
+        (this as any).getIdentityDocumentIdField() as string | undefined,
+      ),
       { session: opts?.session, timeoutMS: requireBoundedInteger(opts?.timeoutMS, 'Atomic delete timeoutMS', 120_000) },
     );
     return {
@@ -3736,7 +4111,10 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
     const collection: SmartdataCollection<T> = (this as any).collection;
     const result = await executeAtomicDeleteMany(
       collection,
-      normalizedFilter,
+      mapIdentityFilterToDocumentId(
+        normalizedFilter,
+        (this as any).getIdentityDocumentIdField() as string | undefined,
+      ),
       { session: opts?.session, timeoutMS: requireBoundedInteger(opts?.timeoutMS, 'Atomic delete-many timeoutMS', 120_000) },
     );
     return {
@@ -3810,7 +4188,10 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
     const collection: SmartdataCollection<T> = (this as any).collection;
     const result = await executeAtomicUpdateMany(
       collection,
-      normalizedFilter,
+      mapIdentityFilterToDocumentId(
+        normalizedFilter,
+        (this as any).getIdentityDocumentIdField() as string | undefined,
+      ),
       normalizedUpdate,
       opts,
     );
@@ -3821,6 +4202,172 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
     };
   }
 
+  /**
+   * Atomically upserts a bounded batch of ordinary model documents in one
+   * round trip. Every entry carries its own strict selector and update, and
+   * each entry applies atomically; the batch as a whole is not isolated unless
+   * the caller supplies a transaction session. The complete batch is validated
+   * before any write, so one invalid entry rejects the call without writing.
+   */
+  public static async atomicUpsertMany<T>(
+    this: plugins.tsclass.typeFest.Class<T>,
+    operationsArg: ReadonlyArray<ISmartdataAtomicUpsertManyOperation<T>>,
+    opts?: ISmartdataAtomicUpsertManyOptions,
+  ): Promise<ISmartdataAtomicUpsertManyResult> {
+    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',
+        'atomicUpsertMany is unavailable for exact-persistence models.',
+      );
+    }
+    if (
+      !Array.isArray(operationsArg)
+      || operationsArg.length < 1
+      || operationsArg.length > 1000
+    ) {
+      throw new SmartdataPersistenceError(
+        'invalid_argument',
+        'Atomic upsert-many requires 1 to 1000 operations.',
+      );
+    }
+    if (opts !== undefined) {
+      const optionsValue: unknown = opts;
+      if (!isPlainObject(optionsValue) || plugins.nodeUtil.types.isProxy(optionsValue)) {
+        throw new SmartdataPersistenceError(
+          'invalid_argument',
+          'Atomic upsert-many options must be an inert ordinary object.',
+        );
+      }
+      for (const key of Reflect.ownKeys(opts)) {
+        if (
+          typeof key !== 'string'
+          || !['session', 'timeoutMS', 'ordered'].includes(key)
+        ) {
+          throw new SmartdataPersistenceError(
+            'invalid_argument',
+            `Atomic upsert-many received unsupported option "${String(key)}".`,
+          );
+        }
+      }
+      if (opts.ordered !== undefined && opts.ordered !== false) {
+        throw new SmartdataPersistenceError(
+          'invalid_argument',
+          'Atomic upsert-many is always unordered; ordered may only be false.',
+        );
+      }
+    }
+    const timeoutMS = requireBoundedInteger(
+      opts?.timeoutMS,
+      'Atomic upsert-many timeoutMS',
+      120_000,
+    );
+    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 identityDocumentIdField = (this as any).getIdentityDocumentIdField() as
+      | string
+      | undefined;
+    const now = new Date().toISOString();
+    const normalizedOperations: Array<{
+      filter: plugins.mongodb.Filter<plugins.mongodb.Document>;
+      update: plugins.mongodb.UpdateFilter<plugins.mongodb.Document>;
+    }> = [];
+    let bytes = 0;
+    for (const operation of operationsArg) {
+      if (
+        !isPlainObject(operation)
+        || plugins.nodeUtil.types.isProxy(operation)
+        || Object.keys(operation).some(
+          (keyArg) => !['filter', 'update'].includes(keyArg),
+        )
+      ) {
+        throw new SmartdataPersistenceError(
+          'invalid_argument',
+          'Atomic upsert-many operations must be inert objects with a filter and an update.',
+        );
+      }
+      const normalizedFilter = normalizeStrictFilter(
+        operation.filter as Record<string, unknown>,
+        declaredRoots,
+        declaredAtomicPaths,
+        identityValueTypes,
+        numericRoots,
+        serializedRoots,
+        'Atomic upsert-many',
+      );
+      if ('$expr' in normalizedFilter) {
+        throw new SmartdataPersistenceError(
+          'invalid_argument',
+          'Atomic upsert-many does not support filters that contain $expr.',
+        );
+      }
+      const normalizedUpdate = normalizeAtomicUpdate(
+        operation.update as ISmartdataAtomicUpdate<T>,
+        declaredRoots,
+        declaredAtomicPaths,
+        uniqueRoots,
+        serializedRoots,
+        { identityValueTypes },
+      );
+      assertSeededIdentitiesMatchFilter(
+        normalizedFilter,
+        normalizedUpdate,
+        uniqueRoots,
+        'Atomic upsert-many',
+      );
+      normalizedUpdate.$set = {
+        ...(normalizedUpdate.$set || {}),
+        _updatedAt: now,
+      };
+      normalizedUpdate.$setOnInsert = {
+        ...(identityDocumentIdField
+          ? {
+            [identityDocumentIdField]: requirePinnedDocumentIdentity(
+              normalizedFilter,
+              identityDocumentIdField,
+              'Atomic upsert-many',
+            ),
+          }
+          : {}),
+        ...(normalizedUpdate.$setOnInsert || {}),
+        _createdAt: now,
+      };
+      const mappedFilter = mapIdentityFilterToDocumentId(
+        normalizedFilter,
+        identityDocumentIdField,
+      );
+      bytes += plugins.mongodb.BSON.calculateObjectSize({
+        q: mappedFilter,
+        u: normalizedUpdate,
+      });
+      if (bytes > 16 * 1024 * 1024) {
+        throw new SmartdataPersistenceError(
+          'invalid_argument',
+          'Atomic upsert-many accepts at most 16 MiB of serialized operations.',
+        );
+      }
+      normalizedOperations.push({
+        filter: mappedFilter as plugins.mongodb.Filter<plugins.mongodb.Document>,
+        update: normalizedUpdate,
+      });
+    }
+    const collection: SmartdataCollection<T> = (this as any).collection;
+    return await executeAtomicUpsertMany(collection, normalizedOperations, {
+      session: opts?.session,
+      timeoutMS,
+    });
+  }
+
   /**
    * Computes bounded grouped counts and optional numeric sums server-side.
    * Groups by one or two declared top-level fields, always returns a `count`
@@ -4001,7 +4548,7 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
     const collection: SmartdataCollection<T> = (this as any).collection;
     const rows = await collection.aggregateGroupedTotals(
       filterOption !== undefined
-        ? convertFilterForMongoDb(filterOption)
+        ? (this as any).normalizeReadFilter(filterOption)
         : undefined,
       groupStage,
       limit + 1,
@@ -4073,7 +4620,7 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
   ): Promise<T[]> {
     // Pass session through to findAll for transactional queries
     const foundDocs = await (this as any).collection.findAll(
-      convertFilterForMongoDb(filterArg),
+      (this as any).normalizeReadFilter(filterArg),
       { session: opts?.session },
     );
     const returnArray: T[] = [];
@@ -4122,7 +4669,7 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
       ? optionsArg.limit!
       : 100;
     const limit = Math.min(requestedLimit, 1000);
-    const baseSelector = convertFilterForMongoDb(optionsArg.filter || {});
+    const baseSelector = (this as any).normalizeReadFilter(optionsArg.filter || {});
 
     let selector: any = baseSelector;
     if (optionsArg.cursor) {
@@ -4194,7 +4741,7 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
     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),
+      (this as any).normalizeReadFilter(filterArg),
       {
         projection: normalizeProjection(
           opts?.projection,
@@ -4226,7 +4773,7 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
     },
   ): Promise<boolean> {
     const foundDoc = await (this as any).collection.findOne(
-      convertFilterForMongoDb(filterArg),
+      (this as any).normalizeReadFilter(filterArg),
       {
         projection: { _id: 1 },
         maxTimeMS: requireBoundedInteger(
@@ -4291,7 +4838,7 @@ 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(convertFilterForMongoDb(filterArg), {
+      collection.mongoDbCollection.find((this as any).normalizeReadFilter(filterArg), {
         projection,
         session,
         hint,
@@ -4365,7 +4912,7 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
     }
     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);
+    const filter = (this as any).normalizeReadFilter(filterArg);
     opts.signal?.throwIfAborted();
     const collection: SmartdataCollection<T> = (this as any).collection;
     if (!collection.isInitializedForCurrentDatabase()) {
@@ -4410,7 +4957,7 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
   ): Promise<SmartdataDbWatcher<T>> {
     const collection: SmartdataCollection<T> = (this as any).collection;
     const watcher: SmartdataDbWatcher<T> = await collection.watch(
-      convertFilterForMongoDb(filterArg),
+      (this as any).normalizeReadFilter(filterArg),
       opts || {},
       this as any,
     );
@@ -4440,7 +4987,7 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
   ) {
     const hint = normalizeQueryHint(opts?.hint, this);
     const collection: SmartdataCollection<T> = (this as any).collection;
-    return await collection.getCount(convertFilterForMongoDb(filterArg), {
+    return await collection.getCount((this as any).normalizeReadFilter(filterArg), {
       hint,
       limit: requireBoundedInteger(opts?.limit, 'limit', 10_000),
       maxTimeMS: requireBoundedInteger(
@@ -4913,7 +5460,14 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
       this.identityValueTypes,
     );
     const identifiableObject: any = {}; // is not exposed to outside, so any is ok here
+    const identityDocumentIdField = getIdentityDocumentIdField(this.constructor);
     for (const propertyNameString of this.uniqueIndexes || []) {
+      if (propertyNameString === identityDocumentIdField) {
+        // The declared identity is the stored primary key, so instance writes
+        // and reads address the document through _id.
+        identifiableObject._id = this[propertyNameString];
+        continue;
+      }
       identifiableObject[propertyNameString] = this[propertyNameString];
     }
     if (getOrdinaryPersistencePolicy(this.constructor)?.idType === 'string') {