@powersync/service-module-mongodb 0.18.2 → 0.19.0

package/dist/replication/checkpoints/CheckpointImplementation.d.ts

@@ -0,0 +1,132 @@
+import { mongo } from '@powersync/lib-service-mongodb';
+import { Logger } from '@powersync/lib-services-framework';
+import { ReplicationHeadCallback, storage } from '@powersync/service-core';
+import { ProjectedChangeStreamDocument } from '../RawChangeStream.js';
+/**
+ * Classification of an event on the `_powersync_checkpoints` collection.
+ *
+ * - 'standalone': source-wide checkpoint (write checkpoints, keepalive bumps,
+ *   snapshot markers). Processed regardless of which process created it.
+ * - 'own-barrier': this stream's private batch barrier document.
+ * - 'foreign': another stream's barrier document — ignore.
+ */
+export type CheckpointEventKind = 'standalone' | 'own-barrier' | 'foreign';
+export interface StreamResumePosition {
+    resumeAfter: mongo.ResumeToken | null;
+    /**
+     * Legacy startAtOperationTime fallback. Only produced by the timestamp implementation,
+     * and only for old LSNs persisted without a resume token.
+     */
+    startAfter: mongo.Timestamp | null;
+}
+export interface CheckpointImplementationContext {
+    client: mongo.MongoClient;
+    db: mongo.Db;
+    checkpointStreamId: mongo.ObjectId;
+    logger: Logger;
+}
+/**
+ * Event-interpretation surface of a {@link CheckpointImplementation}. Every method
+ * operates on a single raw change event.
+ *
+ * Ordering contract: {@link observe} must be called before {@link lsn} for a given
+ * event, so the sentinel implementation's coordinate is current.
+ */
+export interface CheckpointEventApi {
+    /**
+     * Classify a checkpoint-collection event and absorb any coordinate it
+     * carries (sentinel implementation). Must be called for every checkpoint event, in
+     * stream order.
+     */
+    observe(doc: ProjectedChangeStreamDocument): CheckpointEventKind;
+    /**
+     * Comparable LSN for committing/resuming at this event.
+     *
+     * Note this is not purely a function of `doc`. The timestamp implementation
+     * derives the whole LSN from the event (its coordinate is the event's
+     * clusterTime). The sentinel implementation pairs the *tracked* coordinate
+     * (updated by {@link observe}) with the event's resume token, because data
+     * events carry no coordinate of their own — hence the observe-before-lsn
+     * contract.
+     */
+    lsn(doc: ProjectedChangeStreamDocument): string;
+    /** Whether a barrier marker from {@link CheckpointImplementation.createBatchCheckpoint} is resolved by this event. */
+    resolvesBarrier(marker: string, doc: ProjectedChangeStreamDocument): boolean;
+}
+/**
+ * Strategy for producing and interpreting replication checkpoints.
+ *
+ * Two implementations exist:
+ *
+ * - {@link TimestampCheckpointImplementation}: standard MongoDB. The ordered LSN
+ *   coordinate is the oplog clusterTime, which is unique per operation and
+ *   parseable from resume tokens.
+ * - {@link SentinelCheckpointImplementation}: for sources without a usable clusterTime
+ *   (DocumentDB, and technically usable on any MongoDB). The ordered coordinate
+ *   is a shared monotonic counter document, observed through the change
+ *   stream itself.
+ *
+ * An implementation instance belongs to a single ChangeStream (or API adapter) and may
+ * hold per-stream coordinate state; call {@link seedPosition} at the start of
+ * each streaming loop.
+ */
+export interface CheckpointImplementation {
+    /** LSN representing "before any data". */
+    readonly zeroLsn: string;
+    /** Parse a stored LSN into change stream resume options. Pure. */
+    parseResumePosition(lsn: string): StreamResumePosition;
+    /** Reset/seed the implementation's coordinate state for a new stream loop. */
+    seedPosition(lsn: string | null): void;
+    /** Log the resume position at the start of a streaming loop. */
+    logResume(lsn: string): void;
+    /**
+     * Create a source-wide consistency checkpoint (snapshot boundaries,
+     * `no_checkpoint_before` markers). Returns a comparable LSN.
+     */
+    createStandaloneCheckpoint(): Promise<string>;
+    /**
+     * Create a batch barrier for this stream. Returns a marker that is resolved
+     * by a later change stream event via {@link CheckpointEventApi.resolvesBarrier}.
+     */
+    createBatchCheckpoint(): Promise<string>;
+    /**
+     * Create the first batch barrier for snapshot-LSN acquisition and return the
+     * LSN to open the change stream from, or null to open from "now".
+     *
+     * The timestamp implementation's barrier marker is itself a comparable LSN, so
+     * the stream resumes from it. The sentinel implementation's marker is opaque
+     * (content-matched) and carries no resume position, so it returns null and the
+     * stream opens from the current point.
+     */
+    createFirstBarrier(): Promise<string | null>;
+    /**
+     * Idle keepalive for an empty change stream batch. May persist a checkpoint
+     * directly (timestamp implementation) or nudge the source so that a later event
+     * commits (sentinel implementation).
+     */
+    keepalive(batch: storage.BucketStorageBatch, resumeToken: mongo.ResumeToken): Promise<void>;
+    /**
+     * Build a comparable LSN from a bare batch-level resume token (no change
+     * event). Used for the per-batch `setResumeLsn` progress marker.
+     *
+     * The timestamp implementation parses the timestamp embedded in the token.
+     * The sentinel implementation pairs the token with the current coordinate.
+     */
+    lsnFromResumeToken(resumeToken: mongo.ResumeToken): string;
+    /**
+     * Source-side replication head for write checkpoints. The LSN passed to the
+     * callback must compare at or below any LSN committed after the caller's
+     * preceding writes.
+     */
+    createReplicationHead<T>(callback: ReplicationHeadCallback<T>): Promise<T>;
+    /** Event-interpretation methods, all operating on a single raw change event. */
+    readonly event: CheckpointEventApi;
+    /** Filter for clearing the checkpoints collection on startup. */
+    readonly checkpointClearFilter: mongo.Filter<mongo.Document>;
+}
+/**
+ * Extract the event timestamp: clusterTime when present, otherwise wallTime
+ * truncated to second precision.
+ */
+export declare function getEventTimestamp(changeDocument: ProjectedChangeStreamDocument): mongo.Timestamp;
+export declare function getCheckpointId(doc: ProjectedChangeStreamDocument): string | mongo.ObjectId | null;

