@lossless.org/client 1.22.1 → 1.23.0

package/readme.md

@@ -119,13 +119,14 @@ Family imports preserve the established SmartData and SmartBucket names and cons
 | Grouped totals over nested paths | `getGroupedTotals()` / `getGroupedTotalsPage()` group by and sum nested paths declared through `atomicPaths` or `arrayPaths`, and `unwind: path` groups by each element of one declared array |
 | Grouped totals over array elements | with `unwind: 'lines'`, `groupBy` and `sums` name declared fields of the unwound element — `groupBy: ['lines.accountNumber', 'lines.side']`, `sums: ['lines.amountCents']` — so per-account debit and credit totals need no raw aggregation; undeclared element fields and an `unwind` that holds no `groupBy` or `sums` path stay refused with `invalid_argument` |
 | Grouped totals element filter | `elementFilter: { 'lines.accountNumber': '1200' }` beside `unwind: 'lines'` counts and sums only the matching elements — one account's balance per side — with the atomic-filter operators on the unwound array and its declared element paths; any other path or operator is refused with `invalid_argument` |
-| Grouped totals paging | rows come ordered by group key; `getGroupedTotalsPage()` returns `nextCursor` while `hasMore`, `cursor` continues after it, and `iterateGroupedTotals()` reads every group page by page — exact across pages for null, number, string and boolean group values (proven on NoSQLDB 8.0.2, 10.7.2 and MongoDB; ObjectId and date values are ordered by BSON type order but not yet covered by the paging tests), refused with `unsupported_operation` for other values, and a cursor from another query is refused with `invalid_argument` |
+| Grouped totals paging | rows come ordered by group key; `getGroupedTotalsPage()` returns `nextCursor` while `hasMore`, `cursor` continues after it, and `iterateGroupedTotals()` reads every group page by page — exact across pages for null, number, string and boolean group values (proven on NoSQLDB 8.0.2, 10.9.0 and MongoDB; ObjectId and date values are ordered by BSON type order but not yet covered by the paging tests), refused with `unsupported_operation` for other values, and a cursor from another query is refused with `invalid_argument` |
 | Query-plan inspection | `Model.inspectQueryPlan(db, { filter, sort?, projection?, limit?, timeoutMS?, signal? })` — the winning plan's stages (`stage`, `depth`, `indexName`, `direction`) and `nReturned`/`totalKeysExamined`/`totalDocsExamined`, read-only and bounded, so a consumer proves a model query uses its intended index without raw driver access |
 | Per-instance model binding | `bindDocToManager(manager, Model)` returns a subclass of a model declared with `@managed()` and no manager argument, named like the model and bound to that manager, so several databases use the same models at once; any other binding is refused with `invalid_configuration` |
 | Subclasses need their own binding | a subclass of a bound model that declares decorators or a persistence policy of its own and no `@Collection()`, `@managed()` or `defineCollectionModel()` binding is refused with `invalid_configuration` on every read and write, so it never writes through the parent's schema; an undecorated subclass keeps the inherited binding |
 | Observing this process's writes | `db.observeWrites({ fields, listener })` — one frozen report per acknowledged model write, `{ collection, kind, documents, anchors }` with the requested top-level fields of the written documents and of the selector's equality anchors; writes inside a `db.createSession()` transaction are reported after the commit, never after a rollback; works on NoSQLDB, where `watch()` is unsupported |
 | Following this process's reads | `db.trackReads(fn)` resolves `{ result, reads }`; `reads.changed` turns true once a write this process makes through the database's models could have changed what a model read of `fn` returned, judged by the read's query and the ids it returned, and a write it cannot place counts as one that did, so a cache keyed by `reads` rebuilds only what a write touched; works on NoSQLDB |
-| Following every process's writes | with `new SmartdataDb({ ..., writeRevisions: { partitionField: 'organizationId' } })` in every writer, the awaited `reads.isCurrent()` is true while no model write of any process could have changed the reads, counted per collection and partition value in the write's transaction, so one organization's writes keep another's sets current; `db.invalidateTrackedReads()` states raw writes and migrations; needs an engine identified as NoSQLDB, elsewhere `isCurrent()` is always false |
+| Following every process's writes | with `new SmartdataDb({ ..., writeRevisions: { partitionField: 'organizationId' } })` in every writer, the awaited `reads.isCurrent()` counts changes per collection and partition in the write's transaction; confirmed writes of this database that leave `reads.changed` false receive exact revision allowances, while other writers and unknown outcomes stay conservative; a revision snapshot overlapping a local commit that touches its keys is unknowable; `db.invalidateTrackedReads()` states raw writes and migrations; each write inserts its own counter entry, so concurrent writers of one partition do not conflict on it, and every process of a database upgrades together; needs an engine identified as NoSQLDB, elsewhere `isCurrent()` is always false |
+| Following committed writes in commit order | with `new SmartdataDb({ ..., writeLog: { fields: ['id', 'organizationId'] } })` in every writer, `db.followWrites({ fields, onWrite, onGap })` delivers each committed transaction once with its write reports: this instance's own commits at once (`origin: 'local'`), every other commit from the engine's commit journal in commit order (`origin: 'journal'`, with its `stamp`), within 250 ms while active and a second when idle; rollbacks and aborted retry attempts deliver nothing, raw writes name their collections in `unplaced`, and a follower that falls out of the journal's 15-minute retention or meets a restarted memory engine calls `onGap` and continues from the head; needs NoSQLDB 10.9.0, elsewhere the option is inert and following is refused with `unsupported_operation` |
 | Disposable test databases on a unix socket | `SmartdataTestDatabase.create({ connection: { socketPath } })` from `@lossless.org/client/testsupport` reaches an engine that listens only on a unix-domain socket, fault helpers included; the loopback `host`/`port` form is unchanged |
 
 `docs/source/smartdata/readme.md` documents each one with its refusals.
