@peers-app/peers-sdk 0.25.8 → 0.25.10

package/dist/data/sync-recovery-queue.js

@@ -5,7 +5,9 @@
  * separately in ChangeTrackingV2.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SyncRecoveryQueueTable = exports.syncRecoveryQueueMetaData = exports.syncRecoveryEntrySchema = exports.syncRecoveryFailureSchema = void 0;
+exports.SyncRecoveryQueueTable = exports.syncRecoveryQueueMetaData = exports.syncRecoveryEntrySchema = exports.syncRecoveryFailureSchema = exports.syncRecoveryParkedReasons = exports.SYNC_RECOVERY_STUCK_AGE_MS = exports.SYNC_RECOVERY_STUCK_ATTEMPTS = void 0;
+exports.isStuckSyncRecoveryEntry = isStuckSyncRecoveryEntry;
+exports.nextStuckSyncRecoveryAt = nextStuckSyncRecoveryAt;
 exports.syncRecoveryQueueTable = syncRecoveryQueueTable;
 const zod_1 = require("zod");
 const zod_types_1 = require("../types/zod-types");
@@ -13,6 +15,12 @@ const utils_1 = require("../utils");
 const orm_1 = require("./orm");
 const MAX_FAILURE_HISTORY = 10;
 const MAX_ERROR_LENGTH = 1_000;