package/dist/replication/checkpoints/CheckpointImplementation.js

@@ -0,0 +1,22 @@
+import { mongo } from '@powersync/lib-service-mongodb';
+/**
+ * Extract the event timestamp: clusterTime when present, otherwise wallTime
+ * truncated to second precision.
+ */
+export function getEventTimestamp(changeDocument) {
+    if (changeDocument.clusterTime) {
+        return changeDocument.clusterTime;
+    }
+    const wallTime = changeDocument.wallTime;
+    if (wallTime != null) {
+        return mongo.Timestamp.fromBits(0, Math.floor(wallTime.getTime() / 1000));
+    }
+    throw new Error('Change event has neither clusterTime nor wallTime');
+}
+export function getCheckpointId(doc) {
+    if (!('documentKey' in doc)) {
+        return null;
+    }
+    return doc.documentKey._id;
+}
+//# sourceMappingURL=CheckpointImplementation.js.map

package/dist/replication/checkpoints/CheckpointImplementation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CheckpointImplementation.js","sourceRoot":"","sources":["../../../src/replication/checkpoints/CheckpointImplementation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,gCAAgC,CAAC;AAkJvD;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,cAA6C;IAC7E,IAAI,cAAc,CAAC,WAAW,EAAE,CAAC;QAC/B,OAAO,cAAc,CAAC,WAAW,CAAC;IACpC,CAAC;IACD,MAAM,QAAQ,GAAI,cAAsB,CAAC,QAA4B,CAAC;IACtE,IAAI,QAAQ,IAAI,IAAI,EAAE,CAAC;QACrB,OAAO,KAAK,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC;IAC5E,CAAC;IACD,MAAM,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAC;AACvE,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,GAAkC;IAChE,IAAI,CAAC,CAAC,aAAa,IAAI,GAAG,CAAC,EAAE,CAAC;QAC5B,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,GAAG,CAAC,WAAW,CAAC,GAA8B,CAAC;AACxD,CAAC"}