@@ -147,24 +148,24 @@ A bucket lookup sends one HeadBucket for the named bucket, never ListBuckets, so
 
 ### Document APIs that need a MongoDB backend
 
-The document model runs on both NoSQLDB and MongoDB, but several APIs do not mean the same thing on both. The NoSQLDB engine is qualified at 8.0.2 and 10.7.2 (see [Verification](#verification)); the two releases part on the grouped-totals and guarded-`$expr` rows below — 10.7.2 groups composite keys exactly and evaluates the guard, 8.0.2 does neither — on whether a migration can create a partial index or a collection validator at all, on when a transaction learns of a write conflict, and on whether `$elemMatch` applies query operators to scalar array elements.
+The document model runs on both NoSQLDB and MongoDB, but several APIs do not mean the same thing on both. The NoSQLDB engine is qualified at 8.0.2 and 10.9.0 (see [Verification](#verification)); the two releases part on the grouped-totals and guarded-`$expr` rows below — 10.9.0 groups composite keys exactly and evaluates the guard, 8.0.2 does neither — on whether a migration can create a partial index or a collection validator at all, on when a transaction learns of a write conflict, and on whether `$elemMatch` applies query operators to scalar array elements.
 
 `init()` asks the connected engine what it is with one `buildInfo` command and records the answer on the database as `engineIdentity` (`{ product, version }`). NoSQLDB answers with its own `nosqldb` identity document from 10.3.0 onward; a MongoDB server answers `buildInfo` without one; an engine that refuses the command — NoSQLDB 8.0.2 answers `CommandNotFound` — stays `{ product: 'unknown', version: null }`. The identity is what states `capabilities` on a plain `SmartdataDb`, and an unidentified engine states none at all, so every capability-gated call refuses. `NoSqlConnection` keeps stating the capabilities of its declared backend from construction on.
 
 | Document API | On the NoSQLDB engine | On MongoDB |
 | --- | --- | --- |
-| `getGroupedTotals()` / `getGroupedTotalsPage()` / `iterateGroupedTotals()` with one `groupBy` field | exact, including `sums`, declared nested paths, `unwind` of a declared array and declared fields of its element, `elementFilter`, group key order and `cursor` paging, on 8.0.2 and 10.7.2 alike | exact |
+| `getGroupedTotals()` / `getGroupedTotalsPage()` / `iterateGroupedTotals()` with one `groupBy` field | exact, including `sums`, declared nested paths, `unwind` of a declared array and declared fields of its element, `elementFilter`, group key order and `cursor` paging, on 8.0.2 and 10.9.0 alike | exact |
 | the same with **two** `groupBy` fields | exact, `sums`, nested paths, `unwind`, two element fields of one unwound array (`lines.accountNumber` with `lines.side`), `elementFilter` and `cursor` paging included, on an engine that identifies itself as NoSQLDB 10.5.0 or newer: that release evaluates the composite group key per document. Below it the call is refused with `unsupported_operation` naming both fields and the single-field form, because the engine leaves the composite group key unresolved and answers with a single row whose group values are the literal field paths (`'$owner'`) and whose count is the whole filtered collection; the refusal is the guard against that wrong number, not a fix for it | exact; the client wraps each key member in `$ifNull`, because MongoDB leaves a missing member out of the key and would otherwise report it as a second null group |
 | guarded `$expr` atomic filters (`$add`, `$lte`, `$ifNull`) | exact on 10.6.0 and newer: the engine evaluates the client's fail-closed compilation (`$cond`, `$let`, `$isNumber`, `$type`), so the guard admits within the limit, refuses beyond it and never matches a stored value that is not a finite number. 8.0.2 rejects the compilation with `invalid argument: $cond` and leaves the document untouched | exact |
 | `watch()` change streams | unsupported. `NoSqlConnection` refuses with `unsupported_capability`, and so does a plain `SmartdataDb` whose engine identified itself; against an engine that answers no identity the refusal instead arrives from the engine as `CommandNotFound` once the change stream is read. `db.observeWrites()` reports the process's own model writes on both backends | supported on replica sets |
-| model-declared partial indexes (`partialFilterExpression`) | not expressible: the index-option type rejects it and the runtime refuses it with `invalid_configuration`. A client decision, not an engine limit on every release — 10.6.0 and newer create partial indexes, 8.0.2 refuses the option with `InvalidOptions` (72) — because one model declaration has to hold on every qualified backend. A migration may create one on 10.7.2; `toleratedIndexNames` accepts it and inspection reports its filter | not expressible, but a migration may own one; inspection reports its filter |
+| model-declared partial indexes (`partialFilterExpression`) | not expressible: the index-option type rejects it and the runtime refuses it with `invalid_configuration`. A client decision, not an engine limit on every release — 10.6.0 and newer create partial indexes, 8.0.2 refuses the option with `InvalidOptions` (72) — because one model declaration has to hold on every qualified backend. A migration may create one on 10.9.0; `toleratedIndexNames` accepts it and inspection reports its filter | not expressible, but a migration may own one; inspection reports its filter |
 | collection validators (`validator`, `validationLevel`, `validationAction`) | no client API; a migration owns a validator through the driver. 10.7.0 and newer create the collection, list the options exactly as given and enforce them on every model write: a violating `insert()` or `atomicUpdate()` rejects with the engine's `DocumentValidationFailure` (121) and its `errInfo`, which the client passes through unchanged rather than mapping to a `SmartdataPersistenceError` code, and stores nothing. Models initialize on a validated collection like on any other. 8.0.2 refuses the option with `InvalidOptions` (72) and creates no collection, so a validator is never silently dropped | enforced; not exercised by the client's MongoDB suite |
-| write conflicts between transactions, and writes outside a transaction to a document a transaction holds | 10.7.2 (since 10.6.1) detects a conflict at the statement, as MongoDB does: the first writer wins, and the later transaction's statement rejects with the engine's `WriteConflict` (112) labelled `TransientTransactionError`, which the client passes through so `session.withTransaction()` re-runs that callback. A write outside a transaction waits until the transaction holding its document ends, then applies on top; the wait is bounded by the write's own `timeoutMS` and by the engine's fixed 60-second transaction lifetime, after which a waiting writer aborts the holder. Awaiting such a write inside the holding transaction's callback therefore stalls that transaction until one of the two expires. 8.0.2 detects the conflict at commit: the first transaction to commit wins, a write outside a transaction applies at once, and the transaction that wrote first re-runs. Both writes land on either engine; a callback must be safe to re-run and must not swallow the statement error | first writer wins at the statement and outside writes wait, MongoDB's documented rule; not exercised by the client's MongoDB suite |
+| write conflicts between transactions, and writes outside a transaction to a document a transaction holds | 10.9.0 (since 10.6.1) detects a conflict at the statement, as MongoDB does: the first writer wins, and the later transaction's statement rejects with the engine's `WriteConflict` (112) labelled `TransientTransactionError`, which the client passes through so `session.withTransaction()` re-runs that callback. A write outside a transaction waits until the transaction holding its document ends, then applies on top; the wait is bounded by the write's own `timeoutMS` and by the engine's fixed 60-second transaction lifetime, after which a waiting writer aborts the holder. Awaiting such a write inside the holding transaction's callback therefore stalls that transaction until one of the two expires. 8.0.2 detects the conflict at commit: the first transaction to commit wins, a write outside a transaction applies at once, and the transaction that wrote first re-runs. Both writes land on either engine; a callback must be safe to re-run and must not swallow the statement error | first writer wins at the statement and outside writes wait, MongoDB's documented rule; not exercised by the client's MongoDB suite |
 | value-form `$elemMatch` in read filters (`{ scores: { $elemMatch: { $gte: 80, $lt: 90 } } }`, `{ labels: { $not: { $elemMatch: { $nin: runnerLabels } } } }`) | exact on 10.7.1 and newer: the operators apply to each array element as a whole, so the range matches only a document with one score inside it and the claim selects a job only when every one of its labels is a runner label. 8.0.2 parses every operand as a query over embedded documents and refuses the value form with `TypeMismatch` (14). A non-document operand is refused on both, with MongoDB's `BadValue` (2) on 10.7.1 and newer and 14 on 8.0.2. The client passes the operand through unchanged; the filter type admits the value form over scalar elements and the document form over embedded documents. Atomic filters (`atomicUpdate()` and the other atomic writes) accept no `$elemMatch` on any backend: the client refuses it with `invalid_argument` before any backend is contacted | exact |
-| `Model.inspectQueryPlan()` | explains on 10.7.2: the summary names the winning plan's stages and its execution totals. 8.0.2 answers `explain` with `CommandNotFound` (59), and the call rejects with `unsupported_operation` ("The connected engine does not explain queries.") rather than returning a plan it cannot know. Stage shapes are the engine's own: on 10.7.2 a limited sort on an unindexed field is `LIMIT` over `SORT` over `COLLSCAN`, an equality on a unique single-field index is `FETCH` over `IXSCAN`, and an `$or` whose branches each have an index is a `COLLSCAN` | explains: the same limited sort is `SORT` over `COLLSCAN`, the limit folded into the sort; the equality is `EXPRESS_IXSCAN` on the unique index; the `$or` is `SUBPLAN` over `FETCH` over `OR` over one `IXSCAN` per branch |
+| `Model.inspectQueryPlan()` | explains on 10.9.0: the summary names the winning plan's stages and its execution totals. 8.0.2 answers `explain` with `CommandNotFound` (59), and the call rejects with `unsupported_operation` ("The connected engine does not explain queries.") rather than returning a plan it cannot know. Stage shapes are the engine's own: on 10.9.0 a limited sort on an unindexed field is `LIMIT` over `SORT` over `COLLSCAN`, an equality on a unique single-field index is `FETCH` over `IXSCAN`, and an `$or` whose branches each have an index is a `COLLSCAN` | explains: the same limited sort is `SORT` over `COLLSCAN`, the limit folded into the sort; the equality is `EXPRESS_IXSCAN` on the unique index; the `$or` is `SUBPLAN` over `FETCH` over `OR` over one `IXSCAN` per branch |
 | aggregation-pipeline (array) updates | refused by the client with `invalid_argument` before any backend is contacted. A client-owned refusal, not an engine limit: both qualified engines apply a pipeline update themselves | same client refusal |
 
-`test/nosqldb/smartdb/test.engine-capability-boundary.node.ts` asserts the identity, grouped-totals, guarded-`$expr`, partial-index, collection-validator, write-conflict, `$elemMatch` and pipeline-update rows against both qualified engines, so a boundary that moves shows up as a failing suite rather than as a changed number in a consumer. The two halves of the grouped-totals, guarded-`$expr`, write-conflict and `$elemMatch` rows are separate tests, each bound to the engine that answers it, and the engine's own composite-key answer stays under assertion through the raw `aggregateGroupedTotals()` boundary — one literal row on 8.0.2, the two exact pairs on 10.7.2. The same boundary pins the rest of the engine's `$group` stage: a non-document accumulator is refused with `TypeMismatch` (14) on 10.7.2 while 8.0.2 answers it, and a `$cond` inside a composite key is evaluated per document on 10.7.2 while 8.0.2 answers its single literal row. It also pins whether a migration can create a partial index — 10.7.2 creates it and lists the filter, 8.0.2 refuses with 72 — and a collection validator — 10.7.2 creates and enforces it against model inserts and updates, 8.0.2 refuses with 72 — which writer a conflict sends back: on 10.7.2 the later transaction fails at its statement and re-runs while a write outside a transaction waits for the holder's commit, on 8.0.2 the later transaction commits first and the holder re-runs — and what `$elemMatch` answers through `getInstances()`: 10.7.2 matches the documented range and the `$not`/`$elemMatch`/`$nin` claim exactly as the MongoDB filter suite asserts them, 8.0.2 refuses both with 14, and a non-document operand is refused with 2 on 10.7.2 and 14 on 8.0.2. The `watch()` row is the contract refusal `ts/nosqldb/classes.collection.ts` states; the engine suite opens no change stream.
+`test/nosqldb/smartdb/test.engine-capability-boundary.node.ts` asserts the identity, grouped-totals, guarded-`$expr`, partial-index, collection-validator, write-conflict, `$elemMatch` and pipeline-update rows against both qualified engines, so a boundary that moves shows up as a failing suite rather than as a changed number in a consumer. The two halves of the grouped-totals, guarded-`$expr`, write-conflict and `$elemMatch` rows are separate tests, each bound to the engine that answers it, and the engine's own composite-key answer stays under assertion through the raw `aggregateGroupedTotals()` boundary — one literal row on 8.0.2, the two exact pairs on 10.9.0. The same boundary pins the rest of the engine's `$group` stage: a non-document accumulator is refused with `TypeMismatch` (14) on 10.9.0 while 8.0.2 answers it, and a `$cond` inside a composite key is evaluated per document on 10.9.0 while 8.0.2 answers its single literal row. It also pins whether a migration can create a partial index — 10.9.0 creates it and lists the filter, 8.0.2 refuses with 72 — and a collection validator — 10.9.0 creates and enforces it against model inserts and updates, 8.0.2 refuses with 72 — which writer a conflict sends back: on 10.9.0 the later transaction fails at its statement and re-runs while a write outside a transaction waits for the holder's commit, on 8.0.2 the later transaction commits first and the holder re-runs — and what `$elemMatch` answers through `getInstances()`: 10.9.0 matches the documented range and the `$not`/`$elemMatch`/`$nin` claim exactly as the MongoDB filter suite asserts them, 8.0.2 refuses both with 14, and a non-document operand is refused with 2 on 10.9.0 and 14 on 8.0.2. The `watch()` row is the contract refusal `ts/nosqldb/classes.collection.ts` states; the engine suite opens no change stream.
 
 ## Relational SQL
 
@@ -244,14 +245,14 @@ Qualified engines:
 
 | Component | Qualified versions |
 | --- | --- |
-| NoSQLDB engine | **8.0.2 and 10.7.2** — the same `test/nosqldb/smartdb/` suite runs against both, through the single engine seam in `test/nosqldb/helpers/smartdb.ts`; `NOSQLDB_ENGINE=qualified` selects 10.7.2 |
+| NoSQLDB engine | **8.0.2 and 10.9.0** — the same `test/nosqldb/smartdb/` suite runs against both, through the single engine seam in `test/nosqldb/helpers/smartdb.ts`; `NOSQLDB_ENGINE=qualified` selects 10.9.0 |
 | MongoDB | 8.0.26 replica sets |
 | ObjectStorage | 10.3.1 |
 | SQLDB | 0.2.3 |
 | MariaDB | 11.8 |
 | ClickHouse | 25.8 |
 
-Both engine versions run the whole document suite. They part on asserted boundaries — 10.7.2 groups composite keys exactly and answers two-field grouped totals, evaluates guarded `$expr` filters, creates migration-owned partial indexes and collection validators, reports a transaction write conflict at the statement and matches value-form `$elemMatch`, 8.0.2 does none of these, reports the conflict at commit, and the client refuses the two-field form there — which [Document APIs that need a MongoDB backend](#document-apis-that-need-a-mongodb-backend) states row by row. Text search, the Lucene adapter and the broad read-filter surface are exercised against MongoDB only. `pnpm run test:minio` uses a digest-pinned MinIO image: `sha256:14cea493d9a34af32f524e538b8346cf79f3321eff8e708c1e2960462bd8936e`. That MinIO version enforces the tested conditional uploads but does not enforce conditional deletion; its exact-purge capability is correctly unavailable. ObjectStorage passes both live probes. AWS S3 has not been qualified against a live account in this migration; no universal S3 exact-operation guarantee is inferred from the SDK.
+Both engine versions run the whole document suite. They part on asserted boundaries — 10.9.0 groups composite keys exactly and answers two-field grouped totals, evaluates guarded `$expr` filters, creates migration-owned partial indexes and collection validators, reports a transaction write conflict at the statement and matches value-form `$elemMatch`, 8.0.2 does none of these, reports the conflict at commit, and the client refuses the two-field form there — which [Document APIs that need a MongoDB backend](#document-apis-that-need-a-mongodb-backend) states row by row. Text search, the Lucene adapter and the broad read-filter surface are exercised against MongoDB only. `pnpm run test:minio` uses a digest-pinned MinIO image: `sha256:14cea493d9a34af32f524e538b8346cf79f3321eff8e708c1e2960462bd8936e`. That MinIO version enforces the tested conditional uploads but does not enforce conditional deletion; its exact-purge capability is correctly unavailable. ObjectStorage passes both live probes. AWS S3 has not been qualified against a live account in this migration; no universal S3 exact-operation guarantee is inferred from the SDK.
 
 ## License and Legal Information
 

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@lossless.org/client',
-  version: '1.22.1',
+  version: '1.23.0',
   description: 'One typed client for NoSQLDB, MongoDB, SQLDB, MariaDB, ClickHouse and S3 object storage.'
 }

package/ts/nosqldb/classes.bootstraprecord.ts

@@ -10,7 +10,7 @@ import {
   reportSmartdataWrite, reportSmartdataWriteFailure, runWithOrdinarySmartdataSession,
 } from './classes.session.js';
 import { runSmartdataWrite } from './classes.readtracker.js';
-import { isSmartdataWriteRevisionsActive } from './classes.writerevisions.js';
+import { requiresSmartdataWriteTransactions } from './classes.writelog.js';
 import {
   collectionModelSchemaResolverSymbol, collectionTopologyDbInspectionSymbol,
   getExpectedCollectionTopologyForSchema, inspectCollectionTopologySnapshot,
@@ -92,8 +92,8 @@ export const insertBootstrapRecord = async (
         if (topology.status !== 'absent' && topology.status !== 'exact') return 'invalid_configuration';
         const insertOptions = budget.operationOptions();
         dispatched = true;
-        if (isSmartdataWriteRevisionsActive(dbArg)) {
-          // The insert runs in a transaction of its own that commits its write revisions with it.
+        if (requiresSmartdataWriteTransactions(dbArg)) {
+          // The insert runs in a transaction of its own that commits its write revisions and write-log entry with it.
           try {
             const inserted = await runWithOrdinarySmartdataSession(undefined, dbArg, {
               ordinaryWrite: true, prepared: true, ...insertOptions,

package/ts/nosqldb/classes.connection.ts

@@ -1,4 +1,5 @@
 import { SmartdataDb } from './classes.db.js';
+import type { ISmartdataWriteLogOptions } from './classes.writelog.js';
 import type { ISmartdataWriteRevisionsOptions } from './classes.writerevisions.js';
 import {
   composeSmartdataCapabilities,
@@ -17,6 +18,8 @@ export interface INoSqlConnectionOptions {
   connectionLimit?: number;
   /** See `ISmartdataDbOptions.writeRevisions`. */
   writeRevisions?: ISmartdataWriteRevisionsOptions;
+  /** See `ISmartdataDbOptions.writeLog`. */
+  writeLog?: ISmartdataWriteLogOptions;
 }
 
 export class NoSqlConnection extends SmartdataDb {
@@ -28,7 +31,8 @@ export class NoSqlConnection extends SmartdataDb {
     super({ mongoDbUrl: options.url, mongoDbName: options.database,
       mongoDbUser: options.username, mongoDbPass: options.password,
       ...(options.connectionLimit === undefined ? {} : { maxPoolSize: options.connectionLimit }),
-      ...(options.writeRevisions === undefined ? {} : { writeRevisions: options.writeRevisions }) });
+      ...(options.writeRevisions === undefined ? {} : { writeRevisions: options.writeRevisions }),
+      ...(options.writeLog === undefined ? {} : { writeLog: options.writeLog }) });
     this.backend = options.backend;
     this.declaredCapabilities = composeSmartdataCapabilities(this.backend,
       smartdataCompositeGrouping(this.engineIdentity));

package/ts/nosqldb/classes.db.ts

@@ -34,8 +34,19 @@ import {
   configureSmartdataWriteRevisions,
   ensureSmartdataWriteRevisions,
   isSmartdataWriteRevisionsActive,
+  stopSmartdataWriteRevisionCompactions,
   type ISmartdataWriteRevisionsOptions,
 } from './classes.writerevisions.js';
+import {
+  configureSmartdataWriteLog,
+  ensureSmartdataWriteLog,
+  followSmartdataWrites,
+  isSmartdataWriteLogActive,
+  stopSmartdataWriteFollowers,
+  type ISmartdataWriteFollower,
+  type ISmartdataWriteFollowerOptions,
+  type ISmartdataWriteLogOptions,
+} from './classes.writelog.js';
 import {
   requireOperationSignal,
   requireOperationTimeoutMS,
@@ -50,6 +61,15 @@ export type {
   TSmartdataTransactionCommitOutcome,
 } from './classes.session.js';
 export type { ISmartdataWriteRevisionsOptions } from './classes.writerevisions.js';
+export type {
+  ISmartdataCommitStamp,
+  ISmartdataFollowedWrite,
+  ISmartdataWriteFollower,
+  ISmartdataWriteFollowerOptions,
+  ISmartdataWriteGap,
+  ISmartdataWriteLogOptions,
+  TSmartdataWriteGapReason,
+} from './classes.writelog.js';
 export type {
   ISmartdataWriteObserverOptions,
   ISmartdataWriteReport,
@@ -110,6 +130,13 @@ export interface ISmartdataDbOptions {
    * once, by the constructor.
    */
   writeRevisions?: ISmartdataWriteRevisionsOptions;
+  /**
+   * Keeps a write log, so `followWrites()` delivers the model writes of every
+   * process in commit order. Every process that writes the database must
+   * enable it with the fields its followers follow. Needs NoSQLDB 10.9.0 or
+   * newer; elsewhere it is inert. Read once, by the constructor.
+   */
+  writeLog?: ISmartdataWriteLogOptions;
 }
 
 export interface ISmartdataInvalidateTrackedReadsOptions {
@@ -246,6 +273,7 @@ export class SmartdataDb {
 
   constructor(smartdataOptions: ISmartdataDbOptions) {
     configureSmartdataWriteRevisions(this, smartdataOptions.writeRevisions);
+    configureSmartdataWriteLog(this, smartdataOptions.writeLog);
     this.smartdataOptions = smartdataOptions;
     this.status = 'initial';
     void this.statusConnectedDeferred.promise.catch(() => {});
@@ -342,6 +370,10 @@ export class SmartdataDb {
           await ensureSmartdataWriteRevisions(candidateDb, budget?.operationOptions());
           budget?.check();
         }
+        if (isSmartdataWriteLogActive(this)) {
+          await ensureSmartdataWriteLog(candidateDb, budget?.operationOptions());
+          budget?.check();
+        }
         this.mongoDbClient = candidateClient;
         this.mongoDb = candidateDb;
         candidateClient = undefined;
@@ -399,6 +431,17 @@ export class SmartdataDb {
     const mongoDbClient = this.pendingClient ?? this.mongoDbClient;
     try {
       const closeErrors: unknown[] = [];
+      try {
+        // Followers and compactions abort at once; their reads end with the client otherwise.
+        const backgroundStop = Promise.all([
+          stopSmartdataWriteFollowers(this),
+          stopSmartdataWriteRevisionCompactions(this),
+        ]);
+        if (budget) await budget.waitFor(backgroundStop);
+        await backgroundStop;
+      } catch (errorArg) {
+        closeErrors.push(errorArg);
+      }
       try {
         const invalidation = invalidateSmartdataSessions(this, budget?.cleanupOptions());
         // A session whose cleanup outlives the deadline stays owned and invalidated
@@ -582,6 +625,31 @@ export class SmartdataDb {
     return addSmartdataWriteObserver(this, optionsArg);
   }
 
+  /**
+   * Follows the model writes of every process that writes this database with
+   * the `writeLog` option, from now on, in commit order: `onWrite` receives
+   * each committed transaction once, with the reports of its writes. A
+   * transaction of this instance is delivered as soon as its commit returned
+   * (`origin: 'local'`); every other one once the follower reads it from the
+   * engine's commit journal (`origin: 'journal'`, with its `stamp`), within
+   * 250 ms of a commit while the database is active and within a second when
+   * idle. A transaction of this instance whose commit outcome was unknown here
+   * is delivered from the journal if it committed. A commit the log cannot
+   * describe — a raw driver write, a migration, a writer without the option —
+   * names its collections in `unplaced`.
+   *
+   * The journal keeps a commit for 15 minutes, and at most its newest 65,536
+   * commits. A follower that falls further
+   * behind, or whose engine restarted on a new timeline, calls `onGap` and
+   * continues from the journal's head; state derived from earlier deliveries
+   * must then be rebuilt from the database. A failed journal read is logged
+   * and retried. Needs a connected database on NoSQLDB 10.9.0 or newer; MongoDB
+   * has no commit journal and is refused. `close()` stops every follower.
+   */
+  public async followWrites(optionsArg: ISmartdataWriteFollowerOptions): Promise<ISmartdataWriteFollower> {
+    return followSmartdataWrites(this, optionsArg);
+  }
+
   /**
    * Runs `fnArg` and records every model read it makes on this database:
    * `findOne`, `findAll`, `getCursor`, counts, pages and the exact reads.

package/ts/nosqldb/classes.doc.ts

@@ -30,7 +30,7 @@ import { SmartdataDbWatcher } from './classes.watcher.js';
 import { SmartdataLuceneAdapter } from './classes.lucene.adapter.js';
 import { executeAtomicDelete, executeAtomicDeleteMany } from './classes.atomicdelete.js';
 import { requireOperationSignal } from './classes.operationdeadline.js';
-import { isSmartdataWriteRevisionsActive } from './classes.writerevisions.js';
+import { requiresSmartdataWriteTransactions } from './classes.writelog.js';
 import {
   executeAtomicFindOneAndReplace, executeAtomicFindOneAndUpdate,
 } from './classes.atomicfindoneandupdate.js';
@@ -4677,9 +4677,9 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
     }
     const collection: SmartdataCollection<T> = (this as any).collection;
     const inTransaction = isOrdinarySessionInTransaction(opts?.session);
-    // Outside a transaction, a database with write revisions runs the batch
-    // in one of its own, so a failed batch inserted nothing.
-    const insertsWhole = !inTransaction && isSmartdataWriteRevisionsActive(collection.smartdataDb);
+    // Outside a transaction, a database with write revisions or a write log
+    // runs the batch in one of its own, so a failed batch inserted nothing.
+    const insertsWhole = !inTransaction && requiresSmartdataWriteTransactions(collection.smartdataDb);
     const markInsertedDocuments = (
       insertedIdsArg: Record<number, unknown> | undefined,
     ): void => {

package/ts/nosqldb/classes.exactpersistence.ts

@@ -9,11 +9,11 @@ import { registerCollectionReconnectHandler } from './classes.collectionlifecycl
 import {
   SmartdataSession,
   acquireSmartdataSession,
-  needsSmartdataRevisionTransaction,
+  needsSmartdataWriteTransaction,
   readPreviousWriteRevisions,
   reportSmartdataCollectionWrite,
   reportSmartdataWriteFailure,
-  runSmartdataRevisionTransaction,
+  runSmartdataWriteTransaction,
   settleSmartdataOperationError,
   resolveSmartdataOperationDeadline,
   trackSmartdataRead,
@@ -1159,8 +1159,8 @@ export class SmartdataExactCollection<
       deadlineArg: SmartdataOperationDeadline,
     ) => Promise<TResult>,
   ): Promise<TResult> {
-    if (needsSmartdataRevisionTransaction(optionsArg.session, this.collection.smartdataDb)) {
-      return this.runRevisionWriteOperation(optionsArg, operationArg);
+    if (needsSmartdataWriteTransaction(optionsArg.session, this.collection.smartdataDb)) {
+      return this.runTransactionalWriteOperation(optionsArg, operationArg);
     }
     let started = false;
     try {
@@ -1180,13 +1180,14 @@ export class SmartdataExactCollection<
   }
 
   /**
-   * Runs one exact write in a transaction that carries the write's revisions:
+   * Runs one exact write in a transaction that carries the write's revisions
+   * and write-log entry:
    * on the caller's owned session, which needs the collection prepared, or on
    * a session of its own, which prepares the collection first. The
    * transaction's commit is the write's outcome: one whose commit outcome is
    * unknown is `ambiguous_write`.
    */
-  private async runRevisionWriteOperation<TResult>(
+  private async runTransactionalWriteOperation<TResult>(
     optionsArg: IExactBoundedOptions,
     operationArg: (
       sessionArg: plugins.mongodb.ClientSession | undefined,
@@ -1198,7 +1199,7 @@ export class SmartdataExactCollection<
     signal?.throwIfAborted();
     if (optionsArg.session) this.requirePreparedForSession();
     try {
-      return await runSmartdataRevisionTransaction(optionsArg.session, this.collection.smartdataDb, {
+      return await runSmartdataWriteTransaction(optionsArg.session, this.collection.smartdataDb, {
         ...(optionsArg.session ? { prepared: true } : { prepare: () => this.initialize() }),
         collectionName: this.collection.collectionName,
         ...(timeoutMS === undefined ? {} : { timeoutMS }),

package/ts/nosqldb/classes.readtracker.ts

@@ -10,6 +10,7 @@ import {
   readWriteRevisionSnapshot,
   revisionIdOfValue,
   sharedRevisionId,
+  writeRevisionBumpsOfKey,
   writeRevisionKeysOfRead,
 } from './classes.writerevisions.js';
 
@@ -32,13 +33,14 @@ export class SmartdataReadSet {
   /**
    * 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
+   * equal their baseline plus confirmed unrelated own writes. 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.
+   * Confirmed writes of this database that leave `changed` false are accounted
+   * for by their exact revision bumps. Other writers and unknown commit
+   * outcomes stay conservative; overlapping local commits make a revision
+   * snapshot unknowable rather than granting an ambiguous allowance.
    */
   public async isCurrent(): Promise<boolean> {
     const state = readSetStates.get(this);
@@ -57,9 +59,16 @@ export class SmartdataReadSet {
       if (count === 0) return true;
       if (values.some((valueArg) => valueArg === undefined)) return false;
       const keys = [...revisions.snapshots.keys()];
+      const allowances = keys.map((keyArg) => revisions.ownBumps.get(keyArg) ?? 0);
       const current = await readWriteRevisionSnapshot(state.db, keys);
-      if (state.changed) return false;
-      return keys.every((keyArg, indexArg) => current.get(keyArg) === values[indexArg]);
+      if (state.changed || revisions.lost) return false;
+      return keys.every((keyArg, indexArg) => {
+        const allowance = allowances[indexArg];
+        if ((revisions.ownBumps.get(keyArg) ?? 0) !== allowance) return false;
+        if (allowance === 0) return current.get(keyArg) === values[indexArg];
+        const expected = Number(values[indexArg]) + allowance;
+        return Number.isSafeInteger(expected) && current.get(keyArg) === String(expected);
+      });
     } catch {
       return false;
     }
@@ -165,6 +174,7 @@ interface IReadSetState {
 interface IReadSetRevisions {
   /** Per snapshot key, its value before the first read that depends on it; `undefined` when unknown. */
   snapshots: Map<string, Promise<string | undefined>>;
+  ownBumps: Map<string, number>;
   /** A revision could not be read, so the set can never be current. */
   lost: boolean;
 }
@@ -204,6 +214,7 @@ const changeReadSet = (stateArg: IReadSetState): void => {
   if (stateArg.changed) return;
   stateArg.changed = true;
   stateArg.reads.clear();
+  stateArg.revisions?.ownBumps.clear();
   readSetsByDb.get(stateArg.db)?.delete(stateArg);
 };
 
@@ -887,7 +898,9 @@ 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 };
+  if (isSmartdataWriteRevisionsActive(dbArg)) {
+    state.revisions = { snapshots: new Map(), ownBumps: new Map(), lost: false };
+  }
   readSetStates.set(reads, state);
   let states = readSetsByDb.get(dbArg);
   if (!states) {
@@ -915,6 +928,27 @@ export const hasSmartdataReadScope = (): boolean => readScope.getStore() !== und
 export const hasSmartdataReadSets = (dbArg: SmartdataDb): boolean =>
   (readSetsByDb.get(dbArg)?.size ?? 0) > 0;
 
+export const accountSmartdataOwnWriteRevisions = (
+  dbArg: SmartdataDb,
+  idsArg: ReadonlySet<string>,
+): void => {
+  if (idsArg.size === 0) return;
+  for (const state of readSetsByDb.get(dbArg) ?? []) {
+    const revisions = state.revisions;
+    if (!revisions || revisions.lost) continue;
+    for (const key of revisions.snapshots.keys()) {
+      const bumps = writeRevisionBumpsOfKey(key, idsArg);
+      if (bumps === 0) continue;
+      const allowance = (revisions.ownBumps.get(key) ?? 0) + bumps;
+      if (!Number.isSafeInteger(allowance)) {
+        revisions.lost = true;
+        break;
+      }
+      revisions.ownBumps.set(key, allowance);
+    }
+  }
+};
+
 /** @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.