@peers-app/peers-sdk 0.23.12 → 0.23.13

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

@@ -7,7 +7,12 @@
  */
 import { z } from "zod";
 import { Emitter, type Event } from "../events";
+import { HybridLogicalClock } from "../hlc";
 import { type DataFilter, type IDataQueryParams, type ISqlDb, type ITableMetaData, SQLDataSource } from "./orm";
+/**
+ * Zod schema for a single granular change-log row in `ChangeTrackingV2`.
+ * `appliedAt` is assigned locally at insert time; incoming values are replaced.
+ */
 export declare const changeRecordSchema: z.ZodObject<{
     changeId: z.ZodEffects<z.ZodString, string, string>;
     transactionId: z.ZodOptional<z.ZodString>;
@@ -42,13 +47,57 @@ export declare const changeRecordSchema: z.ZodObject<{
     transactionId?: string | undefined;
     supersededAt?: number | undefined;
 }>;
+/**
+ * One JSON-patch operation (or root snapshot / delete) stored for synchronization.
+ */
 export type IChangeRecord = z.infer<typeof changeRecordSchema>;
+/**
+ * Local-only change log used for peer sync.
+ *
+ * Owns two {@link HybridLogicalClock} instances for this database:
+ * - {@link clock} stamps `createdAt` / `supersededAt` (cross-device LWW)
+ * - `appliedClock` stamps `appliedAt` at insert time (per-device sync watermark)
+ */
 export declare class ChangeTrackingTable extends SQLDataSource<IChangeRecord> {
     readonly dataChangedEmitter: Emitter<IChangeRecord>;
     readonly dataChanged: Event<IChangeRecord>;
-    constructor({ db }: {
+    /**
+     * Hybrid logical clock for author write times (`createdAt`, `supersededAt`).
+     * Observes accepted incoming `createdAt` values so later local writes order after them.
+     */
+    readonly clock: HybridLogicalClock;
+    private readonly appliedClock;
+    private clockInit;
+    /**
+     * @param db - SQLite database that stores `ChangeTrackingV2`
+     * @param now - Optional physical-time source shared by both clocks (defaults to {@link getTimestamp})
+     */
+    constructor({ db, now }: {
         db: ISqlDb;
+        now?: () => number;
     });
+    /**
+     * Ensures the table exists, seeds both clocks from durable history, and
+     * rewrites any far-future `createdAt` rows this device still owns.
+     *
+     * @param force - Re-run table migration and clock seeding
+     */
+    initTable(force?: boolean): Promise<boolean>;
+    /**
+     * Drop the change-tracking table and clear memoized clock seeding so the next
+     * {@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.
+     *
+     * @returns Number of rows rewritten
+     */
+    repairFutureTimestamps(): Promise<number>;
     /**
      * Efficiently find which recordIds have been deleted.
      *
@@ -79,6 +128,10 @@ export declare class ChangeTrackingTable extends SQLDataSource<IChangeRecord> {
      * @returns Array of changeIds with no change records
      */
     filterToMissingChangeIds(changeIds: string[]): Promise<string[]>;
+    /**
+     * Mark every still-active change for `recordId` whose `createdAt` is older
+     * than `supersededAt`. Used after a root snapshot, delete, or restore.
+     */
     markAllPriorChangesSuperseded(tableName: string, recordId: string, supersededAt: number): Promise<void>;
     /**
      * Batch update supersededAt timestamps for multiple changes.
@@ -99,7 +152,8 @@ export declare class ChangeTrackingTable extends SQLDataSource<IChangeRecord> {
      */
     get(id: string): Promise<IChangeRecord | undefined>;
     /**
-     * Override to serialize value field to JSON string
+     * Insert a change row, assigning `appliedAt` from the local apply clock
+     * immediately before the SQL statement so watermarks stay monotonic.
      */
     insert(record: IChangeRecord): Promise<IChangeRecord>;
     /**
@@ -109,6 +163,7 @@ export declare class ChangeTrackingTable extends SQLDataSource<IChangeRecord> {
     /**
      * Synchronous insert for use within transactions.
      * Table must be initialized before calling this method.
+     * Assigns `appliedAt` from the local apply clock immediately before the SQL statement.
      */
     insertSync(record: IChangeRecord): IChangeRecord;
     /**

package/dist/data/change-tracking.js

@@ -10,10 +10,16 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ChangeTrackingTable = exports.changeRecordSchema = void 0;
 const zod_1 = require("zod");
 const events_1 = require("../events");
+const hlc_1 = require("../hlc");
 const serial_json_1 = require("../serial-json");
+const peer_device_1 = require("../types/peer-device");
 const zod_types_1 = require("../types/zod-types");
 const utils_1 = require("../utils");
 const orm_1 = require("./orm");
+/**
+ * Zod schema for a single granular change-log row in `ChangeTrackingV2`.
+ * `appliedAt` is assigned locally at insert time; incoming values are replaced.
+ */
 exports.changeRecordSchema = zod_1.z.object({
     changeId: zod_types_1.zodPeerId,
     transactionId: zod_1.z.string().optional(), // not used for now
@@ -25,9 +31,11 @@ exports.changeRecordSchema = zod_1.z.object({
         .any()
         .nullish()
         .describe("JSON value - can be any type (object, string, number, boolean, array, null, or undefined)"),
-    createdAt: zod_1.z.number(),
-    appliedAt: zod_1.z.number(),
-    supersededAt: zod_1.z.number().optional(),
+    createdAt: zod_1.z.number().describe("Author write time from the hybrid logical clock (LWW key)"),
+    appliedAt: zod_1.z
+        .number()
+        .describe("Local apply / sync-visibility time; assigned at insert, incoming values replaced"),
+    supersededAt: zod_1.z.number().optional().describe("When this change was superseded; unset if active"),
 });
 const changeTrackingV2TableMetaData = {
     name: "ChangeTrackingV2",
@@ -47,15 +55,103 @@ const changeTrackingV2TableMetaData = {
     ],
     localOnly: true,
 };
+/**
+ * Local-only change log used for peer sync.
+ *
+ * Owns two {@link HybridLogicalClock} instances for this database:
+ * - {@link clock} stamps `createdAt` / `supersededAt` (cross-device LWW)
+ * - `appliedClock` stamps `appliedAt` at insert time (per-device sync watermark)
+ */
 class ChangeTrackingTable extends orm_1.SQLDataSource {
     dataChangedEmitter;
     dataChanged;
-    constructor({ db }) {
+    /**
+     * Hybrid logical clock for author write times (`createdAt`, `supersededAt`).
+     * Observes accepted incoming `createdAt` values so later local writes order after them.
+     */
+    clock;
+    appliedClock;
+    clockInit;
+    /**
+     * @param db - SQLite database that stores `ChangeTrackingV2`
+     * @param now - Optional physical-time source shared by both clocks (defaults to {@link getTimestamp})
+     */
+    constructor({ db, now }) {
         super(db, changeTrackingV2TableMetaData, exports.changeRecordSchema);
+        const physicalNow = now ?? utils_1.getTimestamp;
+        this.clock = new hlc_1.HybridLogicalClock({ now: physicalNow });
+        this.appliedClock = new hlc_1.HybridLogicalClock({
+            now: physicalNow,
+            maxSkewMs: Number.POSITIVE_INFINITY,
+        });
         const tableName = changeTrackingV2TableMetaData.name;
         this.dataChangedEmitter = new events_1.Emitter(`${tableName}_DataChanged_${(0, utils_1.newid)()}`);
         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.
+     *
+     * @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();
+        }
+        await this.clockInit;
+        return created;
+    }
+    /**
+     * Drop the change-tracking table and clear memoized clock seeding so the next
+     * {@link initTable} reseeds from an empty (or newly created) table.
+     */
+    async dropTableIfExists() {
+        await super.dropTableIfExists();
+        this.clockInit = undefined;
+    }
+    async seedClocksAndRepair() {
+        const physicalNow = this.clock.now();
+        const cutoff = physicalNow + peer_device_1.PeerDeviceConsts.CHANGE_TIMESTAMP_TOLERANCE_MS;
+        const bounds = await this.db.get(`SELECT
+         MAX(CASE WHEN createdAt <= ? THEN createdAt END) as maxCreatedAt,
+         MAX(appliedAt) as maxAppliedAt
+       FROM "${this.tableName}"`, [cutoff]);
+        if (bounds?.maxAppliedAt != null) {
+            this.appliedClock.seed(Number(bounds.maxAppliedAt));
+        }
+        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.
      *
@@ -144,6 +240,10 @@ class ChangeTrackingTable extends orm_1.SQLDataSource {
     `, changeIds);
         return missingChangeIds.map((d) => d.changeId);
     }
+    /**
+     * Mark every still-active change for `recordId` whose `createdAt` is older
+     * than `supersededAt`. Used after a root snapshot, delete, or restore.
+     */
     async markAllPriorChangesSuperseded(tableName, recordId, supersededAt) {
         await this.db.exec(`
       UPDATE "${this.tableName}" 
@@ -193,9 +293,12 @@ class ChangeTrackingTable extends orm_1.SQLDataSource {
         return record ? this.deserializeValue(record) : undefined;
     }
     /**
-     * Override to serialize value field to JSON string
+     * Insert a change row, assigning `appliedAt` from the local apply clock
+     * immediately before the SQL statement so watermarks stay monotonic.
      */
     async insert(record) {
+        await this.initTable();
+        record.appliedAt = this.appliedClock.tick();
         if (record.value !== undefined) {
             record.value = (0, serial_json_1.toJSONString)(record.value);
         }
@@ -216,8 +319,10 @@ class ChangeTrackingTable extends orm_1.SQLDataSource {
     /**
      * Synchronous insert for use within transactions.
      * Table must be initialized before calling this method.
+     * Assigns `appliedAt` from the local apply clock immediately before the SQL statement.
      */
     insertSync(record) {
+        record.appliedAt = this.appliedClock.tick();
         if (record.value !== undefined) {
             record = { ...record, value: (0, serial_json_1.toJSONString)(record.value) };
         }

package/dist/device/connection.js

@@ -4,9 +4,9 @@ exports.Connection = void 0;
 exports.normalizeAddress = normalizeAddress;
 const data_1 = require("../data");
 const keys_1 = require("../keys");
+const peer_device_1 = require("../types/peer-device");
 const utils_1 = require("../utils");
 const socket_type_1 = require("./socket.type");
-const HANDSHAKE_TIMESTAMP_TOLERANCE_MS = 300_000; // 5 minutes
 /** Authenticated RPC connection between two Peers devices. */
 class Connection {
     localDevice;
@@ -26,7 +26,7 @@ class Connection {
     onHandshakeComplete;
     timeoutMs = 60_000; // 60 seconds
     maxChunkSize = socket_type_1.DEFAULT_MAX_CHUNK_SIZE;
-    handshakeTimestampToleranceMs = HANDSHAKE_TIMESTAMP_TOLERANCE_MS;
+    handshakeTimestampToleranceMs = peer_device_1.PeerDeviceConsts.CLOCK_SKEW_TOLERANCE_MS;
     _connectionAddress;
     get connectionAddress() {
         return this._connectionAddress;

package/dist/hlc.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Options for {@link HybridLogicalClock}.
+ */
+export interface IHybridLogicalClockOptions {
+    /**
+     * Physical-time source in milliseconds. Defaults to {@link getTimestamp}
+     * so HLC ticks stay on the same clock as existing change-log rows and tests.
+     * (`Date.now` and `performance.timeOrigin + performance.now` drift apart
+     * in long-running processes.) Injected in tests to simulate clock skew.
+     */
+    now?: () => number;
+    /**
+     * Incoming timestamps more than this many ms ahead of {@link HybridLogicalClock.now}
+     * are ignored by {@link HybridLogicalClock.observe}. Defaults to
+     * {@link PeerDeviceConsts.CHANGE_TIMESTAMP_TOLERANCE_MS}.
+     */
+    maxSkewMs?: number;
+}
+/**
+ * Compact hybrid logical clock stored as a single millisecond number.
+ *
+ * `tick()` is `max(now(), last + 1)` so local timestamps stay close to wall time
+ * while remaining strictly monotonic even when the system clock jumps backward.
+ * `observe(ts)` raises `last` to a received timestamp so a later local tick
+ * always orders after a change this device has already seen.
+ */
+export declare class HybridLogicalClock {
+    private last;
+    private readonly getNow;
+    private readonly maxSkewMs;
+    /**
+     * @param opts - Optional physical-time source and observe-skew bound
+     */
+    constructor(opts?: IHybridLogicalClockOptions);
+    /**
+     * Current physical time from the injected `now` function. Does not advance the clock.
+     */
+    now(): number;
+    /**
+     * Last assigned or observed value, or `0` before the first tick/seed/observe.
+     */
+    get value(): number;
+    /**
+     * Assign the next timestamp: `last = max(now(), last + 1)`.
+     *
+     * @returns The newly assigned timestamp
+     */
+    tick(): number;
+    /**
+     * Incorporate a timestamp received from another device.
+     * Values that are not finite, or that exceed `now() + maxSkewMs`, are ignored
+     * so one misconfigured peer cannot push this clock into the far future.
+     *
+     * @param ts - Received timestamp
+     * @returns `true` if the clock absorbed `ts`
+     */
+    observe(ts: number): boolean;
+    /**
+     * Raise `last` to at least `ts` without consulting the skew bound.
+     * Used when seeding from durable local history on startup.
+     *
+     * @param ts - Known-good timestamp from local storage
+     */
+    seed(ts: number): void;
+}

package/dist/hlc.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HybridLogicalClock = void 0;
+const peer_device_1 = require("./types/peer-device");
+const utils_1 = require("./utils");
+/**
+ * Compact hybrid logical clock stored as a single millisecond number.
+ *
+ * `tick()` is `max(now(), last + 1)` so local timestamps stay close to wall time
+ * while remaining strictly monotonic even when the system clock jumps backward.
+ * `observe(ts)` raises `last` to a received timestamp so a later local tick
+ * always orders after a change this device has already seen.
+ */
+class HybridLogicalClock {
+    last = 0;
+    getNow;
+    maxSkewMs;
+    /**
+     * @param opts - Optional physical-time source and observe-skew bound
+     */
+    constructor(opts) {
+        this.getNow = opts?.now ?? utils_1.getTimestamp;
+        this.maxSkewMs = opts?.maxSkewMs ?? peer_device_1.PeerDeviceConsts.CHANGE_TIMESTAMP_TOLERANCE_MS;
+    }
+    /**
+     * Current physical time from the injected `now` function. Does not advance the clock.
+     */
+    now() {
+        return this.getNow();
+    }
+    /**
+     * Last assigned or observed value, or `0` before the first tick/seed/observe.
+     */
+    get value() {
+        return this.last;
+    }
+    /**
+     * Assign the next timestamp: `last = max(now(), last + 1)`.
+     *
+     * @returns The newly assigned timestamp
+     */
+    tick() {
+        this.last = Math.max(this.getNow(), this.last + 1);
+        return this.last;
+    }
+    /**
+     * Incorporate a timestamp received from another device.
+     * Values that are not finite, or that exceed `now() + maxSkewMs`, are ignored
+     * so one misconfigured peer cannot push this clock into the far future.
+     *
+     * @param ts - Received timestamp
+     * @returns `true` if the clock absorbed `ts`
+     */
+    observe(ts) {
+        if (!Number.isFinite(ts)) {
+            return false;
+        }
+        if (ts > this.getNow() + this.maxSkewMs) {
+            return false;
+        }
+        this.last = Math.max(this.last, ts);
+        return true;
+    }
+    /**
+     * Raise `last` to at least `ts` without consulting the skew bound.
+     * Used when seeding from durable local history on startup.
+     *
+     * @param ts - Known-good timestamp from local storage
+     */
+    seed(ts) {
+        if (!Number.isFinite(ts)) {
+            return;
+        }
+        this.last = Math.max(this.last, ts);
+    }
+}
+exports.HybridLogicalClock = HybridLogicalClock;

package/dist/hlc.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/hlc.test.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const hlc_1 = require("./hlc");
+const peer_device_1 = require("./types/peer-device");
+describe("HybridLogicalClock", () => {
+    it("is monotonic when now goes backward", () => {
+        let t = 1000;
+        const clock = new hlc_1.HybridLogicalClock({ now: () => t });
+        const first = clock.tick();
+        t = 100;
+        const second = clock.tick();
+        expect(second).toBe(first + 1);
+    });
+    it("advances by 1 on the same millisecond", () => {
+        const clock = new hlc_1.HybridLogicalClock({ now: () => 5000 });
+        expect(clock.tick()).toBe(5000);
+        expect(clock.tick()).toBe(5001);
+        expect(clock.tick()).toBe(5002);
+    });
+    it("observe advances last so the next tick is after the observed time", () => {
+        const clock = new hlc_1.HybridLogicalClock({ now: () => 1000 });
+        expect(clock.observe(2500)).toBe(true);
+        expect(clock.tick()).toBe(2501);
+    });
+    it("observe ignores timestamps beyond the skew bound", () => {
+        const now = 10_000;
+        const clock = new hlc_1.HybridLogicalClock({ now: () => now });
+        const future = now + peer_device_1.PeerDeviceConsts.CHANGE_TIMESTAMP_TOLERANCE_MS + 1;
+        expect(clock.observe(future)).toBe(false);
+        expect(clock.tick()).toBe(now);
+    });
+    it("seed raises last without going backward", () => {
+        const clock = new hlc_1.HybridLogicalClock({ now: () => 1000 });
+        clock.seed(2000);
+        clock.seed(1500);
+        expect(clock.tick()).toBe(2001);
+    });
+    it("now peeks physical time without advancing", () => {
+        const clock = new hlc_1.HybridLogicalClock({ now: () => 42 });
+        expect(clock.now()).toBe(42);
+        expect(clock.now()).toBe(42);
+        expect(clock.value).toBe(0);
+        expect(clock.tick()).toBe(42);
+    });
+});

package/dist/index.d.ts

@@ -16,6 +16,7 @@ export * from "./device/tx-encoding";
 export * from "./device-pairing";
 export * from "./events";
 export * from "./group-invite";
+export * from "./hlc";
 export * from "./keys";
 export * from "./logging";
 export * from "./mentions";

package/dist/index.js

@@ -37,6 +37,7 @@ __exportStar(require("./device/tx-encoding"), exports);
 __exportStar(require("./device-pairing"), exports);
 __exportStar(require("./events"), exports);
 __exportStar(require("./group-invite"), exports);
+__exportStar(require("./hlc"), exports);
 __exportStar(require("./keys"), exports);
 __exportStar(require("./logging"), exports);
 __exportStar(require("./mentions"), exports);

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

@@ -81,6 +81,14 @@ export declare const PeerDeviceConsts: Readonly<{
     readonly TIMEOUT_MIN: 3000;
     readonly TIMEOUT_MAX: 30000;
     readonly NETWORK_INFO_CACHE_TIME: 1000;
+    /** 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.
+     */
+    readonly CHANGE_TIMESTAMP_TOLERANCE_MS: 600000;
 }>;
 /** Availability and queue information for a requested file chunk. */
 export type IFileChunkInfo = {

package/dist/types/peer-device.js

@@ -13,4 +13,12 @@ exports.PeerDeviceConsts = Object.freeze({
     TIMEOUT_MIN: 3_000,
     TIMEOUT_MAX: 30_000,
     NETWORK_INFO_CACHE_TIME: 1000,
+    /** 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.
+     */
+    CHANGE_TIMESTAMP_TOLERANCE_MS: 600_000,
 });

package/package.json

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