+/** How many attempts mark a still-retrying entry as stuck. */
+exports.SYNC_RECOVERY_STUCK_ATTEMPTS = 5;
+/** How long a still-retrying entry must have been failing before it is stuck. */
+exports.SYNC_RECOVERY_STUCK_AGE_MS = 10 * 60 * 1000;
+/** Why automatic recovery stopped asking peers for an entry. */
+exports.syncRecoveryParkedReasons = ["schema", "unique-conflict", "unresolvable"];
 /** One recorded materialization failure for a synchronized record. */
 exports.syncRecoveryFailureSchema = zod_1.z.object({
     error: zod_1.z.string(),
@@ -28,7 +36,50 @@ exports.syncRecoveryEntrySchema = zod_1.z.object({
     lastFailedAt: zod_1.z.number(),
     attemptCount: zod_1.z.number(),
     failures: zod_1.z.array(exports.syncRecoveryFailureSchema),
+    /** Set when peer retry has stopped. Absent while the entry is still retrying. */
+    parkedAt: zod_1.z.number().optional(),
+    parkedReason: zod_1.z.enum(exports.syncRecoveryParkedReasons).optional(),
+    /** Earliest time a retrying entry should ask peers again. */
+    nextAttemptAt: zod_1.z.number().optional(),
+    /**
+     * How many due peer sweeps have failed to clear this entry.
+     * Local only. Backoff uses this instead of the materialization attempt count.
+     */
+    sweepCount: zod_1.z.number().optional(),
 });
+/**
+ * True when an operator should look at this entry.
+ *
+ * Parked entries are stuck immediately. Retrying entries are stuck after
+ * {@link SYNC_RECOVERY_STUCK_ATTEMPTS} attempts spanning {@link SYNC_RECOVERY_STUCK_AGE_MS}.
+ */
+function isStuckSyncRecoveryEntry(entry, now = Date.now()) {
+    if (entry.parkedAt != null) {
+        return true;
+    }
+    return (entry.attemptCount >= exports.SYNC_RECOVERY_STUCK_ATTEMPTS &&
+        now - entry.firstFailedAt >= exports.SYNC_RECOVERY_STUCK_AGE_MS);
+}
+/**
+ * When the earliest not-yet-stuck entry will cross the stuck age, if any will.
+ *
+ * Parked entries are already stuck. Entries below {@link SYNC_RECOVERY_STUCK_ATTEMPTS}
+ * do not become stuck by time alone.
+ */
+function nextStuckSyncRecoveryAt(entries, now = Date.now()) {
+    let earliest;
+    for (const entry of entries) {
+        if (entry.parkedAt != null || entry.attemptCount < exports.SYNC_RECOVERY_STUCK_ATTEMPTS) {
+            continue;
+        }
+        const due = entry.firstFailedAt + exports.SYNC_RECOVERY_STUCK_AGE_MS;
+        if (due <= now) {
+            continue;
+        }
+        earliest = earliest == null ? due : Math.min(earliest, due);
+    }
+    return earliest;
+}
 /** Metadata for the local-only SyncRecoveryQueue table. */
 exports.syncRecoveryQueueMetaData = {
     name: "SyncRecoveryQueue",
@@ -114,6 +165,22 @@ class SyncRecoveryQueueTable extends orm_1.SQLDataSource {
             recordId,
         ]);
     }
+    /**
+     * Delete one queue row only when its attempt count still matches.
+     *
+     * A failure recorded after the caller chose this generation changes
+     * `attemptCount`, so the delete matches nothing and throws. Call this inside
+     * the same transaction as the table write so that throw rolls the write back.
+     */
+    clearGenerationSync(syncRecoveryId, attemptCount) {
+        if (!this.db.execSync) {
+            throw new Error("Synchronous database operations are required for recovery queue updates");
+        }
+        const result = this.db.execSync(`DELETE FROM "${this.tableName}" WHERE syncRecoveryId = ? AND attemptCount = ?`, [syncRecoveryId, attemptCount]);
+        if (result.changes !== 1) {
+            throw new Error("Recovery entry changed");
+        }
+    }
     mergeFailure(existing, input) {
         const erroredAt = (0, utils_1.getTimestamp)();
         const failure = {
@@ -129,8 +196,68 @@ class SyncRecoveryQueueTable extends orm_1.SQLDataSource {
             lastFailedAt: erroredAt,
             attemptCount: (existing?.attemptCount ?? 0) + 1,
             failures: [...(existing?.failures ?? []), failure].slice(-MAX_FAILURE_HISTORY),
+            parkedAt: existing?.parkedAt,
+            parkedReason: existing?.parkedReason,
+            nextAttemptAt: existing?.nextAttemptAt,
         };
     }
+    /**
+     * Stop peer retry for an entry without removing it.
+     *
+     * Writes only the park columns. A failure recorded in the same window keeps
+     * its attempt count and history. Parking the same reason again keeps the
+     * original `parkedAt`.
+     */
+    async park(tableName, recordId, reason) {
+        await this.patchEntry(`UPDATE "${this.tableName}"
+       SET parkedAt = COALESCE(parkedAt, ?), parkedReason = ?
+       WHERE tableName = ? AND recordId = ? AND IFNULL(parkedReason, '') != ?`, [(0, utils_1.getTimestamp)(), reason, tableName, recordId, reason]);
+    }
+    /**
+     * Return an entry to peer retry.
+     *
+     * Clears only the park marker and any scheduled next attempt.
+     */
+    async unpark(tableName, recordId) {
+        await this.patchEntry(`UPDATE "${this.tableName}"
+       SET parkedAt = NULL, parkedReason = NULL, nextAttemptAt = NULL
+       WHERE tableName = ? AND recordId = ?`, [tableName, recordId]);
+    }
+    /**
+     * Schedule the next peer retry for an entry that is still queued.
+     *
+     * Writes only `nextAttemptAt`.
+     */
+    async setNextAttempt(tableName, recordId, nextAttemptAt) {
+        await this.patchEntry(`UPDATE "${this.tableName}"
+       SET nextAttemptAt = ?
+       WHERE tableName = ? AND recordId = ?`, [nextAttemptAt, tableName, recordId]);
+    }
+    /**
+     * Count one due peer sweep that did not clear the entry.
+     *
+     * Writes only `sweepCount` and returns the new value. Returns undefined when
+     * the row was removed before the update.
+     */
+    async noteUnresolvedSweep(tableName, recordId) {
+        await this.patchEntry(`UPDATE "${this.tableName}"
+       SET sweepCount = IFNULL(sweepCount, 0) + 1
+       WHERE tableName = ? AND recordId = ?`, [tableName, recordId]);
+        const entry = await this.findOne({ tableName, recordId });
+        return entry?.sweepCount;
+    }
+    /** Apply a column-level update without rewriting the rest of the queue row. */
+    async patchEntry(sql, params) {
+        await this.initTable();
+        if (this.db.runInTransaction && this.db.execSync) {
+            const execSync = this.db.execSync.bind(this.db);
+            this.db.runInTransaction(() => {
+                execSync(sql, params);
+            });
+            return;
+        }
+        await this.db.exec(sql, params);
+    }
 }
 exports.SyncRecoveryQueueTable = SyncRecoveryQueueTable;
 const recoveryQueuesByDb = new WeakMap();

package/dist/data/sync-recovery-queue.test.js

@@ -21,7 +21,8 @@ class DBHarness {
         return this.sqlite.prepare(sql).all(params);
     }
     execSync(sql, params = []) {
-        this.sqlite.prepare(sql).run(params);
+        const result = this.sqlite.prepare(sql).run(params);
+        return { changes: result.changes };
     }
     runInTransaction(fn) {
         return this.sqlite.transaction(fn)();
@@ -135,4 +136,80 @@ describe("SyncRecoveryQueueTable", () => {
         db.runInTransaction(() => queue.clearRecordSync("Notes", "note-1"));
         await expect(queue.count()).resolves.toBe(0);
     });
+    it("parks, unparks, and schedules the next attempt without dropping the entry", async () => {
+        await queue.recordFailure({
+            tableName: "Notes",
+            recordId: "note-1",
+            error: new Error("Validation on insert failed"),
+        });
+        await queue.park("Notes", "note-1", "schema");
+        await queue.park("Notes", "note-1", "schema");
+        const parked = await queue.findOne({ tableName: "Notes", recordId: "note-1" });
+        expect(parked?.parkedReason).toBe("schema");
+        expect(parked?.parkedAt).toEqual(expect.any(Number));
+        await queue.recordFailure({
+            tableName: "Notes",
+            recordId: "note-1",
+            error: new Error("Validation on insert failed again"),
+        });
+        const afterFailure = await queue.findOne({ tableName: "Notes", recordId: "note-1" });
+        expect(afterFailure).toMatchObject({
+            parkedReason: "schema",
+            parkedAt: parked?.parkedAt,
+            attemptCount: 2,
+        });
+        await queue.setNextAttempt("Notes", "note-1", 50);
+        await queue.unpark("Notes", "note-1");
+        const unparked = await queue.findOne({ tableName: "Notes", recordId: "note-1" });
+        expect(unparked?.parkedAt).toBeUndefined();
+        expect(unparked?.parkedReason).toBeUndefined();
+        expect(unparked?.nextAttemptAt).toBeUndefined();
+        await expect(queue.count()).resolves.toBe(1);
+    });
+    it("keeps attempt history when a failure is recorded during park", async () => {
+        await queue.recordFailure({
+            tableName: "Notes",
+            recordId: "note-1",
+            error: new Error("first"),
+        });
+        const originalExecSync = db.execSync.bind(db);
+        let injected = false;
+        db.execSync = (sql, params) => {
+            if (!injected && String(sql).includes("COALESCE(parkedAt")) {
+                injected = true;
+                queue.recordFailureSync({
+                    tableName: "Notes",
+                    recordId: "note-1",
+                    error: new Error("second"),
+                });
+            }
+            return originalExecSync(sql, params);
+        };
+        await queue.park("Notes", "note-1", "schema");
+        const entry = await queue.findOne({ tableName: "Notes", recordId: "note-1" });
+        expect(entry?.attemptCount).toBe(2);
+        expect(entry?.failures.map((failure) => failure.error)).toEqual(["first", "second"]);
+        expect(entry?.parkedReason).toBe("schema");
+        expect(entry?.parkedAt).toEqual(expect.any(Number));
+        db.execSync = originalExecSync;
+    });
+    it("reports the earliest future stuck transition", () => {
+        const now = 1_000_000;
+        const due = now - sync_recovery_queue_1.SYNC_RECOVERY_STUCK_AGE_MS + 5_000;
+        expect((0, sync_recovery_queue_1.nextStuckSyncRecoveryAt)([
+            {
+                parkedAt: now,
+                attemptCount: sync_recovery_queue_1.SYNC_RECOVERY_STUCK_ATTEMPTS,
+                firstFailedAt: now - sync_recovery_queue_1.SYNC_RECOVERY_STUCK_AGE_MS,
+            },
+            {
+                attemptCount: sync_recovery_queue_1.SYNC_RECOVERY_STUCK_ATTEMPTS - 1,
+                firstFailedAt: now - sync_recovery_queue_1.SYNC_RECOVERY_STUCK_AGE_MS,
+            },
+            {
+                attemptCount: sync_recovery_queue_1.SYNC_RECOVERY_STUCK_ATTEMPTS,
+                firstFailedAt: due,
+            },
+        ], now)).toBe(due + sync_recovery_queue_1.SYNC_RECOVERY_STUCK_AGE_MS);
+    });
 });