package/dist/replication/checkpoints/SentinelCheckpointImplementation.d.ts

@@ -0,0 +1,55 @@
+import { mongo } from '@powersync/lib-service-mongodb';
+import { ReplicationHeadCallback, storage } from '@powersync/service-core';
+import { CheckpointEventApi, CheckpointImplementation, CheckpointImplementationContext, StreamResumePosition } from './CheckpointImplementation.js';
+/**
+ * Sentinel checkpoint implementation, used for sources without a usable clusterTime
+ * (DocumentDB). The ordered LSN coordinate is a single shared sentinel checkpoint
+ * counter ({@link SENTINEL_CHECKPOINT_ID}), observed through the change stream:
+ *
+ * - Batch checkpoints advance the global counter and stamp it with this stream's
+ *   id, so the stream recognises its own private barriers by content (stream_id
+ *   + counter) rather than by cross-document event ordering.
+ * - Standalone bumps (write checkpoint heads, snapshot markers) advance the same
+ *   counter with a null stream_id; every stream observes these as the global
+ *   coordinate.
+ * - Keepalives advance the counter without persisting; the bump's own event
+ *   flows through the stream and commits via the standalone handling,
+ *   preserving the "commit only what the stream has seen" barrier property.
+ *
+ * See docs/documentdb/documentdb-lsn-sentinel-checkpoints.md for the full design.
+ */
+export declare class SentinelCheckpointImplementation implements CheckpointImplementation {
+    private context;
+    readonly zeroLsn: string;
+    /**
+     * The highest global sentinel value proven so far, merged monotonically from
+     * the resume seed, standalone events and embedded barrier values. Needed
+     * for lsnFromResumeToken: per-batch resume markers carry only a resume token,
+     * so they need the latest observed coordinate paired in.
+     */
+    private position;
+    constructor(context: CheckpointImplementationContext);
+    parseResumePosition(lsn: string): StreamResumePosition;
+    seedPosition(lsn: string | null): void;
+    logResume(lsn: string): void;
+    createStandaloneCheckpoint(): Promise<string>;
+    createBatchCheckpoint(): Promise<string>;
+    createFirstBarrier(): Promise<string | null>;
+    keepalive(_batch: storage.BucketStorageBatch, _resumeToken: mongo.ResumeToken): Promise<void>;
+    lsnFromResumeToken(resumeToken: mongo.ResumeToken): string;
+    createReplicationHead<T>(callback: ReplicationHeadCallback<T>): Promise<T>;
+    readonly event: CheckpointEventApi;
+    readonly checkpointClearFilter: mongo.Filter<mongo.Document>;
+    /** Never move the position backwards — replayed or reordered events must not regress the coordinate. */
+    private mergePosition;
+    /**
+     * Read the sentinel counter from a sentinel checkpoint post-image.
+     *
+     * The `i` field is required: every sentinel write `$inc`s it. If it is
+     * missing, the document was replaced externally, which destroys the LSN
+     * coordinate system (a re-created counter restarts below already-committed
+     * LSNs). Invalidate the stream so replication restarts from scratch instead
+     * of stalling against a broken coordinate.
+     */
+    private readSentinel;
+}

package/dist/replication/checkpoints/SentinelCheckpointImplementation.js

