@lossless.org/client 1.1.0 → 1.3.0

package/ts/nosqldb/classes.collection.ts

@@ -15,6 +15,7 @@ import { SmartdataDbCursor } from './classes.cursor.js';
 import {
   SmartDataDbDoc,
   type IIndexOptions,
+  type SvDbOptions,
   type TSmartdataNumericDocumentPath,
   type TSmartdataIdentityValueType,
 } from './classes.doc.js';
@@ -23,10 +24,12 @@ import { CollectionFactory } from './classes.collectionfactory.js';
 import { logger } from './logging.js';
 import {
   SmartdataPersistenceError,
+  isMongoIndexConflictError,
   normalizeOrdinaryPersistenceError,
 } from './classes.persistence.js';
 import { notifyCollectionReconnect } from './classes.collectionlifecycle.js';
 import {
+  leaseOrdinarySmartdataSession,
   runWithOrdinarySmartdataSession,
   type TSmartdataOrdinarySession,
 } from './classes.session.js';
@@ -34,6 +37,8 @@ import {
   collectionModelSchemaResolverSymbol,
   collectionTopologyDbInspectionSymbol,
   getExpectedCollectionTopologyForSchema,
+  getIdentityIndexName,
+  isIdentityIndexFor,
   compareSmartdataTopologyStrings,
 } from './classes.collectiontopology.js';
 
@@ -66,6 +71,14 @@ export interface ICollectionBindingOptions {
    * `_id === document[field]`.
    */
   identityAsDocumentId?: string;
+  /**
+   * Names of installed indexes this model accepts without declaring them —
+   * typically migration-owned indexes SmartData does not express, such as
+   * partial or filtered unique indexes. A tolerated index is never created,
+   * never dropped and never verified beyond its name, and it no longer makes
+   * the collection topology divergent.
+   */
+  toleratedIndexNames?: ReadonlyArray<string>;
 }
 
 export type TCollectionModelIndexDirection = 1 | -1 | 'text';
