@lossless.org/client 0.1.0

package/ts/nosqldb/classes.collection.ts

@@ -0,0 +1,2399 @@
+import * as plugins from './plugins.js';
+import { LosslessClientError } from '../core/classes.error.js';
+import { runCursorOperation } from './classes.cursoroperation.js';
+import {
+  CollectionPreparationBudget, prepareBoundCollection,
+  type ISmartdataCollectionPreparationOptions,
+} from './classes.collectionpreparation.js';
+import {
+  getOrdinaryPersistencePolicy, validateOrdinaryStoredDocument,
+  type IOrdinaryPersistencePolicy,
+} from './classes.ordinarypersistence.js';
+import { SmartdataDb } from './classes.db.js';
+import { SmartdataDbCursor } from './classes.cursor.js';
+import {
+  SmartDataDbDoc,
+  type IIndexOptions,
+  type TSmartdataNumericDocumentPath,
+  type TSmartdataIdentityValueType,
+} from './classes.doc.js';
+import { SmartdataDbWatcher } from './classes.watcher.js';
+import { CollectionFactory } from './classes.collectionfactory.js';
+import { logger } from './logging.js';
+import {
+  SmartdataPersistenceError,
+  normalizeOrdinaryPersistenceError,
+} from './classes.persistence.js';
+import { notifyCollectionReconnect } from './classes.collectionlifecycle.js';
+import {
+  runWithOrdinarySmartdataSession,
+  type TSmartdataOrdinarySession,
+} from './classes.session.js';
+import {
+  collectionModelSchemaResolverSymbol,
+  collectionTopologyDbInspectionSymbol,
+  getExpectedCollectionTopologyForSchema,
+  compareSmartdataTopologyStrings,
+} from './classes.collectiontopology.js';
+
+export interface IFindOptions {
+  limit?: number;
+}
+
+/**
+ *
+ */
+export interface IDocValidationFunc<T> {
+  (doc: T): boolean;
+}
+
+export type TDelayed<TDelayedArg> = () => TDelayedArg;
+
+const collectionFactory = new CollectionFactory();
+
+export interface ICollectionBindingOptions {
+  /**
+   * Explicit persisted collection name. Use this to bind a renamed model to
+   * its legacy collection without changing stored data.
+   */
+  collectionName?: string;
+}
+
+export type TCollectionModelIndexDirection = 1 | -1 | 'text';
+
+export interface ICollectionModelIndexOptions {
+  background?: boolean;
+  unique?: boolean;
+  sparse?: boolean;
+  expireAfterSeconds?: number;
+}
+
+export interface ICollectionModelIndex {
+  name: string;
+  key: Record<string, TCollectionModelIndexDirection>;
+  options?: ICollectionModelIndexOptions;
+}
+
+/** Named index on one or more paths rooted in the model's persisted fields. */
+export interface INamedIndexDefinition extends ICollectionModelIndex {}
+
+export type TStringFieldKey<TModel extends object> = {
+  [TKey in keyof TModel]-?: NonNullable<TModel[TKey]> extends string
+    ? TKey
+    : never;
+}[keyof TModel] &
+  string;
+
+export interface ICollectionModelConfig<TModel extends object = any> {
+  /**
+   * The persisted collection name. Programmatic model binding never derives
+   * this value from a constructor name.
+   */
+  collectionName: string;
+  /**
+   * Top-level model fields that SmartData may persist.
+   */
+  persistedFields: ReadonlyArray<keyof TModel & string>;
+  /**
+   * Persisted top-level numeric fields that strict atomic expressions may
+   * reference. This explicit runtime declaration complements the TypeScript
+   * numeric-field constraint.
+   */
+  numericFields?: ReadonlyArray<TSmartdataNumericDocumentPath<TModel>>;
+  /**
+   * Persisted string identity fields with @unI()-equivalent selector and
+   * immutability semantics. Each field requires an explicit single-field,
+   * ascending unique index in `indexes`.
+   */
+  identityFields?: ReadonlyArray<TStringFieldKey<TModel>>;
+  /**
+   * Persisted fields used by SmartData's search helpers.
+   */
+  searchableFields?: ReadonlyArray<keyof TModel & string>;
+  /**
+   * Stable named MongoDB indexes. Object property order defines key order.
+   */
+  indexes?: ReadonlyArray<ICollectionModelIndex>;
+}
+
+export interface INormalizedCollectionModelSchema {
+  readonly ordinaryPersistence?: IOrdinaryPersistencePolicy;
+  readonly collectionName: string;
+  readonly persistedFields: readonly string[];
+  readonly numericFields: readonly string[];
+  readonly identityFields: readonly string[];
+  readonly identityValueTypes: Readonly<
+    Record<string, TSmartdataIdentityValueType>
+  >;
+  readonly searchableFields: readonly string[];
+  readonly indexes: ReadonlyArray<{
+    readonly name: string;
+    readonly key: ReadonlyArray<
+      readonly [string, TCollectionModelIndexDirection]
+    >;
+    readonly options: Readonly<IIndexOptions>;
+  }>;
+  readonly fingerprint: string;
+}
+
+export type TCompoundIndexDirection = 1 | -1;
+
+export interface ICompoundIndexDefinition {
+  /** Stable MongoDB index name. */
+  name: string;
+  /** Ordered fields and their ascending/descending directions. */
+  key: Record<string, TCompoundIndexDirection>;
+  /** MongoDB create-index options other than `name`. */
+  options?: Omit<plugins.mongodb.CreateIndexesOptions, 'name'>;
+}
+
+export interface ISmartdataIndexInfo {
+  name: string;
+  fields: Array<{
+    path: string;
+    direction: 1 | -1 | 'text';
+  }>;
+  unique: boolean;
+  sparse: boolean;
+  expireAfterSeconds?: number;
+}
+interface ISmartdataDecoratorMetadata {
+  globalSaveableProperties?: string[];
+  saveableProperties?: string[];
+  uniqueIndexes?: string[];
+  identityValueTypes?: Record<string, TSmartdataIdentityValueType>;
+  regularIndexes?: Array<{field: string, options: IIndexOptions}>;
+  compoundIndexes?: ICompoundIndexDefinition[];
+  namedIndexes?: INamedIndexDefinition[];
+  searchableFields?: string[];
+  _svDbOptions?: Record<string, any>;
+}
+
+const unsafeFieldNames = new Set(['__proto__', 'prototype', 'constructor']);
+const automaticTextIndexName = 'smartdata_text_index';
+
+const requireSafeFieldName = (
+  fieldArg: string,
+  labelArg: string,
+  allowPathArg = false,
+): string => {
+  if (
+    typeof fieldArg !== 'string' ||
+    fieldArg.length === 0 ||
+    fieldArg.includes('\0') ||
+    fieldArg.startsWith('$')
+  ) {
+    throw new SmartdataPersistenceError(
+      'invalid_configuration',
+      `${labelArg} must be a non-empty safe field name.`,
+    );
+  }
+  const segments = fieldArg.split('.');
+  if (
+    (!allowPathArg && segments.length !== 1) ||
+    segments.some(
+      (segmentArg) =>
+        segmentArg.length === 0 ||
+        segmentArg.startsWith('$') ||
+        unsafeFieldNames.has(segmentArg),
+    )
+  ) {
+    throw new SmartdataPersistenceError(
+      'invalid_configuration',
+      `${labelArg} contains an unsafe field name.`,
+    );
+  }
+  return fieldArg;
+};
+
+const normalizeCollectionName = (
+  collectionNameArg: string,
+  labelArg = 'SmartData collectionName',
+): string => {
+  if (
+    typeof collectionNameArg !== 'string' ||
+    collectionNameArg.trim().length === 0 ||
+    collectionNameArg.includes('\0') ||
+    collectionNameArg.startsWith('system.')
+  ) {
+    throw new SmartdataPersistenceError(
+      'invalid_configuration',
+      `${labelArg} must be a non-empty non-system name without null bytes.`,
+    );
+  }
+  return collectionNameArg;
+};
+
+const normalizeIndexOptions = (
+  optionsArg: IIndexOptions | undefined,
+  indexNameArg: string,
+  allowExtendedOptionsArg = false,
+): Readonly<IIndexOptions> => {
+  const options = optionsArg || {};
+  const allowedKeys = new Set([
+    'background',
+    'unique',
+    'sparse',
+    'expireAfterSeconds',
+  ]);
+  if (!allowExtendedOptionsArg) {
+    for (const optionName of Object.keys(options)) {
+      if (allowedKeys.has(optionName)) {
+        continue;
+      }
+      throw new SmartdataPersistenceError(
+        'invalid_configuration',
+        `Index "${indexNameArg}" defines unsupported option "${optionName}".`,
+      );
+    }
+  }
+  for (const booleanOption of ['background', 'unique', 'sparse'] as const) {
+    if (
+      options[booleanOption] !== undefined &&
+      typeof options[booleanOption] !== 'boolean'
+    ) {
+      throw new SmartdataPersistenceError(
+        'invalid_configuration',
+        `Index "${indexNameArg}" option "${booleanOption}" must be boolean.`,
+      );
+    }
+  }
+  if (
+    options.expireAfterSeconds !== undefined &&
+    (!Number.isFinite(options.expireAfterSeconds) ||
+      options.expireAfterSeconds < 0)
+  ) {
+    throw new SmartdataPersistenceError(
+      'invalid_configuration',
+      `Index "${indexNameArg}" expireAfterSeconds must be a finite non-negative number.`,
+    );
+  }
+  return Object.freeze(
+    allowExtendedOptionsArg
+      ? { ...options }
+      : {
+          ...(options.background === true ? { background: true } : {}),
+          ...(options.unique === true ? { unique: true } : {}),
+          ...(options.sparse === true ? { sparse: true } : {}),
+          ...(options.expireAfterSeconds !== undefined
+            ? { expireAfterSeconds: options.expireAfterSeconds }
+            : {}),
+        },
+  );
+};
+
+const stableValue = (valueArg: unknown): string => {
+  if (Array.isArray(valueArg)) {
+    return `[${valueArg.map((entryArg) => stableValue(entryArg)).join(',')}]`;
+  }
+  if (typeof valueArg === 'object' && valueArg !== null) {
+    return `{${Object.keys(valueArg as Record<string, unknown>)
+      .sort(compareSmartdataTopologyStrings)
+      .map(
+        (keyArg) =>
+          `${JSON.stringify(keyArg)}:${stableValue(
+            (valueArg as Record<string, unknown>)[keyArg],
+          )}`,
+      )
+      .join(',')}}`;
+  }
+  return JSON.stringify(valueArg);
+};
+
+const normalizeCollectionModelSchema = (
+  configArg: ICollectionModelConfig<any>,
+  allowExtendedIndexOptionsArg = false,
+  identityValueTypesArg?: Readonly<
+    Record<string, TSmartdataIdentityValueType>
+  >,
+  ordinaryPolicyArg?: IOrdinaryPersistencePolicy,
+): INormalizedCollectionModelSchema => {
+  if (
+    typeof configArg !== 'object' ||
+    configArg === null ||
+    Array.isArray(configArg)
+  ) {
+    throw new SmartdataPersistenceError(
+      'invalid_configuration',
+      'Collection model config must be an object.',
+    );
+  }
+  const allowedConfigKeys = new Set([
+    'collectionName',
+    'persistedFields',
+    'numericFields',
+    'identityFields',
+    'searchableFields',
+    'indexes',
+  ]);
+  for (const key of Object.keys(configArg)) {
+    if (!allowedConfigKeys.has(key)) {
+      throw new SmartdataPersistenceError(
+        'invalid_configuration',
+        `Collection model config defines unsupported key "${key}".`,
+      );
+    }
+  }
+  const collectionName = normalizeCollectionName(configArg.collectionName);
+  if (!Array.isArray(configArg.persistedFields)) {
+    throw new SmartdataPersistenceError(
+      'invalid_configuration',
+      'Collection model persistedFields must be an array.',
+    );
+  }
+  const persistedFields: string[] = [];
+  for (const field of configArg.persistedFields) {
+    requireSafeFieldName(field, 'A persisted field');
+    if (!persistedFields.includes(field)) {
+      persistedFields.push(field);
+    }
+  }
+  if (ordinaryPolicyArg?.idType === 'string' && !persistedFields.includes('_id')) {
+    persistedFields.push('_id');
+  }
+  if (
+    configArg.numericFields !== undefined &&
+    !Array.isArray(configArg.numericFields)
+  ) {
+    throw new SmartdataPersistenceError(
+      'invalid_configuration',
+      'Collection model numericFields must be an array.',
+    );
+  }
+  const numericFields: string[] = [];
+  for (const field of configArg.numericFields || []) {
+    requireSafeFieldName(field, 'A numeric field');
+    if (!persistedFields.includes(field)) {
+      throw new SmartdataPersistenceError(
+        'invalid_configuration',
+        `Numeric field "${field}" is not a declared persisted field.`,
+      );
+    }
+    if (!numericFields.includes(field)) {
+      numericFields.push(field);
+    }
+  }
+  if (
+    configArg.identityFields !== undefined &&
+    !Array.isArray(configArg.identityFields)
+  ) {
+    throw new SmartdataPersistenceError(
+      'invalid_configuration',
+      'Collection model identityFields must be an array.',
+    );
+  }
+  const identityFields: string[] = [];
+  for (const field of configArg.identityFields || []) {
+    requireSafeFieldName(field, 'An identity field');
+    if (!persistedFields.includes(field)) {
+      throw new SmartdataPersistenceError(
+        'invalid_configuration',
+        `Identity field "${field}" is not a declared persisted field.`,
+      );
+    }
+    if (!identityFields.includes(field)) {
+      identityFields.push(field);
+    }
+  }
+  const identityValueTypes: Record<string, TSmartdataIdentityValueType> = {};
+  for (const field of Object.keys(identityValueTypesArg || {})) {
+    if (!identityFields.includes(field)) {
+      throw new SmartdataPersistenceError(
+        'invalid_configuration',
+        `Identity valueType field "${field}" is not a declared identity field.`,
+      );
+    }
+  }
+  for (const field of identityFields) {
+    const valueType = identityValueTypesArg?.[field] ?? 'string';
+    if (valueType !== 'string' && valueType !== 'positiveSafeInteger') {
+      throw new SmartdataPersistenceError(
+        'invalid_configuration',
+        `Identity field "${field}" has an unsupported valueType.`,
+      );
+    }
+    identityValueTypes[field] = valueType;
+    if (valueType === 'positiveSafeInteger' && !numericFields.includes(field)) {
+      numericFields.push(field);
+    }
+  }
+  const searchableFields: string[] = [];
+  if (
+    configArg.searchableFields !== undefined &&
+    !Array.isArray(configArg.searchableFields)
+  ) {
+    throw new SmartdataPersistenceError(
+      'invalid_configuration',
+      'Collection model searchableFields must be an array.',
+    );
+  }
+  for (const field of configArg.searchableFields || []) {
+    requireSafeFieldName(field, 'A searchable field');
+    if (!persistedFields.includes(field)) {
+      throw new SmartdataPersistenceError(
+        'invalid_configuration',
+        `Searchable field "${field}" is not a declared persisted field.`,
+      );
+    }
+    if (!searchableFields.includes(field)) {
+      searchableFields.push(field);
+    }
+  }
+  if (configArg.indexes !== undefined && !Array.isArray(configArg.indexes)) {
+    throw new SmartdataPersistenceError(
+      'invalid_configuration',
+      'Collection model indexes must be an array.',
+    );
+  }
+  const indexesByName = new Map<
+    string,
+    INormalizedCollectionModelSchema['indexes'][number]
+  >();
+  for (const index of configArg.indexes || []) {
+    if (
+      typeof index !== 'object' ||
+      index === null ||
+      Array.isArray(index) ||
+      typeof index.name !== 'string' ||
+      index.name.trim().length === 0 ||
+      index.name.includes('\0')
+    ) {
+      throw new SmartdataPersistenceError(
+        'invalid_configuration',
+        'Every collection model index requires a non-empty safe name.',
+      );
+    }
+    if (index.name === automaticTextIndexName) {
+      throw new SmartdataPersistenceError(
+        'invalid_configuration',
+        `Index name "${automaticTextIndexName}" is reserved for SmartData's automatic text index.`,
+      );
+    }
+    const indexKeys = Object.entries(index.key || {});
+    if (indexKeys.length === 0) {
+      throw new SmartdataPersistenceError(
+        'invalid_configuration',
+        `Index "${index.name}" requires at least one key.`,
+      );
+    }
+    const normalizedKeys = indexKeys.map(([field, direction]) => {
+      requireSafeFieldName(field, `Index "${index.name}" field`, true);
+      const root = field.split('.')[0];
+      if (
+        !persistedFields.includes(root) &&
+        root !== '_createdAt' &&
+        root !== '_updatedAt'
+      ) {
+        throw new SmartdataPersistenceError(
+          'invalid_configuration',
+          `Index "${index.name}" references undeclared field "${field}".`,
+        );
+      }
+      if (direction !== 1 && direction !== -1 && direction !== 'text') {
+        throw new SmartdataPersistenceError(
+          'invalid_configuration',
+          `Index "${index.name}" has an invalid direction for "${field}".`,
+        );
+      }
+      return Object.freeze([field, direction] as const);
+    });
+    const normalizedIndex = Object.freeze({
+      name: index.name,
+      key: Object.freeze(normalizedKeys),
+      options: normalizeIndexOptions(
+        index.options,
+        index.name,
+        allowExtendedIndexOptionsArg,
+      ),
+    });
+    const existing = indexesByName.get(index.name);
+    if (existing && stableValue(existing) !== stableValue(normalizedIndex)) {
+      throw new SmartdataPersistenceError(
+        'invalid_configuration',
+        `Index "${index.name}" has divergent declarations.`,
+      );
+    }
+    indexesByName.set(index.name, existing || normalizedIndex);
+  }
+  const textIndexes = [...indexesByName.values()].filter((indexArg) =>
+    indexArg.key.some(([, directionArg]) => directionArg === 'text'),
+  );
+  if (textIndexes.length > 1) {
+    throw new SmartdataPersistenceError(
+      'invalid_configuration',
+      'A collection model may declare at most one text index.',
+    );
+  }
+  if (textIndexes.length === 1) {
+    const indexedTextFields = textIndexes[0].key
+      .filter(([, directionArg]) => directionArg === 'text')
+      .map(([fieldArg]) => fieldArg)
+      .sort(compareSmartdataTopologyStrings);
+    const normalizedSearchableFields = [...searchableFields].sort(
+      compareSmartdataTopologyStrings,
+    );
+    if (
+      stableValue(indexedTextFields) !==
+      stableValue(normalizedSearchableFields)
+    ) {
+      throw new SmartdataPersistenceError(
+        'invalid_configuration',
+        `Text index "${textIndexes[0].name}" must cover exactly the declared searchable fields.`,
+      );
+    }
+  }
+  if (searchableFields.length > 0 && textIndexes.length === 0) {
+    indexesByName.set(
+      automaticTextIndexName,
+      Object.freeze({
+        name: automaticTextIndexName,
+        key: Object.freeze(
+          searchableFields.map((fieldArg) =>
+            Object.freeze([fieldArg, 'text'] as const),
+          ),
+        ),
+        options: Object.freeze({}),
+      }),
+    );
+  }
+  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,
+    );
+    if (!hasIdentityIndex) {
+      throw new SmartdataPersistenceError(
+        'invalid_configuration',
+        `Identity field "${identityField}" requires an explicit single-field ascending unique index.`,
+      );
+    }
+  }
+  const normalizedCore = {
+    ordinaryPersistence: ordinaryPolicyArg,
+    collectionName,
+    persistedFields: Object.freeze([...persistedFields]),
+    numericFields: Object.freeze([...numericFields]),
+    identityFields: Object.freeze([...identityFields]),
+    identityValueTypes: Object.freeze({ ...identityValueTypes }),
+    searchableFields: Object.freeze([...searchableFields]),
+    indexes: Object.freeze([...indexesByName.values()]),
+  };
+  return Object.freeze({
+    ...normalizedCore,
+    fingerprint: stableValue({
+      ordinaryPersistence: ordinaryPolicyArg ? {
+        idType: ordinaryPolicyArg.idType, timestamps: ordinaryPolicyArg.timestamps,
+      } : undefined,
+      collectionName,
+      persistedFields: [...persistedFields].sort(compareSmartdataTopologyStrings),
+      numericFields: [...numericFields].sort(compareSmartdataTopologyStrings),
+      identityFields: [...identityFields].sort(compareSmartdataTopologyStrings),
+      identityValueTypes,
+      searchableFields: [...searchableFields].sort(
+        compareSmartdataTopologyStrings,
+      ),
+      indexes: [...indexesByName.values()].sort((leftArg, rightArg) =>
+        compareSmartdataTopologyStrings(leftArg.name, rightArg.name),
+      ),
+    }),
+  });
+};
+
+const getOwnMetadataValue = <T>(metadata: any, key: keyof ISmartdataDecoratorMetadata): T | undefined => {
+  if (!metadata || !Object.prototype.hasOwnProperty.call(metadata, key)) {
+    return undefined;
+  }
+  return metadata[key] as T;
+};
+
+const mergeStringArrays = (...arrays: Array<string[] | undefined>): string[] => {
+  const merged: string[] = [];
+  for (const array of arrays) {
+    if (!array) {
+      continue;
+    }
+    for (const item of array) {
+      if (!merged.includes(item)) {
+        merged.push(item);
+      }
+    }
+  }
+  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 || {})) {
+      const existing = merged[field];
+      if (existing && existing !== valueType) {
+        throw new SmartdataPersistenceError(
+          'invalid_configuration',
+          `Identity field "${field}" has divergent inherited valueType declarations.`,
+        );
+      }
+      merged[field] = valueType;
+    }
+  }
+  return merged;
+};
+
+const mergeRegularIndexes = (
+  ...indexArrays: Array<Array<{field: string, options: IIndexOptions}> | undefined>
+): Array<{field: string, options: IIndexOptions}> => {
+  const mergedMap = new Map<string, {field: string, options: IIndexOptions}>();
+  for (const indexArray of indexArrays) {
+    if (!indexArray) {
+      continue;
+    }
+    for (const indexDef of indexArray) {
+      mergedMap.set(indexDef.field, {
+        field: indexDef.field,
+        options: { ...indexDef.options },
+      });
+    }
+  }
+  return [...mergedMap.values()];
+};
+
+const stableIndexValue = (valueArg: unknown): string => {
+  if (Array.isArray(valueArg)) {
+    return `[${valueArg.map((entryArg) => stableIndexValue(entryArg)).join(',')}]`;
+  }
+  if (typeof valueArg === 'object' && valueArg !== null) {
+    return `{${Object.keys(valueArg as Record<string, unknown>)
+      .sort(compareSmartdataTopologyStrings)
+      .map(
+        (keyArg) =>
+          `${JSON.stringify(keyArg)}:${stableIndexValue(
+            (valueArg as Record<string, unknown>)[keyArg],
+          )}`,
+      )
+      .join(',')}}`;
+  }
+  return JSON.stringify(valueArg);
+};
+
+const compoundIndexesEqual = (
+  leftArg: ICollectionModelIndex,
+  rightArg: ICollectionModelIndex,
+): boolean => {
+  const leftKeyEntries = Object.entries(leftArg.key);
+  const rightKeyEntries = Object.entries(rightArg.key);
+  return (
+    stableIndexValue(leftKeyEntries) === stableIndexValue(rightKeyEntries) &&
+    stableIndexValue(leftArg.options || {}) ===
+      stableIndexValue(rightArg.options || {})
+  );
+};
+
+const mergeCompoundIndexes = <TDefinition extends ICollectionModelIndex>(
+  ...indexArrays: Array<TDefinition[] | undefined>
+): TDefinition[] => {
+  const mergedMap = new Map<string, TDefinition>();
+  for (const indexArray of indexArrays) {
+    if (!indexArray) {
+      continue;
+    }
+    for (const indexDefinition of indexArray) {
+      const existing = mergedMap.get(indexDefinition.name);
+      if (existing && !compoundIndexesEqual(existing, indexDefinition)) {
+        throw new SmartdataPersistenceError(
+          'invalid_configuration',
+          `Compound index "${indexDefinition.name}" has divergent inherited declarations.`,
+        );
+      }
+      if (!existing) {
+        mergedMap.set(indexDefinition.name, {
+          ...indexDefinition,
+          name: indexDefinition.name,
+          key: { ...indexDefinition.key },
+          options: { ...(indexDefinition.options || {}) },
+        });
+      }
+    }
+  }
+  return [...mergedMap.values()];
+};
+
+const mergeDecoratorMetadata = (
+  ...metadataArgs: Array<ISmartdataDecoratorMetadata | undefined>
+): ISmartdataDecoratorMetadata => {
+  const merged: ISmartdataDecoratorMetadata = {};
+
+  merged.globalSaveableProperties = mergeStringArrays(
+    ...metadataArgs.map((metadataArg) => getOwnMetadataValue<string[]>(metadataArg, 'globalSaveableProperties')),
+  );
+  merged.saveableProperties = mergeStringArrays(
+    ...metadataArgs.map((metadataArg) => getOwnMetadataValue<string[]>(metadataArg, 'saveableProperties')),
+  );
+  merged.uniqueIndexes = mergeStringArrays(
+    ...metadataArgs.map((metadataArg) => getOwnMetadataValue<string[]>(metadataArg, 'uniqueIndexes')),
+  );
+  merged.identityValueTypes = mergeIdentityValueTypes(
+    ...metadataArgs.map((metadataArg) =>
+      getOwnMetadataValue<Record<string, TSmartdataIdentityValueType>>(
+        metadataArg,
+        'identityValueTypes',
+      ),
+    ),
+  );
+  merged.searchableFields = mergeStringArrays(
+    ...metadataArgs.map((metadataArg) => getOwnMetadataValue<string[]>(metadataArg, 'searchableFields')),
+  );
+  merged.regularIndexes = mergeRegularIndexes(
+    ...metadataArgs.map((metadataArg) => getOwnMetadataValue<Array<{field: string, options: IIndexOptions}>>(metadataArg, 'regularIndexes')),
+  );
+  merged.compoundIndexes = mergeCompoundIndexes(
+    ...metadataArgs.map((metadataArg) =>
+      getOwnMetadataValue<ICompoundIndexDefinition[]>(
+        metadataArg,
+        'compoundIndexes',
+      ),
+    ),
+  );
+  merged.namedIndexes = mergeCompoundIndexes(
+    ...metadataArgs.map((metadataArg) =>
+      getOwnMetadataValue<INamedIndexDefinition[]>(metadataArg, 'namedIndexes')),
+  );
+
+  const svDbOptions: Record<string, any> = {};
+  for (const metadataArg of metadataArgs) {
+    const options = getOwnMetadataValue<Record<string, any>>(metadataArg, '_svDbOptions');
+    if (options) {
+      Object.assign(svDbOptions, options);
+    }
+  }
+  if (Object.keys(svDbOptions).length > 0) {
+    merged._svDbOptions = svDbOptions;
+  }
+
+  return merged;
+};
+
+const collectInheritedDecoratorMetadata = (
+  constructor: { new (...args: any[]): any; prototype: any },
+): ISmartdataDecoratorMetadata => {
+  const metadataChain: ISmartdataDecoratorMetadata[] = [];
+  let proto = Object.getPrototypeOf(constructor.prototype);
+  while (proto && proto !== Object.prototype) {
+    const metadata = proto.constructor?.[(Symbol as any).metadata] as
+      | ISmartdataDecoratorMetadata
+      | undefined;
+    if (metadata) {
+      metadataChain.unshift(metadata);
+    }
+    proto = Object.getPrototypeOf(proto);
+  }
+  return mergeDecoratorMetadata(...metadataChain);
+};
+
+/**
+ * Initialize prototype and constructor properties from TC39 decorator metadata.
+ * Shared by both Collection and managed decorators.
+ */
+function initializeDecoratorMetadata(
+  constructor: { new (...args: any[]): any; prototype: any },
+  metadata: any
+): void {
+  const mergedMetadata = mergeDecoratorMetadata(
+    collectInheritedDecoratorMetadata(constructor),
+    metadata as ISmartdataDecoratorMetadata | undefined,
+  );
+
+  const proto = constructor.prototype;
+  const ctor = constructor as any;
+
+  // Prototype properties (instance-level)
+  if (mergedMetadata.globalSaveableProperties?.length) {
+    proto.globalSaveableProperties = [...mergedMetadata.globalSaveableProperties];
+  }
+  if (mergedMetadata.saveableProperties?.length) {
+    proto.saveableProperties = [...mergedMetadata.saveableProperties];
+  }
+  if (mergedMetadata.uniqueIndexes?.length) {
+    proto.uniqueIndexes = [...mergedMetadata.uniqueIndexes];
+  }
+  if (mergedMetadata.identityValueTypes) {
+    proto.identityValueTypes = { ...mergedMetadata.identityValueTypes };
+  }
+  if (mergedMetadata.regularIndexes?.length) {
+    proto.regularIndexes = [...mergedMetadata.regularIndexes];
+  }
+  if (mergedMetadata.compoundIndexes?.length) {
+    proto.compoundIndexes = [...mergedMetadata.compoundIndexes];
+    ctor.compoundIndexes = [...mergedMetadata.compoundIndexes];
+  }
+
+  // Constructor properties (static-level)
+  if (mergedMetadata.searchableFields?.length) {
+    ctor.searchableFields = [...mergedMetadata.searchableFields];
+  }
+  if (mergedMetadata._svDbOptions) {
+    ctor._svDbOptions = { ...mergedMetadata._svDbOptions };
+  }
+}
+
+type TCollectionModelConstructor<TModel extends SmartDataDbDoc<any, any>> = {
+  new (...args: any[]): TModel;
+  name: string;
+  prototype: TModel;
+};
+
+const definedModelSchemaSymbol = Symbol.for(
+  '@push.rocks/smartdata.definedCollectionModelSchema',
+);
+
+const schemaFromDecoratorMetadata = (
+  constructorArg: TCollectionModelConstructor<any>,
+  collectionNameArg: string,
+): INormalizedCollectionModelSchema => {
+  const ownMetadata = Object.prototype.hasOwnProperty.call(
+    constructorArg,
+    (Symbol as any).metadata,
+  )
+    ? ((constructorArg as any)[(Symbol as any).metadata] as
+        | ISmartdataDecoratorMetadata
+        | undefined)
+    : undefined;
+  const metadata = mergeDecoratorMetadata(
+    collectInheritedDecoratorMetadata(constructorArg),
+    ownMetadata,
+  );
+  const persistedFields = [
+    ...new Set<string>([
+      ...(metadata.saveableProperties || []),
+      ...(metadata.uniqueIndexes || []),
+      ...(metadata.regularIndexes || []).map(
+        (indexArg: { field: string }) => indexArg.field.split('.')[0],
+      ),
+      ...(metadata.compoundIndexes || []).flatMap(
+        (indexArg: ICompoundIndexDefinition) =>
+          Object.keys(indexArg.key).map((fieldArg) => fieldArg.split('.')[0]),
+      ),
+    ]),
+  ];
+  const numericFields = Object.entries(metadata._svDbOptions || {})
+    .filter(([, optionsArg]) => optionsArg?.numeric === true)
+    .map(([fieldArg]) => fieldArg);
+  const indexes: ICollectionModelIndex[] = [];
+  for (const uniqueField of metadata.uniqueIndexes || []) {
+    indexes.push({
+      name: `${uniqueField}_1`,
+      key: { [uniqueField]: 1 },
+      options: { unique: true },
+    });
+  }
+  for (const regularIndex of metadata.regularIndexes || []) {
+    const rawOptions = { ...(regularIndex.options || {}) } as Record<
+      string,
+      unknown
+    >;
+    const explicitName =
+      typeof rawOptions.name === 'string'
+        ? rawOptions.name
+        : `${regularIndex.field}_1`;
+    delete rawOptions.name;
+    indexes.push({
+      name: explicitName,
+      key: { [regularIndex.field]: 1 },
+      options: rawOptions as ICollectionModelIndexOptions,
+    });
+  }
+  for (const compoundIndexDefinition of metadata.compoundIndexes || []) {
+    const validatedDefinition = validateCompoundIndexDefinition(
+      compoundIndexDefinition,
+    );
+    indexes.push({
+      name: validatedDefinition.name,
+      key: { ...validatedDefinition.key },
+      options: { ...(validatedDefinition.options || {}) },
+    });
+  }
+  indexes.push(...(metadata.namedIndexes || []));
+  return normalizeCollectionModelSchema(
+    {
+      collectionName: collectionNameArg,
+      persistedFields,
+      numericFields,
+      identityFields: metadata.uniqueIndexes || [],
+      searchableFields: metadata.searchableFields || [],
+      indexes,
+    },
+    true,
+    metadata.identityValueTypes,
+    getOrdinaryPersistencePolicy(constructorArg),
+  );
+};
+
+const installCollectionBinding = <
+  TModel extends SmartDataDbDoc<any, any>,
+>(
+  constructorArg: TCollectionModelConstructor<TModel>,
+  dbResolverArg: (receiverArg?: unknown) => SmartdataDb,
+  schemaResolverArg: () => INormalizedCollectionModelSchema,
+): TCollectionModelConstructor<TModel> => {
+  const getCollection = (receiverArg?: unknown) => {
+    const db = dbResolverArg(receiverArg);
+    if (!(db instanceof SmartdataDb)) {
+      throw new SmartdataPersistenceError(
+        'invalid_configuration',
+        `Model "${constructorArg.name}" did not resolve a SmartdataDb.`,
+      );
+    }
+    const schema = schemaResolverArg();
+    if (schema.ordinaryPersistence !== getOrdinaryPersistencePolicy(constructorArg)) {
+      throw new SmartdataPersistenceError('invalid_configuration',
+        'Persistence policy must be installed before binding a programmatic model.');
+    }
+    return collectionFactory.getCollection(
+      schema.collectionName,
+      db,
+      schema,
+    );
+  };
+  Object.defineProperty(constructorArg, collectionModelSchemaResolverSymbol, {
+    value: schemaResolverArg,
+    enumerable: false,
+    configurable: true,
+    writable: false,
+  });
+  (constructorArg as any).className = constructorArg.name;
+  Object.defineProperty(constructorArg, 'collection', {
+    get(this: unknown) {
+      return getCollection(this);
+    },
+    enumerable: false,
+    configurable: true,
+  });
+  Object.defineProperty(constructorArg.prototype, 'collection', {
+    get(this: unknown) {
+      return getCollection(this);
+    },
+    enumerable: false,
+    configurable: true,
+  });
+  return constructorArg;
+};
+
+/**
+ * Programmatically declares and binds an ordinary SmartData model.
+ *
+ * Repeating an equivalent declaration is safe. Divergent declarations for
+ * the same constructor, database and collection fail before database work.
+ */
+export function defineCollectionModel<
+  TModel extends SmartDataDbDoc<any, any>,
+>(
+  modelArg: TCollectionModelConstructor<TModel>,
+  dbArg: SmartdataDb | TDelayed<SmartdataDb>,
+  configArg: ICollectionModelConfig<TModel>,
+): TCollectionModelConstructor<TModel> {
+  if (
+    typeof modelArg !== 'function' ||
+    !(modelArg.prototype instanceof SmartDataDbDoc)
+  ) {
+    throw new SmartdataPersistenceError(
+      'invalid_configuration',
+      'defineCollectionModel requires a SmartDataDbDoc constructor.',
+    );
+  }
+  const inheritedPrototype = Object.getPrototypeOf(modelArg.prototype) as
+    | {
+        saveableProperties?: string[];
+      }
+    | undefined;
+  const inheritedConstructor = Object.getPrototypeOf(modelArg) as
+    | {
+        [definedModelSchemaSymbol]?: INormalizedCollectionModelSchema;
+      }
+    | undefined;
+  const inheritedSchema = inheritedConstructor?.[definedModelSchemaSymbol];
+  const normalizedSchema = normalizeCollectionModelSchema({
+    ...configArg,
+    persistedFields: [
+      ...(inheritedPrototype?.saveableProperties || []),
+      ...(configArg.persistedFields || []),
+    ] as Array<keyof TModel & string>,
+    numericFields: [
+      ...(inheritedSchema?.numericFields || []),
+      ...(configArg.numericFields || []),
+    ] as Array<TSmartdataNumericDocumentPath<TModel>>,
+    identityFields: [
+      ...(inheritedSchema?.identityFields || []),
+      ...(configArg.identityFields || []),
+    ] as Array<keyof TModel & string>,
+    searchableFields: [
+      ...(inheritedSchema?.searchableFields || []),
+      ...(configArg.searchableFields || []),
+    ] as Array<keyof TModel & string>,
+    indexes: [
+      ...(inheritedSchema?.indexes || [])
+        .filter((indexArg) => indexArg.name !== automaticTextIndexName)
+        .map((indexArg) => ({
+          name: indexArg.name,
+          key: Object.fromEntries(indexArg.key),
+          options: { ...indexArg.options },
+        })),
+      ...(configArg.indexes || []),
+    ],
+  }, false, undefined, getOrdinaryPersistencePolicy(modelArg));
+  const existingOwnSchema = Object.prototype.hasOwnProperty.call(
+    modelArg,
+    definedModelSchemaSymbol,
+  )
+    ? ((modelArg as any)[
+        definedModelSchemaSymbol
+      ] as INormalizedCollectionModelSchema)
+    : undefined;
+  if (
+    existingOwnSchema &&
+    (existingOwnSchema.fingerprint !== normalizedSchema.fingerprint ||
+      existingOwnSchema.ordinaryPersistence?.assertStoredDocument !==
+        normalizedSchema.ordinaryPersistence?.assertStoredDocument)
+  ) {
+    throw new SmartdataPersistenceError(
+      'invalid_configuration',
+      `Model "${modelArg.name}" already has a divergent collection schema.`,
+    );
+  }
+  const effectiveSchema = existingOwnSchema || normalizedSchema;
+  if (!existingOwnSchema) {
+    Object.defineProperty(modelArg, definedModelSchemaSymbol, {
+      value: effectiveSchema,
+      enumerable: false,
+      configurable: false,
+      writable: false,
+    });
+  }
+  modelArg.prototype.saveableProperties = [
+    ...effectiveSchema.persistedFields,
+  ];
+  modelArg.prototype.uniqueIndexes = [...effectiveSchema.identityFields];
+  modelArg.prototype.identityValueTypes = {
+    ...effectiveSchema.identityValueTypes,
+  };
+  (modelArg as any).searchableFields = [
+    ...effectiveSchema.searchableFields,
+  ];
+  return installCollectionBinding(
+    modelArg,
+    () => (dbArg instanceof SmartdataDb ? dbArg : dbArg()),
+    () => effectiveSchema,
+  );
+}
+
+const validateCompoundIndexDefinition = (
+  definitionArg: ICompoundIndexDefinition,
+): ICompoundIndexDefinition => {
+  if (
+    typeof definitionArg?.name !== 'string' ||
+    definitionArg.name.trim().length === 0
+  ) {
+    throw new SmartdataPersistenceError(
+      'invalid_configuration',
+      'A compound index requires a non-empty name.',
+    );
+  }
+  if (
+    typeof definitionArg.key !== 'object' ||
+    definitionArg.key === null ||
+    Array.isArray(definitionArg.key) ||
+    Object.keys(definitionArg.key).length < 2
+  ) {
+    throw new SmartdataPersistenceError(
+      'invalid_configuration',
+      `Compound index "${definitionArg.name}" requires at least two ordered fields.`,
+    );
+  }
+  for (const [field, direction] of Object.entries(definitionArg.key)) {
+    if (
+      field.trim().length === 0 ||
+      field.startsWith('$') ||
+      field.includes('\0') ||
+      (direction !== 1 && direction !== -1)
+    ) {
+      throw new SmartdataPersistenceError(
+        'invalid_configuration',
+        `Compound index "${definitionArg.name}" has an invalid field or direction.`,
+      );
+    }
+  }
+  const options = { ...(definitionArg.options || {}) } as Record<string, unknown>;
+  if ('name' in options) {
+    throw new SmartdataPersistenceError(
+      'invalid_configuration',
+      `Compound index "${definitionArg.name}" must define its name outside options.`,
+    );
+  }
+  if ('unique' in options && typeof options.unique !== 'boolean') {
+    throw new SmartdataPersistenceError(
+      'invalid_configuration',
+      `Compound index "${definitionArg.name}" has a non-boolean unique option.`,
+    );
+  }
+  if ('sparse' in options && typeof options.sparse !== 'boolean') {
+    throw new SmartdataPersistenceError(
+      'invalid_configuration',
+      `Compound index "${definitionArg.name}" has a non-boolean sparse option.`,
+    );
+  }
+  if (
+    'expireAfterSeconds' in options &&
+    (!Number.isFinite(options.expireAfterSeconds) ||
+      (options.expireAfterSeconds as number) < 0)
+  ) {
+    throw new SmartdataPersistenceError(
+      'invalid_configuration',
+      `Compound index "${definitionArg.name}" has an invalid expireAfterSeconds option.`,
+    );
+  }
+  return {
+    name: definitionArg.name,
+    key: { ...definitionArg.key },
+    options: { ...(definitionArg.options || {}) },
+  };
+};
+
+/**
+ * Declares a stable named compound index owned by a SmartData model.
+ */
+export function compoundIndex(definitionArg: ICompoundIndexDefinition) {
+  const definition = validateCompoundIndexDefinition(definitionArg);
+  return function classDecorator(value: Function, context: ClassDecoratorContext) {
+    if (context.kind !== 'class') {
+      throw new Error('compoundIndex can only decorate classes');
+    }
+    const metadata = context.metadata as ISmartdataDecoratorMetadata;
+    if (
+      !Object.prototype.hasOwnProperty.call(metadata, 'compoundIndexes')
+    ) {
+      metadata.compoundIndexes = [...(metadata.compoundIndexes || [])];
+    }
+    const ownCompoundIndexes = metadata.compoundIndexes!;
+    const existing = ownCompoundIndexes.find(
+      (indexDefinition) => indexDefinition.name === definition.name,
+    );
+    if (existing && !compoundIndexesEqual(existing, definition)) {
+      throw new SmartdataPersistenceError(
+        'invalid_configuration',
+        `Compound index "${definition.name}" has divergent declarations.`,
+      );
+    }
+    if (!existing) {
+      ownCompoundIndexes.push(definition);
+    }
+    initializeDecoratorMetadata(
+      value as { new (...args: any[]): any; prototype: any },
+      context.metadata,
+    );
+    return value as any;
+  };
+}
+
+/** Declares an inherited named index without implicitly declaring persisted fields. */
+export function namedIndex(definitionArg: INamedIndexDefinition) {
+  const requirePlainDataObject = (valueArg: unknown, keysArg?: string[]) => {
+    if (!valueArg || Object.getPrototypeOf(valueArg) !== Object.prototype ||
+      Reflect.ownKeys(valueArg).some((keyArg) => typeof keyArg !== 'string' ||
+        (keysArg && !keysArg.includes(keyArg)) ||
+        !('value' in Object.getOwnPropertyDescriptor(valueArg, keyArg)!))) {
+      throw new SmartdataPersistenceError('invalid_configuration', 'Invalid named index declaration.');
+    }
+  };
+  requirePlainDataObject(definitionArg, ['name', 'key', 'options']);
+  requirePlainDataObject(definitionArg.key);
+  if (definitionArg.options !== undefined) requirePlainDataObject(definitionArg.options);
+  const schema = normalizeCollectionModelSchema({
+    collectionName: 'named_index_declaration',
+    persistedFields: [...new Set(Object.keys(definitionArg.key).map((pathArg) => pathArg.split('.')[0]))],
+    searchableFields: Object.entries(definitionArg.key)
+      .filter(([, directionArg]) => directionArg === 'text').map(([pathArg]) => pathArg),
+    indexes: [definitionArg],
+  });
+  // Share topology constraints too (reserved names, index widths, supported options).
+  getExpectedCollectionTopologyForSchema(schema);
+  const normalized = schema.indexes[0];
+  const definition: INamedIndexDefinition = Object.freeze({
+    name: normalized.name,
+    key: Object.freeze(Object.fromEntries(normalized.key)),
+    options: normalized.options,
+  });
+  return function classDecorator(value: Function, context: ClassDecoratorContext) {
+    if (context.kind !== 'class') {
+      throw new SmartdataPersistenceError('invalid_configuration', 'namedIndex can only decorate classes.');
+    }
+    const metadata = context.metadata as ISmartdataDecoratorMetadata;
+    metadata.namedIndexes = mergeCompoundIndexes(metadata.namedIndexes, [definition]);
+    return value as any;
+  };
+}
+
+/**
+ * This is a decorator that will tell the decorated class what dbTable to use
+ * @param dbArg
+ */
+export function Collection(
+  dbArg: SmartdataDb | TDelayed<SmartdataDb>,
+  optionsArg?: ICollectionBindingOptions,
+) {
+  return function classDecorator(value: Function, context: ClassDecoratorContext) {
+    if (context.kind !== 'class') {
+      throw new Error('Collection can only decorate classes');
+    }
+
+    const constructor = value as { new (...args: any[]): any } & { className?: string };
+    initializeDecoratorMetadata(constructor, context.metadata);
+    const collectionName = normalizeCollectionName(
+      optionsArg?.collectionName ?? constructor.name,
+    );
+    return installCollectionBinding(
+      constructor as TCollectionModelConstructor<any>,
+      () => (dbArg instanceof SmartdataDb ? dbArg : dbArg()),
+      () => {
+        return schemaFromDecoratorMetadata(
+          constructor as TCollectionModelConstructor<any>,
+          collectionName,
+        );
+      },
+    ) as any;
+  };
+}
+
+export interface IManager {
+  db: SmartdataDb;
+}
+
+export const setDefaultManagerForDoc = <T,>(managerArg: IManager, dbDocArg: T): T => {
+  (dbDocArg as any).prototype.defaultManager = managerArg;
+  return dbDocArg;
+};
+
+/**
+ * This is a decorator that will tell the decorated class what dbTable to use
+ * @param dbArg
+ */
+export function managed<TManager extends IManager>(
+  managerOrOptionsArg?:
+    | TManager
+    | TDelayed<TManager>
+    | ICollectionBindingOptions,
+  optionsArg?: ICollectionBindingOptions,
+) {
+  const firstArgumentIsOptions =
+    typeof managerOrOptionsArg === 'object' &&
+    managerOrOptionsArg !== null &&
+    !('db' in managerOrOptionsArg) &&
+    'collectionName' in managerOrOptionsArg &&
+    optionsArg === undefined;
+  const managerArg = firstArgumentIsOptions
+    ? undefined
+    : (managerOrOptionsArg as TManager | TDelayed<TManager> | undefined);
+  const bindingOptions = firstArgumentIsOptions
+    ? (managerOrOptionsArg as ICollectionBindingOptions)
+    : optionsArg;
+  return function classDecorator(value: Function, context: ClassDecoratorContext) {
+    if (context.kind !== 'class') {
+      throw new Error('managed can only decorate classes');
+    }
+
+    const constructor = value as { new (...args: any[]): any } & { className?: string };
+    initializeDecoratorMetadata(constructor, context.metadata);
+
+    // Resolution helpers (capture managerArg via closure)
+    const getManager = (receiverArg?: unknown): TManager => {
+      if (!managerArg) {
+        if (typeof receiverArg === 'function') {
+          return (receiverArg as typeof constructor).prototype.defaultManager;
+        }
+        return (
+          (receiverArg as { defaultManager?: TManager } | undefined)
+            ?.defaultManager ?? constructor.prototype.defaultManager
+        );
+      }
+      if (typeof managerArg !== 'function' && managerArg.db) {
+        return managerArg as TManager;
+      }
+      return (managerArg as TDelayed<TManager>)();
+    };
+
+    const collectionName = normalizeCollectionName(
+      bindingOptions?.collectionName ?? constructor.name,
+    );
+    installCollectionBinding(
+      constructor as TCollectionModelConstructor<any>,
+      (receiverArg) => getManager(receiverArg).db,
+      () => {
+        return schemaFromDecoratorMetadata(
+          constructor as TCollectionModelConstructor<any>,
+          collectionName,
+        );
+      },
+    );
+    Object.defineProperty(constructor, 'manager', {
+      get(this: unknown) { return getManager(this); },
+      enumerable: false,
+      configurable: true
+    });
+
+    Object.defineProperty(constructor.prototype, 'manager', {
+      get(this: unknown) { return getManager(this); },
+      enumerable: false,
+      configurable: true
+    });
+
+    return constructor as any;
+  };
+}
+
+/**
+ * @dpecrecated use @managed instead
+ */
+export const Manager = managed;
+
+export class SmartdataCollection<T> {
+  /**
+   * the collection that is used
+   */
+  public mongoDbCollection!: plugins.mongodb.Collection;
+  public objectValidation: IDocValidationFunc<T> | null = null;
+  public collectionName: string;
+  public smartdataDb: SmartdataDb;
+  public uniqueIndexes: string[] = [];
+  public regularIndexes: Array<{field: string, options: IIndexOptions}> = [];
+  public compoundIndexes: ICompoundIndexDefinition[] = [];
+  private modelSchema?: INormalizedCollectionModelSchema;
+  private initializationPromise?: Promise<void>;
+  private initializationGeneration = 0;
+  private initialized = false;
+
+  constructor(classNameArg: string, smartDataDbArg: SmartdataDb) {
+    // tell the collection where it belongs
+    this.collectionName = classNameArg;
+    this.smartdataDb = smartDataDbArg;
+
+    // tell the db class about it (important since Db uses different systems under the hood)
+    this.smartdataDb.addCollection(this);
+  }
+
+  private runWithOrdinarySession<TResult>(
+    sessionArg: TSmartdataOrdinarySession | undefined,
+    ordinaryWriteArg: boolean,
+    operationArg: (
+      rawSessionArg: plugins.mongodb.ClientSession | undefined,
+    ) => Promise<TResult>,
+  ): Promise<TResult> {
+    return runWithOrdinarySmartdataSession(
+      sessionArg,
+      this.smartdataDb,
+      {
+        ordinaryWrite: ordinaryWriteArg,
+        prepared: this.isInitializedForCurrentDatabase(),
+        preparationMessage:
+          `Initialize collection "${this.collectionName}" before using an owned SmartData session.`,
+      },
+      operationArg,
+    );
+  }
+
+  /**
+   * Returns the deep-frozen normalized model schema bound to this collection,
+   * or undefined when no model schema has been bound yet. The schema exposes
+   * declared fields and named index definitions only, never raw driver access.
+   */
+  public getBoundModelSchema(): INormalizedCollectionModelSchema | undefined {
+    return this.modelSchema;
+  }
+
+  public bindModelSchema(schemaArg: INormalizedCollectionModelSchema): void {
+    if (
+      schemaArg.collectionName !== this.collectionName ||
+      (this.modelSchema &&
+        (this.modelSchema.fingerprint !== schemaArg.fingerprint ||
+          this.modelSchema.ordinaryPersistence?.assertStoredDocument !==
+            schemaArg.ordinaryPersistence?.assertStoredDocument))
+    ) {
+      throw new SmartdataPersistenceError(
+        'invalid_configuration',
+        `Collection "${this.collectionName}" cannot bind a divergent model schema.`,
+      );
+    }
+    if (!this.modelSchema) {
+      this.modelSchema = schemaArg;
+      this.initializationGeneration++;
+      this.initialized = false;
+      this.initializationPromise = undefined;
+    }
+  }
+
+  public resetForDatabaseReconnect(): void {
+    this.initializationGeneration++;
+    delete (this as { mongoDbCollection?: plugins.mongodb.Collection })
+      .mongoDbCollection;
+    this.initialized = false;
+    this.initializationPromise = undefined;
+    this.uniqueIndexes = [];
+    this.regularIndexes = [];
+    this.compoundIndexes = [];
+    notifyCollectionReconnect(this);
+  }
+
+  /**
+   * makes sure a collection exists within MongoDb that maps to the SmartdataCollection
+   */
+  public async init(): Promise<void> {
+    if (this.initialized) {
+      return;
+    }
+    if (!this.initializationPromise) {
+      const generation = this.initializationGeneration;
+      const targetDb = this.smartdataDb.mongoDb;
+      let initializationPromise!: Promise<void>;
+      initializationPromise = this.initializeOnce(targetDb, generation)
+        .then(() => {
+          if (
+            this.initializationGeneration === generation
+            && this.smartdataDb.mongoDb === targetDb
+          ) {
+            this.initialized = true;
+          }
+        })
+        .catch((errorArg) => {
+          const isCurrentGeneration =
+            this.initializationGeneration === generation
+            && this.smartdataDb.mongoDb === targetDb;
+          if (this.initializationPromise === initializationPromise) {
+            this.initializationPromise = undefined;
+            if (isCurrentGeneration) {
+              this.initialized = false;
+            }
+          }
+          if (isCurrentGeneration) {
+            throw errorArg;
+          }
+        })
+        .finally(() => {
+          if (this.initializationPromise === initializationPromise) {
+            this.initializationPromise = undefined;
+          }
+        });
+      this.initializationPromise = initializationPromise;
+    }
+    const initializationPromise = this.initializationPromise;
+    await initializationPromise;
+    if (!this.initialized) {
+      await this.init();
+    }
+  }
+
+  public async ensureInitialized(): Promise<void> {
+    await this.init();
+  }
+
+  /** Explicit bounded preparation of the bound model's exact declared topology. */
+  public async prepareCollection(opts: ISmartdataCollectionPreparationOptions): Promise<void> {
+    const budget = new CollectionPreparationBudget(opts);
+    const generation = this.initializationGeneration;
+    const targetDb = this.smartdataDb.mongoDb;
+    const assertCurrent = () => {
+      budget.check();
+      if (this.initializationGeneration !== generation || this.smartdataDb.mongoDb !== targetDb ||
+        this.smartdataDb.status !== 'connected') {
+        throw new SmartdataPersistenceError('unsupported_operation',
+          'SmartData connection changed during collection preparation.');
+      }
+    };
+    try {
+      if (!this.modelSchema) {
+        throw new SmartdataPersistenceError('invalid_configuration',
+          'Collection preparation requires a bound model schema.');
+      }
+      // The caller owns its waiting deadline, not the preceding operation.
+      while (this.initializationPromise) {
+        await budget.waitFor(this.initializationPromise);
+        assertCurrent();
+      }
+      assertCurrent();
+      this.initialized = false;
+      const schema = this.modelSchema;
+      const preparation = (async () => {
+        const outcome = await this.smartdataDb[collectionTopologyDbInspectionSymbol](async (dbArg) => {
+          try {
+            return { collection: await prepareBoundCollection(dbArg, schema, budget, assertCurrent) };
+          } catch (errorArg) {
+            // Let the connection owner check its epoch before publishing either outcome.
+            return { error: errorArg };
+          }
+        });
+        assertCurrent();
+        if ('error' in outcome) throw outcome.error;
+        this.mongoDbCollection = outcome.collection;
+        this.publishModelIndexes(schema);
+        this.initialized = true;
+      })();
+      this.initializationPromise = preparation;
+      try {
+        await preparation;
+      } finally {
+        if (this.initializationPromise === preparation) this.initializationPromise = undefined;
+      }
+    } catch (errorArg) {
+      budget.check();
+      throw errorArg;
+    } finally {
+      budget.close();
+    }
+  }
+
+  public isInitializedForCurrentDatabase(): boolean {
+    return this.initialized && Boolean(this.mongoDbCollection);
+  }
+
+  private async initializeOnce(
+    targetDbArg: plugins.mongodb.Db,
+    generationArg: number,
+  ): Promise<void> {
+    let targetCollection = this.mongoDbCollection;
+    if (!targetCollection) {
+      const wantedCollection = await targetDbArg
+        .listCollections(
+          { name: this.collectionName },
+          { nameOnly: true },
+        )
+        .hasNext();
+      if (!wantedCollection) {
+        try {
+          await targetDbArg.createCollection(
+            this.collectionName,
+          );
+        } catch (errorArg) {
+          const mongoError = errorArg as { code?: unknown };
+          if (mongoError.code !== 48) {
+            throw errorArg;
+          }
+        }
+        logger.log('info', `Successfully initiated Collection ${this.collectionName}`);
+      }
+      targetCollection = targetDbArg.collection(this.collectionName);
+    }
+    if (
+      this.initializationGeneration !== generationArg
+      || this.smartdataDb.mongoDb !== targetDbArg
+    ) {
+      return;
+    }
+    this.mongoDbCollection = targetCollection;
+    const modelSchema = this.modelSchema;
+    if (!modelSchema) {
+      return;
+    }
+    for (const index of modelSchema.indexes) {
+      await targetCollection.createIndex(
+        Object.fromEntries(index.key) as plugins.mongodb.IndexSpecification,
+        {
+          ...index.options,
+          name: index.name,
+        },
+      );
+    }
+    const actualIndexes = await targetCollection.listIndexes().toArray();
+    for (const expected of modelSchema.indexes) {
+      const actual = actualIndexes.find(
+        (indexArg) => indexArg.name === expected.name,
+      );
+      if (!actual) {
+        throw new SmartdataPersistenceError(
+          'invalid_configuration',
+          `Index "${expected.name}" was not created on "${this.collectionName}".`,
+        );
+      }
+      const actualKeyEntries = Object.entries(actual.key || {});
+      const expectedTextFields = expected.key
+        .filter(([, directionArg]) => directionArg === 'text')
+        .map(([fieldArg]) => fieldArg);
+      const canonicalExpectedKey: Array<
+        readonly [string, TCollectionModelIndexDirection]
+      > = [];
+      let textMarkerAdded = false;
+      for (const [field, direction] of expected.key) {
+        if (direction === 'text') {
+          if (!textMarkerAdded) {
+            canonicalExpectedKey.push(['_fts', 'text'], ['_ftsx', 1]);
+            textMarkerAdded = true;
+          }
+        } else {
+          canonicalExpectedKey.push([field, direction]);
+        }
+      }
+      const actualTextFields = Object.keys(actual.weights || {}).sort(
+        compareSmartdataTopologyStrings,
+      );
+      if (
+        stableValue(actualKeyEntries) !==
+          stableValue(canonicalExpectedKey) ||
+        stableValue(actualTextFields) !==
+          stableValue(
+            [...expectedTextFields].sort(compareSmartdataTopologyStrings),
+          )
+      ) {
+        throw new SmartdataPersistenceError(
+          'invalid_configuration',
+          `Index "${expected.name}" has an unexpected key specification.`,
+        );
+      }
+      for (const booleanOption of ['unique', 'sparse'] as const) {
+        if (
+          Boolean(actual[booleanOption]) !==
+          Boolean(expected.options[booleanOption])
+        ) {
+          throw new SmartdataPersistenceError(
+            'invalid_configuration',
+            `Index "${expected.name}" has an unexpected "${booleanOption}" option.`,
+          );
+        }
+      }
+      if (
+        expected.options.expireAfterSeconds !== undefined &&
+        actual.expireAfterSeconds !==
+          expected.options.expireAfterSeconds
+      ) {
+        throw new SmartdataPersistenceError(
+          'invalid_configuration',
+          `Index "${expected.name}" has an unexpected expireAfterSeconds option.`,
+        );
+      }
+    }
+    if (
+      this.initializationGeneration !== generationArg
+      || this.smartdataDb.mongoDb !== targetDbArg
+      || this.mongoDbCollection !== targetCollection
+    ) {
+      return;
+    }
+    this.publishModelIndexes(modelSchema);
+  }
+
+  private publishModelIndexes(modelSchema: INormalizedCollectionModelSchema): void {
+    this.uniqueIndexes = modelSchema.indexes
+      .filter((indexArg) => indexArg.options.unique)
+      .filter(
+        (indexArg) =>
+          indexArg.key.length === 1 && indexArg.key[0][1] === 1,
+      )
+      .map((indexArg) => indexArg.key[0][0]);
+    this.regularIndexes = modelSchema.indexes
+      .filter(
+        (indexArg) =>
+          indexArg.key.length === 1 &&
+          indexArg.key[0][1] === 1,
+      )
+      .map((indexArg) => ({
+        field: indexArg.key[0][0],
+        options: { ...indexArg.options },
+      }));
+    this.compoundIndexes = modelSchema.indexes
+      .filter(
+        (indexArg) =>
+          indexArg.key.length >= 2 &&
+          indexArg.key.every(([, directionArg]) => directionArg !== 'text'),
+      )
+      .map((indexArg) => ({
+        name: indexArg.name,
+        key: Object.fromEntries(indexArg.key) as Record<
+          string,
+          TCompoundIndexDirection
+        >,
+        options: { ...indexArg.options },
+      }));
+  }
+
+  /**
+   * mark unique index
+   */
+  public async markUniqueIndexes(keyArrayArg: string[] = []) {
+    for (const key of keyArrayArg) {
+      if (!this.uniqueIndexes.includes(key)) {
+        try {
+          await this.mongoDbCollection.createIndex({ [key]: 1 }, {
+            unique: true,
+            name: `${key}_1`,
+          });
+          this.uniqueIndexes.push(key);
+        } catch (err: any) {
+          const errorCode = err?.code || err?.codeName || 'unknown';
+          const errorMessage = err?.message || String(err);
+          logger.log(
+            'error',
+            `Failed to create unique index on field "${key}" in collection "${this.collectionName}". ` +
+            `MongoDB error [${errorCode}]: ${errorMessage}. ` +
+            `Uniqueness constraint on "${key}" is NOT enforced.`
+          );
+          if (errorCode === 11000 || errorCode === 'DuplicateKey' || String(errorMessage).includes('E11000')) {
+            await this.logDuplicatesForField(key);
+          }
+          throw err;
+        }
+      }
+    }
+  }
+
+  /**
+   * creates regular indexes for the collection
+   */
+  public async createRegularIndexes(indexesArg: Array<{field: string, options: IIndexOptions}> = []) {
+    for (const indexDef of indexesArg) {
+      // Check if we've already created this index
+      const indexKey = indexDef.field;
+      if (!this.regularIndexes.some(i => i.field === indexKey)) {
+        try {
+          await this.mongoDbCollection.createIndex(
+            { [indexDef.field]: 1 }, // Simple single-field index
+            indexDef.options
+          );
+          this.regularIndexes.push(indexDef);
+        } catch (err: any) {
+          const errorCode = err?.code || err?.codeName || 'unknown';
+          const errorMessage = err?.message || String(err);
+          logger.log(
+            'warn',
+            `Failed to create index on field "${indexKey}" in collection "${this.collectionName}". ` +
+            `MongoDB error [${errorCode}]: ${errorMessage}.`
+          );
+          if (
+            indexDef.options?.unique &&
+            (errorCode === 11000 || errorCode === 'DuplicateKey' || String(errorMessage).includes('E11000'))
+          ) {
+            await this.logDuplicatesForField(indexKey);
+          }
+          throw err;
+        }
+      }
+    }
+  }
+
+  /**
+   * Logs duplicate values for a field to help diagnose unique index creation failures.
+   */
+  private async logDuplicatesForField(field: string): Promise<void> {
+    try {
+      const pipeline = [
+        { $group: { _id: `$${field}`, count: { $sum: 1 }, ids: { $push: '$_id' } } },
+        { $match: { count: { $gt: 1 } } },
+        { $limit: 5 },
+      ];
+      const duplicates = await this.mongoDbCollection.aggregate(pipeline).toArray();
+      if (duplicates.length > 0) {
+        for (const dup of duplicates) {
+          logger.log(
+            'warn',
+            `Duplicate values for "${field}" in "${this.collectionName}": ` +
+            `value=${JSON.stringify(dup._id)} appears ${dup.count} times ` +
+            `(document _ids: ${JSON.stringify(dup.ids.slice(0, 5))})`
+          );
+        }
+        logger.log(
+          'warn',
+          `Unique index on "${field}" in "${this.collectionName}" was NOT created. ` +
+          `Resolve duplicates and restart to enforce uniqueness.`
+        );
+      }
+    } catch (aggErr: any) {
+      logger.log(
+        'warn',
+        `Could not identify duplicate documents for field "${field}" in "${this.collectionName}": ${aggErr?.message || String(aggErr)}`
+      );
+    }
+  }
+
+  /**
+   * adds a validation function that all newly inserted and updated objects have to pass
+   */
+  public addDocValidation(funcArg: IDocValidationFunc<T>) {
+    this.objectValidation = funcArg;
+  }
+
+  /**
+   * finds an object in the DbCollection
+   */
+  public async findOne(
+    filterObject: any,
+    opts?: {
+      projection?: plugins.mongodb.Document;
+      maxTimeMS?: number;
+      session?: TSmartdataOrdinarySession;
+    },
+  ): Promise<any> {
+    return this.runWithOrdinarySession(
+      opts?.session,
+      false,
+      async (rawSessionArg) => {
+        await this.init();
+        return this.mongoDbCollection.findOne(filterObject, {
+          projection: opts?.projection,
+          maxTimeMS: opts?.maxTimeMS,
+          session: rawSessionArg,
+        });
+      },
+    );
+  }
+
+  public async getCursor(
+    filterObjectArg: any,
+    dbDocArg: typeof SmartDataDbDoc,
+    opts?: { session?: plugins.mongodb.ClientSession }
+  ): Promise<SmartdataDbCursor<any>> {
+    await this.init();
+    const cursor = this.mongoDbCollection.find(filterObjectArg, { session: opts?.session });
+    return new SmartdataDbCursor(cursor, dbDocArg);
+  }
+
+  /**
+   * finds an object in the DbCollection
+   */
+  public async findAll(
+    filterObject: any,
+    opts?: { session?: TSmartdataOrdinarySession }
+  ): Promise<any[]> {
+    return this.runWithOrdinarySession(
+      opts?.session,
+      false,
+      async (rawSessionArg) => {
+        await this.init();
+        const cursor = this.mongoDbCollection.find(filterObject, {
+          session: rawSessionArg,
+        });
+        let result!: any[];
+        let operationFailed = false;
+        try {
+          result = await cursor.toArray();
+        } catch (errorArg) {
+          operationFailed = true;
+          throw errorArg;
+        } finally {
+          try {
+            await cursor.close();
+          } catch (closeError) {
+            if (!operationFailed) {
+              throw closeError;
+            }
+          }
+        }
+
+        // In-memory check for duplicate _id values (should never happen)
+        if (result.length > 0) {
+          const idSet = new Set<string>();
+          const duplicateIds: string[] = [];
+          for (const doc of result) {
+            const idStr = String(doc._id);
+            if (idSet.has(idStr)) {
+              duplicateIds.push(idStr);
+            } else {
+              idSet.add(idStr);
+            }
+          }
+          if (duplicateIds.length > 0) {
+            logger.log(
+              'error',
+              `Integrity issue in "${this.collectionName}": found ${duplicateIds.length} duplicate _id values ` +
+              `in findAll results: [${duplicateIds.slice(0, 5).join(', ')}]. This should never happen.`
+            );
+          }
+        }
+
+        return result;
+      },
+    );
+  }
+
+  /**
+   * Watches the collection, returning a SmartdataDbWatcher with RxJS and EventEmitter support.
+   * @param filterObject match filter for change stream
+   * @param opts optional MongoDB ChangeStreamOptions & { bufferTimeMs } to buffer events
+   * @param smartdataDbDocArg document class for instance creation
+   */
+  public async watch(
+    filterObject: any,
+    opts: (plugins.mongodb.ChangeStreamOptions & { bufferTimeMs?: number }) = {},
+    smartdataDbDocArg?: typeof SmartDataDbDoc,
+  ): Promise<SmartdataDbWatcher> {
+    if ('capabilities' in this.smartdataDb &&
+      (this.smartdataDb.capabilities as { changeStreams?: string }).changeStreams === 'unsupported') {
+      throw new LosslessClientError('unsupported_capability', 'Change streams are unsupported by this backend.');
+    }
+    await this.init();
+    // Extract bufferTimeMs from options
+    const { bufferTimeMs, fullDocument, ...otherOptions } = opts || {};
+    // Determine fullDocument behavior: default to 'updateLookup'
+    const changeStreamOptions: plugins.mongodb.ChangeStreamOptions = {
+      ...otherOptions,
+      fullDocument:
+        fullDocument === undefined
+          ? 'updateLookup'
+          : (fullDocument as any) === true
+          ? 'updateLookup'
+          : fullDocument,
+    } as any;
+    // Build pipeline with match if provided
+    const pipeline = filterObject ? [{ $match: filterObject }] : [];
+    const changeStream = this.mongoDbCollection.watch(
+      pipeline,
+      changeStreamOptions,
+    );
+    const smartdataWatcher = new SmartdataDbWatcher(
+      changeStream,
+      smartdataDbDocArg!,
+      { bufferTimeMs },
+    );
+    await smartdataWatcher.readyDeferred.promise;
+    return smartdataWatcher;
+  }
+
+  /**
+   * create an object in the database
+   */
+  private prepareOrdinaryInsert(documentArg: any): any {
+    const policy = this.modelSchema?.ordinaryPersistence;
+    if (!policy) return documentArg;
+    if (policy.idType === 'objectId' && !Object.prototype.hasOwnProperty.call(documentArg, '_id')) {
+      documentArg = { ...documentArg, _id: new plugins.mongodb.ObjectId() };
+    }
+    return validateOrdinaryStoredDocument(documentArg, policy, this.modelSchema!.persistedFields);
+  }
+
+  public async insert(
+    dbDocArg: T & SmartDataDbDoc<T, unknown>,
+    opts?: { session?: TSmartdataOrdinarySession }
+  ): Promise<any> {
+    const preparedObject = this.modelSchema?.ordinaryPersistence
+      ? this.prepareOrdinaryInsert(await dbDocArg.createSavableObject()) : undefined;
+    return this.runWithOrdinarySession(
+      opts?.session,
+      true,
+      async (rawSessionArg) => {
+        await this.init();
+        await this.checkDoc(dbDocArg);
+        await this.markUniqueIndexes(dbDocArg.uniqueIndexes);
+
+        // Create regular indexes if available
+        if (dbDocArg.regularIndexes && dbDocArg.regularIndexes.length > 0) {
+          await this.createRegularIndexes(dbDocArg.regularIndexes);
+        }
+
+        const saveableObject = preparedObject ?? await dbDocArg.createSavableObject();
+        try {
+          return await this.mongoDbCollection.insertOne(saveableObject, {
+            session: rawSessionArg,
+          });
+        } catch (err: any) {
+          return normalizeOrdinaryPersistenceError(
+            err,
+            `Insert conflicts with a unique index in collection "${this.collectionName}".`,
+          );
+        }
+      },
+    );
+  }
+
+  /**
+   * Executes a bounded grouped-totals aggregation over already-validated
+   * stages and never exposes the aggregation cursor. Prefer the validated
+   * static `SmartDataDbDoc.getGroupedTotals()`, which owns input validation
+   * before this raw persistence boundary.
+   */
+  public async aggregateGroupedTotals(
+    matchArg: plugins.mongodb.Filter<plugins.mongodb.Document> | undefined,
+    groupArg: plugins.mongodb.Document,
+    limitArg: number,
+    opts?: { session?: TSmartdataOrdinarySession; maxTimeMS?: number; timeoutMS?: number; signal?: AbortSignal }
+  ): Promise<plugins.mongodb.Document[]> {
+    opts?.signal?.throwIfAborted();
+    return this.runWithOrdinarySession(
+      opts?.session,
+      false,
+      async (rawSessionArg) => {
+        await this.init();
+        const pipeline: plugins.mongodb.Document[] = [];
+        if (matchArg && Object.keys(matchArg).length > 0) {
+          pipeline.push({ $match: matchArg });
+        }
+        pipeline.push({ $group: groupArg });
+        pipeline.push({ $limit: limitArg });
+        opts?.signal?.throwIfAborted();
+        const cursor = this.mongoDbCollection.aggregate(pipeline, {
+          session: rawSessionArg,
+          ...(opts?.timeoutMS !== undefined ? { timeoutMS: opts.timeoutMS, timeoutMode: 'cursorLifetime' } : {}),
+          signal: opts?.signal,
+          ...(opts?.maxTimeMS !== undefined
+            ? { maxTimeMS: opts.maxTimeMS }
+            : {}),
+        });
+        return runCursorOperation(cursor, (cursorArg) => cursorArg.toArray(), opts?.signal);
+      },
+    );
+  }
+
+  public async insertMany(
+    dbDocsArg: Array<T & SmartDataDbDoc<T, unknown>>,
+    opts?: { session?: TSmartdataOrdinarySession; ordered?: boolean }
+  ): Promise<plugins.mongodb.InsertManyResult> {
+    if (!Array.isArray(dbDocsArg) || dbDocsArg.length === 0) {
+      throw new SmartdataPersistenceError(
+        'invalid_argument',
+        `insertMany requires a non-empty document batch for collection "${this.collectionName}".`,
+      );
+    }
+    const preparedObjects: any[] | undefined = this.modelSchema?.ordinaryPersistence ? [] : undefined;
+    if (preparedObjects) {
+      for (const dbDocArg of dbDocsArg) {
+        preparedObjects.push(this.prepareOrdinaryInsert(await dbDocArg.createSavableObject()));
+      }
+    }
+    return this.runWithOrdinarySession(
+      opts?.session,
+      true,
+      async (rawSessionArg) => {
+        await this.init();
+        for (const dbDocArg of dbDocsArg) {
+          await this.checkDoc(dbDocArg);
+        }
+        const firstDocument = dbDocsArg[0];
+        await this.markUniqueIndexes(firstDocument.uniqueIndexes);
+        if (
+          firstDocument.regularIndexes
+          && firstDocument.regularIndexes.length > 0
+        ) {
+          await this.createRegularIndexes(firstDocument.regularIndexes);
+        }
+        const saveableObjects: any[] = preparedObjects ?? [];
+        if (!preparedObjects) {
+          for (const dbDocArg of dbDocsArg) {
+            saveableObjects.push(await dbDocArg.createSavableObject());
+          }
+        }
+        try {
+          return await this.mongoDbCollection.insertMany(saveableObjects, {
+            session: rawSessionArg,
+            ordered: opts?.ordered !== false,
+          });
+        } catch (err: any) {
+          return normalizeOrdinaryPersistenceError(
+            err,
+            `Insert conflicts with a unique index in collection "${this.collectionName}".`,
+          );
+        }
+      },
+    );
+  }
+
+  /** Model.insertManyIfAbsent owns identity and new-instance validation. */
+  public async insertManyIfAbsent(
+    documentsArg: Array<T & SmartDataDbDoc<T, unknown>>,
+    identityFieldArg: string,
+    optsArg: { session?: TSmartdataOrdinarySession; timeoutMS?: number },
+  ): Promise<{ insertedCount: number; matchedCount: number }> {
+    const prepared: plugins.mongodb.Document[] = [];
+    let bytes = 0;
+    // Validate the entire batch before any write, including opted-in whole
+    // stored-document policies and collection-level object validation.
+    for (const document of documentsArg) {
+      await this.checkDoc(document);
+      const stored = this.prepareOrdinaryInsert(await document.createSavableObject());
+      const bson = plugins.mongodb.BSON.serialize(stored);
+      bytes += bson.byteLength;
+      if (bytes > 16 * 1024 * 1024) {
+        throw new SmartdataPersistenceError('invalid_argument',
+          'insertManyIfAbsent accepts at most 16 MiB of serialized documents.');
+      }
+      prepared.push(plugins.mongodb.BSON.deserialize(bson));
+    }
+    return this.runWithOrdinarySession(optsArg.session, true, async (rawSessionArg) => {
+      await this.init();
+      const first = documentsArg[0];
+      await this.markUniqueIndexes(first.uniqueIndexes);
+      await this.createRegularIndexes(first.regularIndexes || []);
+      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 });
+        if (result.upsertedCount + result.matchedCount !== prepared.length) {
+          throw new SmartdataPersistenceError('unsupported_operation',
+            'insertManyIfAbsent requires an acknowledged result for every identity.');
+        }
+        return { insertedCount: result.upsertedCount, matchedCount: result.matchedCount };
+      } catch (errorArg) {
+        return normalizeOrdinaryPersistenceError(errorArg,
+          `Insert conflicts with a unique index in collection "${this.collectionName}".`);
+      }
+    });
+  }
+
+  /**
+   * inserts object into the DbCollection
+   */
+  public async update(
+    dbDocArg: T & SmartDataDbDoc<T, unknown>,
+    opts?: { session?: TSmartdataOrdinarySession }
+  ): Promise<any> {
+    if (this.modelSchema?.ordinaryPersistence) {
+      throw new SmartdataPersistenceError('unsupported_operation',
+        'Validated ordinary models require a transactional postimage update.');
+    }
+    return this.runWithOrdinarySession(
+      opts?.session,
+      true,
+      async (rawSessionArg) => {
+        await this.init();
+        await this.checkDoc(dbDocArg);
+        await this.markUniqueIndexes(dbDocArg.uniqueIndexes);
+        if (dbDocArg.regularIndexes && dbDocArg.regularIndexes.length > 0) {
+          await this.createRegularIndexes(dbDocArg.regularIndexes);
+        }
+        const identifiableObject = await dbDocArg.createIdentifiableObject();
+        this.assertConstrainingIdentifiableObject(identifiableObject, 'update');
+        const saveableObject = await dbDocArg.createSavableObject() as any;
+        const updateableObject: any = {};
+        for (const key of Object.keys(saveableObject)) {
+          if (identifiableObject[key]) {
+            continue;
+          }
+          updateableObject[key] = saveableObject[key];
+        }
+        try {
+          return await this.mongoDbCollection.updateOne(
+            identifiableObject,
+            { $set: updateableObject },
+            { upsert: true, session: rawSessionArg },
+          );
+        } catch (errorArg) {
+          return normalizeOrdinaryPersistenceError(
+            errorArg,
+            `Update conflicts with a unique index in collection "${this.collectionName}".`,
+          );
+        }
+      },
+    );
+  }
+
+  public async delete(
+    dbDocArg: T & SmartDataDbDoc<T, unknown>,
+    opts?: { session?: TSmartdataOrdinarySession }
+  ): Promise<any> {
+    return this.runWithOrdinarySession(
+      opts?.session,
+      true,
+      async (rawSessionArg) => {
+        await this.init();
+        await this.checkDoc(dbDocArg);
+        const identifiableObject = await dbDocArg.createIdentifiableObject();
+        this.assertConstrainingIdentifiableObject(identifiableObject, 'delete');
+        return this.mongoDbCollection.deleteOne(identifiableObject, {
+          session: rawSessionArg,
+        });
+      },
+    );
+  }
+
+  /**
+   * Rejects instance-level document targeting when the model declares no
+   * identity fields. An empty identity filter would otherwise address an
+   * arbitrary document in the collection.
+   */
+  private assertConstrainingIdentifiableObject(
+    identifiableObjectArg: Record<string, unknown>,
+    operationLabelArg: string,
+  ): void {
+    if (Object.keys(identifiableObjectArg).length === 0) {
+      throw new SmartdataPersistenceError(
+        'invalid_configuration',
+        `Instance ${operationLabelArg} on collection "${this.collectionName}" requires declared identity fields; without them the operation would target an arbitrary document.`,
+      );
+    }
+  }
+
+  public async getCount(
+    filterObject: any,
+    opts?: {
+      limit?: number;
+      hint?: string;
+      maxTimeMS?: number;
+      timeoutMS?: number;
+      signal?: AbortSignal;
+      session?: TSmartdataOrdinarySession;
+    },
+  ) {
+    if (opts?.hint !== undefined && (
+      typeof opts.hint !== 'string' ||
+      (opts.hint !== '_id_' && !this.modelSchema?.indexes.some(
+        (indexArg) => indexArg.name === opts.hint,
+      ))
+    )) {
+      throw new SmartdataPersistenceError(
+        'invalid_argument',
+        'Query hint must name an index declared by this model or the built-in _id_ index.',
+      );
+    }
+    return this.runWithOrdinarySession(
+      opts?.session,
+      false,
+      async (rawSessionArg) => {
+        await this.init();
+        opts?.signal?.throwIfAborted();
+        const pipeline: plugins.mongodb.Document[] = [{ $match: filterObject }];
+        if (opts?.limit !== undefined) {
+          pipeline.push({ $limit: opts.limit });
+        }
+        pipeline.push({ $count: 'count' });
+        const cursor = this.mongoDbCollection.aggregate<{ count: number }>(pipeline, {
+          hint: opts?.hint,
+          maxTimeMS: opts?.maxTimeMS,
+          timeoutMS: opts?.timeoutMS,
+          signal: opts?.signal,
+          session: rawSessionArg,
+        });
+        return runCursorOperation(cursor, async (cursorArg) =>
+          (await cursorArg.next())?.count ?? 0,
+        opts?.signal);
+      },
+    );
+  }
+
+  public async getIndexInfo(): Promise<ISmartdataIndexInfo[]> {
+    await this.init();
+    const indexes = await this.mongoDbCollection.listIndexes().toArray();
+    return indexes.map((indexArg) => {
+      let fields: ISmartdataIndexInfo['fields'];
+      if (indexArg.key._fts === 'text') {
+        const weights =
+          typeof indexArg.weights === 'object' &&
+          indexArg.weights !== null &&
+          !Array.isArray(indexArg.weights)
+            ? indexArg.weights
+            : {};
+        fields = Object.keys(weights).map((path) => ({
+          path,
+          direction: 'text' as const,
+        }));
+      } else {
+        fields = Object.entries(indexArg.key).map(([path, direction]) => {
+          if (direction !== 1 && direction !== -1) {
+            throw new SmartdataPersistenceError(
+              'unsupported_operation',
+              `Index "${indexArg.name}" uses an unsupported direction.`,
+            );
+          }
+          return {
+            path,
+            direction,
+          };
+        });
+      }
+      return {
+        name: indexArg.name,
+        fields,
+        unique: indexArg.unique === true,
+        sparse: indexArg.sparse === true,
+        expireAfterSeconds:
+          typeof indexArg.expireAfterSeconds === 'number'
+            ? indexArg.expireAfterSeconds
+            : undefined,
+      };
+    });
+  }
+
+  /**
+   * Runs an integrity check on the collection.
+   * Compares estimated vs actual document count and checks for duplicates on unique index fields.
+   */
+  public async checkCollectionIntegrity(): Promise<{
+    ok: boolean;
+    estimatedCount: number;
+    actualCount: number;
+    duplicateFields: Array<{ field: string; duplicateValues: number }>;
+  }> {
+    await this.init();
+    const result = {
+      ok: true,
+      estimatedCount: 0,
+      actualCount: 0,
+      duplicateFields: [] as Array<{ field: string; duplicateValues: number }>,
+    };
+
+    try {
+      result.estimatedCount = await this.mongoDbCollection.estimatedDocumentCount();
+      result.actualCount = await this.mongoDbCollection.countDocuments({});
+
+      if (result.estimatedCount !== result.actualCount) {
+        result.ok = false;
+        logger.log(
+          'warn',
+          `Integrity check on "${this.collectionName}": estimatedDocumentCount=${result.estimatedCount} ` +
+          `but countDocuments=${result.actualCount}. Possible data inconsistency.`
+        );
+      }
+
+      // Check for duplicates on each tracked unique index field
+      for (const field of this.uniqueIndexes) {
+        try {
+          const pipeline = [
+            { $group: { _id: `$${field}`, count: { $sum: 1 } } },
+            { $match: { count: { $gt: 1 } } },
+            { $count: 'total' },
+          ];
+          const countResult = await this.mongoDbCollection.aggregate(pipeline).toArray();
+          const dupCount = countResult[0]?.total || 0;
+          if (dupCount > 0) {
+            result.ok = false;
+            result.duplicateFields.push({ field, duplicateValues: dupCount });
+            logger.log(
+              'warn',
+              `Integrity check on "${this.collectionName}": field "${field}" has ${dupCount} values with duplicates ` +
+              `despite being marked as unique.`
+            );
+          }
+        } catch (fieldErr: any) {
+          logger.log(
+            'warn',
+            `Integrity check: could not verify uniqueness of "${field}" in "${this.collectionName}": ${fieldErr?.message || String(fieldErr)}`
+          );
+        }
+      }
+    } catch (err: any) {
+      result.ok = false;
+      logger.log(
+        'error',
+        `Integrity check failed for "${this.collectionName}": ${err?.message || String(err)}`
+      );
+    }
+
+    return result;
+  }
+
+  /**
+   * checks a Doc for constraints
+   * if this.objectValidation is not set it passes.
+   */
+  private checkDoc(docArg: T): Promise<void> {
+    const done = plugins.smartpromise.defer<void>();
+    let validationResult = true;
+    if (this.objectValidation) {
+      validationResult = this.objectValidation(docArg);
+    }
+    if (validationResult) {
+      done.resolve();
+    } else {
+      done.reject('validation of object did not pass');
+    }
+    return done.promise;
+  }
+}