@@ -0,0 +1,222 @@
+import { mongo } from '@powersync/lib-service-mongodb';
+import { JSONBig } from '@powersync/service-jsonbig';
+import { SentinelLSN } from '../../common/SentinelLSN.js';
+import { ChangeStreamInvalidatedError } from '../ChangeStream.js';
+import { createSentinelCheckpointLsn, SENTINEL_CHECKPOINT_ID } from '../MongoRelation.js';
+import { getCheckpointId } from './CheckpointImplementation.js';
+/**
+ * Sentinel checkpoint implementation, used for sources without a usable clusterTime
+ * (DocumentDB). The ordered LSN coordinate is a single shared sentinel checkpoint
+ * counter ({@link SENTINEL_CHECKPOINT_ID}), observed through the change stream:
+ *
+ * - Batch checkpoints advance the global counter and stamp it with this stream's
+ *   id, so the stream recognises its own private barriers by content (stream_id
+ *   + counter) rather than by cross-document event ordering.
+ * - Standalone bumps (write checkpoint heads, snapshot markers) advance the same
+ *   counter with a null stream_id; every stream observes these as the global
+ *   coordinate.
+ * - Keepalives advance the counter without persisting; the bump's own event
+ *   flows through the stream and commits via the standalone handling,
+ *   preserving the "commit only what the stream has seen" barrier property.
+ *
+ * See docs/documentdb/documentdb-lsn-sentinel-checkpoints.md for the full design.
+ */
+export class SentinelCheckpointImplementation {
+    context;
+    zeroLsn = SentinelLSN.ZERO.comparable;
+    /**
+     * The highest global sentinel value proven so far, merged monotonically from
+     * the resume seed, standalone events and embedded barrier values. Needed
+     * for lsnFromResumeToken: per-batch resume markers carry only a resume token,
+     * so they need the latest observed coordinate paired in.
+     */
+    position = SentinelLSN.ZERO.sentinel;
+    constructor(context) {
+        this.context = context;
+    }
+    parseResumePosition(lsn) {
+        const parsed = SentinelLSN.fromSerialized(lsn);
+        return { resumeAfter: parsed.resumeToken ?? null, startAfter: null };
+    }
+    seedPosition(lsn) {
+        this.position = lsn == null ? SentinelLSN.ZERO.sentinel : SentinelLSN.fromSerialized(lsn).sentinel;
+    }
+    logResume(lsn) {
+        const parsed = SentinelLSN.fromSerialized(lsn);
+        this.context.logger.info(`Resume streaming at sentinel ${parsed.sentinel} / ${parsed}`);
+    }
+    async createStandaloneCheckpoint() {
+        return createSentinelCheckpointLsn(this.context.client, this.context.db);
+    }
+    async createBatchCheckpoint() {
+        // Advance the shared sentinel checkpoint — the global source-database
+        // coordinate. It must be shared so the LSN domain survives new
+        // ChangeStream instances and new sync rules.
+        // This advance is associated with the change stream in order to track stream
+        // barriers. The returned LSN (counter only, no resume token) is the barrier
+        // marker matched by resolvesBarrier.
+        return createSentinelCheckpointLsn(this.context.client, this.context.db, this.context.checkpointStreamId);
+    }
+    async createFirstBarrier() {
+        // The barrier marker is an opaque content-matched marker, not a resume
+        // position, so there is no LSN to open the stream from: a fresh DocumentDB
+        // stream opens from "now" and the snapshot loop re-creates barriers until
+        // one is observed.
+        await this.createBatchCheckpoint();
+        return null;
+    }
+    async keepalive(_batch, _resumeToken) {
+        // Advance the shared sentinel, but do not persist a checkpoint here. The
+        // bump is stamped with this stream's id, so its own change event flows
+        // through the stream as an own-barrier event and is committed by the
+        // own-barrier handling, which advances the ordered LSN prefix and refreshes
+        // the resume token (using the event's own token).
+        //
+        // Why bump at all: with an unchanged sentinel, LSN comparison against the
+        // previously persisted LSN falls to the opaque base64 token suffix, which
+        // is not lexicographically meaningful — storage would silently reject
+        // roughly half of plain token refreshes, leaving the persisted resume
+        // token to go stale on an idle stream. (The timestamp implementation avoids this
+        // because its keepalive timestamp is parsed from the resume token itself,
+        // so the ordered prefix always advances with the token.)
+        //
+        // Why not persist immediately: writes that landed after this empty batch
+        // was read — including a write checkpoint head — would be covered by the
+        // persisted LSN before the stream has processed them, allowing write
+        // checkpoints to resolve before the corresponding data is replicated.
+        // Committing only when the bump's event is observed preserves the
+        // "commit only what the stream has seen" barrier property.
+        await createSentinelCheckpointLsn(this.context.client, this.context.db, this.context.checkpointStreamId);
+        this.context.logger.info(`Idle change stream (sentinel implementation). Bumped sentinel to advance the checkpoint.`);
+    }
+    lsnFromResumeToken(resumeToken) {
+        // Pair the bare token with the current coordinate. The coordinate is
+        // frozen between checkpoint events, so a per-batch resume marker only
+        // advances the token; that is all resumption needs (see the design doc).
+        return new SentinelLSN({ sentinel: this.position, resume_token: resumeToken }).comparable;
+    }
+    async createReplicationHead(callback) {
+        const head = await createSentinelCheckpointLsn(this.context.client, this.context.db);
+        const result = await callback(head);
+        // Create another bump to ensure movement after the reported head. This
+        // covers the race where the head's own event is committed before the
+        // write checkpoint document is stored.
+        // Note that this checkpoint should not be associated with a change stream Id.
+        await createSentinelCheckpointLsn(this.context.client, this.context.db);
+        return result;
+    }
+    event = {
+        observe: (doc) => {
+            const checkpointId = getCheckpointId(doc);
+            if (checkpointId != SENTINEL_CHECKPOINT_ID) {
+                // The sentinel implementation only uses the SENTINEL_CHECKPOINT_ID
+                // document; anything else (including the timestamp impl's standalone
+                // document) is foreign.
+                return 'foreign';
+            }
+            const fullDoc = deserializeFullDocument(doc);
+            if (fullDoc == null) {
+                // An insert/update/replace on our sentinel document must carry a
+                // post-image. A missing fullDocument means the document was deleted or
+                // replaced out from under us, which destroys the coordinate; invalidate
+                // so replication restarts clean instead of stalling.
+                throw new ChangeStreamInvalidatedError('Sentinel checkpoint event has no fullDocument — cannot read the sentinel', new Error(`Unexpected ${doc.operationType} event on the sentinel checkpoint document`));
+            }
+            const streamId = fullDoc.stream_id;
+            let kind;
+            if (streamId == null) {
+                // No stream_id: a standalone bump (write checkpoint head, snapshot
+                // marker). Every stream tracks these as the global coordinate.
+                kind = 'standalone';
+            }
+            else if (this.context.checkpointStreamId.equals(streamId)) {
+                // Stamped with our id: one of our own private batch/keepalive barriers.
+                kind = 'own-barrier';
+            }
+            else {
+                // Another stream's private barrier — ignore.
+                return 'foreign';
+            }
+            // Both kinds carry the global coordinate in `i`; keep our position current.
+            this.mergePosition(this.readSentinel(fullDoc));
+            return kind;
+        },
+        lsn: (doc) => {
+            const fullDoc = deserializeFullDocument(doc);
+            if (fullDoc == null) {
+                throw new ChangeStreamInvalidatedError('Sentinel checkpoint event has no fullDocument — cannot read the sentinel', new Error(`Unexpected ${doc.operationType} event on the sentinel checkpoint document`));
+            }
+            // Checkpoint events carry the global coordinate in `i`; pair that exact
+            // coordinate with this event's resume token. Plain data-batch resume
+            // markers use lsnFromResumeToken, which pairs the token with the tracked
+            // position instead.
+            return new SentinelLSN({
+                sentinel: this.readSentinel(fullDoc),
+                resume_token: doc._id
+            }).comparable;
+        },
+        resolvesBarrier: (marker, doc) => {
+            const fullDoc = deserializeFullDocument(doc);
+            if (fullDoc == null) {
+                this.context.logger.warn('Checkpoint event missing fullDocument — cannot match sentinel barrier');
+                return false;
+            }
+            const parsed = SentinelLSN.fromSerialized(marker);
+            return this.context.checkpointStreamId.equals(fullDoc.stream_id) && fullDoc.i >= parsed.sentinel;
+        }
+    };
+    // The sentinel checkpoint document must survive restarts (hence the $ne
+    // below — the startup cleanup deletes every other checkpoint document). Its
+    // counter is the globally-ordered component of every committed LSN, including
+    // write checkpoint heads. Deleting it would re-seed the counter on the next
+    // upsert, risking moving the LSN coordinate system backwards: new commits
+    // could compare below the persisted last_checkpoint_lsn (so storage rejects
+    // them via checkpointBlocked and the checkpoint stalls), and new write
+    // checkpoint heads could resolve against old, higher committed LSNs before
+    // their data has actually replicated.
+    //
+    // Note: this only protects against our own startup cleanup. The global
+    // LSN coordinate still lives in a user-visible collection, so a consumer
+    // can delete it in their source database. Dropping the whole checkpoints
+    // collection is detected (the streaming loop invalidates the stream on the
+    // collection drop event). Deleting just this document is mitigated by
+    // createSentinelCheckpointLsn seeding re-created counters at the current
+    // epoch seconds, so the coordinate jumps forward instead of resetting
+    // below already-committed LSNs.
+    checkpointClearFilter = { _id: { $ne: SENTINEL_CHECKPOINT_ID } };
+    /** Never move the position backwards — replayed or reordered events must not regress the coordinate. */
+    mergePosition(observed) {
+        if (observed > this.position) {
+            this.position = observed;
+        }
+    }
+    /**
+     * Read the sentinel counter from a sentinel checkpoint post-image.
+     *
+     * The `i` field is required: every sentinel write `$inc`s it. If it is
+     * missing, the document was replaced externally, which destroys the LSN
+     * coordinate system (a re-created counter restarts below already-committed
+     * LSNs). Invalidate the stream so replication restarts from scratch instead
+     * of stalling against a broken coordinate.
+     */
+    readSentinel(fullDoc) {
+        if (fullDoc.i == null) {
+            throw new ChangeStreamInvalidatedError('Sentinel checkpoint document has no `i` field — cannot read the sentinel', 
+            // JSONBig.stringify, since the post-image is deserialized with useBigInt64.
+            new Error(`Sentinel checkpoint document: ${JSONBig.stringify(fullDoc)}`));
+        }
+        return fullDoc.i;
+    }
+}
+function deserializeFullDocument(doc) {
+    const memo = doc;
+    if (memo.parsedFullDocument !== undefined) {
+        return memo.parsedFullDocument;
+    }
+    const fullDocument = 'fullDocument' in doc ? doc.fullDocument : null;
+    // fullDocument is a raw BSON Buffer from parseChangeDocument.
+    const parsed = fullDocument ? mongo.BSON.deserialize(fullDocument, { useBigInt64: true }) : null;
+    memo.parsedFullDocument = parsed;
+    return parsed;
+}
+//# sourceMappingURL=SentinelCheckpointImplementation.js.map