@@ -109,6 +122,16 @@ export interface ICollectionModelConfig<TModel extends object = any> {
    * numeric-field constraint.
    */
   numericFields?: ReadonlyArray<TSmartdataNumericDocumentPath<TModel>>;
+  /**
+   * Persisted top-level fields that only atomic operations may overwrite. Every
+   * write that creates a document stores them — `insert()`, `insertMany()`,
+   * `insertManyIfAbsent()` and the insert branch of `save()` — and they read
+   * like any other declared field, but a `save()` that matches a stored
+   * document leaves them untouched, so a stale instance cannot overwrite a
+   * value concurrent atomic writers own. An identity field cannot be
+   * atomic-only.
+   */
+  atomicOnlyFields?: ReadonlyArray<keyof TModel & string>;
   /**
    * Persisted string identity fields with @unI()-equivalent selector and
    * immutability semantics. Each field requires an explicit single-field,
@@ -130,6 +153,15 @@ export interface ICollectionModelConfig<TModel extends object = any> {
    * Stable named MongoDB indexes. Object property order defines key order.
    */
   indexes?: ReadonlyArray<ICollectionModelIndex>;
+  /**
+   * Names of installed indexes this model does not declare but accepts —
+   * typically indexes a migration owns, such as partial or filtered unique
+   * indexes SmartData does not express. A tolerated index is never created,
+   * never dropped and never verified beyond its name, and it no longer makes
+   * the collection topology divergent. Every undeclared index outside this
+   * list still does.
+   */
+  toleratedIndexNames?: ReadonlyArray<string>;
 }
 
 export interface INormalizedCollectionModelSchema {
@@ -137,6 +169,8 @@ export interface INormalizedCollectionModelSchema {
   readonly collectionName: string;
   readonly persistedFields: readonly string[];
   readonly numericFields: readonly string[];
+  /** Declared persisted fields a matching instance `save()` never overwrites. */
+  readonly atomicOnlyFields: readonly string[];
   readonly identityFields: readonly string[];
   /** Declared identity field stored as the document `_id`, if any. */
   readonly identityAsDocumentId?: string;
@@ -151,6 +185,8 @@ export interface INormalizedCollectionModelSchema {
     >;
     readonly options: Readonly<IIndexOptions>;
   }>;
+  /** Undeclared installed indexes this model accepts by name, never touches. */
+  readonly toleratedIndexNames: readonly string[];
   readonly fingerprint: string;
 }
 
@@ -180,6 +216,7 @@ interface ISmartdataDecoratorMetadata {
   saveableProperties?: string[];
   uniqueIndexes?: string[];
   identityValueTypes?: Record<string, TSmartdataIdentityValueType>;
+  identityIndexNames?: Record<string, string>;
   regularIndexes?: Array<{field: string, options: IIndexOptions}>;
   compoundIndexes?: ICompoundIndexDefinition[];
   namedIndexes?: INamedIndexDefinition[];
@@ -340,10 +377,12 @@ const normalizeCollectionModelSchema = (
     'collectionName',
     'persistedFields',
     'numericFields',
+    'atomicOnlyFields',
     'identityFields',
     'identityAsDocumentId',
     'searchableFields',
     'indexes',
+    'toleratedIndexNames',
   ]);
   for (const key of Object.keys(configArg)) {
     if (!allowedConfigKeys.has(key)) {
@@ -432,6 +471,37 @@ const normalizeCollectionModelSchema = (
       );
     }
   }
+  if (
+    configArg.atomicOnlyFields !== undefined &&
+    !Array.isArray(configArg.atomicOnlyFields)
+  ) {
+    throw new SmartdataPersistenceError(
+      'invalid_configuration',
+      'Collection model atomicOnlyFields must be an array.',
+    );
+  }
+  const atomicOnlyFields: string[] = [];
+  for (const field of configArg.atomicOnlyFields || []) {
+    requireSafeFieldName(field, 'An atomic-only field');
+    if (!persistedFields.includes(field)) {
+      throw new SmartdataPersistenceError(
+        'invalid_configuration',
+        `Atomic-only field "${field}" is not a declared persisted field.`,
+      );
+    }
+    if (identityFields.includes(field)) {
+      // An identity is immutable and addresses the document, so it is written
+      // by the insert that creates it and by nothing else afterwards. Making
+      // it atomic-only would promise an atomic write that is always refused.
+      throw new SmartdataPersistenceError(
+        'invalid_configuration',
+        `Identity field "${field}" cannot be atomic-only.`,
+      );
+    }
+    if (!atomicOnlyFields.includes(field)) {
+      atomicOnlyFields.push(field);
+    }
+  }
   const identityValueTypes: Record<string, TSmartdataIdentityValueType> = {};
   for (const field of Object.keys(identityValueTypesArg || {})) {
     if (!identityFields.includes(field)) {
@@ -594,12 +664,8 @@ const normalizeCollectionModelSchema = (
     );
   }
   for (const identityField of identityFields) {
-    const hasIdentityIndex = [...indexesByName.values()].some(
-      (indexArg) =>
-        indexArg.options.unique === true &&
-        indexArg.key.length === 1 &&
-        indexArg.key[0][0] === identityField &&
-        indexArg.key[0][1] === 1,
+    const hasIdentityIndex = [...indexesByName.values()].some((indexArg) =>
+      isIdentityIndexFor(indexArg, identityField),
     );
     if (identityField === identityAsDocumentId) {
       // The primary key is the only uniqueness authority for this field. A
@@ -627,16 +693,55 @@ const normalizeCollectionModelSchema = (
       );
     }
   }
+  if (
+    configArg.toleratedIndexNames !== undefined &&
+    !Array.isArray(configArg.toleratedIndexNames)
+  ) {
+    throw new SmartdataPersistenceError(
+      'invalid_configuration',
+      'Collection model toleratedIndexNames must be an array.',
+    );
+  }
+  const toleratedIndexNames: string[] = [];
+  for (const name of configArg.toleratedIndexNames || []) {
+    if (typeof name !== 'string' || name.trim().length === 0 || name.includes('\0')) {
+      throw new SmartdataPersistenceError(
+        'invalid_configuration',
+        'Every tolerated index name must be a non-empty safe name.',
+      );
+    }
+    if (name === '_id_') {
+      // The primary-key index is verified for every collection; tolerating it
+      // would accept a changed _id index in silence.
+      throw new SmartdataPersistenceError(
+        'invalid_configuration',
+        'Index name "_id_" cannot be tolerated; SmartData always verifies the primary-key index.',
+      );
+    }
+    if (indexesByName.has(name)) {
+      // A declared index is created and verified. Tolerating the same name
+      // would state both contracts for one index.
+      throw new SmartdataPersistenceError(
+        'invalid_configuration',
+        `Index "${name}" cannot be tolerated and declared at the same time.`,
+      );
+    }
+    if (!toleratedIndexNames.includes(name)) {
+      toleratedIndexNames.push(name);
+    }
+  }
   const normalizedCore = {
     ordinaryPersistence: ordinaryPolicyArg,
     collectionName,
     persistedFields: Object.freeze([...persistedFields]),
     numericFields: Object.freeze([...numericFields]),
+    atomicOnlyFields: Object.freeze([...atomicOnlyFields]),
     identityFields: Object.freeze([...identityFields]),
     ...(identityAsDocumentId !== undefined ? { identityAsDocumentId } : {}),
     identityValueTypes: Object.freeze({ ...identityValueTypes }),
     searchableFields: Object.freeze([...searchableFields]),
     indexes: Object.freeze([...indexesByName.values()]),
+    toleratedIndexNames: Object.freeze([...toleratedIndexNames]),
   };
   return Object.freeze({
     ...normalizedCore,
@@ -647,6 +752,7 @@ const normalizeCollectionModelSchema = (
       collectionName,
       persistedFields: [...persistedFields].sort(compareSmartdataTopologyStrings),
       numericFields: [...numericFields].sort(compareSmartdataTopologyStrings),
+      atomicOnlyFields: [...atomicOnlyFields].sort(compareSmartdataTopologyStrings),
       identityFields: [...identityFields].sort(compareSmartdataTopologyStrings),
       ...(identityAsDocumentId !== undefined ? { identityAsDocumentId } : {}),
       identityValueTypes,
@@ -656,6 +762,9 @@ const normalizeCollectionModelSchema = (
       indexes: [...indexesByName.values()].sort((leftArg, rightArg) =>
         compareSmartdataTopologyStrings(leftArg.name, rightArg.name),
       ),
+      toleratedIndexNames: [...toleratedIndexNames].sort(
+        compareSmartdataTopologyStrings,
+      ),
     }),
   });
 };
@@ -682,22 +791,26 @@ const mergeStringArrays = (...arrays: Array<string[] | undefined>): string[] =>
   return merged;
 };
 
-const mergeIdentityValueTypes = (
-  ...typeMapsArg: Array<
-    Record<string, TSmartdataIdentityValueType> | undefined
-  >
-): Record<string, TSmartdataIdentityValueType> => {
-  const merged: Record<string, TSmartdataIdentityValueType> = {};
-  for (const typeMap of typeMapsArg) {
-    for (const [field, valueType] of Object.entries(typeMap || {})) {
+/**
+ * Merges a per-identity-field declaration across an inheritance chain.
+ * Divergence is refused instead of resolved by declaration order, because
+ * either winner would silently change a subclass's stored contract.
+ */
+const mergeIdentityDeclarations = <TDeclaration extends string>(
+  declarationArg: 'valueType' | 'indexName',
+  ...declarationMapsArg: Array<Record<string, TDeclaration> | undefined>
+): Record<string, TDeclaration> => {
+  const merged: Record<string, TDeclaration> = {};
+  for (const declarationMap of declarationMapsArg) {
+    for (const [field, declaration] of Object.entries(declarationMap || {})) {
       const existing = merged[field];
-      if (existing && existing !== valueType) {
+      if (existing && existing !== declaration) {
         throw new SmartdataPersistenceError(
           'invalid_configuration',
-          `Identity field "${field}" has divergent inherited valueType declarations.`,
+          `Identity field "${field}" has divergent inherited ${declarationArg} declarations.`,
         );
       }
-      merged[field] = valueType;
+      merged[field] = declaration;
     }
   }
   return merged;
@@ -795,7 +908,8 @@ const mergeDecoratorMetadata = (
   merged.uniqueIndexes = mergeStringArrays(
     ...metadataArgs.map((metadataArg) => getOwnMetadataValue<string[]>(metadataArg, 'uniqueIndexes')),
   );
-  merged.identityValueTypes = mergeIdentityValueTypes(
+  merged.identityValueTypes = mergeIdentityDeclarations(
+    'valueType',
     ...metadataArgs.map((metadataArg) =>
       getOwnMetadataValue<Record<string, TSmartdataIdentityValueType>>(
         metadataArg,
@@ -803,6 +917,15 @@ const mergeDecoratorMetadata = (
       ),
     ),
   );
+  merged.identityIndexNames = mergeIdentityDeclarations(
+    'indexName',
+    ...metadataArgs.map((metadataArg) =>
+      getOwnMetadataValue<Record<string, string>>(
+        metadataArg,
+        'identityIndexNames',
+      ),
+    ),
+  );
   merged.searchableFields = mergeStringArrays(
     ...metadataArgs.map((metadataArg) => getOwnMetadataValue<string[]>(metadataArg, 'searchableFields')),
   );
@@ -826,7 +949,22 @@ const mergeDecoratorMetadata = (
   for (const metadataArg of metadataArgs) {
     const options = getOwnMetadataValue<Record<string, any>>(metadataArg, '_svDbOptions');
     if (options) {
-      Object.assign(svDbOptions, options);
+      for (const [field, fieldOptions] of Object.entries(options)) {
+        const inherited = svDbOptions[field];
+        // A later declaration replaces the inherited options wholesale, which
+        // would silently drop an inherited atomic-only contract and let a
+        // subclass's save() overwrite an atomically owned value.
+        if (
+          inherited
+          && Boolean(inherited.atomicOnly) !== Boolean(fieldOptions?.atomicOnly)
+        ) {
+          throw new SmartdataPersistenceError(
+            'invalid_configuration',
+            `Persisted field "${field}" has divergent inherited atomicOnly declarations.`,
+          );
+        }
+        svDbOptions[field] = fieldOptions;
+      }
     }
   }
   if (Object.keys(svDbOptions).length > 0) {
@@ -909,10 +1047,44 @@ const definedModelSchemaSymbol = Symbol.for(
   '@push.rocks/smartdata.definedCollectionModelSchema',
 );
 
+/**
+ * Reads a model's merged `@svDb()` field options from decorator metadata.
+ * Unlike the constructor's `_svDbOptions`, this is available before the first
+ * instance exists, so a programmatic declaration can be checked against the
+ * decorators on the same class.
+ */
+const readDeclaredSvDbOptions = (
+  constructorArg: TCollectionModelConstructor<any>,
+): Record<string, SvDbOptions> => {
+  const ownMetadata = Object.prototype.hasOwnProperty.call(
+    constructorArg,
+    (Symbol as any).metadata,
+  )
+    ? ((constructorArg as any)[(Symbol as any).metadata] as
+        | ISmartdataDecoratorMetadata
+        | undefined)
+    : undefined;
+  return (
+    mergeDecoratorMetadata(
+      collectInheritedDecoratorMetadata(constructorArg),
+      ownMetadata,
+    )._svDbOptions as Record<string, SvDbOptions> | undefined
+  ) || {};
+};
+
+/** Declared persisted fields a model marks `@svDb({ atomicOnly: true })`. */
+const readDecoratedAtomicOnlyFields = (
+  svDbOptionsArg: Record<string, SvDbOptions>,
+): string[] =>
+  Object.entries(svDbOptionsArg)
+    .filter(([, optionsArg]) => optionsArg?.atomicOnly === true)
+    .map(([fieldArg]) => fieldArg);
+
 const schemaFromDecoratorMetadata = (
   constructorArg: TCollectionModelConstructor<any>,
   collectionNameArg: string,
   identityAsDocumentIdArg?: string,
+  toleratedIndexNamesArg?: ReadonlyArray<string>,
 ): INormalizedCollectionModelSchema => {
   const ownMetadata = Object.prototype.hasOwnProperty.call(
     constructorArg,
@@ -942,15 +1114,25 @@ const schemaFromDecoratorMetadata = (
   const numericFields = Object.entries(metadata._svDbOptions || {})
     .filter(([, optionsArg]) => optionsArg?.numeric === true)
     .map(([fieldArg]) => fieldArg);
+  const atomicOnlyFields = readDecoratedAtomicOnlyFields(
+    (metadata._svDbOptions as Record<string, SvDbOptions> | undefined) || {},
+  );
   const indexes: ICollectionModelIndex[] = [];
   for (const uniqueField of metadata.uniqueIndexes || []) {
+    const declaredIndexName = metadata.identityIndexNames?.[uniqueField];
     if (uniqueField === identityAsDocumentIdArg) {
       // The document _id enforces this identity; a derived unique index would
       // duplicate the primary key and require an index build on live data.
+      if (declaredIndexName !== undefined) {
+        throw new SmartdataPersistenceError(
+          'invalid_configuration',
+          `Identity field "${uniqueField}" owns the document _id and must not name a unique index.`,
+        );
+      }
       continue;
     }
     indexes.push({
-      name: `${uniqueField}_1`,
+      name: declaredIndexName ?? `${uniqueField}_1`,
       key: { [uniqueField]: 1 },
       options: { unique: true },
     });
@@ -987,12 +1169,16 @@ const schemaFromDecoratorMetadata = (
       collectionName: collectionNameArg,
       persistedFields,
       numericFields,
+      atomicOnlyFields,
       identityFields: metadata.uniqueIndexes || [],
       ...(identityAsDocumentIdArg !== undefined
         ? { identityAsDocumentId: identityAsDocumentIdArg }
         : {}),
       searchableFields: metadata.searchableFields || [],
       indexes,
+      ...(toleratedIndexNamesArg !== undefined
+        ? { toleratedIndexNames: toleratedIndexNamesArg }
+        : {}),
     },
     true,
     metadata.identityValueTypes,
@@ -1117,6 +1303,30 @@ export function defineCollectionModel<
   if (identityAsDocumentId !== undefined) {
     assertIdentityDocumentIdIsOrdinary(modelArg, identityAsDocumentId);
   }
+  // Where a field states `atomicOnly` explicitly through @svDb(), the
+  // programmatic declaration must say the same, so neither reader of the model
+  // can be misled about which fields instance save() writes. A plain @svDb()
+  // states nothing about it and leaves the decision to this configuration.
+  const declaredSvDbOptions = readDeclaredSvDbOptions(modelArg);
+  const configuredAtomicOnly = new Set<string>([
+    ...(inheritedSchema?.atomicOnlyFields || []),
+    ...(configArg.atomicOnlyFields || []),
+  ]);
+  for (const [field, fieldOptions] of Object.entries(declaredSvDbOptions)) {
+    if (
+      !fieldOptions
+      || !Object.prototype.hasOwnProperty.call(fieldOptions, 'atomicOnly')
+      || fieldOptions.atomicOnly === configuredAtomicOnly.has(field)
+    ) {
+      continue;
+    }
+    throw new SmartdataPersistenceError(
+      'invalid_configuration',
+      fieldOptions.atomicOnly
+        ? `Persisted field "${field}" is declared atomicOnly by @svDb() but missing from atomicOnlyFields.`
+        : `Atomic-only field "${field}" is declared by @svDb({ atomicOnly: false }).`,
+    );
+  }
   const normalizedSchema = normalizeCollectionModelSchema({
     ...configArg,
     persistedFields: [
@@ -1127,6 +1337,14 @@ export function defineCollectionModel<
       ...(inheritedSchema?.numericFields || []),
       ...(configArg.numericFields || []),
     ] as Array<TSmartdataNumericDocumentPath<TModel>>,
+    atomicOnlyFields: [
+      ...(inheritedSchema?.atomicOnlyFields || []),
+      ...(configArg.atomicOnlyFields || []),
+    ] as Array<keyof TModel & string>,
+    toleratedIndexNames: [
+      ...(inheritedSchema?.toleratedIndexNames || []),
+      ...(configArg.toleratedIndexNames || []),
+    ],
     identityFields: [
       ...(inheritedSchema?.identityFields || []),
       ...(configArg.identityFields || []),
@@ -1382,6 +1600,7 @@ export function Collection(
           constructor as TCollectionModelConstructor<any>,
           collectionName,
           identityAsDocumentId,
+          optionsArg?.toleratedIndexNames,
         );
       },
     ) as any;
@@ -1455,6 +1674,8 @@ export function managed<TManager extends IManager>(
         return schemaFromDecoratorMetadata(
           constructor as TCollectionModelConstructor<any>,
           collectionName,
+          undefined,
+          bindingOptions?.toleratedIndexNames,
         );
       },
     );
@@ -1479,6 +1700,79 @@ export function managed<TManager extends IManager>(
  */
 export const Manager = managed;
 
+/**
+ * The index properties MongoDB weighs besides the key when it decides whether
+ * two indexes collide. An existing index over the declared key that differs in
+ * any of them is not interchangeable with the declaration, so adopting its name
+ * would only collide again.
+ */
+const indexEquivalenceSignature = (indexArg: {
+  readonly unique?: unknown;
+  readonly sparse?: unknown;
+  readonly expireAfterSeconds?: unknown;
+  readonly partialFilterExpression?: unknown;
+}): string =>
+  stableValue({
+    unique: indexArg.unique === true,
+    sparse: indexArg.sparse === true,
+    expireAfterSeconds: indexArg.expireAfterSeconds ?? null,
+    partialFilterExpression: indexArg.partialFilterExpression ?? null,
+  });
+
+/**
+ * MongoDB reports an index collision without naming the index already in the
+ * namespace, yet the remedy depends on it: adopt that name in the declaration
+ * or drop the index. Only the collision path pays for the extra catalog read.
+ */
+const describeIndexCollision = async (
+  targetCollectionArg: plugins.mongodb.Collection,
+  collectionNameArg: string,
+  expectedArg: INormalizedCollectionModelSchema['indexes'][number],
+  errorArg: unknown,
+): Promise<unknown> => {
+  if (!isMongoIndexConflictError(errorArg)) {
+    return errorArg;
+  }
+  let actualIndexes: plugins.mongodb.Document[];
+  try {
+    actualIndexes = await targetCollectionArg.listIndexes().toArray();
+  } catch {
+    // Without the catalog the collision cannot be attributed, and the driver's
+    // own error stays the best evidence the caller can act on.
+    return errorArg;
+  }
+  const equivalentIndex = actualIndexes.find(
+    (actualArg) =>
+      actualArg.name !== expectedArg.name &&
+      stableValue(Object.entries(actualArg.key || {})) ===
+        stableValue(expectedArg.key) &&
+      indexEquivalenceSignature(actualArg) ===
+        indexEquivalenceSignature(expectedArg.options),
+  );
+  if (equivalentIndex) {
+    return new SmartdataPersistenceError(
+      'invalid_configuration',
+      `Collection "${collectionNameArg}" already carries the equivalent index ` +
+        `"${equivalentIndex.name}", so declared index "${expectedArg.name}" ` +
+        'cannot be created. Declare the existing name — an identity declares ' +
+        'it with @unI({ indexName }) — or drop the existing index.',
+      { cause: errorArg },
+    );
+  }
+  if (actualIndexes.some((actualArg) => actualArg.name === expectedArg.name)) {
+    return new SmartdataPersistenceError(
+      'invalid_configuration',
+      `Collection "${collectionNameArg}" already carries an index named ` +
+        `"${expectedArg.name}" with a different key or options.`,
+      { cause: errorArg },
+    );
+  }
+  // An index over the same key that is not interchangeable with the
+  // declaration cannot be adopted by name, and MongoDB's own error already
+  // reports the options that differ.
+  return errorArg;
+};
+
 export class SmartdataCollection<T> {
   /**
    * the collection that is used
@@ -1517,8 +1811,7 @@ export class SmartdataCollection<T> {
       {
         ordinaryWrite: ordinaryWriteArg,
         prepared: this.isInitializedForCurrentDatabase(),
-        preparationMessage:
-          `Initialize collection "${this.collectionName}" before using an owned SmartData session.`,
+        collectionName: this.collectionName,
       },
       operationArg,
     );
@@ -1716,13 +2009,22 @@ export class SmartdataCollection<T> {
       return;
     }
     for (const index of modelSchema.indexes) {
-      await targetCollection.createIndex(
-        Object.fromEntries(index.key) as plugins.mongodb.IndexSpecification,
-        {
-          ...index.options,
-          name: index.name,
-        },
-      );
+      try {
+        await targetCollection.createIndex(
+          Object.fromEntries(index.key) as plugins.mongodb.IndexSpecification,
+          {
+            ...index.options,
+            name: index.name,
+          },
+        );
+      } catch (errorArg) {
+        throw await describeIndexCollision(
+          targetCollection,
+          this.collectionName,
+          index,
+          errorArg,
+        );
+      }
     }
     const actualIndexes = await targetCollection.listIndexes().toArray();
     for (const expected of modelSchema.indexes) {
@@ -1849,7 +2151,9 @@ export class SmartdataCollection<T> {
         try {
           await this.mongoDbCollection.createIndex({ [key]: 1 }, {
             unique: true,
-            name: `${key}_1`,
+            // A bound model may back its identity with a differently named
+            // index; creating `<field>_1` would duplicate that key.
+            name: getIdentityIndexName(this.modelSchema, key) ?? `${key}_1`,
           });
           this.uniqueIndexes.push(key);
         } catch (err: any) {
@@ -1970,14 +2274,30 @@ export class SmartdataCollection<T> {
     );
   }
 
+  /**
+   * An owned session stays leased until the returned cursor is closed, because
+   * the cursor outlives this call and the driver forbids a parallel operation
+   * on the same session.
+   */
   public async getCursor(
     filterObjectArg: any,
     dbDocArg: typeof SmartDataDbDoc,
-    opts?: { session?: plugins.mongodb.ClientSession }
+    opts?: { session?: TSmartdataOrdinarySession }
   ): Promise<SmartdataDbCursor<any>> {
-    await this.init();
-    const cursor = this.mongoDbCollection.find(filterObjectArg, { session: opts?.session });
-    return new SmartdataDbCursor(cursor, dbDocArg);
+    const lease = leaseOrdinarySmartdataSession(opts?.session, this.smartdataDb, {
+      prepared: this.isInitializedForCurrentDatabase(),
+      collectionName: this.collectionName,
+    });
+    try {
+      await this.init();
+      const cursor = this.mongoDbCollection.find(filterObjectArg, {
+        session: lease.rawSession,
+      });
+      return new SmartdataDbCursor(cursor, dbDocArg, lease.release);
+    } catch (cursorCreationError) {
+      lease.release();
+      throw cursorCreationError;
+    }
   }
 
   /**
@@ -2333,17 +2653,34 @@ export class SmartdataCollection<T> {
         const identifiableObject = await dbDocArg.createIdentifiableObject();
         this.assertConstrainingIdentifiableObject(identifiableObject, 'update');
         const saveableObject = await dbDocArg.createSavableObject() as any;
+        // Atomic-only fields belong to concurrent atomic writers, so this
+        // instance's value never overwrites a stored one. It still seeds them
+        // when this upsert inserts: a document created here must be as
+        // complete as one created by insert(), or a later guard on a field
+        // that was never stored would fail closed forever. $set and
+        // $setOnInsert stay disjoint by construction, so MongoDB accepts both.
+        const atomicOnlyFields = new Set(this.modelSchema?.atomicOnlyFields || []);
         const updateableObject: any = {};
+        const insertOnlyObject: any = {};
         for (const key of Object.keys(saveableObject)) {
           if (identifiableObject[key]) {
             continue;
           }
+          if (atomicOnlyFields.has(key)) {
+            insertOnlyObject[key] = saveableObject[key];
+            continue;
+          }
           updateableObject[key] = saveableObject[key];
         }
         try {
           return await this.mongoDbCollection.updateOne(
             identifiableObject,
-            { $set: updateableObject },
+            {
+              $set: updateableObject,
+              ...(Object.keys(insertOnlyObject).length > 0
+                ? { $setOnInsert: insertOnlyObject }
+                : {}),
+            },
             { upsert: true, session: rawSessionArg },
           );
         } catch (errorArg) {