@lossless.org/client 1.21.1 → 1.22.0

package/ts/nosqldb/classes.readtracker.ts

@@ -5,6 +5,13 @@ 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';
+import {
+  isSmartdataWriteRevisionsActive,
+  readWriteRevisionSnapshot,
+  revisionIdOfValue,
+  sharedRevisionId,
+  writeRevisionKeysOfRead,
+} from './classes.writerevisions.js';
 
 /**
  * The reads one `db.trackReads()` call made. `changed` turns true once a write
@@ -22,6 +29,42 @@ export class SmartdataReadSet {
     return !state || state.changed;
   }
 
+  /**
+   * Whether no write of any process could have changed what the reads
+   * returned: `changed` is false, and the write revisions the reads depend on
+   * are what they were before the reads ran. Requires the database's
+   * `writeRevisions` option and an engine with transactions; without them,
+   * and whenever the revisions cannot be read in time, it is false.
+   *
+   * The revisions count writes per collection and partition, not per read,
+   * so a write of this process that left `changed` false also makes it false
+   * when it wrote to a partition or collection the reads depend on.
+   */
+  public async isCurrent(): Promise<boolean> {
+    const state = readSetStates.get(this);
+    const revisions = state?.revisions;
+    if (!state || state.changed || !revisions || revisions.lost) return false;
+    if (!isSmartdataWriteRevisionsActive(state.db)) return false;
+    try {
+      // Reads still starting add snapshots; wait until the set has them all.
+      let count: number;
+      let values: (string | undefined)[];
+      do {
+        count = revisions.snapshots.size;
+        values = await Promise.all(revisions.snapshots.values());
+        if (state.changed || revisions.lost) return false;
+      } while (revisions.snapshots.size !== count);
+      if (count === 0) return true;
+      if (values.some((valueArg) => valueArg === undefined)) return false;
+      const keys = [...revisions.snapshots.keys()];
+      const current = await readWriteRevisionSnapshot(state.db, keys);
+      if (state.changed) return false;
+      return keys.every((keyArg, indexArg) => current.get(keyArg) === values[indexArg]);
+    } catch {
+      return false;
+    }
+  }
+
   /** Stops following writes and frees the recorded reads; `changed` is true from then on. */
   public close(): void {
     const state = readSetStates.get(this);
@@ -67,6 +110,11 @@ export interface ISmartdataReadRecorder {
   record(documentArg: unknown): void;
   /** The read returned everything it will return. */
   settle(): void;
+  /**
+   * Settles once the write revisions the read depends on were read; the read
+   * is issued after it. `undefined` when there is nothing to wait for.
+   */
+  ready?: Promise<void>;
 }
 
 // Values an image or a stored path can hold beside real values.
@@ -110,6 +158,15 @@ interface IReadSetState {
   /** The callback returned, so its read collections have been checked. */
   finished: boolean;
   reads: Map<string, IReadObservation[]>;
+  /** The write revisions the reads depend on; only while write revisions are active. */
+  revisions?: IReadSetRevisions;
+}
+
+interface IReadSetRevisions {
+  /** Per snapshot key, its value before the first read that depends on it; `undefined` when unknown. */
+  snapshots: Map<string, Promise<string | undefined>>;
+  /** A revision could not be read, so the set can never be current. */
+  lost: boolean;
 }
 
 /** What one write did to one document, as far as it is known. */
@@ -830,6 +887,7 @@ export const trackSmartdataReads = async <TResult>(
   }
   const reads = new SmartdataReadSet();
   const state: IReadSetState = { db: dbArg, changed: false, finished: false, reads: new Map() };
+  if (isSmartdataWriteRevisionsActive(dbArg)) state.revisions = { snapshots: new Map(), lost: false };
   readSetStates.set(reads, state);
   let states = readSetsByDb.get(dbArg);
   if (!states) {
@@ -883,6 +941,45 @@ const limitFollowsQuery = (specArg: ISmartdataReadSpec): boolean => {
       isPlainRecord(sort) && Object.hasOwn(sort, fieldArg));
 };
 
+/**
+ * Reads the write revisions a read depends on that its sets have no snapshot
+ * of yet, once for all of them. The earliest snapshot of a key stays, so a set
+ * compares against the state before its first read of it.
+ */
+const snapshotWriteRevisions = (
+  dbArg: SmartdataDb,
+  specArg: ISmartdataReadSpec,
+  statesArg: readonly IReadSetState[],
+): Promise<void> | undefined => {
+  const states = statesArg.filter((stateArg) => stateArg.revisions && !stateArg.revisions.lost);
+  if (states.length === 0) return undefined;
+  if (!isSmartdataWriteRevisionsActive(dbArg)) {
+    for (const state of states) state.revisions!.lost = true;
+    return undefined;
+  }
+  const keys = writeRevisionKeysOfRead(dbArg, specArg.collection, specArg.kind, specArg.filter);
+  const missing = keys.filter((keyArg) =>
+    states.some((stateArg) => !stateArg.revisions!.snapshots.has(keyArg)));
+  if (missing.length === 0) return undefined;
+  const snapshot = (async () => readWriteRevisionSnapshot(dbArg, missing))()
+    .catch(() => undefined);
+  const pending: Promise<unknown>[] = [];
+  for (const state of states) {
+    const revisions = state.revisions!;
+    for (const key of missing) {
+      if (revisions.snapshots.has(key)) continue;
+      const value = snapshot.then((snapshotArg) => {
+        const known = snapshotArg?.get(key);
+        if (known === undefined) revisions.lost = true;
+        return known;
+      });
+      revisions.snapshots.set(key, value);
+      pending.push(value);
+    }
+  }
+  return Promise.all(pending).then(() => undefined);
+};
+
 /**
  * @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
@@ -948,6 +1045,7 @@ export const observeSmartdataRead = (
     reads.push(observation);
   }
   return {
+    ready: snapshotWriteRevisions(dbArg, specArg, followed),
     record: (documentArg) => {
       if (observation.settled) return;
       if (!isPlainRecord(documentArg)) {
@@ -1029,3 +1127,44 @@ export const captureSmartdataCollectionChange = (
   if (!deferredArg && !hasSmartdataReadSets(dbArg)) return undefined;
   return () => applyChanges(dbArg, collectionArg, [{ kind: 'unknown', touched: 'all', startedAt: 0 }]);
 };
+
+/**
+ * @internal The write-revision counters one acknowledged write bumps: the
+ * partition of each document state it names before and after, and the shared
+ * counter for each state it cannot place. A state before the write that the
+ * report does not carry was read ahead of the write when
+ * `previousPartitionsRead` is set; a field the write left alone keeps the
+ * value it has afterwards.
+ */
+export const writeRevisionIdsOfWrite = (
+  writeArg: ISmartdataWrite,
+  fieldArg: string,
+): Set<string> => {
+  const collection = writeArg.collection;
+  const ids = new Set<string>();
+  const add = (valueArg: unknown) => {
+    ids.add(valueArg === UNKNOWN
+      ? sharedRevisionId(collection)
+      : revisionIdOfValue(collection, valueArg === MISSING ? undefined : valueArg));
+  };
+  for (const change of describeWrite(writeArg, 0)) {
+    if (change.kind === 'unknown') {
+      ids.add(sharedRevisionId(collection));
+      continue;
+    }
+    const fieldTouched = change.touched === 'all'
+      || [...change.touched].some((pathArg) => pathsOverlap(pathArg, fieldArg));
+    const after = change.kind === 'delete' ? undefined : lookupPath(change.after, fieldArg);
+    if (change.kind !== 'delete' && (after !== UNKNOWN || fieldTouched || change.kind === 'insert')) {
+      add(after);
+    }
+    if (change.kind === 'insert') continue;
+    const before = lookupPath(change.before, fieldArg);
+    if (before !== UNKNOWN) {
+      add(before);
+    } else if (!writeArg.previousPartitionsRead && (fieldTouched || after === UNKNOWN)) {
+      add(UNKNOWN);
+    }
+  }
+  return ids;
+};

package/ts/nosqldb/classes.session.ts

@@ -30,9 +30,17 @@ import {
   hasSmartdataReadSets,
   observeSmartdataRead,
   runSmartdataWrite,
+  writeRevisionIdsOfWrite,
   type ISmartdataReadRecorder,
   type ISmartdataReadSpec,
 } from './classes.readtracker.js';
+import {
+  flushSmartdataWriteRevisions,
+  isSmartdataWriteRevisionsActive,
+  readPreviousRevisionIds,
+  sharedRevisionId,
+  writeRevisionsPartitionField,
+} from './classes.writerevisions.js';
 
 interface ISmartdataSessionBinding {
   session: SmartdataSession;
@@ -60,6 +68,8 @@ interface ISmartdataSessionBinding {
    * when the commit outcome is unknown.
    */
   transactionWrites: ISmartdataTransactionWrite[];
+  /** The write-revision counters the current attempt's writes bump right before its commit. */
+  revisionBumps: Set<string>;
   operationSettled?: Promise<void>;
   resolveOperationSettled?: () => void;
   invalidated: boolean;
@@ -136,6 +146,8 @@ const createTransactionSessionEndedError = (
   );
 
 const bindings = new WeakMap<SmartdataSession, ISmartdataSessionBinding>();
+/** The binding of each owned session's driver session, for writes that only hold the latter. */
+const bindingsByRawSession = new WeakMap<plugins.mongodb.ClientSession, ISmartdataSessionBinding>();
 const bindingsByOwner = new WeakMap<SmartdataDb, Set<ISmartdataSessionBinding>>();
 const smartdataSessionInvalidationAggregateBrand = Symbol(
   'smartdataSessionInvalidationAggregate',
@@ -156,6 +168,11 @@ interface ISmartdataSessionAcquireOptions {
 interface IOrdinarySessionOperationOptions {
   ordinaryWrite?: boolean;
   prepared?: boolean;
+  /**
+   * Prepares the collection. A write of a database with write revisions that
+   * runs in a transaction of its own prepares first, outside it.
+   */
+  prepare?: () => Promise<void>;
   /** Names the collection whose preparation a refusal must ask for. */
   collectionName?: string;
   /** The caller's validated client deadline for the call's database work. */
@@ -186,6 +203,16 @@ const transactionContext = new plugins.nodeAsyncHooks.AsyncLocalStorage<
   ITransactionContext
 >();
 
+/**
+ * The session of the transaction a write of a database with write revisions
+ * runs in when its caller passed none, so the write's reports and reads
+ * belong to that transaction.
+ */
+const revisionTransactionScope = new plugins.nodeAsyncHooks.AsyncLocalStorage<{
+  owner: SmartdataDb;
+  session: SmartdataSession;
+}>();
+
 const resolveBinding = (
   sessionArg: SmartdataSession,
   ownerArg?: SmartdataDb,
@@ -342,6 +369,7 @@ export class SmartdataSession {
       binding.transactionFailure = undefined;
       binding.transactionCommitReached = false;
       binding.transactionWrites = [];
+      binding.revisionBumps = new Set();
       callbackError = undefined;
       attemptInterruption = undefined;
       try {
@@ -393,6 +421,16 @@ export class SmartdataSession {
         }
         // An abort that arrived while the callback ran rolls the attempt back.
         signal?.throwIfAborted();
+        // The writes' revisions commit with them. A failure fails the attempt
+        // before its commit, and a transient one is retried with it.
+        if (binding.revisionBumps.size > 0) {
+          await flushSmartdataWriteRevisions(
+            binding.client.db(binding.owner.smartdataOptions.mongoDbName),
+            binding.rawSession,
+            binding.revisionBumps,
+            signal,
+          );
+        }
         // The driver commits next; a deadline that expires or a session that
         // ends from here on leaves the commit outcome unknown.
         binding.transactionCommitReached = true;
@@ -490,6 +528,7 @@ export class SmartdataSession {
       binding.transactionCommitReached = false;
       binding.transactionEnded = undefined;
       binding.transactionWrites = [];
+      binding.revisionBumps = new Set();
     }
     if (transactionEnded) {
       const outcome = commitOutcomeOfTransactionEnd(transactionEnded);
@@ -538,9 +577,11 @@ export const createSmartdataSession = (ownerArg: SmartdataDb): SmartdataSession
     transactionUsesOrdinaryWrite: false,
     transactionCommitReached: false,
     transactionWrites: [],
+    revisionBumps: new Set(),
     invalidated: false,
   };
   bindings.set(session, binding);
+  bindingsByRawSession.set(binding.rawSession, binding);
   let ownerBindings = bindingsByOwner.get(ownerArg);
   if (!ownerBindings) {
     ownerBindings = new Set();
@@ -780,12 +821,90 @@ export const settleSmartdataOperationError = (
   return error;
 };
 
+/**
+ * The session of the transaction a write of a database with write revisions
+ * runs in on its caller's behalf, while that transaction runs.
+ */
+const revisionTransactionSessionOf = (ownerArg: SmartdataDb): SmartdataSession | undefined => {
+  const scope = revisionTransactionScope.getStore();
+  return scope?.owner === ownerArg && bindings.get(scope.session)?.transactionActive
+    ? scope.session
+    : undefined;
+};
+
+/**
+ * Whether a write must start a transaction of its own to carry its write
+ * revisions: the database keeps them and the write runs outside an owned
+ * transaction. A raw driver session cannot carry them and is refused.
+ */
+export const needsSmartdataRevisionTransaction = (
+  sessionArg: TSmartdataOrdinarySession | undefined,
+  ownerArg: SmartdataDb,
+): boolean => {
+  if (!isSmartdataWriteRevisionsActive(ownerArg)) return false;
+  if (sessionArg !== undefined && !isSmartdataSession(sessionArg)) {
+    throw new SmartdataPersistenceError(
+      'unsupported_operation',
+      'Writes of a database with write revisions run on sessions of db.createSession(), not raw driver sessions.',
+    );
+  }
+  return sessionArg === undefined || !resolveBinding(sessionArg, ownerArg).transactionActive;
+};
+
+const transactionOptionsOf = (
+  timeoutMSArg: number | undefined,
+  signalArg: AbortSignal | undefined,
+): ISmartdataTransactionOptions => ({
+  ...(timeoutMSArg === undefined ? {} : { timeoutMS: timeoutMSArg }),
+  ...(signalArg === undefined ? {} : { signal: signalArg }),
+});
+
+/**
+ * Runs one write of a database with write revisions in a transaction, so its
+ * revisions commit with it: on the caller's owned session, or on a session of
+ * its own that ends with the call. The call's deadline and signal bound the
+ * whole transaction; the collection is prepared before it starts, since its
+ * DDL cannot run inside.
+ */
+export const runSmartdataRevisionTransaction = async <TResult>(
+  sessionArg: SmartdataSession | undefined,
+  ownerArg: SmartdataDb,
+  optionsArg: Pick<
+    IOrdinarySessionOperationOptions,
+    'prepared' | 'prepare' | 'collectionName' | 'timeoutMS' | 'defaultTimeoutMS' | 'signal'
+  >,
+  writeArg: (sessionArg: SmartdataSession) => Promise<TResult>,
+): Promise<TResult> => {
+  const timeoutMS = optionsArg.timeoutMS ?? optionsArg.defaultTimeoutMS;
+  if (sessionArg) {
+    if (!optionsArg.prepared) refuseUnpreparedCollection(optionsArg, 'with an owned SmartData session');
+    return await sessionArg.withTransaction(writeArg, transactionOptionsOf(timeoutMS, optionsArg.signal)) as TResult;
+  }
+  const deadline = new SmartdataOperationDeadline(timeoutMS, optionsArg.signal);
+  if (!optionsArg.prepared) {
+    if (!optionsArg.prepare) refuseUnpreparedCollection(optionsArg, 'inside a transaction');
+    await deadline.join(optionsArg.prepare!());
+  }
+  const transactionOptions = transactionOptionsOf(deadline.remainingTimeoutMS(), optionsArg.signal);
+  const session = createSmartdataSession(ownerArg);
+  try {
+    return await revisionTransactionScope.run(
+      { owner: ownerArg, session },
+      () => session.withTransaction(writeArg, transactionOptions),
+    ) as TResult;
+  } finally {
+    // A session whose end fails stays owned and invalidated; the database's close() ends it again.
+    await session.close().catch(() => {});
+  }
+};
+
 /**
  * Runs one model operation on the ordinary session boundary: the owned
  * session lease, the operation's client deadline and signal, and the mapping
  * of an expired driver deadline to the `timeout` persistence error. A write
  * that fails once started may still have applied, so it changes every open
- * read set that read its collection.
+ * read set that read its collection. A write of a database with write
+ * revisions runs in an owned transaction; outside one it starts its own.
  */
 export const runWithOrdinarySmartdataSession = async <TResult>(
   sessionArg: TSmartdataOrdinarySession | undefined,
@@ -797,6 +916,18 @@ export const runWithOrdinarySmartdataSession = async <TResult>(
   ) => Promise<TResult>,
 ): Promise<TResult> => {
   optionsArg.signal?.throwIfAborted();
+  if (optionsArg.ordinaryWrite && needsSmartdataRevisionTransaction(sessionArg, ownerArg)) {
+    return runSmartdataRevisionTransaction(
+      sessionArg as SmartdataSession | undefined,
+      ownerArg,
+      optionsArg,
+      (transactionSessionArg) => runWithOrdinarySmartdataSession(transactionSessionArg, ownerArg, {
+        ordinaryWrite: true,
+        prepared: true,
+        ...(optionsArg.collectionName === undefined ? {} : { collectionName: optionsArg.collectionName }),
+      }, operationArg),
+    );
+  }
   const lease = leaseOrdinarySmartdataSession(sessionArg, ownerArg, optionsArg);
   let deadline: SmartdataOperationDeadline | undefined;
   let writeStarted = false;
@@ -834,6 +965,41 @@ const bufferTransactionWrite = (
   }
 };
 
+/**
+ * Adds write-revision counters to the current attempt of an owned transaction.
+ * A write that settles after its attempt ended rolls back with that attempt.
+ */
+const bumpTransactionRevisions = (
+  bindingArg: ISmartdataSessionBinding,
+  idsArg: Iterable<string>,
+): void => {
+  const attempt = transactionContext.getStore()?.attempt;
+  if (attempt === undefined || attempt !== bindingArg.transactionAttempt) return;
+  for (const id of idsArg) bindingArg.revisionBumps.add(id);
+};
+
+/**
+ * Reads, in the write's transaction, the write-revision partitions of the
+ * documents a write by selector is about to change, and returns whether it
+ * did; the write's report then states `previousPartitionsRead`. `false` when
+ * the database keeps no revisions or the write runs outside an owned
+ * transaction.
+ */
+export const readPreviousWriteRevisions = async (
+  ownerArg: SmartdataDb,
+  collectionArg: plugins.mongodb.Collection<any>,
+  rawSessionArg: plugins.mongodb.ClientSession | undefined,
+  selectorArg: unknown,
+  deadlineArg: SmartdataOperationDeadline,
+): Promise<boolean> => {
+  if (!rawSessionArg || !isSmartdataWriteRevisionsActive(ownerArg)) return false;
+  const binding = bindingsByRawSession.get(rawSessionArg);
+  if (!binding?.transactionActive || binding.owner !== ownerArg) return false;
+  const ids = await readPreviousRevisionIds(ownerArg, collectionArg, rawSessionArg, selectorArg, deadlineArg);
+  bumpTransactionRevisions(binding, ids);
+  return true;
+};
+
 /**
  * Reports one acknowledged write to the owner's write observers and open read
  * sets: at once, or, inside an owned transaction, after it committed. A
@@ -846,6 +1012,7 @@ export const reportSmartdataWrite = (
   sessionArg: TSmartdataOrdinarySession | undefined,
   writeArg: ISmartdataWrite,
 ): void => {
+  sessionArg ??= revisionTransactionSessionOf(ownerArg);
   if (!isSmartdataSession(sessionArg) && sessionArg?.inTransaction()) {
     // A raw driver transaction passed its lease while nobody observed or
     // tracked, and whether it commits is never known here.
@@ -854,6 +1021,12 @@ export const reportSmartdataWrite = (
   }
   const binding = isSmartdataSession(sessionArg) ? bindings.get(sessionArg) : undefined;
   const buffered = binding?.transactionActive === true;
+  if (binding && buffered) {
+    const field = writeRevisionsPartitionField(ownerArg);
+    if (field !== undefined && isSmartdataWriteRevisionsActive(ownerArg)) {
+      bumpTransactionRevisions(binding, writeRevisionIdsOfWrite(writeArg, field));
+    }
+  }
   const changeReads = captureSmartdataReadChange(ownerArg, writeArg, buffered);
   const deliver = captureSmartdataWrite(ownerArg, writeArg);
   if (!changeReads && !deliver) return;
@@ -875,8 +1048,12 @@ export const reportSmartdataWriteFailure = (
   sessionArg: TSmartdataOrdinarySession | undefined,
   collectionNameArg: string,
 ): void => {
+  sessionArg ??= revisionTransactionSessionOf(ownerArg);
   const binding = isSmartdataSession(sessionArg) ? bindings.get(sessionArg) : undefined;
   const buffered = binding?.transactionActive === true;
+  if (binding && buffered && isSmartdataWriteRevisionsActive(ownerArg)) {
+    bumpTransactionRevisions(binding, [sharedRevisionId(collectionNameArg)]);
+  }
   const changeReads = captureSmartdataCollectionChange(ownerArg, collectionNameArg, buffered);
   if (!changeReads) return;
   if (binding && buffered) {
@@ -898,7 +1075,7 @@ export const reportSmartdataCollectionWrite = (
   kindArg: TSmartdataWriteKind,
   documentsArg: readonly object[] | null,
   selectorArg?: unknown,
-  readImagesArg?: Pick<ISmartdataWrite, 'images' | 'update'>,
+  readImagesArg?: Pick<ISmartdataWrite, 'images' | 'update' | 'previousPartitionsRead'>,
 ): void => {
   const schema = collectionArg.getBoundModelSchema();
   reportSmartdataWrite(collectionArg.smartdataDb, sessionArg, {
@@ -923,43 +1100,49 @@ const identityFieldsOfSchema = (
 /**
  * Registers one read of a model collection with the open read sets of the
  * current async context, right before it is issued; `undefined` when none is
- * open. See `observeSmartdataRead`.
+ * open. See `observeSmartdataRead`. Settles once the write revisions the read
+ * depends on were read, within `deadlineArg`; issue the read after it.
  */
 export const trackSmartdataRead = (
   collectionArg: SmartdataCollection<any>,
   sessionArg: TSmartdataOrdinarySession | undefined,
   specArg: Omit<ISmartdataReadSpec, 'collection' | 'identityFields' | 'orderingIdentityFields'>,
-): ISmartdataReadRecorder | undefined => trackSmartdataModelRead(
+  deadlineArg?: SmartdataOperationDeadline,
+): Promise<ISmartdataReadRecorder | undefined> => trackSmartdataModelRead(
   collectionArg.smartdataDb,
   collectionArg.collectionName,
   collectionArg.getBoundModelSchema(),
   sessionArg,
   specArg,
+  deadlineArg,
 );
 
 /** `trackSmartdataRead` for a read that names its model by schema rather than collection. */
-export const trackSmartdataModelRead = (
+export const trackSmartdataModelRead = async (
   dbArg: SmartdataDb,
   collectionNameArg: string,
   schemaArg: ReturnType<SmartdataCollection<any>['getBoundModelSchema']>,
   sessionArg: TSmartdataOrdinarySession | undefined,
   specArg: Omit<ISmartdataReadSpec, 'collection' | 'identityFields' | 'orderingIdentityFields'>,
-): ISmartdataReadRecorder | undefined => {
+  deadlineArg?: SmartdataOperationDeadline,
+): Promise<ISmartdataReadRecorder | undefined> => {
   if (!hasSmartdataReadScope()) return undefined;
   let inTransaction: boolean;
   try {
-    inTransaction = isOrdinarySessionInTransaction(sessionArg);
+    inTransaction = isOrdinarySessionInTransaction(sessionArg ?? revisionTransactionSessionOf(dbArg));
   } catch {
     // An ended session's read fails; a set must not count it as followed.
     inTransaction = true;
   }
   const identityFields = identityFieldsOfSchema(schemaArg);
-  return observeSmartdataRead(dbArg, {
+  const recorder = observeSmartdataRead(dbArg, {
     ...specArg,
     collection: collectionNameArg,
     identityFields,
     orderingIdentityFields: schemaArg && identityFields ? getOrderingIdentityFields(schemaArg) : undefined,
   }, inTransaction);
+  if (recorder?.ready) await (deadlineArg ? deadlineArg.join(recorder.ready) : recorder.ready);
+  return recorder;
 };
 
 /**

package/ts/nosqldb/classes.storedinspection.ts

@@ -3,6 +3,7 @@ import type { SmartdataDb } from './classes.db.js';
 import { convertFilterForMongoDb } from './classes.doc.js';
 import { SmartdataPersistenceError } from './classes.persistence.js';
 import { runCursorOperation } from './classes.cursoroperation.js';
+import { SmartdataOperationDeadline } from './classes.operationdeadline.js';
 import {
   acquireSmartdataSession, isSmartdataSession, trackSmartdataModelRead, type SmartdataSession,
 } from './classes.session.js';
@@ -81,12 +82,14 @@ const readStoredDocuments = async (
   let page: { documents: plugins.mongodb.Document[]; hasMore: boolean };
   try {
     page = await dbArg[collectionTopologyDbInspectionSymbol](async (mongoDbArg) => {
-      const tracked = trackSmartdataModelRead(dbArg, schema.collectionName, schema, opts.session, {
+      const deadline = new SmartdataOperationDeadline(timeoutMS, opts.signal);
+      const tracked = await trackSmartdataModelRead(dbArg, schema.collectionName, schema, opts.session, {
         kind: 'documents', filter, sort: { _id: 1 }, matches: skip > 0, limited: true,
-      });
+      }, deadline);
       const cursor = mongoDbArg.collection(schema.collectionName).find(filter, {
         sort: { _id: 1 }, skip, limit: limit + 1, batchSize: 1,
-        timeoutMS, timeoutMode: 'cursorLifetime', signal: opts.signal, session: lease?.rawSession,
+        timeoutMS: deadline.remainingTimeoutMS(), timeoutMode: 'cursorLifetime', signal: opts.signal,
+        session: lease?.rawSession,
       });
       return runCursorOperation(cursor, async (cursorArg) => {
         const documents: plugins.mongodb.Document[] = [];

package/ts/nosqldb/classes.writeobserver.ts

@@ -62,6 +62,11 @@ export interface ISmartdataWrite {
   update?: unknown;
   /** The model's identity fields, by which a selector names a document without its `_id`. */
   identityFields?: readonly string[];
+  /**
+   * The write-revision partitions of the documents the selector matched were
+   * read in the write's transaction before it ran.
+   */
+  previousPartitionsRead?: true;
 }
 
 interface IWriteObserver {