package/dist/replication/checkpoints/SentinelCheckpointImplementation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SentinelCheckpointImplementation.js","sourceRoot":"","sources":["../../../src/replication/checkpoints/SentinelCheckpointImplementation.ts"],"names":[],"mappings":"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"}

package/dist/replication/checkpoints/TimestampCheckpointImplementation.d.ts

@@ -0,0 +1,24 @@
+import { mongo } from '@powersync/lib-service-mongodb';
+import { ReplicationHeadCallback, storage } from '@powersync/service-core';
+import { CheckpointEventApi, CheckpointImplementation, CheckpointImplementationContext, StreamResumePosition } from './CheckpointImplementation.js';
+/**
+ * Standard MongoDB checkpoint implementation. The ordered LSN coordinate is the oplog
+ * clusterTime — unique per operation, monotonic, and parseable from resume
+ * tokens. Barriers and event LSNs are plain comparable LSN strings.
+ */
+export declare class TimestampCheckpointImplementation implements CheckpointImplementation {
+    private context;
+    readonly zeroLsn: string;
+    constructor(context: CheckpointImplementationContext);
+    parseResumePosition(lsn: string): StreamResumePosition;
+    seedPosition(_lsn: string | null): void;
+    logResume(lsn: string): void;
+    createStandaloneCheckpoint(): Promise<string>;
+    createBatchCheckpoint(): Promise<string>;
+    createFirstBarrier(): Promise<string | null>;
+    keepalive(batch: storage.BucketStorageBatch, resumeToken: mongo.ResumeToken): Promise<void>;
+    lsnFromResumeToken(resumeToken: mongo.ResumeToken): string;
+    createReplicationHead<T>(callback: ReplicationHeadCallback<T>): Promise<T>;
+    readonly event: CheckpointEventApi;
+    readonly checkpointClearFilter: mongo.Filter<mongo.Document>;
+}

