@peers-app/peers-sdk 0.25.5 → 0.25.6

package/dist/data/change-tracking.d.ts

@@ -77,8 +77,7 @@ export declare class ChangeTrackingTable extends SQLDataSource<IChangeRecord> {
         now?: () => number;
     });
     /**
-     * Ensures the table exists, seeds both clocks from durable history, and
-     * rewrites any far-future `createdAt` rows this device still owns.
+     * Ensures the table exists and seeds both clocks from durable history.
      *
      * @param force - Re-run table migration and clock seeding
      */
@@ -88,16 +87,17 @@ export declare class ChangeTrackingTable extends SQLDataSource<IChangeRecord> {
      * {@link initTable} reseeds from an empty (or newly created) table.
      */
     dropTableIfExists(): Promise<void>;
-    private seedClocksAndRepair;
     /**
-     * Rewrite local rows whose `createdAt` is beyond the change-timestamp bound.
-     * `createdAt` is restamped from {@link clock} (near wall time) and `appliedAt`
-     * from the unbounded apply clock so peers whose watermark already passed the
-     * old value will pull the repaired rows.
+     * Seed the apply clock from `MAX(appliedAt)` and the write clock from the largest
+     * `createdAt` that is not far in the future, so a stored row with a bad timestamp
+     * cannot push every later local write into the future.
      *
-     * @returns Number of rows rewritten
+     * Rows are never rewritten here. A change's `createdAt` and `changeId` are its
+     * identity across devices: peers that already hold the row would ignore a
+     * re-sent copy, so restamping locally would make this device order the change
+     * differently from everyone else.
      */
-    repairFutureTimestamps(): Promise<number>;
+    private seedClocks;
     /**
      * Efficiently find which recordIds have been deleted.
      *

package/dist/data/change-tracking.js

@@ -89,15 +89,14 @@ class ChangeTrackingTable extends orm_1.SQLDataSource {
         this.dataChanged = this.dataChangedEmitter.event;
     }
     /**
-     * Ensures the table exists, seeds both clocks from durable history, and
-     * rewrites any far-future `createdAt` rows this device still owns.
+     * Ensures the table exists and seeds both clocks from durable history.
      *
      * @param force - Re-run table migration and clock seeding
      */
     async initTable(force = false) {
         const created = await super.initTable(force);
         if (!this.clockInit || force) {
-            this.clockInit = this.seedClocksAndRepair();
+            this.clockInit = this.seedClocks();
         }
         await this.clockInit;
         return created;
@@ -110,7 +109,17 @@ class ChangeTrackingTable extends orm_1.SQLDataSource {
         await super.dropTableIfExists();
         this.clockInit = undefined;
     }
-    async seedClocksAndRepair() {
+    /**
+     * Seed the apply clock from `MAX(appliedAt)` and the write clock from the largest
+     * `createdAt` that is not far in the future, so a stored row with a bad timestamp
+     * cannot push every later local write into the future.
+     *
+     * Rows are never rewritten here. A change's `createdAt` and `changeId` are its
+     * identity across devices: peers that already hold the row would ignore a
+     * re-sent copy, so restamping locally would make this device order the change
+     * differently from everyone else.
+     */
+    async seedClocks() {
         const physicalNow = this.clock.now();
         const cutoff = physicalNow + peer_device_1.PeerDeviceConsts.CHANGE_TIMESTAMP_TOLERANCE_MS;
         const bounds = await this.db.get(`SELECT
@@ -123,34 +132,6 @@ class ChangeTrackingTable extends orm_1.SQLDataSource {
         if (bounds?.maxCreatedAt != null) {
             this.clock.seed(Number(bounds.maxCreatedAt));
         }
-        await this.repairFutureTimestamps();
-    }
-    /**
-     * Rewrite local rows whose `createdAt` is beyond the change-timestamp bound.
-     * `createdAt` is restamped from {@link clock} (near wall time) and `appliedAt`
-     * from the unbounded apply clock so peers whose watermark already passed the
-     * old value will pull the repaired rows.
-     *
-     * @returns Number of rows rewritten
-     */
-    async repairFutureTimestamps() {
-        await super.initTable();
-        const cutoff = this.clock.now() + peer_device_1.PeerDeviceConsts.CHANGE_TIMESTAMP_TOLERANCE_MS;
-        const inBoundMax = await this.db.get(`SELECT MAX(createdAt) as maxCreatedAt FROM "${this.tableName}" WHERE createdAt <= ?`, [cutoff]);
-        if (inBoundMax?.maxCreatedAt != null) {
-            this.clock.seed(Number(inBoundMax.maxCreatedAt));
-        }
-        const rows = await this.db.all(`SELECT changeId FROM "${this.tableName}" WHERE createdAt > ? ORDER BY createdAt ASC`, [cutoff]);
-        if (rows.length === 0) {
-            return 0;
-        }
-        for (const row of rows) {
-            const createdAt = this.clock.tick();
-            const appliedAt = this.appliedClock.tick();
-            await this.db.exec(`UPDATE "${this.tableName}" SET createdAt = ?, appliedAt = ? WHERE changeId = ?`, [createdAt, appliedAt, row.changeId]);
-        }
-        console.log(`Repaired ${rows.length} change tracking row(s) with timestamps too far in the future`);
-        return rows.length;
     }
     /**
      * Efficiently find which recordIds have been deleted.

package/dist/types/peer-device.d.ts

@@ -98,9 +98,11 @@ export declare const PeerDeviceConsts: Readonly<{
     /** Handshake rejects peers whose wall clock differs by more than this. */
     readonly CLOCK_SKEW_TOLERANCE_MS: 300000;
     /**
-     * Incoming change `createdAt` values more than this far ahead of local now
-     * are skipped. 2× the handshake bound so multi-hop HLC lead plus allowed
-     * skew does not reject legitimate changes.
+     * Incoming change `createdAt` values more than this far ahead of local now are
+     * excluded from active history and do not advance the local hybrid logical
+     * clock. The receiver must also leave the source sync watermark unchanged so
+     * the row is offered again after its clock is corrected. 2× the handshake
+     * bound allows for multi-hop HLC lead plus permitted direct-peer skew.
      */
     readonly CHANGE_TIMESTAMP_TOLERANCE_MS: 600000;
 }>;

package/dist/types/peer-device.js

@@ -30,9 +30,11 @@ exports.PeerDeviceConsts = Object.freeze({
     /** Handshake rejects peers whose wall clock differs by more than this. */
     CLOCK_SKEW_TOLERANCE_MS: 300_000,
     /**
-     * Incoming change `createdAt` values more than this far ahead of local now
-     * are skipped. 2× the handshake bound so multi-hop HLC lead plus allowed
-     * skew does not reject legitimate changes.
+     * Incoming change `createdAt` values more than this far ahead of local now are
+     * excluded from active history and do not advance the local hybrid logical
+     * clock. The receiver must also leave the source sync watermark unchanged so
+     * the row is offered again after its clock is corrected. 2× the handshake
+     * bound allows for multi-hop HLC lead plus permitted direct-peer skew.
      */
     CHANGE_TIMESTAMP_TOLERANCE_MS: 600_000,
 });

package/dist/utils.d.ts

@@ -89,8 +89,26 @@ export declare function memoizePromise<F extends (...args: any[]) => Promise<any
  */
 export declare function debounceByArgs<F extends (...args: any[]) => any>(fn: F, wait?: number): F;
 /**
- * Monotonic-ish high-resolution time when `performance` exists; otherwise `Date.now()`.
- * Uses `timeOrigin + now()` in browsers; suitable for relative timing, not wall-clock.
+ * If the high-resolution estimate drifts from `Date.now()` by more than this many
+ * milliseconds, {@link getTimestamp} re-anchors to the wall clock.
+ */
+export declare const TIMESTAMP_REANCHOR_THRESHOLD_MS = 1000;
+/**
+ * Wall-clock time in milliseconds with sub-millisecond resolution where available.
+ *
+ * Returns `Date.now()` when the `performance` API is missing. Otherwise the value
+ * is `performance.now()` offset by an anchor taken from `Date.now()`, which is
+ * re-taken whenever the two disagree by more than
+ * {@link TIMESTAMP_REANCHOR_THRESHOLD_MS}. The anchor matters: `performance.now()`
+ * is a monotonic clock that on iOS Safari (and some other hosts) does **not**
+ * advance while the page or device is suspended, so a naive
+ * `timeOrigin + now()` falls behind the wall clock by the length of every sleep.
+ * A change-tracking clock built on that value then sees every fresh remote
+ * change as "far in the future". This function tracks `Date.now()` instead and
+ * only uses `performance.now()` for the fractional part and short-term smoothness.
+ *
+ * Values may step backward when the system clock is adjusted; callers that need
+ * monotonicity (e.g. `HybridLogicalClock`) handle that themselves.
  */
 export declare function getTimestamp(): number;
 /**

package/dist/utils.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.moneyFormatter = exports.MAX_ID = exports.MIN_ID = void 0;
+exports.TIMESTAMP_REANCHOR_THRESHOLD_MS = exports.moneyFormatter = exports.MAX_ID = exports.MIN_ID = void 0;
 exports.cryptoRandomString = cryptoRandomString;
 exports.newid = newid;
 exports.isid = isid;
@@ -276,16 +276,45 @@ function debounceByArgs(fn, wait = 300) {
     return debounced;
 }
 /**
- * Monotonic-ish high-resolution time when `performance` exists; otherwise `Date.now()`.
- * Uses `timeOrigin + now()` in browsers; suitable for relative timing, not wall-clock.
+ * If the high-resolution estimate drifts from `Date.now()` by more than this many
+ * milliseconds, {@link getTimestamp} re-anchors to the wall clock.
+ */
+exports.TIMESTAMP_REANCHOR_THRESHOLD_MS = 1_000;
+let perfAnchorWall;
+let perfAnchorHighRes;
+/**
+ * Wall-clock time in milliseconds with sub-millisecond resolution where available.
+ *
+ * Returns `Date.now()` when the `performance` API is missing. Otherwise the value
+ * is `performance.now()` offset by an anchor taken from `Date.now()`, which is
+ * re-taken whenever the two disagree by more than
+ * {@link TIMESTAMP_REANCHOR_THRESHOLD_MS}. The anchor matters: `performance.now()`
+ * is a monotonic clock that on iOS Safari (and some other hosts) does **not**
+ * advance while the page or device is suspended, so a naive
+ * `timeOrigin + now()` falls behind the wall clock by the length of every sleep.
+ * A change-tracking clock built on that value then sees every fresh remote
+ * change as "far in the future". This function tracks `Date.now()` instead and
+ * only uses `performance.now()` for the fractional part and short-term smoothness.
+ *
+ * Values may step backward when the system clock is adjusted; callers that need
+ * monotonicity (e.g. `HybridLogicalClock`) handle that themselves.
  */
 function getTimestamp() {
+    const wall = Date.now();
     // check if in node.js environment
-    if (typeof performance === "undefined" || !performance.timeOrigin) {
+    if (typeof performance === "undefined" || typeof performance.now !== "function") {
         // Fallback for environments without performance API
-        return Date.now();
+        return wall;
+    }
+    const highRes = performance.now();
+    if (perfAnchorWall === undefined ||
+        perfAnchorHighRes === undefined ||
+        Math.abs(perfAnchorWall + (highRes - perfAnchorHighRes) - wall) >
+            exports.TIMESTAMP_REANCHOR_THRESHOLD_MS) {
+        perfAnchorWall = wall;
+        perfAnchorHighRes = highRes;
     }
-    return performance.timeOrigin + performance.now();
+    return perfAnchorWall + (highRes - perfAnchorHighRes);
 }
 /**
  * Runs `fn` with adaptive timeout from {@link IDeviceConnection.latencyMs}, retrying on error or until the op finishes.

package/dist/utils.test.js

@@ -2,6 +2,35 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 const lodash_1 = require("lodash");
 const utils_1 = require("./utils");
+describe("getTimestamp", () => {
+    afterEach(() => {
+        jest.restoreAllMocks();
+    });
+    it("tracks the wall clock while the high-resolution clock is frozen (suspended tab)", () => {
+        // performance.now() stops advancing on iOS while the page is suspended; Date.now() does not.
+        const wallStart = 1_790_000_000_000;
+        let wall = wallStart;
+        const frozenHighRes = 12_345.678;
+        jest.spyOn(Date, "now").mockImplementation(() => wall);
+        jest.spyOn(performance, "now").mockImplementation(() => frozenHighRes);
+        const before = (0, utils_1.getTimestamp)();
+        expect(Math.abs(before - wallStart)).toBeLessThanOrEqual(utils_1.TIMESTAMP_REANCHOR_THRESHOLD_MS);
+        wall += 15 * 60 * 1000; // device slept for 15 minutes
+        const after = (0, utils_1.getTimestamp)();
+        expect(Math.abs(after - wall)).toBeLessThanOrEqual(utils_1.TIMESTAMP_REANCHOR_THRESHOLD_MS);
+        expect(after - before).toBeGreaterThan(14 * 60 * 1000);
+    });
+    it("keeps sub-millisecond resolution between re-anchors", () => {
+        const wall = 1_790_000_000_000;
+        let highRes = 1_000;
+        jest.spyOn(Date, "now").mockImplementation(() => wall + Math.floor(highRes - 1_000));
+        jest.spyOn(performance, "now").mockImplementation(() => highRes);
+        const first = (0, utils_1.getTimestamp)();
+        highRes += 0.25;
+        const second = (0, utils_1.getTimestamp)();
+        expect(second - first).toBeCloseTo(0.25, 5);
+    });
+});
 describe("newid", () => {
     it("should return a valid id", async () => {
         const id = (0, utils_1.newid)();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peers-app/peers-sdk",
-  "version": "0.25.5",
+  "version": "0.25.6",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/peers-app/peers-sdk.git"