package/dist/rpc-types.d.ts

@@ -93,9 +93,6 @@ export declare const rpcServerCalls: {
         mimeType?: string;
     }>;
     injectUIBundle: (uiBundleFileId: string) => Promise<void>;
-    resetAllDeviceSyncInfo: () => Promise<void>;
-    /** Clear change tracking and rebuild from current rows for the default data context (same as Data Explorer). */
-    resetChangeTracking: () => Promise<void>;
     deleteLocalDatabase: () => Promise<void>;
     /** Returns info about the pre-migration data directory, or `null` if already cleaned up. */
     getOldDataDirInfo: () => Promise<{

package/dist/rpc-types.js

@@ -36,9 +36,6 @@ exports.rpcServerCalls = {
     saveFile: rpcStub("saveFile"),
     // Inject UI bundle directly into WebView (bypasses slow postMessage for large strings)
     injectUIBundle: rpcStub("injectUIBundle"),
-    resetAllDeviceSyncInfo: rpcStub("resetAllDeviceSyncInfo"),
-    /** Clear change tracking and rebuild from current rows for the default data context (same as Data Explorer). */
-    resetChangeTracking: rpcStub("resetChangeTracking"),
     deleteLocalDatabase: rpcStub("deleteLocalDatabase"),
     /** Returns info about the pre-migration data directory, or `null` if already cleaned up. */
     getOldDataDirInfo: rpcStub("getOldDataDirInfo"),

package/dist/system-ids.d.ts

@@ -93,3 +93,25 @@ export declare const identityToolIds: {
     readonly signOut: "00muc9mlzxwdm2yj5p5wkjvz7";
     readonly registerWithPeersServices: "00muc9mlzx07q98l3f9x49o10";
 };
+/**
+ * Contract id for the local-only System Local Folders surface (`system.fs`).
+ * Scoped folder grants, directory listing, and host-side indexing. Not available
+ * over device-to-device connections; block exchange is a separate path.
+ */
+export declare const localFoldersContractId = "00mukk9dwb1mjtd845kftuazm";
+/** Stable IDs for tools in System Local Folders v1. */
+export declare const localFoldersToolIds: {
+    readonly requestGrant: "00mukk9dwdcv4f99ydwxao97f";
+    readonly listGrants: "00mukk9dwdq119xmvz4ap8aum";
+    readonly revokeGrant: "00mukk9dwdezt5sbjviq1n1sp";
+    readonly list: "00mukk9dwd6mxscrv9eeaanai";
+    readonly stat: "00mukk9dwdon2y2487clcg67k";
+    readonly readRange: "00mukk9dwdih6mh8rrofph80o";
+    readonly index: "00mukk9dwdm01bxg3hrby6pli";
+    readonly getFileBlocks: "00mumw1pmmf3y2ujfdc99h4ib";
+    readonly getJob: "00mukk9dwd1c1f51xjysssgtv";
+    readonly cancelJob: "00mukk9dweizvif4ghp6kfa92";
+    readonly move: "00mukk9dwer8wsw5eiwis8tzm";
+    readonly trash: "00mukk9dwejbuehqzszpyxefx";
+    readonly purgeTrash: "00mukk9dwe6co8gvuy44kmuzd";
+};

package/dist/system-ids.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.identityToolIds = exports.identityContractId = exports.invitesToolIds = exports.invitesContractId = exports.toolAccessControlToolIds = exports.toolAccessControlContractId = exports.networkControlContractId = exports.networkDiagnosticsContractId = exports.deviceOperationsContractId = exports.logsContractId = exports.peersSystemPackageId = exports.peersCorePublishPublicKey = exports.peersCorePackageRepoUrl = exports.peersCorePackageId = exports.createGroupToolId = exports.queryDatabaseToolId = exports.runWorkflowToolId = exports.defaultSendMessageToolId = exports.defaultAssistantRunnerToolId = exports.adminAssistantId = exports.openCodeAssistantId = exports.defaultAssistantId = exports.peersRootUserId = void 0;
+exports.localFoldersToolIds = exports.localFoldersContractId = exports.identityToolIds = exports.identityContractId = exports.invitesToolIds = exports.invitesContractId = exports.toolAccessControlToolIds = exports.toolAccessControlContractId = exports.networkControlContractId = exports.networkDiagnosticsContractId = exports.deviceOperationsContractId = exports.logsContractId = exports.peersSystemPackageId = exports.peersCorePublishPublicKey = exports.peersCorePackageRepoUrl = exports.peersCorePackageId = exports.createGroupToolId = exports.queryDatabaseToolId = exports.runWorkflowToolId = exports.defaultSendMessageToolId = exports.defaultAssistantRunnerToolId = exports.adminAssistantId = exports.openCodeAssistantId = exports.defaultAssistantId = exports.peersRootUserId = void 0;
 /** Stable user ID that owns built-in Peers system records. */
 exports.peersRootUserId = "000peers0user000000000001";
 /** Default assistant used when no user-selected assistant is available. */
@@ -97,3 +97,25 @@ exports.identityToolIds = {
     signOut: "00muc9mlzxwdm2yj5p5wkjvz7",
     registerWithPeersServices: "00muc9mlzx07q98l3f9x49o10",
 };
+/**
+ * Contract id for the local-only System Local Folders surface (`system.fs`).
+ * Scoped folder grants, directory listing, and host-side indexing. Not available
+ * over device-to-device connections; block exchange is a separate path.
+ */
+exports.localFoldersContractId = "00mukk9dwb1mjtd845kftuazm";
+/** Stable IDs for tools in System Local Folders v1. */
+exports.localFoldersToolIds = {
+    requestGrant: "00mukk9dwdcv4f99ydwxao97f",
+    listGrants: "00mukk9dwdq119xmvz4ap8aum",
+    revokeGrant: "00mukk9dwdezt5sbjviq1n1sp",
+    list: "00mukk9dwd6mxscrv9eeaanai",
+    stat: "00mukk9dwdon2y2487clcg67k",
+    readRange: "00mukk9dwdih6mh8rrofph80o",
+    index: "00mukk9dwdm01bxg3hrby6pli",
+    getFileBlocks: "00mumw1pmmf3y2ujfdc99h4ib",
+    getJob: "00mukk9dwd1c1f51xjysssgtv",
+    cancelJob: "00mukk9dweizvif4ghp6kfa92",
+    move: "00mukk9dwer8wsw5eiwis8tzm",
+    trash: "00mukk9dwejbuehqzszpyxefx",
+    purgeTrash: "00mukk9dwe6co8gvuy44kmuzd",
+};

package/package.json

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