package/dist/replication/checkpoints/TimestampCheckpointImplementation.js

@@ -0,0 +1,113 @@
+import { ServiceAssertionError } from '@powersync/lib-services-framework';
+import { MongoLSN } from '../../common/MongoLSN.js';
+import { createCheckpoint, SENTINEL_CHECKPOINT_ID, STANDALONE_CHECKPOINT_ID } from '../MongoRelation.js';
+import { CHECKPOINTS_COLLECTION, timestampToDate } from '../replication-utils.js';
+import { getCheckpointId, getEventTimestamp } from './CheckpointImplementation.js';
+/**
+ * Standard MongoDB checkpoint implementation. The ordered LSN coordinate is the oplog
+ * clusterTime — unique per operation, monotonic, and parseable from resume
+ * tokens. Barriers and event LSNs are plain comparable LSN strings.
+ */
+export class TimestampCheckpointImplementation {
+    context;
+    zeroLsn = MongoLSN.ZERO.comparable;
+    constructor(context) {
+        this.context = context;
+    }
+    parseResumePosition(lsn) {
+        const parsed = MongoLSN.fromSerialized(lsn);
+        return { resumeAfter: parsed.resumeToken ?? null, startAfter: parsed.timestamp };
+    }
+    seedPosition(_lsn) {
+        // The coordinate comes from each event's clusterTime; no state to seed.
+    }
+    logResume(lsn) {
+        const parsed = MongoLSN.fromSerialized(lsn);
+        // It is normal for this to be a minute or two old when there is a low volume
+        // of ChangeStream events.
+        const tokenAgeSeconds = Math.round((Date.now() - timestampToDate(parsed.timestamp).getTime()) / 1000);
+        this.context.logger.info(`Resume streaming at ${parsed.timestamp.inspect()} / ${parsed} | Token age: ${tokenAgeSeconds}s`);
+    }
+    async createStandaloneCheckpoint() {
+        return createCheckpoint(this.context.db, STANDALONE_CHECKPOINT_ID);
+    }
+    async createBatchCheckpoint() {
+        return createCheckpoint(this.context.db, this.context.checkpointStreamId);
+    }
+    async createFirstBarrier() {
+        // The barrier marker is a comparable LSN; resume the snapshot stream from it.
+        return this.createBatchCheckpoint();
+    }
+    async keepalive(batch, resumeToken) {
+        // Parse the timestamp from the resume token. The ordered LSN prefix
+        // advances together with the token, so persisting is always safe.
+        const { comparable: lsn, timestamp } = MongoLSN.fromResumeToken(resumeToken);
+        await batch.keepalive(lsn);
+        // Log the token update. This helps as a general "replication is still active" message in the logs.
+        // This token would typically be around 10s behind.
+        this.context.logger.info(`Idle change stream. Persisted resumeToken for ${timestampToDate(timestamp).toISOString()}`);
+    }
+    lsnFromResumeToken(resumeToken) {
+        // The timestamp is embedded in the resume token.
+        return MongoLSN.fromResumeToken(resumeToken).comparable;
+    }
+    async createReplicationHead(callback) {
+        const session = this.context.client.startSession();
+        try {
+            await this.context.db.command({ hello: 1 }, { session });
+            const head = session.clusterTime?.clusterTime;
+            if (head == null) {
+                throw new ServiceAssertionError(`clusterTime not available for write checkpoint`);
+            }
+            const r = await callback(new MongoLSN({ timestamp: head }).comparable);
+            // Trigger a change on the changestream, so that the write checkpoint
+            // is processed without waiting for other writes.
+            await this.context.db.collection(CHECKPOINTS_COLLECTION).findOneAndUpdate({
+                _id: STANDALONE_CHECKPOINT_ID
+            }, {
+                $inc: { i: 1 }
+            }, {
+                upsert: true,
+                returnDocument: 'after',
+                session
+            });
+            const time = session.operationTime;
+            if (time == null) {
+                throw new ServiceAssertionError(`operationTime not available for write checkpoint`);
+            }
+            else if (time.lt(head)) {
+                throw new ServiceAssertionError(`operationTime must be > clusterTime`);
+            }
+            return r;
+        }
+        finally {
+            await session.endSession();
+        }
+    }
+    event = {
+        observe: (doc) => {
+            const checkpointId = getCheckpointId(doc);
+            if (checkpointId == null || checkpointId == SENTINEL_CHECKPOINT_ID) {
+                return 'foreign';
+            }
+            // The STANDALONE_CHECKPOINT_ID is only used for the TimestampCheckpointImplementation
+            if (checkpointId == STANDALONE_CHECKPOINT_ID) {
+                return 'standalone';
+            }
+            return this.context.checkpointStreamId.equals(checkpointId) ? 'own-barrier' : 'foreign';
+        },
+        lsn: (doc) => {
+            return new MongoLSN({
+                timestamp: getEventTimestamp(doc),
+                resume_token: doc._id
+            }).comparable;
+        },
+        resolvesBarrier: (marker, doc) => {
+            // Barrier markers are comparable LSNs in this implementation.
+            return this.event.lsn(doc) >= marker;
+        }
+    };
+    // It's safe to clear the entire _powersync_checkpoints collection in this mode.
+    checkpointClearFilter = {};
+}
+//# sourceMappingURL=TimestampCheckpointImplementation.js.map

