@lossless.org/client 1.0.0 → 1.2.0

package/ts/nosqldb/classes.collection.ts

@@ -6,7 +6,8 @@ import {
   type ISmartdataCollectionPreparationOptions,
 } from './classes.collectionpreparation.js';
 import {
-  getOrdinaryPersistencePolicy, validateOrdinaryStoredDocument,
+  getOrdinaryPersistencePolicy, hasExactPersistencePolicy,
+  validateOrdinaryStoredDocument,
   type IOrdinaryPersistencePolicy,
 } from './classes.ordinarypersistence.js';
 import { SmartdataDb } from './classes.db.js';
@@ -22,6 +23,7 @@ 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';
@@ -33,6 +35,8 @@ import {
   collectionModelSchemaResolverSymbol,
   collectionTopologyDbInspectionSymbol,
   getExpectedCollectionTopologyForSchema,
+  getIdentityIndexName,
+  isIdentityIndexFor,
   compareSmartdataTopologyStrings,
 } from './classes.collectiontopology.js';
 
@@ -57,6 +61,14 @@ export interface ICollectionBindingOptions {
    * its legacy collection without changing stored data.
    */
   collectionName?: string;
+  /**
+   * Stores one declared `@unI()` string identity as the document `_id`, making
+   * the primary key itself the uniqueness authority. The field keeps its own
+   * stored value and receives no separate unique index. Irreversible for an
+   * existing collection: every stored document must already satisfy
+   * `_id === document[field]`.
+   */
+  identityAsDocumentId?: string;
 }
 
 export type TCollectionModelIndexDirection = 1 | -1 | 'text';
@@ -106,6 +118,13 @@ export interface ICollectionModelConfig<TModel extends object = any> {
    * ascending unique index in `indexes`.
    */
   identityFields?: ReadonlyArray<TStringFieldKey<TModel>>;
+  /**
+   * Stores one declared string identity as the document `_id`. The primary key
+   * becomes the uniqueness authority, so the field must not declare its own
+   * unique index. Irreversible for an existing collection: every stored
+   * document must already satisfy `_id === document[field]`.
+   */
+  identityAsDocumentId?: TStringFieldKey<TModel>;
   /**
    * Persisted fields used by SmartData's search helpers.
    */
@@ -122,6 +141,8 @@ export interface INormalizedCollectionModelSchema {
   readonly persistedFields: readonly string[];
   readonly numericFields: readonly string[];
   readonly identityFields: readonly string[];
+  /** Declared identity field stored as the document `_id`, if any. */
+  readonly identityAsDocumentId?: string;
   readonly identityValueTypes: Readonly<
     Record<string, TSmartdataIdentityValueType>
   >;
@@ -162,6 +183,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[];
@@ -323,6 +345,7 @@ const normalizeCollectionModelSchema = (
     'persistedFields',
     'numericFields',
     'identityFields',
+    'identityAsDocumentId',
     'searchableFields',
     'indexes',
   ]);
@@ -395,6 +418,24 @@ const normalizeCollectionModelSchema = (
       identityFields.push(field);
     }
   }
