@lossless.org/client 1.22.2 → 1.23.1

package/ts/nosqldb/classes.writelog.ts

@@ -0,0 +1,701 @@
+import * as plugins from './plugins.js';
+
+import type { SmartdataDb } from './classes.db.js';
+import { assertDataOptions } from './classes.operationbudget.js';
+import { SmartdataPersistenceError } from './classes.persistence.js';
+import {
+  narrowSmartdataWriteReport,
+  normalizeObservedFields,
+  reportOfSmartdataWrite,
+  type ISmartdataWrite,
+  type ISmartdataWriteReport,
+} from './classes.writeobserver.js';
+import { isSmartdataWriteRevisionsActive, writeRevisionsCollectionName } from './classes.writerevisions.js';
+import { smartdataCommitJournal } from './engineidentity.js';
+import { logger } from './logging.js';
+
+/**
+ * The write log lets a process follow the model writes of every process in
+ * commit order. Every transaction that writes through the models adds one
+ * entry to `__smartdata_write_log` right before its commit: the observed
+ * fields of its writes, keyed by the transaction's commit receipt. The
+ * engine's commit journal lists each committed transaction with that receipt,
+ * so a follower reads the journal in commit order and joins every commit to
+ * its entry. A commit without an entry — a raw driver write, a migration, an
+ * entry the retention removed — still names its collections, which the
+ * follower reports as changed in ways no report describes.
+ */
+export interface ISmartdataWriteLogOptions {
+  /**
+   * Top-level field names the log records of every write: 1 to 64 distinct
+   * names, no `.` and no leading `$`. A follower follows some or all of them.
+   */
+  fields: readonly string[];
+}
+
+/** A commit's position in the engine's commit journal. */
+export interface ISmartdataCommitStamp {
+  /** The journal's timeline; a restart of a memory-backed engine starts a new one. */
+  readonly timeline: string;
+  /** The commit's position on the timeline, an exact unsigned decimal. */
+  readonly sequence: string;
+}
+
+/** One committed transaction, delivered once to every follower of its database. */
+export interface ISmartdataFollowedWrite {
+  /**
+   * `local` for a transaction of this database instance, delivered as soon as
+   * its commit was confirmed; `journal` for one read from the commit journal.
+   */
+  readonly origin: 'local' | 'journal';
+  /** The commit's journal position; `null` for a local delivery. */
+  readonly stamp: ISmartdataCommitStamp | null;
+  /** When the engine committed it; `null` for a local delivery. */
+  readonly committedAtMs: number | null;
+  /** The transaction's model writes, with the follower's fields. */
+  readonly reports: readonly ISmartdataWriteReport[];
+  /** Collections the transaction changed in ways no report describes. */
+  readonly unplaced: readonly string[];
+}
+
+/**
+ * Why a follower lost its place in the journal: the journal no longer
+ * continues the history the follower read, as after a restart of a
+ * memory-backed engine, or it no longer holds every commit since the
+ * follower's position.
+ */
+export type TSmartdataWriteGapReason = 'timeline' | 'retention';
+
+export interface ISmartdataWriteGap {
+  readonly reason: TSmartdataWriteGapReason;
+}
+
+export interface ISmartdataWriteFollowerOptions {
+  /** Fields of the database's write log the deliveries carry. */
+  fields: readonly string[];
+  /**
+   * Called synchronously once per committed transaction. A listener that
+   * throws is logged and the follower moves on.
+   */
+  onWrite: (writeArg: ISmartdataFollowedWrite) => void;
+  /**
+   * Called when commits may have been missed. The follower has already moved
+   * to the journal's head, so state rebuilt from the database now misses
+   * nothing later deliveries do not report.
+   */
+  onGap: (gapArg: ISmartdataWriteGap) => void;
+}
+
+export interface ISmartdataWriteFollower {
+  /** Stops the follower and waits until its last delivery returned. */
+  stop(): Promise<void>;
+}
+
+/** The collection that holds the entries. */
+export const writeLogCollectionName = '__smartdata_write_log';
+
+/** How long an entry is kept. The engine keeps a commit in its journal at most as long. */
+export const writeLogRetentionSeconds = 15 * 60;
+const expiryIndexName = 'smartdata_write_log_expiry';
+const activePollMs = 250;
+const idlePollMs = 1_000;
+/** A follower that saw a commit this recently polls at the active pace. */
+const activeWindowMs = 60_000;
+const pageLimit = 128;
+/** The engine's largest page; a single commit record larger than a page is refused. */
+const pageBytes = 4 * 1024 * 1024;
+const readTimeoutMs = 5_000;
+/** Beyond these bounds, an entry states its largest collections as unplaced instead. */
+const maximumEntryDocuments = 4_096;
+const maximumEntryBytes = 1024 * 1024;
+/** How long a follower remembers a local delivery whose commit the journal has not listed yet. */
+const localDeliveryMemoryMs = 2 * writeLogRetentionSeconds * 1_000;
+/**
+ * Namespaces whose changes only carry the bookkeeping of model writes, and the
+ * database's own namespace, which a catalog change publishes beside the
+ * collection it changed.
+ */
+const bookkeepingCollections: ReadonlySet<string> = new Set([
+  '',
+  writeLogCollectionName,
+  writeRevisionsCollectionName,
+]);
+const writeKinds: ReadonlySet<unknown> = new Set(['insert', 'update', 'replace', 'delete']);
+
+interface IWriteLogEntry {
+  readonly reports: readonly ISmartdataWriteReport[];
+  readonly unplaced: readonly string[];
+}
+
+interface IWriteLogDocument {
+  _id: string;
+  at: Date;
+  fields: string[];
+  reports: ISmartdataWriteReport[];
+  unplaced: string[];
+}
+
+/** @internal One transaction's entry, written in the transaction, until its outcome settled. */
+export interface ISmartdataWriteLogCommit {
+  readonly receipt: string;
+  readonly entry: IWriteLogEntry;
+  /** Releases the followers that wait for the outcome; called once the outcome is known. */
+  settle(): void;
+}
+
+interface IWriteLogState {
+  followers: Set<SmartdataWriteFollower>;
+  /** The transactions of this database instance that wrote an entry and have not settled. */
+  pending: Map<string, Promise<void>>;
+}
+
+const logFields = new WeakMap<SmartdataDb, readonly string[]>();
+const logStates = new WeakMap<SmartdataDb, IWriteLogState>();
+
+const stateOf = (dbArg: SmartdataDb): IWriteLogState => {
+  let state = logStates.get(dbArg);
+  if (!state) {
+    state = { followers: new Set(), pending: new Map() };
+    logStates.set(dbArg, state);
+  }
+  return state;
+};
+
+/** @internal Validates and records the option; called once by the database's constructor. */
+export const configureSmartdataWriteLog = (dbArg: SmartdataDb, optionsArg: unknown): void => {
+  if (optionsArg === undefined) return;
+  const { fields } = assertDataOptions(optionsArg, ['fields']);
+  logFields.set(dbArg, normalizeObservedFields(fields, 'A SmartData write log'));
+};
+
+/**
+ * @internal The write log is configured and the engine journals its commits
+ * in commit order; elsewhere the option is inert.
+ */
+export const isSmartdataWriteLogActive = (dbArg: SmartdataDb): boolean =>
+  logFields.has(dbArg)
+  && dbArg.capabilities?.transactions === 'available'
+  && smartdataCommitJournal(dbArg.engineIdentity);
+
+/**
+ * @internal Every model write runs in an owned transaction, which carries its
+ * write revisions and its write-log entry.
+ */
+export const requiresSmartdataWriteTransactions = (dbArg: SmartdataDb): boolean =>
+  isSmartdataWriteRevisionsActive(dbArg) || isSmartdataWriteLogActive(dbArg);
+
+/** @internal The report a write adds to its transaction's entry, or `undefined` without an active log. */
+export const writeLogReportOf = (
+  dbArg: SmartdataDb,
+  writeArg: ISmartdataWrite,
+): ISmartdataWriteReport | undefined => {
+  const fields = logFields.get(dbArg);
+  return fields !== undefined && isSmartdataWriteLogActive(dbArg)
+    ? reportOfSmartdataWrite(writeArg, fields)
+    : undefined;
+};
+
+const logCollection = (mongoDbArg: plugins.mongodb.Db) =>
+  mongoDbArg.collection<IWriteLogDocument>(writeLogCollectionName);
+
+/**
+ * @internal Creates the index that expires entries, before `init()` publishes
+ * the connection. Another process creating it at the same time is fine.
+ */
+export const ensureSmartdataWriteLog = async (
+  mongoDbArg: plugins.mongodb.Db,
+  optionsArg: { timeoutMS?: number; signal?: AbortSignal } = {},
+): Promise<void> => {
+  await logCollection(mongoDbArg).createIndex({ at: 1 }, {
+    name: expiryIndexName,
+    expireAfterSeconds: writeLogRetentionSeconds,
+    ...optionsArg,
+  });
+};
+
+/**
+ * The receipt the engine journals a transaction's commit with. The driver
+ * numbers a transaction when it sends the transaction's first command.
+ */
+const receiptOfSession = (rawSessionArg: plugins.mongodb.ClientSession): string => {
+  const id = rawSessionArg.id;
+  if (id === undefined) {
+    throw new SmartdataPersistenceError('unsupported_operation',
+      'A SmartData transaction has no server session to key its write-log entry by.');
+  }
+  return `${id.id.toUUID().toHexString()}:${rawSessionArg.serverSession.txnNumber}`;
+};
+
+const receiptOfJournal = (sessionArg: string, transactionArg: string): string =>
+  `${sessionArg}:${transactionArg}`;
+
+/**
+ * The entry as written: a collection whose writes cannot be placed changed as
+ * a whole, so its reports add nothing, and the largest collections become
+ * unplaced until the entry fits its bounds.
+ */
+const boundWriteLogEntry = (
+  reportsArg: readonly ISmartdataWriteReport[],
+  unplacedArg: ReadonlySet<string>,
+): IWriteLogEntry => {
+  const unplaced = new Set(unplacedArg);
+  const sizes = new Map<string, { documents: number; bytes: number }>();
+  let documents = 0;
+  let bytes = plugins.mongodb.BSON.calculateObjectSize({ unplaced: [...unplaced] });
+  for (const report of reportsArg) {
+    if (unplaced.has(report.collection)) continue;
+    const size = sizes.get(report.collection) ?? { documents: 0, bytes: 0 };
+    const reportDocuments = report.documents?.length ?? 0;
+    const reportBytes = plugins.mongodb.BSON.calculateObjectSize(report);
+    size.documents += reportDocuments;
+    size.bytes += reportBytes;
+    documents += reportDocuments;
+    bytes += reportBytes;
+    sizes.set(report.collection, size);
+  }
+  const bySize = [...sizes].sort(([, aArg], [, bArg]) => bArg.bytes - aArg.bytes);
+  for (const [collection, size] of bySize) {
+    if (documents <= maximumEntryDocuments && bytes <= maximumEntryBytes) break;
+    unplaced.add(collection);
+    documents -= size.documents;
+    bytes -= size.bytes;
+  }
+  return Object.freeze({
+    reports: Object.freeze(reportsArg.filter((reportArg) => !unplaced.has(reportArg.collection))),
+    unplaced: Object.freeze([...unplaced].sort()),
+  });
+};
+
+/**
+ * @internal Writes a transaction's entry inside that transaction, right
+ * before its commit, and registers it until its outcome settled. `undefined`
+ * when the transaction wrote nothing through the models.
+ */
+export const flushSmartdataWriteLog = async (
+  dbArg: SmartdataDb,
+  mongoDbArg: plugins.mongodb.Db,
+  rawSessionArg: plugins.mongodb.ClientSession,
+  reportsArg: readonly ISmartdataWriteReport[],
+  unplacedArg: ReadonlySet<string>,
+  signalArg: AbortSignal | undefined,
+): Promise<ISmartdataWriteLogCommit | undefined> => {
+  const fields = logFields.get(dbArg);
+  if (fields === undefined || (reportsArg.length === 0 && unplacedArg.size === 0)) return undefined;
+  const collection = logCollection(mongoDbArg);
+  const signalOptions = signalArg === undefined ? {} : { signal: signalArg };
+  if (reportsArg.length === 0) {
+    // No write of the attempt was acknowledged, so none may have numbered the transaction yet.
+    await collection.findOne({ _id: '' }, { projection: { _id: 1 }, session: rawSessionArg, ...signalOptions });
+  }
+  const receipt = receiptOfSession(rawSessionArg);
+  const entry = boundWriteLogEntry(reportsArg, unplacedArg);
+  await collection.insertOne({
+    _id: receipt,
+    at: new Date(),
+    fields: [...fields],
+    reports: [...entry.reports],
+    unplaced: [...entry.unplaced],
+  }, { session: rawSessionArg, ...signalOptions });
+  const { pending } = stateOf(dbArg);
+  const settled = Promise.withResolvers<void>();
+  pending.set(receipt, settled.promise);
+  let open = true;
+  return {
+    receipt,
+    entry,
+    settle: () => {
+      if (!open) return;
+      open = false;
+      if (pending.get(receipt) === settled.promise) pending.delete(receipt);
+      settled.resolve();
+    },
+  };
+};
+
+/**
+ * @internal Delivers a confirmed commit of this database instance to its
+ * followers at once; each then skips the commit when the journal lists it.
+ */
+export const deliverSmartdataWriteLogCommit = (
+  dbArg: SmartdataDb,
+  commitArg: ISmartdataWriteLogCommit,
+): void => {
+  const followers = logStates.get(dbArg)?.followers;
+  if (!followers) return;
+  for (const follower of [...followers]) {
+    follower.deliverLocal(commitArg);
+  }
+};
+
+interface ICommittedWrite {
+  stamp: ISmartdataCommitStamp;
+  committedAtMs: number;
+  /** The changed collections of the database, bookkeeping left out. */
+  collections: string[];
+  /** The key of a transaction's receipt; a retryable single statement has none. */
+  receipt: string | undefined;
+  /**
+   * The commit wrote an entry. Writes that changed nothing publish no
+   * namespace of their own, so their entry is all the journal shows of them.
+   */
+  logged: boolean;
+}
+
+interface ICommittedWritesPage {
+  writes: ICommittedWrite[];
+  cursor: ISmartdataCommitStamp;
+  head: ISmartdataCommitStamp;
+  gap: boolean;
+  hasMore: boolean;
+}
+
+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 unexpectedPage = (): SmartdataPersistenceError =>
+  new SmartdataPersistenceError('unsupported_operation',
+    'The engine answered getCommittedWrites with an unexpected page.');
+
+const unsignedDecimal = /^(?:0|[1-9][0-9]*)$/;
+
+const stampOf = (valueArg: unknown): ISmartdataCommitStamp => {
+  if (
+    !isPlainRecord(valueArg)
+    || typeof valueArg.timeline !== 'string'
+    || typeof valueArg.sequence !== 'string'
+    || !unsignedDecimal.test(valueArg.sequence)
+  ) {
+    throw unexpectedPage();
+  }
+  return Object.freeze({ timeline: valueArg.timeline, sequence: valueArg.sequence });
+};
+
+const committedWriteOf = (valueArg: unknown, databaseArg: string): ICommittedWrite => {
+  if (!isPlainRecord(valueArg) || !Array.isArray(valueArg.namespaces) || typeof valueArg.committedAtMs !== 'number') {
+    throw unexpectedPage();
+  }
+  const collections = new Set<string>();
+  let logged = false;
+  for (const namespace of valueArg.namespaces) {
+    if (!isPlainRecord(namespace) || typeof namespace.database !== 'string' || typeof namespace.collection !== 'string') {
+      throw unexpectedPage();
+    }
+    if (namespace.database !== databaseArg) continue;
+    if (namespace.collection === writeLogCollectionName) logged = true;
+    if (!bookkeepingCollections.has(namespace.collection)) collections.add(namespace.collection);
+  }
+  const receipt = valueArg.receipt;
+  if (receipt !== null && receipt !== undefined && (
+    !isPlainRecord(receipt) || typeof receipt.session !== 'string' || typeof receipt.transaction !== 'string'
+  )) {
+    throw unexpectedPage();
+  }
+  return {
+    stamp: stampOf(valueArg.stamp),
+    committedAtMs: valueArg.committedAtMs,
+    collections: [...collections].sort(),
+    // A retryable statement outside a transaction carries its number; only a
+    // transaction can have written an entry.
+    receipt: isPlainRecord(receipt) && (receipt.statement === null || receipt.statement === undefined)
+      ? receiptOfJournal(receipt.session as string, receipt.transaction as string)
+      : undefined,
+    logged,
+  };
+};
+
+/** One page of the database's commit journal after `afterArg`, or its head without `afterArg`. */
+const readCommittedWrites = async (
+  mongoDbArg: plugins.mongodb.Db,
+  afterArg: ISmartdataCommitStamp | undefined,
+  signalArg?: AbortSignal,
+): Promise<ICommittedWritesPage> => {
+  const page = await mongoDbArg.command({
+    getCommittedWrites: 1,
+    ...(afterArg === undefined ? {} : { after: { timeline: afterArg.timeline, sequence: afterArg.sequence } }),
+    limit: pageLimit,
+    maximumBytes: pageBytes,
+  }, { timeoutMS: readTimeoutMs, ...(signalArg === undefined ? {} : { signal: signalArg }) });
+  if (!Array.isArray(page.writes) || typeof page.gap !== 'boolean' || typeof page.hasMore !== 'boolean') {
+    throw unexpectedPage();
+  }
+  return {
+    writes: page.writes.map((writeArg: unknown) => committedWriteOf(writeArg, mongoDbArg.databaseName)),
+    cursor: stampOf(page.cursor),
+    head: stampOf(page.head),
+    gap: page.gap,
+    hasMore: page.hasMore,
+  };
+};
+
+/**
+ * The entry a stored document states for a follower of `fieldsArg`, or
+ * `undefined` when it states none: a document another version wrote or one
+ * that does not record every field followed.
+ */
+const entryOfDocument = (documentArg: unknown, fieldsArg: readonly string[]): IWriteLogEntry | undefined => {
+  if (!isPlainRecord(documentArg)) return undefined;
+  const { fields, reports, unplaced } = documentArg;
+  if (
+    !Array.isArray(fields)
+    || !fieldsArg.every((fieldArg) => fields.includes(fieldArg))
+    || !Array.isArray(unplaced)
+    || !unplaced.every((collectionArg) => typeof collectionArg === 'string')
+    || !Array.isArray(reports)
+    || !reports.every((reportArg) =>
+      isPlainRecord(reportArg)
+      && typeof reportArg.collection === 'string'
+      && writeKinds.has(reportArg.kind)
+      && isPlainRecord(reportArg.anchors)
+      && (reportArg.documents === null
+        || (Array.isArray(reportArg.documents) && reportArg.documents.every(isPlainRecord))))
+  ) {
+    return undefined;
+  }
+  return { reports: reports as ISmartdataWriteReport[], unplaced: unplaced as string[] };
+};
+
+const describeError = (errorArg: unknown): string =>
+  errorArg instanceof Error ? errorArg.message : String(errorArg);
+
+/** Resolves after `millisecondsArg`, or at once when `signalArg` aborts. */
+const pause = (millisecondsArg: number, signalArg: AbortSignal): Promise<void> =>
+  new Promise((resolveArg) => {
+    if (signalArg.aborted) return resolveArg();
+    const done = () => {
+      clearTimeout(timer);
+      signalArg.removeEventListener('abort', done);
+      resolveArg();
+    };
+    const timer = setTimeout(done, millisecondsArg);
+    signalArg.addEventListener('abort', done, { once: true });
+  });
+
+/** Resolves when `promiseArg` settles, or at once when `signalArg` aborts. */
+const settledOrAborted = (promiseArg: Promise<void>, signalArg: AbortSignal): Promise<void> =>
+  new Promise((resolveArg) => {
+    if (signalArg.aborted) return resolveArg();
+    const done = () => {
+      signalArg.removeEventListener('abort', done);
+      resolveArg();
+    };
+    signalArg.addEventListener('abort', done, { once: true });
+    void promiseArg.finally(done);
+  });
+
+class SmartdataWriteFollower {
+  /** The receipts of local deliveries, by when they were delivered, until the journal lists them. */
+  private readonly delivered = new Map<string, number>();
+  private readonly controller = new AbortController();
+  private running: Promise<void> = Promise.resolve();
+  private stopping?: Promise<void>;
+
+  constructor(
+    private readonly state: IWriteLogState,
+    private readonly fields: readonly string[],
+    private readonly onWrite: ISmartdataWriteFollowerOptions['onWrite'],
+    private readonly onGap: ISmartdataWriteFollowerOptions['onGap'],
+  ) {}
+
+  public start(mongoDbArg: plugins.mongodb.Db, cursorArg: ISmartdataCommitStamp): void {
+    this.state.followers.add(this);
+    this.running = this.follow(mongoDbArg, cursorArg);
+  }
+
+  public stop(): Promise<void> {
+    this.stopping ??= (async () => {
+      this.state.followers.delete(this);
+      this.controller.abort();
+      await this.running;
+    })();
+    return this.stopping;
+  }
+
+  public deliverLocal(commitArg: ISmartdataWriteLogCommit): void {
+    if (this.controller.signal.aborted) return;
+    this.delivered.set(commitArg.receipt, Date.now());
+    this.deliver('local', null, null, commitArg.entry.reports, commitArg.entry.unplaced);
+  }
+
+  private deliver(
+    originArg: ISmartdataFollowedWrite['origin'],
+    stampArg: ISmartdataCommitStamp | null,
+    committedAtMsArg: number | null,
+    reportsArg: readonly ISmartdataWriteReport[],
+    unplacedArg: readonly string[],
+  ): void {
+    const write: ISmartdataFollowedWrite = Object.freeze({
+      origin: originArg,
+      stamp: stampArg,
+      committedAtMs: committedAtMsArg,
+      reports: Object.freeze(reportsArg.map((reportArg) => narrowSmartdataWriteReport(reportArg, this.fields))),
+      unplaced: Object.freeze([...unplacedArg]),
+    });
+    try {
+      this.onWrite(write);
+    } catch (errorArg) {
+      logger.log('error', `A SmartData write follower threw on a commit: ${describeError(errorArg)}`);
+    }
+  }
+
+  private reportGap(reasonArg: TSmartdataWriteGapReason): void {
+    try {
+      this.onGap(Object.freeze({ reason: reasonArg }));
+    } catch (errorArg) {
+      logger.log('error', `A SmartData write follower threw on a gap: ${describeError(errorArg)}`);
+    }
+  }
+
+  /**
+   * Reads the journal from `cursorArg` on until stopped. A failed read is
+   * retried from the same position; a position the journal lost reports a gap
+   * and continues from its head.
+   */
+  private async follow(mongoDbArg: plugins.mongodb.Db, cursorArg: ISmartdataCommitStamp): Promise<void> {
+    const signal = this.controller.signal;
+    let cursor = cursorArg;
+    let lastCommitAt = Number.NEGATIVE_INFINITY;
+    let failing = false;
+    while (!signal.aborted) {
+      try {
+        let page: ICommittedWritesPage;
+        do {
+          page = await readCommittedWrites(mongoDbArg, cursor, signal);
+          if (page.gap) {
+            // A position beyond the head belongs to a history the journal no longer continues.
+            const reason: TSmartdataWriteGapReason = page.head.timeline !== cursor.timeline
+              || BigInt(cursor.sequence) > BigInt(page.head.sequence) ? 'timeline' : 'retention';
+            cursor = (await readCommittedWrites(mongoDbArg, undefined, signal)).cursor;
+            this.reportGap(reason);
+            break;
+          }
+          const committed = await this.deliverPage(mongoDbArg, page.writes, signal);
+          if (signal.aborted) return;
+          if (committed) lastCommitAt = performance.now();
+          cursor = page.cursor;
+        } while (page.hasMore && !signal.aborted);
+        if (failing) {
+          failing = false;
+          logger.log('info', `A SmartData write follower of "${mongoDbArg.databaseName}" reads the commit journal again.`);
+        }
+      } catch (errorArg) {
+        if (signal.aborted) return;
+        if (!failing) {
+          failing = true;
+          logger.log('warn', `A SmartData write follower of "${mongoDbArg.databaseName}" failed to read the commit journal and retries: ${describeError(errorArg)}`);
+        }
+      }
+      this.forgetOldDeliveries();
+      await pause(performance.now() - lastCommitAt < activeWindowMs ? activePollMs : idlePollMs, signal);
+    }
+  }
+
+  /**
+   * Delivers one page's commits in order and returns whether it held any.
+   * A commit of this database instance still settling is waited for, so the
+   * follower knows whether it was delivered locally. Every read happens before
+   * the first delivery, so a failed read delivers nothing and is retried with
+   * the page.
+   */
+  private async deliverPage(
+    mongoDbArg: plugins.mongodb.Db,
+    writesArg: readonly ICommittedWrite[],
+    signalArg: AbortSignal,
+  ): Promise<boolean> {
+    const writes = writesArg.filter((writeArg) =>
+      writeArg.collections.length > 0 || (writeArg.logged && writeArg.receipt !== undefined));
+    if (writes.length === 0) return false;
+    const receipts = writes.flatMap((writeArg) => writeArg.receipt === undefined ? [] : [writeArg.receipt]);
+    for (const receipt of receipts) {
+      const pending = this.state.pending.get(receipt);
+      if (pending) await settledOrAborted(pending, signalArg);
+    }
+    if (signalArg.aborted) return true;
+    const lookups = receipts.filter((receiptArg) => !this.delivered.has(receiptArg));
+    const documents = new Map<unknown, unknown>();
+    if (lookups.length > 0) {
+      const found = await logCollection(mongoDbArg).find(
+        { _id: { $in: lookups } },
+        { projection: { at: 0 }, timeoutMS: readTimeoutMs, signal: signalArg },
+      ).toArray();
+      for (const document of found) documents.set(document._id, document);
+    }
+    for (const write of writes) {
+      if (signalArg.aborted) return true;
+      if (write.receipt !== undefined && this.delivered.delete(write.receipt)) continue;
+      const entry = write.receipt === undefined
+        ? undefined
+        : entryOfDocument(documents.get(write.receipt), this.fields);
+      const unplaced = new Set(entry?.unplaced);
+      const covered = new Set([...unplaced, ...(entry?.reports ?? []).map((reportArg) => reportArg.collection)]);
+      for (const collection of write.collections) {
+        if (!covered.has(collection)) unplaced.add(collection);
+      }
+      this.deliver('journal', write.stamp, write.committedAtMs, entry?.reports ?? [], [...unplaced].sort());
+    }
+    return true;
+  }
+
+  private forgetOldDeliveries(): void {
+    const oldest = Date.now() - localDeliveryMemoryMs;
+    for (const [receipt, deliveredAt] of this.delivered) {
+      if (deliveredAt < oldest) this.delivered.delete(receipt);
+    }
+  }
+}
+
+/**
+ * @internal Starts a follower at the journal's head; `db.followWrites()`
+ * documents it.
+ */
+export const followSmartdataWrites = async (
+  dbArg: SmartdataDb,
+  optionsArg: unknown,
+): Promise<ISmartdataWriteFollower> => {
+  const { fields, onWrite, onGap } = assertDataOptions(optionsArg, ['fields', 'onWrite', 'onGap']);
+  const followed = normalizeObservedFields(fields, 'A SmartData write follower');
+  if (typeof onWrite !== 'function' || typeof onGap !== 'function') {
+    throw new SmartdataPersistenceError('invalid_argument',
+      'A SmartData write follower requires onWrite and onGap functions.');
+  }
+  const logged = logFields.get(dbArg);
+  if (logged === undefined) {
+    throw new SmartdataPersistenceError('unsupported_operation',
+      'Following writes requires the writeLog option of the SmartdataDb.');
+  }
+  if (!followed.every((fieldArg) => logged.includes(fieldArg))) {
+    throw new SmartdataPersistenceError('invalid_argument',
+      'A SmartData write follower follows fields of the write log only.');
+  }
+  const mongoDb = dbArg.mongoDb;
+  if (dbArg.status !== 'connected' || !mongoDb) {
+    throw new SmartdataPersistenceError('unsupported_operation',
+      'Following writes requires a connected SmartdataDb.');
+  }
+  if (!isSmartdataWriteLogActive(dbArg)) {
+    throw new SmartdataPersistenceError('unsupported_operation',
+      'Following writes requires NoSQLDB 10.9.0 or newer, whose commit journal orders the commits.');
+  }
+  const tail = await readCommittedWrites(mongoDb, undefined);
+  if (dbArg.status !== 'connected' || dbArg.mongoDb !== mongoDb) {
+    throw new SmartdataPersistenceError('unsupported_operation',
+      'The SmartdataDb closed while the write follower started.');
+  }
+  const follower = new SmartdataWriteFollower(
+    stateOf(dbArg),
+    followed,
+    onWrite as ISmartdataWriteFollowerOptions['onWrite'],
+    onGap as ISmartdataWriteFollowerOptions['onGap'],
+  );
+  follower.start(mongoDb, tail.cursor);
+  return Object.freeze({ stop: () => follower.stop() });
+};
+
+/** @internal Stops every follower of the database; `close()` calls it. */
+export const stopSmartdataWriteFollowers = async (dbArg: SmartdataDb): Promise<void> => {
+  const followers = logStates.get(dbArg)?.followers;
+  if (!followers) return;
+  await Promise.all([...followers].map((followerArg) => followerArg.stop()));
+};