package/dist/replication/checkpoints/TimestampCheckpointImplementation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TimestampCheckpointImplementation.js","sourceRoot":"","sources":["../../../src/replication/checkpoints/TimestampCheckpointImplementation.ts"],"names":[],"mappings":"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"}

package/dist/replication/checkpoints/create-checkpoint-implementation.d.ts

@@ -0,0 +1,6 @@
+import { CheckpointImplementation, CheckpointImplementationContext } from './CheckpointImplementation.js';
+/**
+ * Select the checkpoint implementation for a source: sentinel-based for DocumentDB
+ * DB, clusterTime-based for standard MongoDB.
+ */
+export declare function createCheckpointImplementation(isDocumentDb: boolean, context: CheckpointImplementationContext): CheckpointImplementation;

package/dist/replication/checkpoints/create-checkpoint-implementation.js

@@ -0,0 +1,10 @@
+import { SentinelCheckpointImplementation } from './SentinelCheckpointImplementation.js';
+import { TimestampCheckpointImplementation } from './TimestampCheckpointImplementation.js';
+/**
+ * Select the checkpoint implementation for a source: sentinel-based for DocumentDB
+ * DB, clusterTime-based for standard MongoDB.
+ */
+export function createCheckpointImplementation(isDocumentDb, context) {
+    return isDocumentDb ? new SentinelCheckpointImplementation(context) : new TimestampCheckpointImplementation(context);
+}
+//# sourceMappingURL=create-checkpoint-implementation.js.map

