@lossless.org/client 0.1.0

package/ts/nosqldb/classes.exactpersistence.ts

@@ -0,0 +1,1974 @@
+import * as plugins from './plugins.js';
+import { getInertObjectIdBytes } from './classes.bsonobjectid.js';
+import { assertBsonWithoutMutation } from './classes.bsonassertion.js';
+import { getOrdinaryPersistencePolicy } from './classes.ordinarypersistence.js';
+
+import type { SmartdataCollection } from './classes.collection.js';
+import { registerCollectionReconnectHandler } from './classes.collectionlifecycle.js';
+import type { SmartdataSession } from './classes.session.js';
+import { acquireSmartdataSession } from './classes.session.js';
+import {
+  convertFilterForMongoDb,
+  type MongoFilter,
+  type SmartDataDbDoc,
+  type TSmartdataIdentityValueType,
+} from './classes.doc.js';
+
+const exactPersistencePolicySymbol = Symbol.for(
+  '@push.rocks/smartdata.exactPersistencePolicy',
+);
+
+const storageMetadataKeys = ['_id', '_smartdataRevision'] as const;
+const reservedKeys = [
+  ...storageMetadataKeys,
+  '_createdAt',
+  '_updatedAt',
+] as const;
+
+type TReservedKey = (typeof reservedKeys)[number];
+type TStorageMetadataKey = (typeof storageMetadataKeys)[number];
+
+export type TExactPersistedDocument<TPersisted extends object> = Omit<
+  TPersisted,
+  TReservedKey
+> & {
+  [TKey in TReservedKey]?: never;
+};
+
+export type TStoredDocument<TPersisted extends object> = Omit<
+  TPersisted,
+  TReservedKey
+> & {
+  _id: plugins.mongodb.ObjectId;
+  _smartdataRevision?: string;
+  _createdAt?: never;
+  _updatedAt?: never;
+};
+
+export type TExactDistinctValue<TValue> = TValue extends ReadonlyArray<infer TEntry>
+  ? TEntry
+  : TValue;
+
+type TExactDocumentPathLeaf =
+  | string
+  | number
+  | boolean
+  | bigint
+  | symbol
+  | null
+  | undefined
+  | Date
+  | RegExp
+  | Uint8Array
+  | ((...args: any[]) => unknown)
+  | { readonly _bsontype: string };
+
+type TExactDocumentPathTarget<TValue> =
+  NonNullable<TValue> extends ReadonlyArray<infer TEntry>
+    ? NonNullable<TEntry>
+    : NonNullable<TValue>;
+
+type TExactDocumentPathInternal<
+  TDocument,
+  TDepth extends readonly unknown[],
+> = TDepth['length'] extends 8
+  ? never
+  : TDocument extends TExactDocumentPathLeaf
+    ? never
+    : TDocument extends object
+      ? {
+          [TKey in keyof TDocument & string]:
+            TExactDocumentPathTarget<TDocument[TKey]> extends TExactDocumentPathLeaf
+              ? TKey
+              : TExactDocumentPathTarget<TDocument[TKey]> extends object
+                ? TKey | `${TKey}.${TExactDocumentPathInternal<
+                    TExactDocumentPathTarget<TDocument[TKey]>,
+                    [...TDepth, unknown]
+                  >}`
+                : TKey;
+        }[keyof TDocument & string]
+      : never;
+
+type TExactDocumentPathContainer<TValue> =
+  NonNullable<TValue> extends ReadonlyArray<infer TEntry>
+    ? NonNullable<TEntry>
+    : NonNullable<TValue>;
+
+export type TExactDocumentPath<TDocument extends object> =
+  TExactDocumentPathInternal<TDocument, []>;
+
+type TExactDocumentPathValueForContainer<
+  TContainer,
+  TPath extends string,
+> = TContainer extends unknown
+  ? TPath extends `${infer THead}.${infer TTail}`
+    ? THead extends keyof TContainer
+      ? TExactDocumentPathValue<
+          TContainer[THead],
+          TTail
+        >
+      : never
+    : TPath extends keyof TContainer
+      ? Exclude<TContainer[TPath], undefined>
+      : never
+  : never;
+
+export type TExactDocumentPathValue<
+  TDocument,
+  TPath extends string,
+> = TExactDocumentPathValueForContainer<
+  TExactDocumentPathContainer<TDocument>,
+  TPath
+>;
+
+export const isMongoObjectId = (
+  valueArg: unknown,
+): valueArg is plugins.mongodb.ObjectId =>
+  valueArg instanceof plugins.mongodb.ObjectId;
+
+export type TExactInsertResult<TPersisted extends object> =
+  | {
+      status: 'inserted' | 'already_committed';
+      document: TStoredDocument<TPersisted>;
+    }
+  | {
+      status: 'conflict';
+      document: TStoredDocument<TPersisted>;
+    };
+
+export type TExactTransitionResult<TPersisted extends object> =
+  | {
+      status: 'transitioned';
+      document: TStoredDocument<TPersisted>;
+    }
+  | {
+      status: 'concurrent_change';
+    };
+
+export type TExactDeleteResult =
+  | {
+      status: 'deleted';
+      deletedCount: 1;
+    }
+  | {
+      status: 'concurrent_change';
+      deletedCount: 0;
+    };
+
+export type TExactPersistenceErrorCode =
+  | 'ambiguous_write'
+  | 'invalid_configuration'
+  | 'invalid_document'
+  | 'noncanonical_document'
+  | 'reserved_field'
+  | 'unique_conflict'
+  | 'unsupported_operation';
+
+export class SmartdataExactPersistenceError extends Error {
+  public readonly code: TExactPersistenceErrorCode;
+
+  constructor(
+    codeArg: TExactPersistenceErrorCode,
+    messageArg: string,
+    optionsArg?: ErrorOptions,
+  ) {
+    super(messageArg, optionsArg);
+    this.name = 'SmartdataExactPersistenceError';
+    this.code = codeArg;
+  }
+}
+
+export type TExactDocumentAssertion<TPersisted extends object> = (
+  documentArg: unknown,
+) => asserts documentArg is TPersisted;
+
+type TExactAssertedDocument<
+  TAssertion extends TExactDocumentAssertion<object>,
+> = TAssertion extends TExactDocumentAssertion<infer TPersisted>
+  ? TPersisted
+  : never;
+
+export type TExactIdentityKey<TPersisted extends object> = {
+  [TKey in Exclude<keyof TPersisted, TReservedKey> & string]-?:
+    [TPersisted[TKey]] extends [string] ? TKey : never;
+}[Exclude<keyof TPersisted, TReservedKey> & string];
+
+export interface IExactPersistenceOptions<TPersisted extends object> {
+  reconcileBy?: TExactIdentityKey<TPersisted>;
+  assertDocument: TExactDocumentAssertion<TPersisted>;
+}
+
+export type TPersistedOf<
+  TModel extends SmartDataDbDoc<any, any, any>,
+> = TModel extends SmartDataDbDoc<any, infer TPersisted, any>
+  ? TPersisted
+  : never;
+
+export type TExact<
+  TModel extends SmartDataDbDoc<any, any, any>,
+> = SmartdataExactCollection<TModel, TPersistedOf<TModel>>;
+
+export interface IExactSessionOptions {
+  session?: SmartdataSession;
+}
+
+export interface IExactReadOptions extends IExactSessionOptions {
+  signal?: AbortSignal;
+}
+
+export interface IFindStoredOptions<TPersisted extends object> extends IExactReadOptions {
+  filter?: MongoFilter<TStoredDocument<TPersisted>>;
+  sort?: Partial<
+    Record<TExactDocumentPath<TStoredDocument<TPersisted>>, 1 | -1>
+  >;
+  skip?: number;
+  limit?: number;
+}
+
+interface IExactModelConstructor<
+  TModel extends SmartDataDbDoc<any, any, any>,
+> {
+  new (...args: any[]): TModel;
+  collection: SmartdataCollection<any>;
+  createInstanceFromMongoDbNativeDoc<T>(documentArg: any): T;
+  name: string;
+  prototype: TModel;
+}
+
+const exactCollectionCache = new WeakMap<
+  object,
+  WeakMap<object, SmartdataExactCollection<any, any>>
+>();
+
+const bytesEqual = (leftArg: Uint8Array, rightArg: Uint8Array): boolean => {
+  if (leftArg.byteLength !== rightArg.byteLength) {
+    return false;
+  }
+  for (let index = 0; index < leftArg.byteLength; index++) {
+    if (leftArg[index] !== rightArg[index]) {
+      return false;
+    }
+  }
+  return true;
+};
+
+const waitWithSignal = async <T>(
+  promiseArg: Promise<T>,
+  signalArg?: AbortSignal,
+): Promise<T> => {
+  if (!signalArg) return promiseArg;
+  signalArg.throwIfAborted();
+  return new Promise<T>((resolve, reject) => {
+    let settled = false;
+    const beginSettlement = (): boolean => {
+      if (settled) return false;
+      settled = true;
+      signalArg.removeEventListener('abort', onAbort);
+      return true;
+    };
+    const onAbort = () => {
+      if (beginSettlement()) reject(signalArg.reason);
+    };
+    signalArg.addEventListener('abort', onAbort, { once: true });
+    if (signalArg.aborted) onAbort();
+    void promiseArg.then(
+      (valueArg) => {
+        if (beginSettlement()) resolve(valueArg);
+      },
+      (errorArg) => {
+        if (beginSettlement()) reject(errorArg);
+      },
+    );
+  });
+};
+
+const hasOwn = (documentArg: object, keyArg: PropertyKey): boolean =>
+  Object.prototype.hasOwnProperty.call(documentArg, keyArg);
+
+const isPlainObject = (
+  valueArg: unknown,
+): valueArg is Record<string, unknown> => {
+  if (typeof valueArg !== 'object' || valueArg === null) {
+    return false;
+  }
+  const prototype = Object.getPrototypeOf(valueArg);
+  return prototype === Object.prototype || prototype === null;
+};
+
+const hasActiveInheritedToBsonEncoder = (
+  prototypeArg: object | null,
+): boolean => {
+  let prototype = prototypeArg;
+  while (prototype) {
+    const descriptor = Object.getOwnPropertyDescriptor(prototype, 'toBSON');
+    if (
+      descriptor &&
+      (
+        !('value' in descriptor) ||
+        descriptor.value !== undefined
+      )
+    ) {
+      return true;
+    }
+    prototype = Object.getPrototypeOf(prototype);
+  }
+  return false;
+};
+
+const maxExactSnapshotArrayLength = 100_000;
+const maxExactSnapshotByteLength = 16 * 1024 * 1024;
+const minSignedInt32 = -(2 ** 31);
+const maxSignedInt32 = 2 ** 31 - 1;
+
+const isSignedInt32 = (valueArg: unknown): valueArg is number =>
+  typeof valueArg === 'number' &&
+  Number.isInteger(valueArg) &&
+  !Object.is(valueArg, -0) &&
+  valueArg >= minSignedInt32 &&
+  valueArg <= maxSignedInt32;
+
+const typedArrayPrototype = Object.getPrototypeOf(Uint8Array.prototype);
+const typedArrayBufferGetter = Object.getOwnPropertyDescriptor(
+  typedArrayPrototype,
+  'buffer',
+)?.get;
+const typedArrayByteOffsetGetter = Object.getOwnPropertyDescriptor(
+  typedArrayPrototype,
+  'byteOffset',
+)?.get;
+const typedArrayByteLengthGetter = Object.getOwnPropertyDescriptor(
+  typedArrayPrototype,
+  'byteLength',
+)?.get;
+const regExpSourceGetter = Object.getOwnPropertyDescriptor(
+  RegExp.prototype,
+  'source',
+)?.get;
+const regExpFlagGetters = [
+  ['d', 'hasIndices'],
+  ['g', 'global'],
+  ['i', 'ignoreCase'],
+  ['m', 'multiline'],
+  ['s', 'dotAll'],
+  ['u', 'unicode'],
+  ['v', 'unicodeSets'],
+  ['y', 'sticky'],
+].map(([flag, property]) => ({
+  flag,
+  getter: Object.getOwnPropertyDescriptor(
+    RegExp.prototype,
+    property,
+  )?.get,
+}));
+
+const exactSnapshotError = (
+  labelArg: string,
+  detailArg: string,
+): SmartdataExactPersistenceError =>
+  new SmartdataExactPersistenceError(
+    'invalid_document',
+    `${labelArg} ${detailArg}`,
+  );
+
+const constructExactBsonScalar = (
+  constructorArg: () => object,
+  labelArg: string,
+): object => {
+  try {
+    return constructorArg();
+  } catch (errorArg) {
+    if (errorArg instanceof SmartdataExactPersistenceError) {
+      throw errorArg;
+    }
+    throw new SmartdataExactPersistenceError(
+      'invalid_document',
+      `${labelArg} contains malformed BSON scalar data.`,
+      {
+        cause: errorArg,
+      },
+    );
+  }
+};
+
+const getOwnDataValue = (
+  valueArg: object,
+  keyArg: string,
+  labelArg: string,
+): unknown => {
+  const descriptor = Object.getOwnPropertyDescriptor(valueArg, keyArg);
+  if (!descriptor || !('value' in descriptor)) {
+    throw exactSnapshotError(
+      labelArg,
+      `contains a non-inert "${keyArg}" property.`,
+    );
+  }
+  return descriptor.value;
+};
+
+const getExactSnapshotBytes = (
+  valueArg: unknown,
+  labelArg: string,
+): Uint8Array => {
+  if (
+    typeof valueArg !== 'object' ||
+    valueArg === null ||
+    plugins.nodeUtil.types.isProxy(valueArg) ||
+    !ArrayBuffer.isView(valueArg) ||
+    !typedArrayBufferGetter ||
+    !typedArrayByteOffsetGetter ||
+    !typedArrayByteLengthGetter
+  ) {
+    throw exactSnapshotError(labelArg, 'contains invalid byte data.');
+  }
+  try {
+    const buffer = Reflect.apply(typedArrayBufferGetter, valueArg, []);
+    const byteOffset = Reflect.apply(typedArrayByteOffsetGetter, valueArg, []);
+    const byteLength = Reflect.apply(typedArrayByteLengthGetter, valueArg, []);
+    if (
+      !Number.isSafeInteger(byteOffset) ||
+      !Number.isSafeInteger(byteLength) ||
+      byteLength < 0 ||
+      byteLength > maxExactSnapshotByteLength
+    ) {
+      throw exactSnapshotError(labelArg, 'contains oversized byte data.');
+    }
+    return Uint8Array.from(
+      new Uint8Array(buffer, byteOffset, byteLength),
+    );
+  } catch (errorArg) {
+    if (errorArg instanceof SmartdataExactPersistenceError) {
+      throw errorArg;
+    }
+    throw exactSnapshotError(labelArg, 'contains invalid byte data.');
+  }
+};
+
+const markInertBsonSnapshot = <TValue extends object>(
+  valueArg: TValue,
+): TValue => {
+  Object.defineProperty(valueArg, 'toBSON', {
+    value: undefined,
+    enumerable: false,
+  });
+  return valueArg;
+};
+
+const snapshotInertExactValue = (
+  valueArg: unknown,
+  labelArg: string,
+  seenArg = new WeakSet<object>(),
+  depthArg = 0,
+): unknown => {
+  if (typeof valueArg === 'function' || typeof valueArg === 'symbol') {
+    throw exactSnapshotError(
+      labelArg,
+      'contains a value that cannot be inert BSON data.',
+    );
+  }
+  if (typeof valueArg !== 'object' || valueArg === null) {
+    return valueArg;
+  }
+  if (plugins.nodeUtil.types.isProxy(valueArg)) {
+    throw exactSnapshotError(labelArg, 'may not contain Proxy objects.');
+  }
+  if (seenArg.has(valueArg)) {
+    throw exactSnapshotError(labelArg, 'may not contain circular data.');
+  }
+  if (depthArg >= 100) {
+    throw exactSnapshotError(
+      labelArg,
+      'exceeds the maximum supported nesting depth.',
+    );
+  }
+  seenArg.add(valueArg);
+  try {
+    const prototype = Object.getPrototypeOf(valueArg);
+    if (Array.isArray(valueArg)) {
+      if (
+        prototype !== Array.prototype ||
+        valueArg.length > maxExactSnapshotArrayLength
+      ) {
+        throw exactSnapshotError(
+          labelArg,
+          'must be a bounded ordinary array.',
+        );
+      }
+      if (hasActiveInheritedToBsonEncoder(prototype)) {
+        throw exactSnapshotError(
+          labelArg,
+          'may not inherit a custom BSON encoder.',
+        );
+      }
+      const ownKeys = Reflect.ownKeys(valueArg);
+      const toBsonDescriptor = Object.getOwnPropertyDescriptor(
+        valueArg,
+        'toBSON',
+      );
+      if (
+        toBsonDescriptor &&
+        (
+          !('value' in toBsonDescriptor) ||
+          toBsonDescriptor.value !== undefined ||
+          toBsonDescriptor.enumerable === true
+        )
+      ) {
+        throw exactSnapshotError(
+          labelArg,
+          'arrays may contain only an inert non-enumerable toBSON marker.',
+        );
+      }
+      const indexedKeys = ownKeys.filter(
+        (keyArg) => keyArg !== 'length' && keyArg !== 'toBSON',
+      );
+      if (
+        indexedKeys.length !== valueArg.length ||
+        indexedKeys.some((keyArg) => {
+          if (
+            typeof keyArg !== 'string' ||
+            !/^(0|[1-9]\d*)$/.test(keyArg)
+          ) {
+            return true;
+          }
+          const index = Number(keyArg);
+          return !Number.isSafeInteger(index) || index >= valueArg.length;
+        })
+      ) {
+        throw exactSnapshotError(
+          labelArg,
+          'arrays must be dense and contain only indexed data properties.',
+        );
+      }
+      const snapshot: unknown[] = [];
+      for (let index = 0; index < valueArg.length; index++) {
+        const descriptor = Object.getOwnPropertyDescriptor(
+          valueArg,
+          String(index),
+        );
+        if (
+          !descriptor ||
+          !('value' in descriptor) ||
+          descriptor.enumerable !== true
+        ) {
+          throw exactSnapshotError(
+            labelArg,
+            'arrays may contain only inert enumerable data properties.',
+          );
+        }
+        snapshot.push(
+          snapshotInertExactValue(
+            descriptor.value,
+            `${labelArg}.${index}`,
+            seenArg,
+            depthArg + 1,
+          ),
+        );
+      }
+      return snapshot;
+    }
+    if (isPlainObject(valueArg)) {
+      const snapshot = Object.create(null) as Record<string, unknown>;
+      for (const key of Reflect.ownKeys(valueArg)) {
+        if (
+          typeof key !== 'string' ||
+          key === 'toBSON' ||
+          key === '_bsontype'
+        ) {
+          throw exactSnapshotError(
+            labelArg,
+            'may contain only ordinary string-keyed data.',
+          );
+        }
+        const descriptor = Object.getOwnPropertyDescriptor(valueArg, key);
+        if (
+          !descriptor ||
+          !('value' in descriptor) ||
+          descriptor.enumerable !== true
+        ) {
+          throw exactSnapshotError(
+            labelArg,
+            'may contain only inert enumerable data properties.',
+          );
+        }
+        snapshot[key] = snapshotInertExactValue(
+          descriptor.value,
+          `${labelArg}.${key}`,
+          seenArg,
+          depthArg + 1,
+        );
+      }
+      return snapshot;
+    }
+
+    if (hasActiveInheritedToBsonEncoder(prototype)) {
+      throw exactSnapshotError(
+        labelArg,
+        'may not inherit a custom BSON encoder.',
+      );
+    }
+
+    if (prototype === Date.prototype) {
+      if (Reflect.ownKeys(valueArg).length !== 0) {
+        throw exactSnapshotError(labelArg, 'contains a customized Date.');
+      }
+      return markInertBsonSnapshot(
+        new Date(Reflect.apply(Date.prototype.getTime, valueArg, [])),
+      );
+    }
+    if (prototype === RegExp.prototype) {
+      const ownKeys = Reflect.ownKeys(valueArg);
+      if (
+        ownKeys.length !== 1 ||
+        ownKeys[0] !== 'lastIndex' ||
+        !regExpSourceGetter
+      ) {
+        throw exactSnapshotError(
+          labelArg,
+          'contains a customized regular expression.',
+        );
+      }
+      const source = Reflect.apply(regExpSourceGetter, valueArg, []);
+      const flags = regExpFlagGetters
+        .filter(({ getter }) => getter && Reflect.apply(getter, valueArg, []))
+        .map(({ flag }) => flag)
+        .join('');
+      return markInertBsonSnapshot(new RegExp(source, flags));
+    }
+    if (prototype === Uint8Array.prototype) {
+      return markInertBsonSnapshot(
+        getExactSnapshotBytes(valueArg, labelArg),
+      );
+    }
+
+    const scalarToBsonDescriptor = Object.getOwnPropertyDescriptor(
+      valueArg,
+      'toBSON',
+    );
+    if (
+      scalarToBsonDescriptor &&
+      (
+        !('value' in scalarToBsonDescriptor) ||
+        scalarToBsonDescriptor.value !== undefined ||
+        scalarToBsonDescriptor.enumerable === true
+      )
+    ) {
+      throw exactSnapshotError(
+        labelArg,
+        'contains a customized BSON scalar encoder.',
+      );
+    }
+
+    let scalarSnapshot: object;
+    if (prototype === plugins.mongodb.ObjectId.prototype) {
+      scalarSnapshot = constructExactBsonScalar(
+        () => new plugins.mongodb.ObjectId(getInertObjectIdBytes(valueArg, () =>
+          exactSnapshotError(labelArg, 'contains a malformed or non-inert ObjectId.'))),
+        labelArg,
+      );
+    } else if (prototype === plugins.mongodb.UUID.prototype) {
+      scalarSnapshot = constructExactBsonScalar(
+        () => new plugins.mongodb.UUID(
+          getExactSnapshotBytes(
+            getOwnDataValue(valueArg, 'buffer', labelArg),
+            labelArg,
+          ),
+        ),
+        labelArg,
+      );
+    } else if (prototype === plugins.mongodb.Binary.prototype) {
+      const buffer = getExactSnapshotBytes(
+        getOwnDataValue(valueArg, 'buffer', labelArg),
+        labelArg,
+      );
+      const subType = getOwnDataValue(valueArg, 'sub_type', labelArg);
+      const position = getOwnDataValue(valueArg, 'position', labelArg);
+      if (
+        typeof subType !== 'number' ||
+        !Number.isSafeInteger(subType) ||
+        typeof position !== 'number' ||
+        !Number.isSafeInteger(position) ||
+        position < 0 ||
+        position > buffer.length
+      ) {
+        throw exactSnapshotError(labelArg, 'contains invalid binary data.');
+      }
+      scalarSnapshot = constructExactBsonScalar(
+        () => new plugins.mongodb.Binary(
+          buffer.subarray(0, position),
+          subType,
+        ),
+        labelArg,
+      );
+    } else if (prototype === plugins.mongodb.Decimal128.prototype) {
+      scalarSnapshot = constructExactBsonScalar(
+        () => new plugins.mongodb.Decimal128(
+          getExactSnapshotBytes(
+            getOwnDataValue(valueArg, 'bytes', labelArg),
+            labelArg,
+          ),
+        ),
+        labelArg,
+      );
+    } else if (prototype === plugins.mongodb.Int32.prototype) {
+      const value = getOwnDataValue(valueArg, 'value', labelArg);
+      if (!isSignedInt32(value)) {
+        throw exactSnapshotError(labelArg, 'contains an invalid Int32.');
+      }
+      scalarSnapshot = constructExactBsonScalar(
+        () => new plugins.mongodb.Int32(value),
+        labelArg,
+      );
+    } else if (prototype === plugins.mongodb.Double.prototype) {
+      const value = getOwnDataValue(valueArg, 'value', labelArg);
+      if (typeof value !== 'number') {
+        throw exactSnapshotError(labelArg, 'contains an invalid Double.');
+      }
+      scalarSnapshot = constructExactBsonScalar(
+        () => new plugins.mongodb.Double(value),
+        labelArg,
+      );
+    } else if (prototype === plugins.mongodb.Long.prototype) {
+      const low = getOwnDataValue(valueArg, 'low', labelArg);
+      const high = getOwnDataValue(valueArg, 'high', labelArg);
+      const unsigned = getOwnDataValue(valueArg, 'unsigned', labelArg);
+      if (
+        !isSignedInt32(low) ||
+        !isSignedInt32(high) ||
+        typeof unsigned !== 'boolean'
+      ) {
+        throw exactSnapshotError(labelArg, 'contains an invalid 64-bit value.');
+      }
+      scalarSnapshot = constructExactBsonScalar(
+        () => new plugins.mongodb.Long(low, high, unsigned),
+        labelArg,
+      );
+    } else if (prototype === plugins.mongodb.Timestamp.prototype) {
+      const low = getOwnDataValue(valueArg, 'low', labelArg);
+      const high = getOwnDataValue(valueArg, 'high', labelArg);
+      const unsigned = getOwnDataValue(valueArg, 'unsigned', labelArg);
+      if (!isSignedInt32(low) || !isSignedInt32(high) || unsigned !== true) {
+        throw exactSnapshotError(labelArg, 'contains an invalid Timestamp.');
+      }
+      scalarSnapshot = constructExactBsonScalar(
+        () => new plugins.mongodb.Timestamp(
+          new plugins.mongodb.Long(low, high, true),
+        ),
+        labelArg,
+      );
+    } else if (prototype === plugins.mongodb.BSONRegExp.prototype) {
+      const pattern = getOwnDataValue(valueArg, 'pattern', labelArg);
+      const options = getOwnDataValue(valueArg, 'options', labelArg);
+      if (typeof pattern !== 'string' || typeof options !== 'string') {
+        throw exactSnapshotError(labelArg, 'contains an invalid BSON regex.');
+      }
+      scalarSnapshot = constructExactBsonScalar(
+        () => new plugins.mongodb.BSONRegExp(pattern, options),
+        labelArg,
+      );
+    } else if (prototype === plugins.mongodb.BSONSymbol.prototype) {
+      const value = getOwnDataValue(valueArg, 'value', labelArg);
+      if (typeof value !== 'string') {
+        throw exactSnapshotError(labelArg, 'contains an invalid BSON symbol.');
+      }
+      scalarSnapshot = constructExactBsonScalar(
+        () => new plugins.mongodb.BSONSymbol(value),
+        labelArg,
+      );
+    } else if (prototype === plugins.mongodb.Code.prototype) {
+      const code = getOwnDataValue(valueArg, 'code', labelArg);
+      const scope = getOwnDataValue(valueArg, 'scope', labelArg);
+      if (typeof code !== 'string') {
+        throw exactSnapshotError(labelArg, 'contains invalid BSON code.');
+      }
+      scalarSnapshot = constructExactBsonScalar(
+        () => new plugins.mongodb.Code(
+          code,
+          scope === null
+            ? null
+            : snapshotInertExactValue(
+                scope,
+                `${labelArg}.scope`,
+                seenArg,
+                depthArg + 1,
+              ) as plugins.mongodb.Document,
+        ),
+        labelArg,
+      );
+    } else if (prototype === plugins.mongodb.DBRef.prototype) {
+      const collection = getOwnDataValue(valueArg, 'collection', labelArg);
+      const oid = snapshotInertExactValue(
+        getOwnDataValue(valueArg, 'oid', labelArg),
+        `${labelArg}.oid`,
+        seenArg,
+        depthArg + 1,
+      );
+      const db = getOwnDataValue(valueArg, 'db', labelArg);
+      const fields = snapshotInertExactValue(
+        getOwnDataValue(valueArg, 'fields', labelArg),
+        `${labelArg}.fields`,
+        seenArg,
+        depthArg + 1,
+      );
+      if (
+        typeof collection !== 'string' ||
+        !(oid instanceof plugins.mongodb.ObjectId) ||
+        (db !== undefined && typeof db !== 'string') ||
+        !isPlainObject(fields)
+      ) {
+        throw exactSnapshotError(labelArg, 'contains an invalid DBRef.');
+      }
+      scalarSnapshot = constructExactBsonScalar(
+        () => new plugins.mongodb.DBRef(
+          collection,
+          oid,
+          db,
+          fields,
+        ),
+        labelArg,
+      );
+    } else if (prototype === plugins.mongodb.MinKey.prototype) {
+      scalarSnapshot = new plugins.mongodb.MinKey();
+    } else if (prototype === plugins.mongodb.MaxKey.prototype) {
+      scalarSnapshot = new plugins.mongodb.MaxKey();
+    } else {
+      throw exactSnapshotError(
+        labelArg,
+        'contains an object with a custom BSON encoding boundary.',
+      );
+    }
+    return markInertBsonSnapshot(scalarSnapshot);
+  } finally {
+    seenArg.delete(valueArg);
+  }
+};
+
+const canonicalizeValue = <TValue>(
+  valueArg: TValue,
+  seenArg = new WeakSet<object>(),
+): TValue => {
+  if (typeof valueArg !== 'object' || valueArg === null) {
+    return valueArg;
+  }
+  const isArray = Array.isArray(valueArg);
+  if (!isArray && !isPlainObject(valueArg)) {
+    return valueArg;
+  }
+  if (seenArg.has(valueArg)) {
+    return valueArg;
+  }
+  seenArg.add(valueArg);
+  if (isArray) {
+    const canonicalArray = (valueArg as unknown[]).map((entryArg) =>
+      canonicalizeValue(entryArg, seenArg),
+    ) as TValue;
+    seenArg.delete(valueArg);
+    return canonicalArray;
+  }
+  const canonical = Object.create(null) as Record<string, unknown>;
+  for (const key of Object.keys(valueArg).sort()) {
+    const entry = valueArg[key];
+    if (entry !== undefined) {
+      canonical[key] = canonicalizeValue(entry, seenArg);
+    }
+  }
+  seenArg.delete(valueArg);
+  return canonical as TValue;
+};
+
+const isDuplicateKeyError = (errorArg: unknown): boolean => {
+  const mongoError = errorArg as { code?: number; codeName?: string } | undefined;
+  return mongoError?.code === 11000 || mongoError?.codeName === 'DuplicateKey';
+};
+
+const isTransientTransactionError = (
+  errorArg: unknown,
+  sessionArg?: plugins.mongodb.ClientSession,
+): boolean =>
+  Boolean(sessionArg)
+  && typeof (errorArg as { hasErrorLabel?: unknown })?.hasErrorLabel === 'function'
+  && (errorArg as { hasErrorLabel: (labelArg: string) => boolean })
+    .hasErrorLabel('TransientTransactionError');
+
+const hasActiveTransaction = (
+  sessionArg?: plugins.mongodb.ClientSession,
+): boolean => Boolean(sessionArg?.inTransaction());
+
+const unsupportedExactSave = async (): Promise<never> => {
+  throw new SmartdataExactPersistenceError(
+    'unsupported_operation',
+    'save() is unavailable for exact-persistence models. Use the model exact API.',
+  );
+};
+
+const forbiddenExactDelete = async (): Promise<never> => {
+  throw new SmartdataExactPersistenceError(
+    'unsupported_operation',
+    'delete() is forbidden for exact-persistence models.',
+  );
+};
+
+export class SmartdataExactCollection<
+  TModel extends SmartDataDbDoc<any, any, any>,
+  TPersisted extends object,
+> {
+  private initializationPromise?: Promise<void>;
+  private initializedCollection?: plugins.mongodb.Collection;
+  private initializationTarget?: plugins.mongodb.Collection;
+  private initializationGeneration = 0;
+  private readonly allowedPersistedKeys: ReadonlySet<string>;
+  private readonly uniqueIndexes: readonly string[];
+  private readonly reconcileBy: string;
+
+  constructor(
+    private readonly modelConstructor: IExactModelConstructor<TModel>,
+    private readonly collection: SmartdataCollection<any>,
+    private readonly options: IExactPersistenceOptions<TPersisted>,
+  ) {
+    // Field-decorator initializers materialize the model metadata on its
+    // prototype. Exact persistence uses that metadata as the ownership boundary.
+    new this.modelConstructor();
+    const prototype = this.modelConstructor.prototype;
+    this.allowedPersistedKeys = new Set(
+      [
+        ...(prototype.globalSaveableProperties || []),
+        ...(prototype.saveableProperties || []),
+      ].filter((keyArg) => !reservedKeys.includes(keyArg as TReservedKey)),
+    );
+    this.uniqueIndexes = [
+      ...new Set(prototype.uniqueIndexes || []),
+    ];
+    const identityValueTypes = prototype.identityValueTypes as
+      | Record<string, TSmartdataIdentityValueType>
+      | undefined;
+    const numericIdentityField = this.uniqueIndexes.find(
+      (fieldArg) => identityValueTypes?.[fieldArg] === 'positiveSafeInteger',
+    );
+    if (numericIdentityField) {
+      throw new SmartdataExactPersistenceError(
+        'invalid_configuration',
+        `Exact persistence identity field "${numericIdentityField}" must use the default string valueType.`,
+      );
+    }
+
+    const explicitReconcileBy = options.reconcileBy as string | undefined;
+    if (explicitReconcileBy) {
+      if (
+        !this.allowedPersistedKeys.has(explicitReconcileBy) ||
+        !this.uniqueIndexes.includes(explicitReconcileBy)
+      ) {
+        throw new SmartdataExactPersistenceError(
+          'invalid_configuration',
+          `Exact persistence reconcileBy field "${explicitReconcileBy}" must be a persisted field decorated with @unI().`,
+        );
+      }
+      this.reconcileBy = explicitReconcileBy;
+    } else if (this.uniqueIndexes.length === 1) {
+      this.reconcileBy = this.uniqueIndexes[0];
+    } else if (this.uniqueIndexes.length === 0) {
+      throw new SmartdataExactPersistenceError(
+        'invalid_configuration',
+        'Exact persistence requires at least one persisted field decorated with @unI().',
+      );
+    } else {
+      throw new SmartdataExactPersistenceError(
+        'invalid_configuration',
+        `Exact persistence requires reconcileBy when the model has multiple @unI() fields.`,
+      );
+    }
+    registerCollectionReconnectHandler(this.collection, () => {
+      this.initializationGeneration++;
+      this.initializationPromise = undefined;
+      this.initializedCollection = undefined;
+      this.initializationTarget = undefined;
+    });
+  }
+
+  private async initialize(): Promise<void> {
+    await this.collection.init();
+    if (this.initializedCollection === this.collection.mongoDbCollection) {
+      return;
+    }
+    const targetCollection = this.collection.mongoDbCollection;
+    if (this.initializationTarget !== targetCollection) {
+      this.initializationTarget = targetCollection;
+      this.initializationPromise = undefined;
+      this.initializationGeneration++;
+    }
+    if (!this.initializationPromise) {
+      const generation = this.initializationGeneration;
+      const initializationPromise = this.initializeOnce(targetCollection)
+        .then(() => {
+          if (
+            this.initializationGeneration === generation
+            && this.collection.mongoDbCollection === targetCollection
+          ) {
+            this.initializedCollection = targetCollection;
+          }
+        })
+        .catch((errorArg) => {
+          if (this.initializationPromise === initializationPromise) {
+            this.initializationPromise = undefined;
+          }
+          throw errorArg;
+        });
+      this.initializationPromise = initializationPromise;
+    }
+    await this.initializationPromise;
+    if (this.initializedCollection !== this.collection.mongoDbCollection) {
+      await this.initialize();
+    }
+  }
+
+  private async initializeOnce(
+    targetCollectionArg: plugins.mongodb.Collection,
+  ): Promise<void> {
+    const missingUniqueIndexes = this.uniqueIndexes.filter(
+      (uniqueIndexArg) => !this.collection.uniqueIndexes.includes(uniqueIndexArg),
+    );
+    for (const uniqueIndex of missingUniqueIndexes) {
+      await targetCollectionArg.createIndex(
+        { [uniqueIndex]: 1 },
+        { unique: true, name: `${uniqueIndex}_1` },
+      );
+    }
+
+    const regularIndexes = this.modelConstructor.prototype.regularIndexes || [];
+    const missingRegularIndexes = regularIndexes.filter((regularIndexArg) =>
+      !this.collection.regularIndexes.some(
+        (existingIndexArg) => existingIndexArg.field === regularIndexArg.field,
+      )
+    );
+    for (const regularIndex of missingRegularIndexes) {
+      await targetCollectionArg.createIndex(
+        { [regularIndex.field]: 1 },
+        regularIndex.options,
+      );
+    }
+    if (this.collection.mongoDbCollection !== targetCollectionArg) {
+      return;
+    }
+    for (const uniqueIndex of missingUniqueIndexes) {
+      if (!this.collection.uniqueIndexes.includes(uniqueIndex)) {
+        this.collection.uniqueIndexes.push(uniqueIndex);
+      }
+    }
+    for (const regularIndex of missingRegularIndexes) {
+      if (!this.collection.regularIndexes.some(
+        (existingIndexArg) => existingIndexArg.field === regularIndex.field,
+      )) {
+        this.collection.regularIndexes.push(regularIndex);
+      }
+    }
+  }
+
+  public async prepare(): Promise<void> {
+    await this.initialize();
+  }
+
+  private async beginOperation(
+    optionsArg: IExactSessionOptions,
+    signalArg?: AbortSignal,
+  ): Promise<{
+    session?: plugins.mongodb.ClientSession;
+    release: () => void;
+  }> {
+    signalArg?.throwIfAborted();
+    if (!optionsArg.session) {
+      await waitWithSignal(this.initialize(), signalArg);
+      signalArg?.throwIfAborted();
+      return { release: () => {} };
+    }
+    if (
+      !this.collection.isInitializedForCurrentDatabase()
+      || this.initializedCollection !== this.collection.mongoDbCollection
+    ) {
+      throw new SmartdataExactPersistenceError(
+        'unsupported_operation',
+        'Exact collection must be prepared before it participates in a transaction.',
+      );
+    }
+    const lease = acquireSmartdataSession(
+      optionsArg.session,
+      this.collection.smartdataDb,
+    );
+    if (signalArg?.aborted) {
+      lease.release();
+      signalArg.throwIfAborted();
+    }
+    return {
+      session: lease.rawSession,
+      release: lease.release,
+    };
+  }
+
+  private async runOperation<TResult>(
+    optionsArg: IExactSessionOptions,
+    operationArg: (
+      sessionArg?: plugins.mongodb.ClientSession,
+    ) => Promise<TResult>,
+    signalArg?: AbortSignal,
+  ): Promise<TResult> {
+    const operation = await this.beginOperation(optionsArg, signalArg);
+    try {
+      signalArg?.throwIfAborted();
+      return await operationArg(operation.session);
+    } finally {
+      operation.release();
+    }
+  }
+
+  private canonicalizeDocument<TDocument extends object>(
+    documentArg: TDocument,
+    labelArg: string,
+  ): TDocument {
+    let canonicalInput: TDocument;
+    let serialized: Uint8Array;
+    let canonical: TDocument;
+    let reserialized: Uint8Array;
+    try {
+      canonicalInput = canonicalizeValue(documentArg);
+      serialized = plugins.mongodb.BSON.serialize(canonicalInput);
+      canonical = canonicalizeValue(
+        plugins.mongodb.BSON.deserialize(serialized) as TDocument,
+      );
+      reserialized = plugins.mongodb.BSON.serialize(canonical);
+    } catch (errorArg) {
+      throw new SmartdataExactPersistenceError(
+        'invalid_document',
+        `${labelArg} is not BSON serializable.`,
+        { cause: errorArg },
+      );
+    }
+    if (!bytesEqual(serialized, reserialized)) {
+      throw new SmartdataExactPersistenceError(
+        'noncanonical_document',
+        `${labelArg} is not byte-stable across a BSON roundtrip.`,
+      );
+    }
+    return canonical;
+  }
+
+  private assertAllowedTopLevelKeys(
+    documentArg: object,
+    allowedMetadataKeysArg: readonly TStorageMetadataKey[],
+    labelArg: string,
+  ): void {
+    const allowedMetadataKeys = new Set<string>(allowedMetadataKeysArg);
+    for (const key of Object.keys(documentArg)) {
+      if (
+        reservedKeys.includes(key as TReservedKey) &&
+        !allowedMetadataKeys.has(key)
+      ) {
+        throw new SmartdataExactPersistenceError(
+          'reserved_field',
+          `${labelArg} may not define reserved field "${key}".`,
+        );
+      }
+      if (
+        !this.allowedPersistedKeys.has(key) &&
+        !allowedMetadataKeys.has(key)
+      ) {
+        throw new SmartdataExactPersistenceError(
+          'invalid_document',
+          `${labelArg} defines undeclared top-level field "${key}".`,
+        );
+      }
+    }
+  }
+
+  private canonicalizePersistedDocument(
+    documentArg: object,
+  ): TExactPersistedDocument<TPersisted> {
+    this.assertAllowedTopLevelKeys(documentArg, [], 'Persisted document');
+    const canonical = this.canonicalizeDocument(
+      documentArg,
+      'Persisted document',
+    );
+    this.assertWithoutMutation(canonical, 'Persisted document');
+    return canonical as TExactPersistedDocument<TPersisted>;
+  }
+
+  private canonicalizeStoredDocument(
+    documentArg: object,
+  ): TStoredDocument<TPersisted> {
+    this.assertAllowedTopLevelKeys(
+      documentArg,
+      storageMetadataKeys,
+      'Stored document',
+    );
+    const canonical = this.canonicalizeDocument(documentArg, 'Stored document');
+    const revision = (canonical as Record<string, unknown>)._smartdataRevision;
+    if (!isMongoObjectId((canonical as Record<string, unknown>)._id)) {
+      throw new SmartdataExactPersistenceError(
+        'invalid_document',
+        'Stored document _id must be a MongoDB ObjectId.',
+      );
+    }
+    if (
+      revision !== undefined &&
+      (typeof revision !== 'string' || revision.length === 0)
+    ) {
+      throw new SmartdataExactPersistenceError(
+        'invalid_document',
+        'Stored document _smartdataRevision must be a nonempty string when present.',
+      );
+    }
+    this.getPersistedBody(canonical as TStoredDocument<TPersisted>);
+    return canonical as TStoredDocument<TPersisted>;
+  }
+
+  private assertWithoutMutation(
+    documentArg: object,
+    labelArg: string,
+  ): void {
+    assertBsonWithoutMutation(documentArg, this.options.assertDocument, (reasonArg, causeArg) =>
+      new SmartdataExactPersistenceError('invalid_document', `${labelArg} ${
+        reasonArg === 'assertion' ? 'assertion failed.' :
+        reasonArg === 'bson' ? 'validator produced a non-BSON document.' :
+        'validator must not mutate the document.'
+      }`, causeArg === undefined ? undefined : { cause: causeArg }));
+  }
+
+  private getPersistedBody(
+    storedDocumentArg: TStoredDocument<TPersisted>,
+  ): TExactPersistedDocument<TPersisted> {
+    const body = Object.create(null) as Record<string, unknown>;
+    for (const key of Object.keys(storedDocumentArg)) {
+      if (!reservedKeys.includes(key as TReservedKey)) {
+        body[key] = (storedDocumentArg as Record<string, unknown>)[key];
+      }
+    }
+    return this.canonicalizePersistedDocument(body);
+  }
+
+  private persistedDocumentsEqual(
+    leftArg: TExactPersistedDocument<TPersisted>,
+    rightArg: TExactPersistedDocument<TPersisted>,
+  ): boolean {
+    return bytesEqual(
+      plugins.mongodb.BSON.serialize(leftArg),
+      plugins.mongodb.BSON.serialize(rightArg),
+    );
+  }
+
+  private storedDocumentsEqual(
+    leftArg: TStoredDocument<TPersisted>,
+    rightArg: TStoredDocument<TPersisted>,
+  ): boolean {
+    if (!leftArg._id.equals(rightArg._id)) {
+      return false;
+    }
+    if (leftArg._smartdataRevision !== rightArg._smartdataRevision) {
+      return false;
+    }
+    return this.persistedDocumentsEqual(
+      this.getPersistedBody(leftArg),
+      this.getPersistedBody(rightArg),
+    );
+  }
+
+  private validateReconcileIdentity(
+    documentArg: TExactPersistedDocument<TPersisted>,
+  ): string {
+    const value = (documentArg as Record<string, unknown>)[this.reconcileBy];
+    if (typeof value !== 'string' || value.trim().length === 0) {
+      throw new SmartdataExactPersistenceError(
+        'invalid_document',
+        `Exact persistence reconcileBy field "${this.reconcileBy}" must be a nonempty string.`,
+      );
+    }
+    return value;
+  }
+
+  private async serializeModel(
+    modelArg: TModel,
+  ): Promise<TExactPersistedDocument<TPersisted>> {
+    const serialized = (await modelArg.createSavableObject()) as Record<
+      string,
+      unknown
+    >;
+    if (
+      typeof serialized !== 'object' ||
+      serialized === null ||
+      Array.isArray(serialized)
+    ) {
+      throw new SmartdataExactPersistenceError(
+        'invalid_document',
+        'createSavableObject() must return a document object.',
+      );
+    }
+    for (const key of Object.keys(serialized)) {
+      if (
+        !this.allowedPersistedKeys.has(key) &&
+        key !== '_createdAt' &&
+        key !== '_updatedAt'
+      ) {
+        const code: TExactPersistenceErrorCode = reservedKeys.includes(
+          key as TReservedKey,
+        )
+          ? 'reserved_field'
+          : 'invalid_document';
+        throw new SmartdataExactPersistenceError(
+          code,
+          `Model serialization produced forbidden top-level field "${key}".`,
+        );
+      }
+    }
+    const body = Object.create(null) as Record<string, unknown>;
+    for (const key of this.allowedPersistedKeys) {
+      if (hasOwn(serialized, key)) {
+        body[key] = serialized[key];
+      }
+    }
+    return this.canonicalizePersistedDocument(body);
+  }
+
+  private async createPersistedDocument(
+    documentArg: TModel | TExactPersistedDocument<TPersisted>,
+  ): Promise<TExactPersistedDocument<TPersisted>> {
+    if (typeof documentArg !== 'object' || documentArg === null) {
+      throw new SmartdataExactPersistenceError(
+        'invalid_document',
+        'Exact persistence insert input must be an object.',
+      );
+    }
+    if (documentArg instanceof this.modelConstructor) {
+      return this.serializeModel(documentArg);
+    }
+    return this.canonicalizePersistedDocument(documentArg);
+  }
+
+  private hydrateStoredDocument(
+    documentArg: TStoredDocument<TPersisted>,
+  ): TModel {
+    return this.modelConstructor.createInstanceFromMongoDbNativeDoc<TModel>(
+      documentArg,
+    );
+  }
+
+  private async findByReconcileIdentity(
+    identityArg: string,
+    sessionArg?: plugins.mongodb.ClientSession,
+  ): Promise<TStoredDocument<TPersisted> | null> {
+    const rawDocument = await this.collection.mongoDbCollection.findOne({
+      [this.reconcileBy]: identityArg,
+    }, { session: sessionArg });
+    return rawDocument
+      ? this.canonicalizeStoredDocument(rawDocument)
+      : null;
+  }
+
+  private ambiguousWriteError(messageArg: string, causeArg: unknown): Error {
+    return new SmartdataExactPersistenceError('ambiguous_write', messageArg, {
+      cause: causeArg,
+    });
+  }
+
+  private canonicalizeDeleteCurrent(
+    optionsArg: {
+      current: TStoredDocument<TPersisted>;
+    },
+  ): {
+    current: TStoredDocument<TPersisted>;
+    identity: string;
+  } {
+    if (
+      typeof optionsArg !== 'object' ||
+      optionsArg === null ||
+      plugins.nodeUtil.types.isProxy(optionsArg) ||
+      !isPlainObject(optionsArg)
+    ) {
+      throw new SmartdataExactPersistenceError(
+        'invalid_document',
+        'Exact delete options must be an object containing only current.',
+      );
+    }
+    const optionKeys = Reflect.ownKeys(optionsArg);
+    const currentDescriptor = Object.getOwnPropertyDescriptor(
+      optionsArg,
+      'current',
+    );
+    if (
+      optionKeys.length !== 1 ||
+      optionKeys[0] !== 'current' ||
+      !currentDescriptor ||
+      !('value' in currentDescriptor) ||
+      currentDescriptor.enumerable !== true
+    ) {
+      throw new SmartdataExactPersistenceError(
+        'invalid_document',
+        'Exact delete options must contain one inert enumerable current data property.',
+      );
+    }
+    const currentSnapshot = snapshotInertExactValue(
+      currentDescriptor.value,
+      'Exact delete current',
+    );
+    const current = this.canonicalizeStoredDocument(
+      currentSnapshot as object,
+    );
+    const identity = this.validateReconcileIdentity(
+      this.getPersistedBody(current),
+    );
+    return { current, identity };
+  }
+
+  private async reconcileDeleteOutcome(
+    currentArg: TStoredDocument<TPersisted>,
+    identityArg: string,
+    causeArg: unknown,
+    sessionArg?: plugins.mongodb.ClientSession,
+  ): Promise<TExactDeleteResult> {
+    let reconciled: TStoredDocument<TPersisted> | null;
+    try {
+      reconciled = await this.findByReconcileIdentity(identityArg, sessionArg);
+    } catch (errorArg) {
+      if (isTransientTransactionError(errorArg, sessionArg)) {
+        throw errorArg;
+      }
+      throw this.ambiguousWriteError(
+        'Exact delete outcome was inconclusive and reconciliation could not be completed.',
+        causeArg,
+      );
+    }
+    if (reconciled && reconciled._id.equals(currentArg._id)) {
+      return { status: 'concurrent_change', deletedCount: 0 };
+    }
+    throw this.ambiguousWriteError(
+      'Exact delete outcome was inconclusive and could not be authoritatively reconciled.',
+      causeArg,
+    );
+  }
+
+  public async insert(
+    documentArg: TModel | TExactPersistedDocument<TPersisted>,
+    optionsArg: IExactSessionOptions = {},
+  ): Promise<TExactInsertResult<TPersisted>> {
+    return this.runOperation(optionsArg, async (sessionArg) => {
+    const persistedDocument = await this.createPersistedDocument(documentArg);
+    const identity = this.validateReconcileIdentity(persistedDocument);
+    const expectedStoredDocument = this.canonicalizeStoredDocument({
+      _id: new plugins.mongodb.ObjectId(),
+      ...persistedDocument,
+    });
+    if (hasActiveTransaction(sessionArg)) {
+      const existing = await this.findByReconcileIdentity(identity, sessionArg);
+      if (existing) {
+        return this.persistedDocumentsEqual(
+          this.getPersistedBody(existing),
+          persistedDocument,
+        )
+          ? { status: 'already_committed', document: existing }
+          : { status: 'conflict', document: existing };
+      }
+    }
+
+    let result: plugins.mongodb.InsertOneResult;
+    try {
+      result = await this.collection.mongoDbCollection.insertOne(
+        expectedStoredDocument,
+        { session: sessionArg },
+      );
+    } catch (errorArg) {
+      if (isTransientTransactionError(errorArg, sessionArg)) {
+        throw errorArg;
+      }
+      if (hasActiveTransaction(sessionArg)) {
+        if (isDuplicateKeyError(errorArg)) {
+          throw new SmartdataExactPersistenceError(
+            'unique_conflict',
+            'Exact transactional insert conflicts with a unique index.',
+            { cause: errorArg },
+          );
+        }
+        throw errorArg;
+      }
+      let reconciled: TStoredDocument<TPersisted> | null;
+      try {
+        reconciled = await this.findByReconcileIdentity(identity, sessionArg);
+      } catch (reconciliationError) {
+        if (isTransientTransactionError(reconciliationError, sessionArg)) {
+          throw reconciliationError;
+        }
+        if (isDuplicateKeyError(errorArg)) {
+          throw new SmartdataExactPersistenceError(
+            'unique_conflict',
+            'Exact insert conflicts with a unique index and reconciliation failed.',
+            { cause: errorArg },
+          );
+        }
+        throw this.ambiguousWriteError(
+          'Exact insert failed and reconciliation could not be completed.',
+          errorArg,
+        );
+      }
+      if (reconciled) {
+        if (
+          this.persistedDocumentsEqual(
+            this.getPersistedBody(reconciled),
+            persistedDocument,
+          )
+        ) {
+          return { status: 'already_committed', document: reconciled };
+        }
+        if (isDuplicateKeyError(errorArg)) {
+          return { status: 'conflict', document: reconciled };
+        }
+      }
+      if (isDuplicateKeyError(errorArg)) {
+        throw new SmartdataExactPersistenceError(
+          'unique_conflict',
+          'Exact insert conflicts with a secondary unique index.',
+          { cause: errorArg },
+        );
+      }
+      throw this.ambiguousWriteError(
+        'Exact insert failed and its outcome could not be reconciled.',
+        errorArg,
+      );
+    }
+
+    if (!result.acknowledged) {
+      if (hasActiveTransaction(sessionArg)) {
+        throw this.ambiguousWriteError(
+          'Exact transactional insert was not acknowledged.',
+          result,
+        );
+      }
+      let reconciled: TStoredDocument<TPersisted> | null;
+      try {
+        reconciled = await this.findByReconcileIdentity(identity, sessionArg);
+      } catch (errorArg) {
+        if (isTransientTransactionError(errorArg, sessionArg)) {
+          throw errorArg;
+        }
+        throw this.ambiguousWriteError(
+          'Exact insert was not acknowledged and reconciliation could not be completed.',
+          result,
+        );
+      }
+      if (
+        reconciled &&
+        this.persistedDocumentsEqual(
+          this.getPersistedBody(reconciled),
+          persistedDocument,
+        )
+      ) {
+        return { status: 'already_committed', document: reconciled };
+      }
+      throw this.ambiguousWriteError(
+        'Exact insert was not acknowledged and could not be reconciled.',
+        result,
+      );
+    }
+    return { status: 'inserted', document: expectedStoredDocument };
+    });
+  }
+
+  public toPersisted(
+    storedDocumentArg: TStoredDocument<TPersisted>,
+  ): TExactPersistedDocument<TPersisted> {
+    const storedDocument = this.canonicalizeStoredDocument(storedDocumentArg);
+    const persistedDocument = this.getPersistedBody(storedDocument);
+    return plugins.mongodb.BSON.deserialize(
+      plugins.mongodb.BSON.serialize(persistedDocument),
+    ) as TExactPersistedDocument<TPersisted>;
+  }
+
+  public canonicalBytes(
+    persistedDocumentArg: TExactPersistedDocument<TPersisted>,
+  ): Uint8Array {
+    return plugins.mongodb.BSON.serialize(
+      this.canonicalizePersistedDocument(persistedDocumentArg),
+    );
+  }
+
+  public async findStoredOne(
+    filterArg: MongoFilter<TStoredDocument<TPersisted>>,
+    optionsArg: IExactReadOptions = {},
+  ): Promise<TStoredDocument<TPersisted> | null> {
+    return this.runOperation(optionsArg, async (sessionArg) => {
+    const cursor = this.collection.mongoDbCollection.find(
+      convertFilterForMongoDb(filterArg),
+      {
+        session: sessionArg,
+        signal: optionsArg.signal,
+        singleBatch: true,
+      },
+    ).limit(1);
+    const nativeCursorClose = cursor.close.bind(cursor);
+    let cursorClosePromise: Promise<void> | undefined;
+    cursor.close = ((...args: Parameters<typeof cursor.close>) => {
+      cursorClosePromise ??= nativeCursorClose(...args);
+      return cursorClosePromise;
+    }) as typeof cursor.close;
+    let storedDocument: TStoredDocument<TPersisted> | null;
+    try {
+      const rawDocument = await cursor.next();
+      storedDocument = rawDocument
+        ? this.canonicalizeStoredDocument(rawDocument)
+        : null;
+    } catch (errorArg) {
+      try {
+        await cursor.close();
+      } catch {
+        // Cleanup must not replace the exact primary operation error.
+      }
+      throw errorArg;
+    }
+    await cursor.close();
+    return storedDocument;
+    }, optionsArg.signal);
+  }
+
+  public async findStored(
+    optionsArg: IFindStoredOptions<TPersisted> = {},
+  ): Promise<Array<TStoredDocument<TPersisted>>> {
+    optionsArg.signal?.throwIfAborted();
+    return this.runOperation(optionsArg, async (sessionArg) => {
+    let cursor = this.collection.mongoDbCollection.find(
+      convertFilterForMongoDb(optionsArg.filter || {}),
+      { session: sessionArg, signal: optionsArg.signal },
+    );
+    // The driver abort listener does not await close, so every close must join
+    // the same native cleanup before runOperation releases its session lease.
+    const nativeCursorClose = cursor.close.bind(cursor);
+    let cursorClosePromise: Promise<void> | undefined;
+    cursor.close = ((...args: Parameters<typeof cursor.close>) => {
+      cursorClosePromise ??= nativeCursorClose(...args);
+      return cursorClosePromise;
+    }) as typeof cursor.close;
+    let storedDocuments: Array<TStoredDocument<TPersisted>>;
+    try {
+      if (optionsArg.sort) {
+        cursor = cursor.sort(optionsArg.sort as plugins.mongodb.Sort);
+      }
+      if (optionsArg.skip !== undefined) {
+        cursor = cursor.skip(optionsArg.skip);
+      }
+      if (optionsArg.limit !== undefined) {
+        cursor = cursor.limit(optionsArg.limit);
+      }
+      const rawDocuments = await cursor.toArray();
+      storedDocuments = rawDocuments.map((documentArg) =>
+        this.canonicalizeStoredDocument(documentArg),
+      );
+    } catch (errorArg) {
+      try {
+        await cursor.close();
+      } catch {
+        // Cleanup must not replace the exact primary operation error.
+      }
+      throw errorArg;
+    }
+    await cursor.close();
+    return storedDocuments;
+    }, optionsArg.signal);
+  }
+
+  public async count(
+    filterArg: MongoFilter<TStoredDocument<TPersisted>> = {},
+    optionsArg: IExactSessionOptions = {},
+  ): Promise<number> {
+    return this.runOperation(optionsArg, async (sessionArg) =>
+      this.collection.mongoDbCollection.countDocuments(
+        convertFilterForMongoDb(filterArg),
+        { session: sessionArg },
+      )
+    );
+  }
+
+  public async distinct<
+    TField extends TExactDocumentPath<TStoredDocument<TPersisted>>,
+  >(
+    fieldArg: TField,
+    filterArg: MongoFilter<TStoredDocument<TPersisted>> = {},
+    optionsArg: IExactSessionOptions = {},
+  ): Promise<Array<TExactDistinctValue<
+    TExactDocumentPathValue<TStoredDocument<TPersisted>, TField>
+  >>> {
+    return this.runOperation(optionsArg, async (sessionArg) =>
+      (await this.collection.mongoDbCollection.distinct(
+        fieldArg as string,
+        convertFilterForMongoDb(filterArg),
+        { session: sessionArg },
+      )) as Array<TExactDistinctValue<
+        TExactDocumentPathValue<TStoredDocument<TPersisted>, TField>
+      >>
+    );
+  }
+
+  public async transition(
+    optionsArg: {
+      current: TStoredDocument<TPersisted>;
+      change: (modelArg: TModel) => void;
+    },
+    sessionOptionsArg: IExactSessionOptions = {},
+  ): Promise<TExactTransitionResult<TPersisted>> {
+    return this.runOperation(sessionOptionsArg, async (sessionArg) => {
+    const current = this.canonicalizeStoredDocument(optionsArg.current);
+    const currentBody = this.getPersistedBody(current);
+    const currentIdentity = this.validateReconcileIdentity(currentBody);
+    const model = this.hydrateStoredDocument(current);
+    const untouchedBody = await this.serializeModel(model);
+    if (!this.persistedDocumentsEqual(currentBody, untouchedBody)) {
+      throw new SmartdataExactPersistenceError(
+        'noncanonical_document',
+        'Stored document does not survive an untouched model serialization roundtrip.',
+      );
+    }
+
+    const changeResult = optionsArg.change(model);
+    if (
+      changeResult !== null &&
+      (typeof changeResult === 'object' || typeof changeResult === 'function') &&
+      typeof (changeResult as { then?: unknown }).then === 'function'
+    ) {
+      void Promise.resolve(changeResult).catch(() => undefined);
+      throw new SmartdataExactPersistenceError(
+        'unsupported_operation',
+        'Exact persistence transition callbacks must be synchronous.',
+      );
+    }
+
+    const candidateBody = await this.serializeModel(model);
+    const candidateIdentity = this.validateReconcileIdentity(candidateBody);
+    if (candidateIdentity !== currentIdentity) {
+      throw new SmartdataExactPersistenceError(
+        'invalid_document',
+        `Exact persistence reconcileBy field "${this.reconcileBy}" is immutable.`,
+      );
+    }
+    const newRevision = globalThis.crypto.randomUUID();
+    const expectedStoredDocument = this.canonicalizeStoredDocument({
+      _id: current._id,
+      ...candidateBody,
+      _smartdataRevision: newRevision,
+    });
+    const selector = current._smartdataRevision !== undefined
+      ? { _id: current._id, _smartdataRevision: current._smartdataRevision }
+      : { _id: current._id, _smartdataRevision: { $exists: false } };
+
+    try {
+      const postimage = await this.collection.mongoDbCollection.findOneAndReplace(
+        selector,
+        expectedStoredDocument,
+        {
+          returnDocument: 'after',
+          includeResultMetadata: false,
+          upsert: false,
+          session: sessionArg,
+        },
+      );
+      if (!postimage) {
+        return { status: 'concurrent_change' };
+      }
+      const canonicalPostimage = this.canonicalizeStoredDocument(postimage);
+      if (!this.storedDocumentsEqual(canonicalPostimage, expectedStoredDocument)) {
+        throw new SmartdataExactPersistenceError(
+          'ambiguous_write',
+          'Exact transition returned a postimage different from the requested state.',
+        );
+      }
+      return { status: 'transitioned', document: canonicalPostimage };
+    } catch (errorArg) {
+      if (isTransientTransactionError(errorArg, sessionArg)) {
+        throw errorArg;
+      }
+      if (isDuplicateKeyError(errorArg)) {
+        throw new SmartdataExactPersistenceError(
+          'unique_conflict',
+          'Exact transition conflicts with a secondary unique index.',
+          { cause: errorArg },
+        );
+      }
+      if (hasActiveTransaction(sessionArg)) {
+        throw errorArg;
+      }
+      try {
+        const reconciledRaw = await this.collection.mongoDbCollection.findOne({
+          _id: current._id,
+        }, { session: sessionArg });
+        if (reconciledRaw) {
+          const reconciled = this.canonicalizeStoredDocument(reconciledRaw);
+          if (
+            reconciled._smartdataRevision === newRevision &&
+            this.storedDocumentsEqual(reconciled, expectedStoredDocument)
+          ) {
+            return { status: 'transitioned', document: reconciled };
+          }
+        }
+      } catch (reconciliationError) {
+        if (isTransientTransactionError(reconciliationError, sessionArg)) {
+          throw reconciliationError;
+        }
+        throw this.ambiguousWriteError(
+          'Exact transition failed and reconciliation could not be completed.',
+          errorArg,
+        );
+      }
+      throw this.ambiguousWriteError(
+        'Exact transition failed and its outcome could not be reconciled.',
+        errorArg,
+      );
+    }
+    });
+  }
+
+  public async delete(
+    optionsArg: {
+      current: TStoredDocument<TPersisted>;
+    },
+    sessionOptionsArg: IExactSessionOptions = {},
+  ): Promise<TExactDeleteResult> {
+    const { current, identity } = this.canonicalizeDeleteCurrent(optionsArg);
+    return this.runOperation(sessionOptionsArg, async (sessionArg) => {
+    const selector = current._smartdataRevision !== undefined
+      ? {
+          _id: current._id,
+          [this.reconcileBy]: identity,
+          _smartdataRevision: current._smartdataRevision,
+        }
+      : {
+          _id: current._id,
+          [this.reconcileBy]: identity,
+          _smartdataRevision: { $exists: false },
+        };
+    let result: plugins.mongodb.DeleteResult;
+    try {
+      result = await this.collection.mongoDbCollection.deleteOne(selector, {
+        session: sessionArg,
+      });
+    } catch (errorArg) {
+      if (isTransientTransactionError(errorArg, sessionArg)) {
+        throw errorArg;
+      }
+      if (hasActiveTransaction(sessionArg)) {
+        throw errorArg;
+      }
+      return this.reconcileDeleteOutcome(current, identity, errorArg, sessionArg);
+    }
+    if (
+      result.acknowledged === true &&
+      result.deletedCount === 1
+    ) {
+      return { status: 'deleted', deletedCount: 1 };
+    }
+    if (
+      result.acknowledged === true &&
+      result.deletedCount === 0
+    ) {
+      return { status: 'concurrent_change', deletedCount: 0 };
+    }
+    if (result.acknowledged === false) {
+      if (hasActiveTransaction(sessionArg)) {
+        throw this.ambiguousWriteError(
+          'Exact transactional delete was not acknowledged.',
+          result,
+        );
+      }
+      return this.reconcileDeleteOutcome(current, identity, result, sessionArg);
+    }
+
+    try {
+      await this.findByReconcileIdentity(identity, sessionArg);
+    } catch (errorArg) {
+      if (isTransientTransactionError(errorArg, sessionArg)) {
+        throw errorArg;
+      }
+      throw this.ambiguousWriteError(
+        'Exact delete returned an invalid result and reconciliation could not be completed.',
+        result,
+      );
+    }
+    throw this.ambiguousWriteError(
+      'Exact delete returned an invalid acknowledged result.',
+      result,
+    );
+    });
+  }
+}
+
+export function exactPersistence<
+  TAssertion extends TExactDocumentAssertion<object>,
+>(
+  optionsArg: {
+    assertDocument: TAssertion;
+    reconcileBy?: TExactIdentityKey<TExactAssertedDocument<TAssertion>>;
+  },
+) {
+  type TPersisted = TExactAssertedDocument<TAssertion>;
+  return function classDecorator<
+    TConstructor extends new (
+      ...args: any[]
+    ) => SmartDataDbDoc<any, TPersisted, any> & TPersisted,
+  >(
+    valueArg: TConstructor,
+    contextArg: ClassDecoratorContext,
+  ): void {
+    if (contextArg.kind !== 'class') {
+      throw new Error('exactPersistence can only decorate classes.');
+    }
+    if (getOrdinaryPersistencePolicy(valueArg)) {
+      throw new Error('Ordinary and exact persistence policies cannot be combined.');
+    }
+
+    const exactOptions = Object.freeze({ ...optionsArg }) as unknown as
+      IExactPersistenceOptions<TPersisted>;
+    const constructor = valueArg as unknown as IExactModelConstructor<
+      SmartDataDbDoc<any, TPersisted>
+    >;
+
+    const exactPolicy = Object.freeze({
+      options: exactOptions,
+      unsupportedSave: unsupportedExactSave,
+      forbiddenDelete: forbiddenExactDelete,
+    });
+    Object.defineProperty(constructor, exactPersistencePolicySymbol, {
+      value: exactPolicy,
+      enumerable: false,
+      configurable: false,
+      writable: false,
+    });
+    Object.defineProperty(constructor.prototype, 'save', {
+      value: unsupportedExactSave,
+      enumerable: false,
+      configurable: false,
+      writable: false,
+    });
+    Object.defineProperty(constructor.prototype, 'delete', {
+      value: forbiddenExactDelete,
+      enumerable: false,
+      configurable: false,
+      writable: false,
+    });
+    Object.defineProperty(constructor, 'exact', {
+      get(this: IExactModelConstructor<SmartDataDbDoc<any, TPersisted>>) {
+        const receiver = this;
+        if (typeof receiver !== 'function' || (receiver !== constructor
+          && !Object.prototype.isPrototypeOf.call(constructor, receiver))
+          || Reflect.get(receiver, exactPersistencePolicySymbol) !== exactPolicy) {
+          throw new SmartdataExactPersistenceError('invalid_configuration',
+            'Exact persistence requires the decorated model or an inheriting receiver.');
+        }
+        const collection = receiver.collection;
+        let byCollection = exactCollectionCache.get(receiver);
+        if (!byCollection) {
+          byCollection = new WeakMap();
+          exactCollectionCache.set(receiver, byCollection);
+        }
+        let exactCollection = byCollection.get(collection);
+        if (!exactCollection) {
+          exactCollection = new SmartdataExactCollection(
+            receiver,
+            collection,
+            exactOptions,
+          );
+          byCollection.set(collection, exactCollection);
+        }
+        return exactCollection;
+      },
+      enumerable: false,
+      configurable: false,
+    });
+  };
+}