+  const identityAsDocumentId = configArg.identityAsDocumentId;
+  if (identityAsDocumentId !== undefined) {
+    if (
+      typeof identityAsDocumentId !== 'string' ||
+      !identityFields.includes(identityAsDocumentId)
+    ) {
+      throw new SmartdataPersistenceError(
+        'invalid_configuration',
+        'Collection model identityAsDocumentId must name a declared identity field.',
+      );
+    }
+    if (ordinaryPolicyArg?.idType === 'string') {
+      throw new SmartdataPersistenceError(
+        'invalid_configuration',
+        `Identity field "${identityAsDocumentId}" cannot own the document _id together with a string ordinary persistence _id.`,
+      );
+    }
+  }
   const identityValueTypes: Record<string, TSmartdataIdentityValueType> = {};
   for (const field of Object.keys(identityValueTypesArg || {})) {
     if (!identityFields.includes(field)) {
@@ -557,13 +598,28 @@ 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
+      // second unique index would have to be built on a live collection and
+      // could disagree with _id, so the declaration is refused rather than
+      // silently ignored.
+      if (hasIdentityIndex) {
+        throw new SmartdataPersistenceError(
+          'invalid_configuration',
+          `Identity field "${identityField}" owns the document _id and must not declare its own unique index.`,
+        );
+      }
+      if (identityValueTypes[identityField] !== 'string') {
+        throw new SmartdataPersistenceError(
+          'invalid_configuration',
+          `Identity field "${identityField}" must be a string identity to own the document _id.`,
+        );
+      }
+      continue;
+    }
     if (!hasIdentityIndex) {
       throw new SmartdataPersistenceError(
         'invalid_configuration',
@@ -577,6 +633,7 @@ const normalizeCollectionModelSchema = (
     persistedFields: Object.freeze([...persistedFields]),
     numericFields: Object.freeze([...numericFields]),
     identityFields: Object.freeze([...identityFields]),
+    ...(identityAsDocumentId !== undefined ? { identityAsDocumentId } : {}),
     identityValueTypes: Object.freeze({ ...identityValueTypes }),
     searchableFields: Object.freeze([...searchableFields]),
     indexes: Object.freeze([...indexesByName.values()]),
@@ -591,6 +648,7 @@ const normalizeCollectionModelSchema = (
       persistedFields: [...persistedFields].sort(compareSmartdataTopologyStrings),
       numericFields: [...numericFields].sort(compareSmartdataTopologyStrings),
       identityFields: [...identityFields].sort(compareSmartdataTopologyStrings),
+      ...(identityAsDocumentId !== undefined ? { identityAsDocumentId } : {}),
       identityValueTypes,
       searchableFields: [...searchableFields].sort(
         compareSmartdataTopologyStrings,
@@ -624,22 +682,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;
@@ -737,7 +799,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,
@@ -745,6 +808,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')),
   );
@@ -854,6 +926,7 @@ const definedModelSchemaSymbol = Symbol.for(
 const schemaFromDecoratorMetadata = (
   constructorArg: TCollectionModelConstructor<any>,
   collectionNameArg: string,
+  identityAsDocumentIdArg?: string,
 ): INormalizedCollectionModelSchema => {
   const ownMetadata = Object.prototype.hasOwnProperty.call(
     constructorArg,
@@ -885,8 +958,20 @@ const schemaFromDecoratorMetadata = (
     .map(([fieldArg]) => fieldArg);
   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 },
     });
@@ -924,6 +1009,9 @@ const schemaFromDecoratorMetadata = (
       persistedFields,
       numericFields,
       identityFields: metadata.uniqueIndexes || [],
+      ...(identityAsDocumentIdArg !== undefined
+        ? { identityAsDocumentId: identityAsDocumentIdArg }
+        : {}),
       searchableFields: metadata.searchableFields || [],
       indexes,
     },
@@ -933,6 +1021,35 @@ const schemaFromDecoratorMetadata = (
   );
 };
 
+/**
+ * Exact persistence owns the stored `_id` as a MongoDB ObjectId, so a model
+ * cannot also hand the primary key to a declared identity field.
+ */
+const assertIdentityDocumentIdIsOrdinary = (
+  modelArg: TCollectionModelConstructor<any>,
+  identityAsDocumentIdArg: string,
+): void => {
+  if (hasExactPersistencePolicy(modelArg)) {
+    throw new SmartdataPersistenceError(
+      'invalid_configuration',
+      `Identity field "${identityAsDocumentIdArg}" cannot own the document _id for an exact-persistence model.`,
+    );
+  }
+};
+
+/**
+ * Returns the declared identity field a model stores as its document `_id`.
+ * Reading the bound schema resolver never resolves a database.
+ */
+export const getIdentityDocumentIdField = (modelArg: any): string | undefined => {
+  const resolver = modelArg?.[collectionModelSchemaResolverSymbol] as
+    | (() => INormalizedCollectionModelSchema)
+    | undefined;
+  return typeof resolver === 'function'
+    ? resolver().identityAsDocumentId
+    : undefined;
+};
+
 const installCollectionBinding = <
   TModel extends SmartDataDbDoc<any, any>,
 >(
@@ -1016,6 +1133,11 @@ export function defineCollectionModel<
       }
     | undefined;
   const inheritedSchema = inheritedConstructor?.[definedModelSchemaSymbol];
+  const identityAsDocumentId =
+    configArg.identityAsDocumentId ?? inheritedSchema?.identityAsDocumentId;
+  if (identityAsDocumentId !== undefined) {
+    assertIdentityDocumentIdIsOrdinary(modelArg, identityAsDocumentId);
+  }
   const normalizedSchema = normalizeCollectionModelSchema({
     ...configArg,
     persistedFields: [
@@ -1030,6 +1152,9 @@ export function defineCollectionModel<
       ...(inheritedSchema?.identityFields || []),
       ...(configArg.identityFields || []),
     ] as Array<keyof TModel & string>,
+    ...(identityAsDocumentId !== undefined
+      ? { identityAsDocumentId: identityAsDocumentId as TStringFieldKey<TModel> }
+      : {}),
     searchableFields: [
       ...(inheritedSchema?.searchableFields || []),
       ...(configArg.searchableFields || []),
@@ -1254,13 +1379,30 @@ export function Collection(
     const collectionName = normalizeCollectionName(
       optionsArg?.collectionName ?? constructor.name,
     );
+    const identityAsDocumentId = optionsArg?.identityAsDocumentId;
+    if (
+      identityAsDocumentId !== undefined
+      && (typeof identityAsDocumentId !== 'string' || identityAsDocumentId.length === 0)
+    ) {
+      throw new SmartdataPersistenceError(
+        'invalid_configuration',
+        'Collection identityAsDocumentId must name a declared @unI() identity field.',
+      );
+    }
     return installCollectionBinding(
       constructor as TCollectionModelConstructor<any>,
       () => (dbArg instanceof SmartdataDb ? dbArg : dbArg()),
       () => {
+        if (identityAsDocumentId !== undefined) {
+          assertIdentityDocumentIdIsOrdinary(
+            constructor as TCollectionModelConstructor<any>,
+            identityAsDocumentId,
+          );
+        }
         return schemaFromDecoratorMetadata(
           constructor as TCollectionModelConstructor<any>,
           collectionName,
+          identityAsDocumentId,
         );
       },
     ) as any;
@@ -1358,6 +1500,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
@@ -1595,13 +1810,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) {
@@ -1719,11 +1943,18 @@ export class SmartdataCollection<T> {
    */
   public async markUniqueIndexes(keyArrayArg: string[] = []) {
     for (const key of keyArrayArg) {
+      if (key === this.modelSchema?.identityAsDocumentId) {
+        // The primary key already enforces this identity; building a second
+        // unique index on a live collection is exactly what the option avoids.
+        continue;
+      }
       if (!this.uniqueIndexes.includes(key)) {
         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) {
@@ -1959,6 +2190,7 @@ export class SmartdataCollection<T> {
    * create an object in the database
    */
   private prepareOrdinaryInsert(documentArg: any): any {
+    documentArg = this.applyIdentityDocumentId(documentArg);
     const policy = this.modelSchema?.ordinaryPersistence;
     if (!policy) return documentArg;
     if (policy.idType === 'objectId' && !Object.prototype.hasOwnProperty.call(documentArg, '_id')) {
@@ -1967,11 +2199,46 @@ export class SmartdataCollection<T> {
     return validateOrdinaryStoredDocument(documentArg, policy, this.modelSchema!.persistedFields);
   }
 
+  /**
+   * Keys a stored document by its declared identity when the model opted into
+   * `identityAsDocumentId`. The identity keeps its own stored field, but reads
+   * address `_id`, so a document written before the option was declared is
+   * reachable only if its `_id` already equals that identity.
+   */
+  private applyIdentityDocumentId(documentArg: any): any {
+    const identityField = this.modelSchema?.identityAsDocumentId;
+    if (!identityField) return documentArg;
+    const identityValue = documentArg?.[identityField];
+    if (typeof identityValue !== 'string' || identityValue.trim().length === 0) {
+      throw new SmartdataPersistenceError(
+        'invalid_argument',
+        `Identity field "${identityField}" must contain a non-empty string identity value to key the document.`,
+      );
+    }
+    if (
+      Object.prototype.hasOwnProperty.call(documentArg, '_id')
+      && documentArg._id !== identityValue
+    ) {
+      throw new SmartdataPersistenceError(
+        'invalid_argument',
+        `Identity field "${identityField}" owns the document _id and cannot be stored with a divergent _id.`,
+      );
+    }
+    return { ...documentArg, _id: identityValue };
+  }
+
+  /** True when stored documents need SmartData-owned preparation before a write. */
+  private get preparesStoredDocuments(): boolean {
+    return Boolean(
+      this.modelSchema?.ordinaryPersistence || this.modelSchema?.identityAsDocumentId,
+    );
+  }
+
   public async insert(
     dbDocArg: T & SmartDataDbDoc<T, unknown>,
     opts?: { session?: TSmartdataOrdinarySession }
   ): Promise<any> {
-    const preparedObject = this.modelSchema?.ordinaryPersistence
+    const preparedObject = this.preparesStoredDocuments
       ? this.prepareOrdinaryInsert(await dbDocArg.createSavableObject()) : undefined;
     return this.runWithOrdinarySession(
       opts?.session,
@@ -2049,7 +2316,7 @@ export class SmartdataCollection<T> {
         `insertMany requires a non-empty document batch for collection "${this.collectionName}".`,
       );
     }
-    const preparedObjects: any[] | undefined = this.modelSchema?.ordinaryPersistence ? [] : undefined;
+    const preparedObjects: any[] | undefined = this.preparesStoredDocuments ? [] : undefined;
     if (preparedObjects) {
       for (const dbDocArg of dbDocsArg) {
         preparedObjects.push(this.prepareOrdinaryInsert(await dbDocArg.createSavableObject()));
@@ -2118,14 +2385,23 @@ export class SmartdataCollection<T> {
       const first = documentsArg[0];
       await this.markUniqueIndexes(first.uniqueIndexes);
       await this.createRegularIndexes(first.regularIndexes || []);
+      // A document keyed by its identity is addressed through _id, and the
+      // seeded body must not repeat the immutable primary key: MongoDB derives
+      // it from the filter's equality condition on the insert branch.
+      const documentIdIdentity = this.modelSchema?.identityAsDocumentId === identityFieldArg;
       try {
-        const result = await this.mongoDbCollection.bulkWrite(prepared.map((document) => ({
-          updateOne: {
-            filter: { [identityFieldArg]: document[identityFieldArg] },
-            update: { $setOnInsert: document },
-            upsert: true,
-          },
-        })), { ordered: false, session: rawSessionArg, timeoutMS: optsArg.timeoutMS });
+        const result = await this.mongoDbCollection.bulkWrite(prepared.map((document) => {
+          const { _id: storedId, ...body } = document as Record<string, unknown>;
+          return {
+            updateOne: {
+              filter: documentIdIdentity
+                ? { _id: storedId as plugins.mongodb.Condition<plugins.mongodb.ObjectId> }
+                : { [identityFieldArg]: document[identityFieldArg] },
+              update: { $setOnInsert: documentIdIdentity ? body : document },
+              upsert: true,
+            },
+          };
+        }), { ordered: false, session: rawSessionArg, timeoutMS: optsArg.timeoutMS });
         if (result.upsertedCount + result.matchedCount !== prepared.length) {
           throw new SmartdataPersistenceError('unsupported_operation',
             'insertManyIfAbsent requires an acknowledged result for every identity.');

package/ts/nosqldb/classes.collectiontopology.ts

@@ -298,6 +298,31 @@ export const getExpectedCollectionTopologyForSchema = (
   });
 };
 
+/**
+ * @internal A single-field ascending unique index is what makes a declared
+ * identity globally constraining, whatever the index is called.
+ */
+export const isIdentityIndexFor = (
+  indexArg: INormalizedCollectionModelSchema['indexes'][number],
+  fieldArg: string,
+): boolean =>
+  indexArg.options.unique === true &&
+  indexArg.key.length === 1 &&
+  indexArg.key[0][0] === fieldArg &&
+  indexArg.key[0][1] === 1;
+
+/**
+ * @internal Name of the unique index that backs an identity field in a bound
+ * schema. Index-creation fallbacks resolve it here so that a model naming its
+ * own backing index never gets a second unique index over the same key.
+ */
+export const getIdentityIndexName = (
+  schemaArg: INormalizedCollectionModelSchema | undefined,
+  fieldArg: string,
+): string | undefined =>
+  schemaArg?.indexes.find((indexArg) => isIdentityIndexFor(indexArg, fieldArg))
+    ?.name;
+
 const normalizeActualIndex = (
   rawIndexArg: unknown,
 ): IActualIndexNormalization => {