package/dist/replication/checkpoints/create-checkpoint-implementation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-checkpoint-implementation.js","sourceRoot":"","sources":["../../../src/replication/checkpoints/create-checkpoint-implementation.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gCAAgC,EAAE,MAAM,uCAAuC,CAAC;AACzF,OAAO,EAAE,iCAAiC,EAAE,MAAM,wCAAwC,CAAC;AAE3F;;;GAGG;AACH,MAAM,UAAU,8BAA8B,CAC5C,YAAqB,EACrB,OAAwC;IAExC,OAAO,YAAY,CAAC,CAAC,CAAC,IAAI,gCAAgC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,iCAAiC,CAAC,OAAO,CAAC,CAAC;AACvH,CAAC"}

package/dist/replication/replication-utils.d.ts

@@ -1,5 +1,11 @@
+import { mongo } from '@powersync/lib-service-mongodb';
 import * as bson from 'bson';
 import { MongoManager } from './MongoManager.js';
 export declare const CHECKPOINTS_COLLECTION = "_powersync_checkpoints";
+/**
+ * Detect whether the connected server is DocumentDB. DocumentDB lacks usable
+ * clusterTime/operationTime and uses the sentinel checkpoint implementation.
+ */
+export declare function detectDocumentDb(db: mongo.Db): Promise<boolean>;
 export declare function checkSourceConfiguration(connectionManager: MongoManager): Promise<void>;
 export declare function timestampToDate(timestamp: bson.Timestamp): Date;