@lossless.org/client 1.19.0 → 1.20.0

package/ts/nosqldb/classes.atomicupdate.ts

@@ -1,7 +1,11 @@
 import * as plugins from './plugins.js';
 import type { SmartdataCollection } from './classes.collection.js';
-import { normalizeOrdinaryPersistenceError } from './classes.persistence.js';
 import {
+  getMongoBulkWriteErrorIndexes,
+  normalizeOrdinaryPersistenceError,
+} from './classes.persistence.js';
+import {
+  reportSmartdataCollectionWrite,
   runWithOrdinarySmartdataSession,
   type TSmartdataOrdinarySession,
 } from './classes.session.js';
@@ -21,6 +25,8 @@ export const executeAtomicUpdate = async <T>(
     upsert?: boolean;
     session?: TSmartdataOrdinarySession;
     timeoutMS?: number;
+    /** The document image the update writes, when the caller holds one: a fenced save's instance. */
+    observedDocument?: object;
   },
 ): Promise<plugins.mongodb.UpdateResult> => {
   return runWithOrdinarySmartdataSession(
@@ -35,7 +41,7 @@ export const executeAtomicUpdate = async <T>(
     async (rawSessionArg, deadlineArg) => {
       await deadlineArg.join(collectionArg.init());
       try {
-        return await collectionArg.mongoDbCollection.updateOne(
+        const result = await collectionArg.mongoDbCollection.updateOne(
           filterArg,
           updateArg,
           {
@@ -44,6 +50,16 @@ export const executeAtomicUpdate = async <T>(
             ...deadlineArg.commandOptions(),
           },
         );
+        if (result.upsertedCount > 0 || result.matchedCount > 0) {
+          reportSmartdataCollectionWrite(
+            collectionArg,
+            optsArg?.session,
+            result.upsertedCount > 0 ? 'insert' : 'update',
+            optsArg?.observedDocument ? [optsArg.observedDocument] : null,
+            filterArg,
+          );
+        }
+        return result;
       } catch (errorArg) {
         return normalizeOrdinaryPersistenceError(
           errorArg,
@@ -90,6 +106,25 @@ export const executeAtomicUpsertMany = async <T>(
     },
     async (rawSessionArg, deadlineArg) => {
       await deadlineArg.join(collectionArg.init());
+      /**
+       * Every entry upserts, so an entry that neither inserted nor failed
+       * matched its document.
+       */
+      const reportEntries = (
+        upsertedIdsArg: Record<number, unknown> | undefined,
+        failedIndexesArg: ReadonlySet<number>,
+      ): void => {
+        operationsArg.forEach((operationArg, indexArg) => {
+          if (failedIndexesArg.has(indexArg)) return;
+          reportSmartdataCollectionWrite(
+            collectionArg,
+            optsArg?.session,
+            Object.hasOwn(upsertedIdsArg ?? {}, indexArg) ? 'insert' : 'update',
+            null,
+            operationArg.filter,
+          );
+        });
+      };
       try {
         const result = await collectionArg.mongoDbCollection.bulkWrite(
           operationsArg.map((operationArg) => ({
@@ -105,6 +140,9 @@ export const executeAtomicUpsertMany = async <T>(
             ...deadlineArg.commandOptions(),
           },
         );
+        if (result.isOk()) {
+          reportEntries(result.upsertedIds, new Set());
+        }
         return {
           acknowledged: result.isOk(),
           matchedCount: result.matchedCount,
@@ -112,6 +150,14 @@ export const executeAtomicUpsertMany = async <T>(
           upsertedCount: result.upsertedCount,
         };
       } catch (errorArg) {
+        // An unordered batch that failed on write errors attempted every entry.
+        const failedIndexes = getMongoBulkWriteErrorIndexes(errorArg);
+        if (failedIndexes) {
+          reportEntries(
+            (errorArg as plugins.mongodb.MongoBulkWriteError).result?.upsertedIds,
+            failedIndexes,
+          );
+        }
         return normalizeOrdinaryPersistenceError(
           errorArg,
           `Atomic upsert-many conflicts with a unique index in collection "${collectionArg.collectionName}".`,
@@ -151,7 +197,7 @@ export const executeAtomicUpdateMany = async <T>(
     async (rawSessionArg, deadlineArg) => {
       await deadlineArg.join(collectionArg.init());
       try {
-        return await collectionArg.mongoDbCollection.updateMany(
+        const result = await collectionArg.mongoDbCollection.updateMany(
           filterArg,
           updateArg,
           {
@@ -159,6 +205,10 @@ export const executeAtomicUpdateMany = async <T>(
             ...deadlineArg.commandOptions(),
           },
         );
+        if (result.matchedCount > 0) {
+          reportSmartdataCollectionWrite(collectionArg, optsArg?.session, 'update', null, filterArg);
+        }
+        return result;
       } catch (errorArg) {
         return normalizeOrdinaryPersistenceError(
           errorArg,

package/ts/nosqldb/classes.bootstraprecord.ts

@@ -6,6 +6,7 @@ import { snapshotBoundedBsonDocument } from './classes.bsonsnapshot.js';
 import { validateOrdinaryStoredDocument } from './classes.ordinarypersistence.js';
 import { SmartdataPersistenceError, isMongoDuplicateKeyError } from './classes.persistence.js';
 import { readBoundedInspectionCursor } from './classes.namespaceinspection.js';
+import { reportSmartdataWrite } from './classes.session.js';
 import {
   collectionModelSchemaResolverSymbol, collectionTopologyDbInspectionSymbol,
   getExpectedCollectionTopologyForSchema, inspectCollectionTopologySnapshot,
@@ -96,7 +97,12 @@ export const insertBootstrapRecord = async (
         dispatched ? 'Bootstrap insertion outcome is uncertain; inspect its explicit ID before proceeding.'
           : 'Bootstrap insertion could not inspect the current database connection.');
     }
-    if (outcome === 'inserted') return Object.freeze({ acknowledged: true, insertedId: document._id as string });
+    if (outcome === 'inserted') {
+      reportSmartdataWrite(dbArg, undefined, {
+        collection: schema.collectionName, kind: 'insert', documents: [document],
+      });
+      return Object.freeze({ acknowledged: true, insertedId: document._id as string });
+    }
     const messages = {
       unique_conflict: 'Bootstrap record conflicts with a unique index.',
       invalid_configuration: 'Bootstrap insertion requires absent or exact primary-only collection topology.',

package/ts/nosqldb/classes.collection.ts

@@ -24,13 +24,16 @@ import { CollectionFactory } from './classes.collectionfactory.js';
 import { logger } from './logging.js';
 import {
   SmartdataPersistenceError,
+  getMongoBulkWriteErrorIndexes,
   isMongoIndexConflictError,
   normalizeOrdinaryPersistenceError,
 } from './classes.persistence.js';
 import { notifyCollectionReconnect } from './classes.collectionlifecycle.js';
 import type { SmartdataOperationDeadline } from './classes.operationdeadline.js';
+import { hasSmartdataWriteObservers } from './classes.writeobserver.js';
 import {
   leaseOrdinarySmartdataSession,
+  reportSmartdataCollectionWrite,
   runWithOrdinarySmartdataSession,
   type TSmartdataOrdinarySession,
 } from './classes.session.js';
@@ -2595,10 +2598,14 @@ export class SmartdataCollection<T> {
 
         const saveableObject = preparedObject ?? await dbDocArg.createSavableObject();
         try {
-          return await this.mongoDbCollection.insertOne(saveableObject, {
+          const result = await this.mongoDbCollection.insertOne(saveableObject, {
             session: rawSessionArg,
             ...deadlineArg.commandOptions(),
           });
+          if (result.acknowledged) {
+            reportSmartdataCollectionWrite(this, opts?.session, 'insert', [saveableObject]);
+          }
+          return result;
         } catch (err: any) {
           return normalizeOrdinaryPersistenceError(
             err,
@@ -2707,13 +2714,29 @@ export class SmartdataCollection<T> {
             saveableObjects.push(await dbDocArg.createSavableObject());
           }
         }
+        const reportInserted = (insertedIdsArg: Record<number, unknown> | undefined): void => {
+          const inserted = Object.keys(insertedIdsArg ?? {})
+            .map((indexArg) => saveableObjects[Number(indexArg)])
+            .filter((documentArg) => documentArg !== undefined);
+          if (inserted.length > 0) {
+            reportSmartdataCollectionWrite(this, opts?.session, 'insert', inserted);
+          }
+        };
         try {
-          return await this.mongoDbCollection.insertMany(saveableObjects, {
+          const result = await this.mongoDbCollection.insertMany(saveableObjects, {
             session: rawSessionArg,
             ordered: opts?.ordered !== false,
             ...deadlineArg.commandOptions(),
           });
+          if (result.acknowledged) {
+            reportInserted(result.insertedIds);
+          }
+          return result;
         } catch (err: any) {
+          // A batch that failed on write errors names the documents it still inserted.
+          if (getMongoBulkWriteErrorIndexes(err)) {
+            reportInserted((err as plugins.mongodb.MongoBulkWriteError).result?.insertedIds);
+          }
           return normalizeOrdinaryPersistenceError(
             err,
             `Insert conflicts with a unique index in collection "${this.collectionName}".`,
@@ -2756,6 +2779,14 @@ export class SmartdataCollection<T> {
       // seeded body must not repeat the immutable primary key: MongoDB derives
       // it from the filter's equality condition on the insert branch.
       const documentIdIdentity = this.modelSchema?.identityAsDocumentId === identityFieldArg;
+      const reportUpserted = (upsertedIdsArg: Record<number, unknown> | undefined): void => {
+        const inserted = Object.keys(upsertedIdsArg ?? {})
+          .map((indexArg) => prepared[Number(indexArg)])
+          .filter((documentArg) => documentArg !== undefined);
+        if (inserted.length > 0) {
+          reportSmartdataCollectionWrite(this, optsArg.session, 'insert', inserted);
+        }
+      };
       try {
         const result = await this.mongoDbCollection.bulkWrite(prepared.map((document) => {
           const { _id: storedId, ...body } = document as Record<string, unknown>;
@@ -2769,12 +2800,16 @@ export class SmartdataCollection<T> {
             },
           };
         }), { ordered: false, session: rawSessionArg, ...deadlineArg.commandOptions() });
+        reportUpserted(result.upsertedIds);
         if (result.upsertedCount + result.matchedCount !== prepared.length) {
           throw new SmartdataPersistenceError('unsupported_operation',
             'insertManyIfAbsent requires an acknowledged result for every identity.');
         }
         return { insertedCount: result.upsertedCount, matchedCount: result.matchedCount };
       } catch (errorArg) {
+        if (getMongoBulkWriteErrorIndexes(errorArg)) {
+          reportUpserted((errorArg as plugins.mongodb.MongoBulkWriteError).result?.upsertedIds);
+        }
         return normalizeOrdinaryPersistenceError(errorArg,
           `Insert conflicts with a unique index in collection "${this.collectionName}".`);
       }
@@ -2825,7 +2860,7 @@ export class SmartdataCollection<T> {
           updateableObject[key] = saveableObject[key];
         }
         try {
-          return await this.mongoDbCollection.updateOne(
+          const result = await this.mongoDbCollection.updateOne(
             identifiableObject,
             {
               $set: updateableObject,
@@ -2835,6 +2870,16 @@ export class SmartdataCollection<T> {
             },
             { upsert: true, session: rawSessionArg, ...deadlineArg.commandOptions() },
           );
+          if (result.upsertedCount > 0 || result.matchedCount > 0) {
+            reportSmartdataCollectionWrite(
+              this,
+              opts?.session,
+              result.upsertedCount > 0 ? 'insert' : 'update',
+              [saveableObject],
+              identifiableObject,
+            );
+          }
+          return result;
         } catch (errorArg) {
           return normalizeOrdinaryPersistenceError(
             errorArg,
@@ -2857,10 +2902,24 @@ export class SmartdataCollection<T> {
         await this.checkDoc(dbDocArg);
         const identifiableObject = await dbDocArg.createIdentifiableObject();
         this.assertConstrainingIdentifiableObject(identifiableObject, 'delete');
-        return this.mongoDbCollection.deleteOne(identifiableObject, {
+        // Serialized before the delete, so a failing serializer never fails an acknowledged delete.
+        const observedDocument = hasSmartdataWriteObservers(this.smartdataDb)
+          ? await dbDocArg.createSavableObject() as object
+          : undefined;
+        const result = await this.mongoDbCollection.deleteOne(identifiableObject, {
           session: rawSessionArg,
           ...deadlineArg.commandOptions(),
         });
+        if (result.deletedCount > 0) {
+          reportSmartdataCollectionWrite(
+            this,
+            opts?.session,
+            'delete',
+            observedDocument ? [observedDocument] : null,
+            identifiableObject,
+          );
+        }
+        return result;
       },
     );
   }

package/ts/nosqldb/classes.db.ts

@@ -20,6 +20,10 @@ import {
   type ISmartdataNamespaceInspectionOptions,
   type ISmartdataNamespaceInspection,
 } from './classes.namespaceinspection.js';
+import {
+  addSmartdataWriteObserver,
+  type ISmartdataWriteObserverOptions,
+} from './classes.writeobserver.js';
 
 export { SmartdataSession } from './classes.session.js';
 export type {
@@ -27,6 +31,13 @@ export type {
   TSmartdataOrdinarySession,
   TSmartdataTransactionCommitOutcome,
 } from './classes.session.js';
+export type {
+  ISmartdataWriteObserverOptions,
+  ISmartdataWriteReport,
+  TSmartdataObservedFields,
+  TSmartdataObservedValue,
+  TSmartdataWriteKind,
+} from './classes.writeobserver.js';
 
 import { logger } from './logging.js';
 import { assertDataOptions, SmartdataOperationBudget } from './classes.operationbudget.js';
@@ -524,6 +535,26 @@ export class SmartdataDb {
     return createSmartdataSession(this);
   }
 
+  /**
+   * Observes every acknowledged write that this process makes through the
+   * database's models: inserts, saves, deletes, atomic and exact writes. Each
+   * write is reported once, after the database acknowledged it; a write inside
+   * a `createSession()` transaction is reported after the commit, and not at
+   * all when the transaction rolls back or its outcome is unknown. A write
+   * that changed nothing (no match, nothing deleted) is not reported. Writes
+   * of other processes, raw driver access and migrations are not observed.
+   *
+   * Reports carry the values of the requested top-level `fields` only, from
+   * the written documents and from the selector's equality conditions. While
+   * an observer is registered, transactions on raw `startSession()` sessions
+   * are refused for model writes, since their outcome is not known here.
+   *
+   * Returns the function that stops the observer.
+   */
+  public observeWrites(optionsArg: ISmartdataWriteObserverOptions): () => void {
+    return addSmartdataWriteObserver(this, optionsArg);
+  }
+
   /**
    * Creates a narrowly scoped MongoDB administration facade bound to this
    * SmartData lifecycle. Applications never need direct driver access.

package/ts/nosqldb/classes.doc.ts

@@ -6851,7 +6851,7 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
         $set: setObject,
         ...(Object.keys(unsetObject).length > 0 ? { $unset: unsetObject } : {}),
       },
-      { session: options.session, timeoutMS: options.timeoutMS },
+      { session: options.session, timeoutMS: options.timeoutMS, observedDocument: saveableObject },
     );
     if (result.matchedCount === 0) {
       // Nothing was written, so the instance keeps the update timestamp the

package/ts/nosqldb/classes.exactpersistence.ts

@@ -9,6 +9,7 @@ import { registerCollectionReconnectHandler } from './classes.collectionlifecycl
 import type { SmartdataSession } from './classes.session.js';
 import {
   acquireSmartdataSession,
+  reportSmartdataCollectionWrite,
   settleSmartdataOperationError,
   resolveSmartdataOperationDeadline,
 } from './classes.session.js';
@@ -1549,6 +1550,14 @@ export class SmartdataExactCollection<
       }
     }
 
+    /** A reconciled body is this call's own insert only when it carries this call's `_id`. */
+    const reportReconciledInsert = (storedArg: TStoredDocument<TPersisted>): void => {
+      if (storedArg._id.equals(expectedStoredDocument._id)) {
+        reportSmartdataCollectionWrite(
+          this.collection, optionsArg.session, 'insert', [expectedStoredDocument],
+        );
+      }
+    };
     let result: plugins.mongodb.InsertOneResult;
     const insertOptions = { session: sessionArg, ...deadlineArg.commandOptions() };
     try {
@@ -1594,6 +1603,7 @@ export class SmartdataExactCollection<
       }
       if (reconciled) {
         if (bytesEqual(reconciled.bodyBytes, persistedBytes)) {
+          reportReconciledInsert(reconciled.document);
           return { status: 'already_committed', document: reconciled.document };
         }
         if (isDuplicateKeyError(errorArg)) {
@@ -1633,6 +1643,7 @@ export class SmartdataExactCollection<
         );
       }
       if (reconciled && bytesEqual(reconciled.bodyBytes, persistedBytes)) {
+        reportReconciledInsert(reconciled.document);
         return { status: 'already_committed', document: reconciled.document };
       }
       throw this.ambiguousWriteError(
@@ -1640,6 +1651,9 @@ export class SmartdataExactCollection<
         result,
       );
     }
+    reportSmartdataCollectionWrite(
+      this.collection, optionsArg.session, 'insert', [expectedStoredDocument],
+    );
     return { status: 'inserted', document: expectedStoredDocument };
     });
   }
@@ -1827,6 +1841,11 @@ export class SmartdataExactCollection<
       ? { _id: current._id, _smartdataRevision: current._smartdataRevision }
       : { _id: current._id, _smartdataRevision: { $exists: false } };
 
+    const reportTransition = (): void => {
+      reportSmartdataCollectionWrite(
+        this.collection, sessionOptionsArg.session, 'replace', [current, expectedStoredDocument], selector,
+      );
+    };
     const replaceOptions = {
       returnDocument: 'after' as const,
       includeResultMetadata: false as const,
@@ -1851,6 +1870,7 @@ export class SmartdataExactCollection<
           'Exact transition returned a postimage different from the requested state.',
         );
       }
+      reportTransition();
       return { status: 'transitioned', document: expectedStoredDocument };
     } catch (errorArg) {
       if (isTransientTransactionError(errorArg, sessionArg)) {
@@ -1875,6 +1895,7 @@ export class SmartdataExactCollection<
         }, { session: sessionArg, ...deadlineArg.commandOptions() });
         if (reconciledRaw) {
           if (this.encodesAs(reconciledRaw, expectedBytes)) {
+            reportTransition();
             return { status: 'transitioned', document: expectedStoredDocument };
           }
           // A malformed document fails the reconciliation itself.
@@ -1936,6 +1957,9 @@ export class SmartdataExactCollection<
       result.acknowledged === true &&
       result.deletedCount === 1
     ) {
+      reportSmartdataCollectionWrite(
+        this.collection, sessionOptionsArg.session, 'delete', [current], selector,
+      );
       return { status: 'deleted', deletedCount: 1 };
     }
     if (

package/ts/nosqldb/classes.persistence.ts

@@ -78,6 +78,22 @@ export const isMongoTransientTransactionError = (errorArg: unknown): boolean =>
   errorArg instanceof plugins.mongodb.MongoError
   && errorArg.hasErrorLabel(plugins.mongodb.MongoErrorLabel.TransientTransactionError);
 
+/**
+ * The failed operations of a bulk write that failed on write errors. Only then
+ * does the error's result state which operations applied: after a driver or
+ * write-concern error the outcome is unknown and this returns `undefined`.
+ */
+export const getMongoBulkWriteErrorIndexes = (
+  errorArg: unknown,
+): ReadonlySet<number> | undefined => {
+  if (!(errorArg instanceof plugins.mongodb.MongoBulkWriteError)) return undefined;
+  if (errorArg.result?.getWriteConcernError() !== undefined) return undefined;
+  const writeErrors = [errorArg.writeErrors].flat();
+  return writeErrors.length > 0
+    ? new Set(writeErrors.map((writeErrorArg) => writeErrorArg.index))
+    : undefined;
+};
+
 export const isMongoDuplicateKeyError = (
   errorArg: unknown,
 ): errorArg is plugins.mongodb.MongoServerError => {

package/ts/nosqldb/classes.session.ts

@@ -1,5 +1,6 @@
 import * as plugins from './plugins.js';
 
+import type { SmartdataCollection } from './classes.collection.js';
 import type { SmartdataDb } from './classes.db.js';
 import {
   SmartdataOperationDeadline,
@@ -15,6 +16,12 @@ import {
   normalizeDeadlineError,
   normalizeOrdinaryPersistenceError,
 } from './classes.persistence.js';
+import {
+  captureSmartdataWrite,
+  hasSmartdataWriteObservers,
+  type ISmartdataWrite,
+  type TSmartdataWriteKind,
+} from './classes.writeobserver.js';
 
 interface ISmartdataSessionBinding {
   session: SmartdataSession;
@@ -36,6 +43,8 @@ interface ISmartdataSessionBinding {
   transactionCommitReached: boolean;
   /** Set when the session ended while a transaction ran, stating how far the transaction had got. */
   transactionEnded?: TSmartdataTransactionEnd;
+  /** The write reports of the current attempt, delivered once the transaction committed. */
+  transactionWrites: Array<() => void>;
   operationSettled?: Promise<void>;
   resolveOperationSettled?: () => void;
   invalidated: boolean;
@@ -307,6 +316,7 @@ export class SmartdataSession {
       binding.transactionUsesOrdinaryWrite = false;
       binding.transactionFailure = undefined;
       binding.transactionCommitReached = false;
+      binding.transactionWrites = [];
       callbackError = undefined;
       attemptInterruption = undefined;
       try {
@@ -435,11 +445,13 @@ export class SmartdataSession {
     };
     let result: TResult | undefined;
     let transactionEnded: TSmartdataTransactionEnd | undefined;
+    let committedWrites: Array<() => void> = [];
     try {
       result = timeoutMS === undefined
         ? await binding.rawSession.withTransaction(runAttempt)
         : await binding.rawSession.withTransaction(runAttempt, { timeoutMS });
       transactionEnded = binding.transactionEnded;
+      committedWrites = binding.transactionWrites;
     } catch (errorArg) {
       const { error, outcome } = settleTransactionRejection(errorArg);
       throw rejectTransaction(error, outcome);
@@ -451,6 +463,7 @@ export class SmartdataSession {
       binding.transactionFailure = undefined;
       binding.transactionCommitReached = false;
       binding.transactionEnded = undefined;
+      binding.transactionWrites = [];
     }
     if (transactionEnded) {
       throw rejectTransaction(
@@ -458,6 +471,9 @@ export class SmartdataSession {
         commitOutcomeOfTransactionEnd(transactionEnded),
       );
     }
+    for (const deliverWrite of committedWrites) {
+      deliverWrite();
+    }
     return result;
   }
 
@@ -495,6 +511,7 @@ export const createSmartdataSession = (ownerArg: SmartdataDb): SmartdataSession
     transactionCallbackOpen: false,
     transactionUsesOrdinaryWrite: false,
     transactionCommitReached: false,
+    transactionWrites: [],
     invalidated: false,
   };
   bindings.set(session, binding);
@@ -656,6 +673,17 @@ export const leaseOrdinarySmartdataSession = (
     if (!optionsArg.prepared && sessionArg?.inTransaction()) {
       refuseUnpreparedCollection(optionsArg, 'inside a transaction');
     }
+    if (
+      optionsArg.ordinaryWrite
+      && sessionArg?.inTransaction()
+      && hasSmartdataWriteObservers(ownerArg)
+    ) {
+      // Only an owned transaction tells SmartData whether it committed.
+      throw new SmartdataPersistenceError(
+        'unsupported_operation',
+        'Writes of an observed database run in transactions of db.createSession(), not raw driver sessions.',
+      );
+    }
     return { rawSession: sessionArg, release: () => {} };
   }
   if (!optionsArg.prepared) {
@@ -753,6 +781,51 @@ export const runWithOrdinarySmartdataSession = async <TResult>(
   }
 };
 
+/**
+ * Reports one acknowledged write to the owner's write observers: at once, or,
+ * inside an owned transaction, after it committed. A transaction that rolls
+ * back, or whose commit outcome is unknown, reports nothing, and a retried
+ * attempt reports only its own writes.
+ */
+export const reportSmartdataWrite = (
+  ownerArg: SmartdataDb,
+  sessionArg: TSmartdataOrdinarySession | undefined,
+  writeArg: ISmartdataWrite,
+): void => {
+  // A raw driver transaction passed its lease while nobody observed, and
+  // whether it commits is never known here.
+  if (!isSmartdataSession(sessionArg) && sessionArg?.inTransaction()) return;
+  const deliver = captureSmartdataWrite(ownerArg, writeArg);
+  if (!deliver) return;
+  const binding = isSmartdataSession(sessionArg) ? bindings.get(sessionArg) : undefined;
+  if (binding?.transactionActive) {
+    // A write that settles after its attempt ended rolls back with that attempt.
+    const attempt = transactionContext.getStore()?.attempt;
+    if (attempt !== undefined && attempt === binding.transactionAttempt) {
+      binding.transactionWrites.push(deliver);
+    }
+    return;
+  }
+  deliver();
+};
+
+/** Reports one acknowledged write of a model collection; see `reportSmartdataWrite`. */
+export const reportSmartdataCollectionWrite = (
+  collectionArg: SmartdataCollection<any>,
+  sessionArg: TSmartdataOrdinarySession | undefined,
+  kindArg: TSmartdataWriteKind,
+  documentsArg: readonly object[] | null,
+  selectorArg?: unknown,
+): void => {
+  reportSmartdataWrite(collectionArg.smartdataDb, sessionArg, {
+    collection: collectionArg.collectionName,
+    kind: kindArg,
+    documents: documentsArg,
+    selector: selectorArg,
+    identityDocumentIdField: collectionArg.getBoundModelSchema()?.identityAsDocumentId,
+  });
+};
+
 /**
  * Ends every session of the owner. `endOptionsArg.timeoutMS` is the driver's
  * deadline for aborting a transaction a session still holds.