@lossless.org/client 1.20.2 → 1.21.1

package/ts/nosqldb/classes.readtracker.ts

@@ -0,0 +1,1031 @@
+import * as plugins from './plugins.js';
+
+import { collectionTopologyDbInspectionSymbol } from './classes.collectiontopology.js';
+import type { SmartdataDb } from './classes.db.js';
+import { readBoundedInspectionCursor } from './classes.namespaceinspection.js';
+import { SmartdataPersistenceError } from './classes.persistence.js';
+import type { ISmartdataWrite } from './classes.writeobserver.js';
+
+/**
+ * The reads one `db.trackReads()` call made. `changed` turns true once a write
+ * of this process may have changed what any of them returned, and stays true.
+ */
+export class SmartdataReadSet {
+  /**
+   * Whether a write this process made through the database's models since the
+   * reads ran could have changed any of their results. Also true after
+   * `close()`, after the database closed, and for a set that tracked a read
+   * it cannot follow.
+   */
+  public get changed(): boolean {
+    const state = readSetStates.get(this);
+    return !state || state.changed;
+  }
+
+  /** Stops following writes and frees the recorded reads; `changed` is true from then on. */
+  public close(): void {
+    const state = readSetStates.get(this);
+    if (state) changeReadSet(state);
+  }
+}
+
+/** What `db.trackReads()` resolves with: the callback's result and the reads it made. */
+export interface ISmartdataTrackedReads<TResult> {
+  readonly result: TResult;
+  readonly reads: SmartdataReadSet;
+}
+
+/** @internal What one model read asks for, stated before it is issued. */
+export interface ISmartdataReadSpec {
+  collection: string;
+  /**
+   * `documents` returns the matching documents, `count` counts them, and
+   * `collection` depends on the whole collection: every write to it changes it.
+   */
+  kind: 'documents' | 'count' | 'collection';
+  /** The filter as sent to the database. */
+  filter?: unknown;
+  sort?: unknown;
+  hint?: unknown;
+  /**
+   * The result depends on the matching documents' contents beyond which ones
+   * were returned (skipped pages, distinct values, grouped totals), so the
+   * returned documents never settle it.
+   */
+  matches?: boolean;
+  /** The read returns at most a limit of the matching documents. */
+  limited?: boolean;
+  /** The model's identity fields, by which a write names a document without its `_id`. */
+  identityFields?: readonly string[];
+  /** The identity fields a sort by orders every document; see `getOrderingIdentityFields`. */
+  orderingIdentityFields?: readonly string[];
+}
+
+/** @internal Records what one read returned. */
+export interface ISmartdataReadRecorder {
+  /** Records one raw document the read returned. */
+  record(documentArg: unknown): void;
+  /** The read returned everything it will return. */
+  settle(): void;
+}
+
+// Values an image or a stored path can hold beside real values.
+const MISSING = Symbol('missing');
+const UNKNOWN = Symbol('unknown');
+
+/**
+ * What is known about one document: values by path, layered over `base`. A
+ * complete image knows every top-level field, so a field it lacks is missing.
+ */
+interface IDocumentImage {
+  values: ReadonlyMap<string, unknown>;
+  complete: boolean;
+  base?: IDocumentImage;
+}
+
+/** `true`, `false`, or `undefined` when the known values do not decide. */
+type TMatch = boolean | undefined;
+type TPredicate = (imageArg: IDocumentImage | undefined) => TMatch;
+type TCondition = (valueArg: unknown) => TMatch;
+
+interface IReadObservation {
+  kind: ISmartdataReadSpec['kind'];
+  predicate: TPredicate;
+  /** The paths the filter and sort read; `all` when they cannot be named. */
+  refs: ReadonlySet<string> | 'all';
+  identityFields?: readonly string[];
+  settles: boolean;
+  settled: boolean;
+  /** The sequence number at settling; a write that started earlier is not concurrent. */
+  settledAt: number;
+  /** The `_id` keys of the returned documents; `null` when one cannot be keyed. */
+  byId: Set<string> | null;
+  /** The identity keys of the returned documents; `null` when one cannot be keyed. */
+  byIdentity: Set<string> | null;
+}
+
+interface IReadSetState {
+  db: SmartdataDb;
+  changed: boolean;
+  /** The callback returned, so its read collections have been checked. */
+  finished: boolean;
+  reads: Map<string, IReadObservation[]>;
+}
+
+/** What one write did to one document, as far as it is known. */
+interface IReadChange {
+  kind: ISmartdataWrite['kind'] | 'unknown';
+  before?: IDocumentImage;
+  after?: IDocumentImage;
+  touched: ReadonlySet<string> | 'all';
+  idKey?: string;
+  identityKey?: string;
+  startedAt: number;
+}
+
+const readSetStates = new WeakMap<SmartdataReadSet, IReadSetState>();
+const readSetsByDb = new WeakMap<SmartdataDb, Set<IReadSetState>>();
+/** Databases a read set was ever opened on; writes to others skip all capture work. */
+const trackedDbs = new WeakSet<SmartdataDb>();
+const droppedReadSets = new FinalizationRegistry<IReadSetState>((stateArg) => {
+  changeReadSet(stateArg);
+});
+const readScope = new plugins.nodeAsyncHooks.AsyncLocalStorage<readonly IReadSetState[]>();
+/**
+ * Per database, whether the predicates can follow a collection's reads: only a
+ * plain collection without a default collation compares like they do.
+ */
+const followableCollections = new WeakMap<SmartdataDb, Map<string, boolean>>();
+const writeScope = new plugins.nodeAsyncHooks.AsyncLocalStorage<{
+  db: SmartdataDb;
+  startedAt: number;
+}>();
+/** Orders read settling against write starts. */
+let sequence = 0;
+
+const changeReadSet = (stateArg: IReadSetState): void => {
+  if (stateArg.changed) return;
+  stateArg.changed = true;
+  stateArg.reads.clear();
+  readSetsByDb.get(stateArg.db)?.delete(stateArg);
+};
+
+const isPlainRecord = (valueArg: unknown): valueArg is Record<string, unknown> => {
+  if (typeof valueArg !== 'object' || valueArg === null || Array.isArray(valueArg)) {
+    return false;
+  }
+  const prototype = Object.getPrototypeOf(valueArg);
+  return prototype === Object.prototype || prototype === null;
+};
+
+const isObjectIdLike = (
+  valueArg: unknown,
+): valueArg is { toHexString(): string } =>
+  typeof valueArg === 'object'
+  && valueArg !== null
+  && (valueArg as { _bsontype?: unknown })._bsontype === 'ObjectId'
+  && typeof (valueArg as { toHexString?: unknown }).toHexString === 'function';
+
+const isFilterPrimitive = (valueArg: unknown): boolean =>
+  valueArg === null
+  || typeof valueArg === 'boolean'
+  || (typeof valueArg === 'number' && Number.isFinite(valueArg))
+  || (typeof valueArg === 'string' && valueArg.isWellFormed());
+
+/** A stable key for an `_id`, or `undefined` for a value that has none. */
+const documentIdKeyOf = (valueArg: unknown): string | undefined => {
+  if (typeof valueArg === 'string') return `s${valueArg}`;
+  if (typeof valueArg === 'number' && Number.isFinite(valueArg)) return `n${valueArg}`;
+  if (typeof valueArg === 'boolean') return `b${valueArg}`;
+  if (isObjectIdLike(valueArg)) return `o${valueArg.toHexString()}`;
+  return undefined;
+};
+
+/** A stable key for a document's identity values, or `undefined` unless all are concrete primitives. */
+const identityKeyOf = (valuesArg: readonly unknown[]): string | undefined =>
+  valuesArg.every((valueArg) => valueArg !== null && isFilterPrimitive(valueArg))
+    ? JSON.stringify(valuesArg)
+    : undefined;
+
+// --- Document images --------------------------------------------------------
+
+/** The image of a whole stored document, or `undefined` when its shape cannot be followed. */
+const completeImage = (documentArg: unknown): IDocumentImage | undefined => {
+  if (!isPlainRecord(documentArg) || 'toBSON' in documentArg) return undefined;
+  const values = new Map<string, unknown>();
+  for (const key of Object.keys(documentArg)) {
+    if (key.length === 0 || key.includes('.') || key.startsWith('$')) return undefined;
+    values.set(key, documentArg[key]);
+  }
+  return { values, complete: true };
+};
+
+/** Follows `segmentsArg` below a value; arrays and foreign objects are not followed. */
+const descendValue = (valueArg: unknown, segmentsArg: readonly string[]): unknown => {
+  let value = valueArg;
+  for (const segment of segmentsArg) {
+    if (value === MISSING || value === UNKNOWN) return value;
+    if (value === undefined) return UNKNOWN;
+    if (typeof value !== 'object' || value === null) return MISSING;
+    if (!isPlainRecord(value) || 'toBSON' in value) return UNKNOWN;
+    value = Object.hasOwn(value, segment) ? value[segment] : MISSING;
+  }
+  if (value === undefined) return UNKNOWN;
+  if (isPlainRecord(value) && 'toBSON' in value) return UNKNOWN;
+  return value;
+};
+
+/** The value at a dotted path of an image: a value, `MISSING`, or `UNKNOWN`. */
+const lookupPath = (imageArg: IDocumentImage | undefined, pathArg: string): unknown => {
+  if (!imageArg) return UNKNOWN;
+  const segments = pathArg.split('.');
+  for (let length = segments.length; length > 0; length--) {
+    const key = length === segments.length ? pathArg : segments.slice(0, length).join('.');
+    if (imageArg.values.has(key)) {
+      return descendValue(imageArg.values.get(key), segments.slice(length));
+    }
+  }
+  const prefix = `${pathArg}.`;
+  for (const key of imageArg.values.keys()) {
+    // The image changed part of the value, so the rest of it is not known here.
+    if (key.startsWith(prefix)) return UNKNOWN;
+  }
+  if (imageArg.base) return lookupPath(imageArg.base, pathArg);
+  if (imageArg.complete) return pathArg === '_id' ? UNKNOWN : MISSING;
+  return UNKNOWN;
+};
+
+/** A deep copy of plain records and arrays, so a buffered change keeps the values of its write. */
+const snapshotValue = (valueArg: unknown): unknown => {
+  if (Array.isArray(valueArg)) return valueArg.map(snapshotValue);
+  if (isPlainRecord(valueArg) && !('toBSON' in valueArg)) {
+    const copy: Record<string, unknown> = {};
+    for (const key of Object.keys(valueArg)) copy[key] = snapshotValue(valueArg[key]);
+    return copy;
+  }
+  return valueArg;
+};
+
+// --- Filters ----------------------------------------------------------------
+
+interface IRefs {
+  paths: Set<string>;
+  all: boolean;
+}
+
+const unknownPredicate: TPredicate = () => undefined;
+const unknownCondition: TCondition = () => undefined;
+
+const allOf = <TArg>(partsArg: Array<(arg: TArg) => TMatch>) =>
+  (arg: TArg): TMatch => {
+    let result: TMatch = true;
+    for (const part of partsArg) {
+      const match = part(arg);
+      if (match === false) return false;
+      if (match === undefined) result = undefined;
+    }
+    return result;
+  };
+
+const anyOf = <TArg>(partsArg: Array<(arg: TArg) => TMatch>) =>
+  (arg: TArg): TMatch => {
+    let result: TMatch = false;
+    for (const part of partsArg) {
+      const match = part(arg);
+      if (match === true) return true;
+      if (match === undefined) result = undefined;
+    }
+    return result;
+  };
+
+const negate = <TArg>(partArg: (arg: TArg) => TMatch) =>
+  (arg: TArg): TMatch => {
+    const match = partArg(arg);
+    return match === undefined ? undefined : !match;
+  };
+
+/**
+ * Whether a stored value is one the supported operators decide on. Arrays
+ * match element-wise, and other BSON types compare across numeric types, so
+ * both stay undecided.
+ */
+const isDecidableValue = (valueArg: unknown): boolean =>
+  valueArg === MISSING
+  || isFilterPrimitive(valueArg)
+  || isObjectIdLike(valueArg)
+  || isPlainRecord(valueArg);
+
+const decided = (conditionArg: TCondition): TCondition =>
+  (valueArg) => isDecidableValue(valueArg) ? conditionArg(valueArg) : undefined;
+
+/** Equality with a filter primitive or ObjectId; `null` also matches a missing field. */
+const equals = (operandArg: unknown): TCondition => decided((valueArg) => {
+  if (valueArg === MISSING || valueArg === null) return operandArg === null;
+  if (isObjectIdLike(operandArg)) {
+    return isObjectIdLike(valueArg) && valueArg.toHexString() === operandArg.toHexString();
+  }
+  if (isObjectIdLike(valueArg)) return false;
+  if (isPlainRecord(valueArg)) return false;
+  return valueArg === operandArg;
+});
+
+const isEqualityOperand = (valueArg: unknown): boolean =>
+  isFilterPrimitive(valueArg) || isObjectIdLike(valueArg);
+
+/** Strings without surrogates order the same by UTF-16 units and by UTF-8 bytes. */
+const isPlainOrderString = (valueArg: string): boolean => !/[\uD800-￿]/.test(valueArg);
+
+const compares = (
+  operatorArg: '$gt' | '$gte' | '$lt' | '$lte',
+  operandArg: unknown,
+): TCondition => {
+  if (
+    !(typeof operandArg === 'number' && Number.isFinite(operandArg))
+    && !(typeof operandArg === 'string' && isPlainOrderString(operandArg))
+  ) {
+    return unknownCondition;
+  }
+  return decided((valueArg) => {
+    if (valueArg === MISSING) return false;
+    // A range only matches values of its operand's BSON type.
+    if (typeof valueArg !== typeof operandArg) return false;
+    if (typeof valueArg === 'string' && !isPlainOrderString(valueArg)) return undefined;
+    const value = valueArg as number | string;
+    const operand = operandArg as number | string;
+    switch (operatorArg) {
+      case '$gt': return value > operand;
+      case '$gte': return value >= operand;
+      case '$lt': return value < operand;
+      case '$lte': return value <= operand;
+    }
+  });
+};
+
+const isOperatorObject = (valueArg: unknown): valueArg is Record<string, unknown> =>
+  isPlainRecord(valueArg)
+  && Object.keys(valueArg).length > 0
+  && Object.keys(valueArg).every((keyArg) => keyArg.startsWith('$'));
+
+const compileCondition = (conditionArg: unknown): TCondition => {
+  if (isEqualityOperand(conditionArg)) return equals(conditionArg);
+  if (!isOperatorObject(conditionArg)) return unknownCondition;
+  const parts: TCondition[] = [];
+  for (const operator of Object.keys(conditionArg)) {
+    const operand = conditionArg[operator];
+    switch (operator) {
+      case '$eq':
+        parts.push(isEqualityOperand(operand) ? equals(operand) : unknownCondition);
+        break;
+      case '$ne':
+        parts.push(isEqualityOperand(operand) ? negate(equals(operand)) : unknownCondition);
+        break;
+      case '$in':
+      case '$nin': {
+        const listed = Array.isArray(operand) && operand.every(isEqualityOperand)
+          ? anyOf(operand.map(equals))
+          : unknownCondition;
+        parts.push(operator === '$in' ? listed : negate(listed));
+        break;
+      }
+      case '$gt':
+      case '$gte':
+      case '$lt':
+      case '$lte':
+        parts.push(compares(operator, operand));
+        break;
+      case '$exists':
+        parts.push(typeof operand === 'boolean'
+          ? (valueArg) => valueArg === UNKNOWN
+            ? undefined
+            : (valueArg !== MISSING) === operand
+          : unknownCondition);
+        break;
+      case '$not':
+        parts.push(isOperatorObject(operand) ? negate(compileCondition(operand)) : unknownCondition);
+        break;
+      default:
+        parts.push(unknownCondition);
+    }
+  }
+  return allOf(parts);
+};
+
+/**
+ * The part of a path a write or filter can be followed on: up to the first
+ * positional or numeric segment, which may address array elements.
+ */
+const followablePath = (pathArg: string): { path: string; whole: boolean } | undefined => {
+  const segments = pathArg.split('.');
+  if (segments.some((segmentArg) => segmentArg.length === 0)) return undefined;
+  const cut = segments.findIndex((segmentArg) =>
+    segmentArg.startsWith('$') || /^\d+$/.test(segmentArg));
+  if (cut === 0) return undefined;
+  return cut === -1
+    ? { path: pathArg, whole: true }
+    : { path: segments.slice(0, cut).join('.'), whole: false };
+};
+
+const compileFilter = (filterArg: unknown, refsArg: IRefs): TPredicate => {
+  if (!isPlainRecord(filterArg)) {
+    refsArg.all = true;
+    return unknownPredicate;
+  }
+  const parts: TPredicate[] = [];
+  for (const key of Object.keys(filterArg)) {
+    const value = filterArg[key];
+    if (key === '$and' || key === '$or' || key === '$nor') {
+      if (!Array.isArray(value) || value.length === 0 || !value.every(isPlainRecord)) {
+        refsArg.all = true;
+        parts.push(unknownPredicate);
+        continue;
+      }
+      const branches = value.map((branchArg) => compileFilter(branchArg, refsArg));
+      parts.push(key === '$and'
+        ? allOf(branches)
+        : key === '$or' ? anyOf(branches) : negate(anyOf(branches)));
+      continue;
+    }
+    if (key === '$comment') continue;
+    const followable = key.startsWith('$') ? undefined : followablePath(key);
+    if (!followable) {
+      refsArg.all = true;
+      parts.push(unknownPredicate);
+      continue;
+    }
+    refsArg.paths.add(followable.path);
+    if (!followable.whole) {
+      parts.push(unknownPredicate);
+      continue;
+    }
+    const condition = compileCondition(value);
+    parts.push((imageArg) => condition(lookupPath(imageArg, key)));
+  }
+  return allOf(parts);
+};
+
+const addSortRefs = (sortArg: unknown, refsArg: IRefs): void => {
+  if (sortArg === undefined) return;
+  if (!isPlainRecord(sortArg)) {
+    refsArg.all = true;
+    return;
+  }
+  for (const key of Object.keys(sortArg)) {
+    const followable = key.startsWith('$') ? undefined : followablePath(key);
+    const direction = sortArg[key];
+    if (!followable || (direction !== 1 && direction !== -1)) {
+      refsArg.all = true;
+      return;
+    }
+    refsArg.paths.add(followable.path);
+  }
+};
+
+// --- Writes -----------------------------------------------------------------
+
+interface IUpdateEffect {
+  touched: Set<string> | 'all';
+  /** The values the update leaves at the touched paths. */
+  sets: Map<string, unknown>;
+}
+
+const updatesWithUnknownResult = new Set([
+  '$inc', '$mul', '$min', '$max', '$currentDate',
+  '$push', '$pull', '$pullAll', '$addToSet', '$pop', '$bit',
+]);
+
+const analyzeUpdate = (updateArg: unknown, insertedArg: boolean): IUpdateEffect => {
+  const everything: IUpdateEffect = { touched: 'all', sets: new Map() };
+  if (!isPlainRecord(updateArg)) return everything;
+  const operators = Object.keys(updateArg);
+  if (operators.length === 0 || operators.some((operatorArg) => !operatorArg.startsWith('$'))) {
+    return everything;
+  }
+  const touched = new Set<string>();
+  const sets = new Map<string, unknown>();
+  const touch = (pathArg: string, valueArg: unknown): boolean => {
+    const followable = followablePath(pathArg);
+    if (!followable) return false;
+    const value = !followable.whole || sets.has(followable.path) ? UNKNOWN : valueArg;
+    touched.add(followable.path);
+    sets.set(followable.path, value);
+    return true;
+  };
+  for (const operator of operators) {
+    const fields = updateArg[operator];
+    if (!isPlainRecord(fields)) return everything;
+    for (const path of Object.keys(fields)) {
+      let followed = true;
+      switch (operator) {
+        case '$set':
+          followed = touch(path, fields[path]);
+          break;
+        case '$setOnInsert':
+          if (insertedArg) followed = touch(path, fields[path]);
+          break;
+        case '$unset':
+          followed = touch(path, MISSING);
+          break;
+        case '$rename':
+          followed = typeof fields[path] === 'string'
+            && touch(path, UNKNOWN)
+            && touch(fields[path] as string, UNKNOWN);
+          break;
+        default:
+          if (!updatesWithUnknownResult.has(operator)) return everything;
+          followed = touch(path, UNKNOWN);
+      }
+      if (!followed) return everything;
+    }
+  }
+  return { touched, sets };
+};
+
+/**
+ * The top-level equality conditions of a selector, including inside `$and`.
+ * `null` also matches a missing field, and a non-null value also matches an
+ * array holding it, so only an `_id` (never an array) states a stored value.
+ */
+const collectEqualities = (
+  selectorArg: unknown,
+  equalitiesArg: Map<string, unknown>,
+): void => {
+  if (!isPlainRecord(selectorArg)) return;
+  for (const key of Object.keys(selectorArg)) {
+    const condition = selectorArg[key];
+    if (key === '$and') {
+      if (Array.isArray(condition)) {
+        for (const conjunct of condition) collectEqualities(conjunct, equalitiesArg);
+      }
+      continue;
+    }
+    if (key.startsWith('$') || key.includes('.')) continue;
+    let value: unknown = UNKNOWN;
+    if (isEqualityOperand(condition)) {
+      value = condition;
+    } else if (
+      isPlainRecord(condition)
+      && Object.keys(condition).length === 1
+      && Object.hasOwn(condition, '$eq')
+      && isEqualityOperand(condition.$eq)
+    ) {
+      value = condition.$eq;
+    }
+    if (value === UNKNOWN || value === null) continue;
+    if (!equalitiesArg.has(key)) equalitiesArg.set(key, value);
+  }
+};
+
+const documentIdImage = (selectorArg: unknown): IDocumentImage => {
+  const equalities = new Map<string, unknown>();
+  collectEqualities(selectorArg, equalities);
+  const values = new Map<string, unknown>();
+  if (documentIdKeyOf(equalities.get('_id')) !== undefined) values.set('_id', equalities.get('_id'));
+  return { values, complete: false };
+};
+
+const selectorIdentityKey = (
+  selectorArg: unknown,
+  identityFieldsArg: readonly string[] | undefined,
+): string | undefined => {
+  if (!identityFieldsArg?.length) return undefined;
+  const equalities = new Map<string, unknown>();
+  collectEqualities(selectorArg, equalities);
+  if (!identityFieldsArg.every((fieldArg) => equalities.has(fieldArg))) return undefined;
+  return identityKeyOf(identityFieldsArg.map((fieldArg) => equalities.get(fieldArg)));
+};
+
+const imageIdentityKey = (
+  imageArg: IDocumentImage | undefined,
+  identityFieldsArg: readonly string[] | undefined,
+): string | undefined => {
+  if (!imageArg || !identityFieldsArg?.length) return undefined;
+  return identityKeyOf(identityFieldsArg.map((fieldArg) => lookupPath(imageArg, fieldArg)));
+};
+
+/**
+ * The document an upsert inserted: the selector's plain top-level equalities
+ * under the update's values. A selector of only such equalities states every
+ * field; any other condition leaves its field unknown.
+ */
+const upsertedImage = (selectorArg: unknown, effectArg: IUpdateEffect): IDocumentImage | undefined => {
+  if (effectArg.touched === 'all' || !isPlainRecord(selectorArg)) return undefined;
+  const values = new Map<string, unknown>();
+  let complete = true;
+  for (const key of Object.keys(selectorArg)) {
+    const condition = selectorArg[key];
+    if (key.startsWith('$') || key.includes('.')) {
+      complete = false;
+      continue;
+    }
+    values.set(key, isEqualityOperand(condition) && condition !== null ? condition : UNKNOWN);
+  }
+  return { values: effectArg.sets, complete: false, base: { values, complete } };
+};
+
+const withDocumentKeys = (
+  changeArg: IReadChange,
+  writeArg: ISmartdataWrite,
+): IReadChange => {
+  changeArg.idKey = documentIdKeyOf(lookupPath(changeArg.before, '_id'))
+    ?? documentIdKeyOf(lookupPath(changeArg.after, '_id'));
+  changeArg.identityKey = imageIdentityKey(changeArg.before, writeArg.identityFields)
+    ?? selectorIdentityKey(writeArg.selector, writeArg.identityFields);
+  return changeArg;
+};
+
+/** What one acknowledged write did to each document it wrote, as far as its report tells. */
+const describeWrite = (writeArg: ISmartdataWrite, startedAtArg: number): IReadChange[] => {
+  const { kind, images, documents } = writeArg;
+  const unknown: IReadChange[] = [{ kind: 'unknown', touched: 'all', startedAt: startedAtArg }];
+  const change = (fieldsArg: Omit<IReadChange, 'kind' | 'startedAt'>): IReadChange =>
+    withDocumentKeys({ kind, startedAt: startedAtArg, ...fieldsArg }, writeArg);
+  const documentIdOf = (imageArg: IDocumentImage | undefined): IDocumentImage | undefined => {
+    const id = lookupPath(imageArg, '_id');
+    return documentIdKeyOf(id) === undefined
+      ? undefined
+      : { values: new Map([['_id', id]]), complete: false };
+  };
+  switch (kind) {
+    case 'insert':
+      if (images === 'after' && documents) {
+        return documents.map((documentArg) =>
+          change({ after: completeImage(documentArg), touched: 'all' }));
+      }
+      if (images === 'none' && writeArg.update !== undefined) {
+        return [change({
+          after: upsertedImage(writeArg.selector, analyzeUpdate(writeArg.update, true)),
+          touched: 'all',
+        })];
+      }
+      return images === undefined ? unknown : [change({ touched: 'all' })];
+    case 'update': {
+      const effect = analyzeUpdate(writeArg.update, false);
+      if (images === 'after' && documents?.length === 1) {
+        const after = completeImage(documents[0]);
+        return [change({ before: documentIdOf(after), after, touched: effect.touched })];
+      }
+      if (images === 'before' && documents?.length === 1) {
+        const before = completeImage(documents[0]);
+        return [change({
+          before,
+          after: effect.touched === 'all' || !before
+            ? undefined
+            : { values: effect.sets, complete: false, base: before },
+          touched: effect.touched,
+        })];
+      }
+      if (images === 'none') {
+        const before = documentIdImage(writeArg.selector);
+        return [change({
+          before,
+          after: effect.touched === 'all'
+            ? undefined
+            : { values: effect.sets, complete: false, base: before },
+          touched: effect.touched,
+        })];
+      }
+      return unknown;
+    }
+    case 'replace': {
+      if (images === 'beforeAndAfter' && documents?.length === 2) {
+        const before = completeImage(documents[0]);
+        let after = completeImage(documents[1]);
+        if (after && !after.values.has('_id') && before?.values.has('_id')) {
+          after = { ...after, values: new Map([...after.values, ['_id', before.values.get('_id')]]) };
+        }
+        return [change({ before, after, touched: 'all' })];
+      }
+      if (images === 'after' && documents?.length) {
+        // Documents before the last are what the caller expected, not what was stored.
+        const after = completeImage(documents[documents.length - 1]);
+        return [change({ before: documentIdOf(after), after, touched: 'all' })];
+      }
+      return unknown;
+    }
+    case 'delete':
+      if (images === 'before' && documents) {
+        return documents.map((documentArg) =>
+          change({ before: completeImage(documentArg), touched: 'all' }));
+      }
+      if (images === 'none') {
+        return [change({ before: documentIdImage(writeArg.selector), touched: 'all' })];
+      }
+      return unknown;
+  }
+  return unknown;
+};
+
+// --- Evaluation -------------------------------------------------------------
+
+const pathsOverlap = (leftArg: string, rightArg: string): boolean =>
+  leftArg === rightArg
+  || leftArg.startsWith(`${rightArg}.`)
+  || rightArg.startsWith(`${leftArg}.`);
+
+const refsOverlap = (
+  refsArg: ReadonlySet<string> | 'all',
+  touchedArg: ReadonlySet<string> | 'all',
+): boolean => {
+  if (refsArg === 'all' || touchedArg === 'all') return true;
+  for (const ref of refsArg) {
+    for (const path of touchedArg) {
+      if (pathsOverlap(ref, path)) return true;
+    }
+  }
+  return false;
+};
+
+/**
+ * Whether the change could alter what the read returned. Anything that is not
+ * known to leave the result alone counts as a change.
+ */
+const changeAffectsRead = (readArg: IReadObservation, changeArg: IReadChange): boolean => {
+  if (changeArg.kind === 'unknown' || readArg.kind === 'collection') return true;
+  const matchesBefore = () => readArg.predicate(changeArg.before);
+  const matchesAfter = () => readArg.predicate(changeArg.after);
+  // A write that started before the read settled may be part of what it returned.
+  const concurrent = !readArg.settled || readArg.settledAt > changeArg.startedAt;
+  if (readArg.kind === 'count') {
+    if (changeArg.kind === 'insert') return matchesAfter() !== false;
+    if (changeArg.kind === 'delete') return matchesBefore() !== false;
+    if (!refsOverlap(readArg.refs, changeArg.touched)) return false;
+    const before = matchesBefore();
+    const after = matchesAfter();
+    if (concurrent) return !(before === false && after === false);
+    return before === undefined || after === undefined || before !== after;
+  }
+  if (changeArg.kind === 'insert') return matchesAfter() !== false;
+  let returned: boolean | undefined;
+  if (readArg.settled && !concurrent) {
+    if (changeArg.idKey !== undefined && readArg.byId) {
+      returned = readArg.byId.has(changeArg.idKey);
+    } else if (changeArg.identityKey !== undefined && readArg.byIdentity) {
+      returned = readArg.byIdentity.has(changeArg.identityKey);
+    }
+  }
+  if (returned === true) return true;
+  if (returned === undefined && matchesBefore() !== false) return true;
+  // The document was not returned: only one that matches afterwards can enter.
+  if (changeArg.kind === 'delete') return false;
+  if (matchesAfter() === false) return false;
+  return refsOverlap(readArg.refs, changeArg.touched);
+};
+
+const applyChanges = (
+  dbArg: SmartdataDb,
+  collectionArg: string,
+  changesArg: readonly IReadChange[],
+): void => {
+  const states = readSetsByDb.get(dbArg);
+  if (!states) return;
+  for (const state of [...states]) {
+    const reads = state.reads.get(collectionArg);
+    if (!reads) continue;
+    if (reads.some((readArg) => changesArg.some((changeArg) => changeAffectsRead(readArg, changeArg)))) {
+      changeReadSet(state);
+    }
+  }
+};
+
+/** How long the check of one read collection may take. */
+const collectionCheckTimeoutMs = 5_000;
+
+/**
+ * Whether the reads of a collection can be followed, or `undefined` when it
+ * does not exist: a view, another namespace type and a collection with a
+ * default collation compare in ways the predicates do not.
+ */
+const isFollowableCollection = async (
+  dbArg: SmartdataDb,
+  collectionArg: string,
+): Promise<boolean | undefined> => {
+  const signal = AbortSignal.timeout(collectionCheckTimeoutMs);
+  const expiresAt = performance.now() + collectionCheckTimeoutMs;
+  const cleanupOptions = () => ({ timeoutMS: Math.max(1, Math.ceil(expiresAt - performance.now())) });
+  const [namespace] = await dbArg[collectionTopologyDbInspectionSymbol]((mongoDbArg) =>
+    readBoundedInspectionCursor(mongoDbArg.listCollections(
+      { name: collectionArg },
+      { nameOnly: false, batchSize: 1, ...cleanupOptions(), signal },
+    ), 1, signal, cleanupOptions));
+  if (!namespace) return undefined;
+  const options = (namespace as { options?: unknown }).options;
+  return namespace.type === 'collection'
+    && (options === undefined || (isPlainRecord(options) && options.collation === undefined));
+};
+
+/**
+ * Checks each collection the set read, once per database. A collection that
+ * cannot be followed, does not exist or cannot be checked changes the set.
+ */
+const checkReadCollections = async (stateArg: IReadSetState): Promise<void> => {
+  let known = followableCollections.get(stateArg.db);
+  if (!known) {
+    known = new Map();
+    followableCollections.set(stateArg.db, known);
+  }
+  const collections = [...stateArg.reads.keys()];
+  try {
+    await Promise.all(collections.filter((collectionArg) => !known.has(collectionArg))
+      .map(async (collectionArg) => {
+        const followable = await isFollowableCollection(stateArg.db, collectionArg);
+        if (followable !== undefined) known.set(collectionArg, followable);
+      }));
+  } catch {
+    changeReadSet(stateArg);
+    return;
+  }
+  if (collections.some((collectionArg) => known.get(collectionArg) !== true)) changeReadSet(stateArg);
+};
+
+// --- Internal API -----------------------------------------------------------
+
+/** @internal Runs `fnArg` with a new read set open; see `SmartdataDb.trackReads`. */
+export const trackSmartdataReads = async <TResult>(
+  dbArg: SmartdataDb,
+  fnArg: () => TResult | Promise<TResult>,
+): Promise<ISmartdataTrackedReads<TResult>> => {
+  if (typeof fnArg !== 'function') {
+    throw new SmartdataPersistenceError('invalid_argument',
+      'db.trackReads() requires a callback function.');
+  }
+  const reads = new SmartdataReadSet();
+  const state: IReadSetState = { db: dbArg, changed: false, finished: false, reads: new Map() };
+  readSetStates.set(reads, state);
+  let states = readSetsByDb.get(dbArg);
+  if (!states) {
+    states = new Set();
+    readSetsByDb.set(dbArg, states);
+  }
+  states.add(state);
+  trackedDbs.add(dbArg);
+  droppedReadSets.register(reads, state);
+  try {
+    const result = await readScope.run([...(readScope.getStore() ?? []), state], fnArg);
+    state.finished = true;
+    if (!state.changed) await checkReadCollections(state);
+    return { result, reads };
+  } catch (errorArg) {
+    reads.close();
+    throw errorArg;
+  }
+};
+
+/** @internal Whether a read of the current async context is tracked. */
+export const hasSmartdataReadScope = (): boolean => readScope.getStore() !== undefined;
+
+/** @internal Whether any read set of the database is open. */
+export const hasSmartdataReadSets = (dbArg: SmartdataDb): boolean =>
+  (readSetsByDb.get(dbArg)?.size ?? 0) > 0;
+
+/** @internal Marks every open read set of the database changed, as its `close()` does. */
+export const changeSmartdataReadSetsOfDb = (dbArg: SmartdataDb): void => {
+  // A reconnected database may hold recreated collections.
+  followableCollections.delete(dbArg);
+  for (const state of [...(readSetsByDb.get(dbArg) ?? [])]) changeReadSet(state);
+};
+
+/**
+ * Whether a limited read keeps the documents its filter and sort decide: at
+ * most one document matches an equality on `_id` or an identity field, and a
+ * sort by `_id` or by an identity field whose index holds every document
+ * orders them all.
+ */
+const limitFollowsQuery = (specArg: ISmartdataReadSpec): boolean => {
+  const filter = specArg.filter;
+  const sort = specArg.sort;
+  const pins = (valueArg: unknown): boolean =>
+    (isFilterPrimitive(valueArg) && valueArg !== null)
+    || isObjectIdLike(valueArg)
+    || (isPlainRecord(valueArg) && Object.keys(valueArg).length === 1 && Object.hasOwn(valueArg, '$eq') && pins(valueArg.$eq));
+  return ['_id', ...(specArg.identityFields ?? [])].some((fieldArg) =>
+    isPlainRecord(filter) && Object.hasOwn(filter, fieldArg) && pins(filter[fieldArg]))
+    || ['_id', ...(specArg.orderingIdentityFields ?? [])].some((fieldArg) =>
+      isPlainRecord(sort) && Object.hasOwn(sort, fieldArg));
+};
+
+/**
+ * @internal Registers one read with every open read set of the current async
+ * context, before the read is issued. A read inside a transaction sees writes
+ * that may never commit, and a read of another database or of a collection the
+ * predicates cannot follow is not followed, so each marks the sets changed
+ * instead.
+ */
+export const observeSmartdataRead = (
+  dbArg: SmartdataDb,
+  specArg: ISmartdataReadSpec,
+  inTransactionArg: boolean,
+): ISmartdataReadRecorder | undefined => {
+  const states = readScope.getStore()?.filter((stateArg) => !stateArg.changed);
+  if (!states?.length) return undefined;
+  const followed: IReadSetState[] = [];
+  const followable = followableCollections.get(dbArg)?.get(specArg.collection);
+  for (const state of states) {
+    // A read after the callback returned was never checked with the others.
+    if (
+      inTransactionArg
+      || state.db !== dbArg
+      || followable === false
+      || (state.finished && followable !== true)
+    ) {
+      changeReadSet(state);
+    } else {
+      followed.push(state);
+    }
+  }
+  if (followed.length === 0) return undefined;
+  const refs: IRefs = { paths: new Set(), all: false };
+  let predicate = specArg.kind === 'collection'
+    ? unknownPredicate
+    : compileFilter(specArg.filter ?? {}, refs);
+  addSortRefs(specArg.sort, refs);
+  if (specArg.limited && !limitFollowsQuery(specArg)) {
+    // Which matching documents the limit keeps follows the query plan, which a write to any field can reorder.
+    refs.all = true;
+  }
+  if (specArg.hint !== undefined) {
+    // A hinted sparse or partial index can leave out matching documents.
+    const filterPredicate = predicate;
+    predicate = (imageArg) => filterPredicate(imageArg) === false ? false : undefined;
+    refs.all = true;
+  }
+  const observation: IReadObservation = {
+    kind: specArg.kind,
+    predicate,
+    refs: refs.all ? 'all' : refs.paths,
+    identityFields: specArg.identityFields?.length ? [...specArg.identityFields] : undefined,
+    settles: specArg.matches !== true,
+    settled: false,
+    settledAt: 0,
+    byId: new Set(),
+    byIdentity: specArg.identityFields?.length ? new Set() : null,
+  };
+  for (const state of followed) {
+    let reads = state.reads.get(specArg.collection);
+    if (!reads) {
+      reads = [];
+      state.reads.set(specArg.collection, reads);
+    }
+    reads.push(observation);
+  }
+  return {
+    record: (documentArg) => {
+      if (observation.settled) return;
+      if (!isPlainRecord(documentArg)) {
+        observation.byId = null;
+        observation.byIdentity = null;
+        return;
+      }
+      const idKey = documentIdKeyOf(documentArg._id);
+      if (idKey === undefined) observation.byId = null;
+      else observation.byId?.add(idKey);
+      if (observation.byIdentity && observation.identityFields) {
+        const identityKey = identityKeyOf(observation.identityFields.map((fieldArg) =>
+          Object.hasOwn(documentArg, fieldArg) ? documentArg[fieldArg] : undefined));
+        if (identityKey === undefined) observation.byIdentity = null;
+        else observation.byIdentity.add(identityKey);
+      }
+    },
+    settle: () => {
+      if (!observation.settles || observation.settled) return;
+      observation.settled = true;
+      observation.settledAt = ++sequence;
+    },
+  };
+};
+
+/**
+ * @internal Runs one model write. A write inside a read scope marks its sets
+ * changed; any other write records when it started, so its report can tell
+ * which reads ran concurrently with it.
+ */
+export const runSmartdataWrite = <TResult>(
+  dbArg: SmartdataDb,
+  operationArg: () => Promise<TResult>,
+): Promise<TResult> => {
+  for (const state of readScope.getStore() ?? []) changeReadSet(state);
+  if (!trackedDbs.has(dbArg)) return operationArg();
+  return writeScope.run({ db: dbArg, startedAt: ++sequence }, operationArg);
+};
+
+/**
+ * @internal Captures how one acknowledged write changes the open read sets of
+ * its database, and returns the change to apply, or `undefined` when no set
+ * can be affected. A `deferred` change is applied after a transaction
+ * commits; it copies the written values now and also reaches sets opened in
+ * the meantime.
+ */
+export const captureSmartdataReadChange = (
+  dbArg: SmartdataDb,
+  writeArg: ISmartdataWrite,
+  deferredArg: boolean,
+): (() => void) | undefined => {
+  if (!trackedDbs.has(dbArg)) {
+    return deferredArg ? captureSmartdataCollectionChange(dbArg, writeArg.collection, true) : undefined;
+  }
+  if (!deferredArg && !hasSmartdataReadSets(dbArg)) return undefined;
+  const scope = writeScope.getStore();
+  const startedAt = scope?.db === dbArg ? scope.startedAt : 0;
+  const write = deferredArg
+    ? {
+      ...writeArg,
+      documents: writeArg.documents?.map((documentArg) => snapshotValue(documentArg) as object) ?? null,
+      selector: snapshotValue(writeArg.selector),
+      update: snapshotValue(writeArg.update),
+    }
+    : writeArg;
+  const changes = describeWrite(write, startedAt);
+  return () => applyChanges(dbArg, writeArg.collection, changes);
+};
+
+/**
+ * @internal Captures a write to the collection whose effect is not known — a
+ * failed write may still have applied — so every read of it counts as changed.
+ */
+export const captureSmartdataCollectionChange = (
+  dbArg: SmartdataDb,
+  collectionArg: string,
+  deferredArg: boolean,
+): (() => void) | undefined => {
+  if (!deferredArg && !hasSmartdataReadSets(dbArg)) return undefined;
+  return () => applyChanges(dbArg, collectionArg, [{ kind: 'unknown', touched: 'all', startedAt: 0 }]);
+};