@peers-app/peers-sdk 0.25.8 → 0.25.9

package/dist/contracts/system/network-contracts.d.ts

@@ -17,6 +17,7 @@ export declare const networkDiagnosticsToolIds: {
     readonly getGroupDetails: "00ms1yb50yuru8h1fg4t9na3e";
     readonly getDisconnectedDevices: "00ms1yb50y3jpoby5zomltahr";
     readonly queryRemoteLogs: "00ms1yb50y2fbfnth22yz52eu";
+    readonly getSyncRecoveryEntries: "00mujw2tgbpoohxvwd23u9moz";
 };
 /** Stable IDs for tools in System Network Control v1. */
 export declare const networkControlToolIds: {
@@ -26,6 +27,9 @@ export declare const networkControlToolIds: {
     readonly deleteDevice: "00ms1yb50y5mc448nuavlex86";
     readonly syncGroupNow: "00ms1yb50ylnqlra26jx232py";
     readonly resetChangeTracking: "00ms1yb50yfuackpl1w37hmxc";
+    readonly retrySyncRecovery: "00mujw2tgcelvpg556n836ah7";
+    readonly resolveSyncRecovery: "00mujw2tgciywn8krykc6gmwx";
+    readonly resetDeviceSyncInfo: "00mujw2tgc5lrezqrw4oneaot";
 };
 /** Overall status shown by the shell's compact network indicator. */
 export type NetworkStatusState = "offline" | "syncing" | "synced" | "error";
@@ -51,6 +55,11 @@ export interface INetworkStatusSummary {
     disconnectedContextCount: number;
     /** Sync contexts that currently have at least one live SyncGroup connection. */
     connectedContextCount: number;
+    /**
+     * Recovery-queue entries that are parked or have been retrying long enough
+     * that an operator should look at them. Zero means the indicator stays green.
+     */
+    stuckRecoveryCount: number;
     lastSuccessfulSyncAt?: number;
     errors: INetworkSyncError[];
 }
@@ -176,6 +185,56 @@ export interface INetworkControlResult {
     success: boolean;
     message: string;
 }
+/** How an operator resolves one stuck recovery-queue entry. */
+export type SyncRecoveryResolution = "keepLocal" | "deleteEverywhere" | "ignoreLocal";
+/** One recovery-queue entry prepared for the Sync Recovery screen. */
+export interface INetworkSyncRecoveryEntry {
+    dataContextId: string;
+    dataContextName: string;
+    syncRecoveryId: string;
+    tableName: string;
+    recordId: string;
+    firstFailedAt: number;
+    lastFailedAt: number;
+    attemptCount: number;
+    latestError: string;
+    status: "retrying" | "parked";
+    parkedReason?: "schema" | "unique-conflict" | "unresolvable";
+    stuck: boolean;
+    /** True when this device has a row that "Keep this device's version" can snapshot. */
+    localRowExists: boolean;
+    /** Other record id holding the same unique key, when the failure is a unique conflict. */
+    conflictingRecordId?: string;
+    /**
+     * Record id Keep will tombstone.
+     * The other stored row when both exist, or this queued id when only the other row is stored.
+     */
+    tombstoneRecordId?: string;
+    /**
+     * Short label taken from the row Keep will snapshot, or from queued history when nothing is stored.
+     */
+    recordSummary?: string;
+    /**
+     * Pretty-printed row Keep will snapshot, with secret values hidden.
+     * Dates and other special values use the change-history encoding (`__DATE`, and so on).
+     */
+    keptRecordPreview?: string;
+    /**
+     * Pretty-printed queued history when it differs from {@link keptRecordPreview}.
+     * Uses the same secret hiding and change-history encoding.
+     */
+    queuedRecordPreview?: string;
+    /**
+     * Pretty-printed stored record, with secret values hidden.
+     * Prefers the row Keep will snapshot, then queued history.
+     */
+    recordPreview?: string;
+    /**
+     * Author time of the change-tracking row that failed to materialize.
+     * Hybrid-logical-clock milliseconds. Omitted when no change row is stored.
+     */
+    changeCreatedAt?: number;
+}
 /** Typed consumer proxy for System Network Diagnostics v1. */
 export interface INetworkDiagnosticsConsumer extends IContractConsumerBase {
     tools: {
@@ -207,6 +266,11 @@ export interface INetworkDiagnosticsConsumer extends IContractConsumerBase {
             deviceId: string;
             query?: INetworkRemoteLogsQuery;
         }): Promise<INetworkRemoteLogsResult>;
+        getSyncRecoveryEntries(input?: {
+            dataContextId?: string;
+        }): Promise<{
+            entries: INetworkSyncRecoveryEntry[];
+        }>;
     };
     observables: {
         status: Observable<INetworkStatusSummary>;
@@ -228,8 +292,24 @@ export interface INetworkControlConsumer extends IContractConsumerBase {
         syncGroupNow(input: {
             groupId: string;
         }): Promise<INetworkControlResult>;
-        resetChangeTracking(input: {
+        resetChangeTracking(input?: {
+            dataContextId?: string;
+        }): Promise<INetworkControlResult>;
+        resetDeviceSyncInfo(input?: {
+            dataContextId?: string;
+        }): Promise<INetworkControlResult>;
+        retrySyncRecovery(input: {
+            dataContextId: string;
+            tableName?: string;
+            recordId?: string;
+            syncRecoveryId?: string;
+        }): Promise<INetworkControlResult>;
+        resolveSyncRecovery(input: {
             dataContextId: string;
+            tableName: string;
+            recordId: string;
+            resolution: SyncRecoveryResolution;
+            syncRecoveryId?: string;
         }): Promise<INetworkControlResult>;
     };
 }

package/dist/contracts/system/network-contracts.js

@@ -19,6 +19,7 @@ exports.networkDiagnosticsToolIds = {
     getGroupDetails: "00ms1yb50yuru8h1fg4t9na3e",
     getDisconnectedDevices: "00ms1yb50y3jpoby5zomltahr",
     queryRemoteLogs: "00ms1yb50y2fbfnth22yz52eu",
+    getSyncRecoveryEntries: "00mujw2tgbpoohxvwd23u9moz",
 };
 /** Stable IDs for tools in System Network Control v1. */
 exports.networkControlToolIds = {
@@ -28,6 +29,9 @@ exports.networkControlToolIds = {
     deleteDevice: "00ms1yb50y5mc448nuavlex86",
     syncGroupNow: "00ms1yb50ylnqlra26jx232py",
     resetChangeTracking: "00ms1yb50yfuackpl1w37hmxc",
+    retrySyncRecovery: "00mujw2tgcelvpg556n836ah7",
+    resolveSyncRecovery: "00mujw2tgciywn8krykc6gmwx",
+    resetDeviceSyncInfo: "00mujw2tgc5lrezqrw4oneaot",
 };
 const field = (name, type, description, opts = {}) => ({ name, type, description, ...opts });
 let diagnosticsDefinition;
@@ -106,6 +110,18 @@ function getNetworkDiagnosticsContractDefinition() {
                     field("queriedAt", field_type_1.FieldType.number, "Local completion timestamp."),
                 ],
             },
+            {
+                name: "getSyncRecoveryEntries",
+                usageDescription: "List records whose synchronized changes could not be materialized.",
+                inputFields: [
+                    field("dataContextId", field_type_1.FieldType.id, "Optional personal or group context ID.", {
+                        optional: true,
+                    }),
+                ],
+                outputFields: [
+                    field("entries", field_type_1.FieldType.object, "Recovery queue entries.", { isArray: true }),
+                ],
+            },
         ],
         observables: [
             {
@@ -166,9 +182,46 @@ function getNetworkControlContractDefinition() {
             },
             {
                 name: "resetChangeTracking",
-                usageDescription: "Reset one data context's change tracking for an expensive full sync.",
+                usageDescription: "Reset change tracking for one data context, or every local context when omitted.",
+                inputFields: [
+                    field("dataContextId", field_type_1.FieldType.id, "Personal or group context ID to reset.", {
+                        optional: true,
+                    }),
+                ],
+                outputFields: resultFields,
+            },
+            {
+                name: "resetDeviceSyncInfo",
+                usageDescription: "Clear device sync checkpoints for one data context, or every local context when omitted.",
+                inputFields: [
+                    field("dataContextId", field_type_1.FieldType.id, "Personal or group context ID to reset.", {
+                        optional: true,
+                    }),
+                ],
+                outputFields: resultFields,
+            },
+            {
+                name: "retrySyncRecovery",
+                usageDescription: "Retry one recovery entry, or every entry in a data context.",
+                inputFields: [
+                    field("dataContextId", field_type_1.FieldType.id, "Personal or group context ID."),
+                    field("tableName", field_type_1.FieldType.string, "Table of one entry to retry.", { optional: true }),
+                    field("recordId", field_type_1.FieldType.string, "Record id of one entry to retry.", {
+                        optional: true,
+                    }),
+                    field("syncRecoveryId", field_type_1.FieldType.id, "Queue row to retry. When set, a replaced row is not retried.", { optional: true }),
+                ],
+                outputFields: resultFields,
+            },
+            {
+                name: "resolveSyncRecovery",
+                usageDescription: "Resolve one recovery entry by snapshotting this device, tombstoning the record, or ignoring it locally.",
                 inputFields: [
-                    field("dataContextId", field_type_1.FieldType.id, "Personal or group context ID to reset."),
+                    field("dataContextId", field_type_1.FieldType.id, "Personal or group context ID."),
+                    field("tableName", field_type_1.FieldType.string, "Table of the queued record."),
+                    field("recordId", field_type_1.FieldType.string, "Record id of the queued record."),
+                    field("resolution", field_type_1.FieldType.string, "keepLocal, deleteEverywhere, or ignoreLocal."),
+                    field("syncRecoveryId", field_type_1.FieldType.id, "Queue row to resolve. When set, a replaced row is left unchanged.", { optional: true }),
                 ],
                 outputFields: resultFields,
             },

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

@@ -133,6 +133,11 @@ export declare class ChangeTrackingTable extends SQLDataSource<IChangeRecord> {
      * than `supersededAt`. Used after a root snapshot, delete, or restore.
      */
     markAllPriorChangesSuperseded(tableName: string, recordId: string, supersededAt: number): Promise<void>;
+    /**
+     * Synchronous form of {@link markAllPriorChangesSuperseded} for an open
+     * writer transaction. The table must already be initialized.
+     */
+    markAllPriorChangesSupersededSync(tableName: string, recordId: string, supersededAt: number): void;
     /**
      * Batch update supersededAt timestamps for multiple changes.
      * More efficient than updating one at a time.

package/dist/data/change-tracking.js

@@ -236,6 +236,24 @@ class ChangeTrackingTable extends orm_1.SQLDataSource {
         supersededAt IS NULL 
     `, { tableName, recordId, supersededAt });
     }
+    /**
+     * Synchronous form of {@link markAllPriorChangesSuperseded} for an open
+     * writer transaction. The table must already be initialized.
+     */
+    markAllPriorChangesSupersededSync(tableName, recordId, supersededAt) {
+        if (!this.db.execSync) {
+            throw new Error("Recovery writes require a synchronous database");
+        }
+        this.db.execSync(`
+      UPDATE "${this.tableName}"
+      SET supersededAt = $supersededAt
+      WHERE
+        tableName = $tableName AND
+        recordId = $recordId AND
+        createdAt < $supersededAt AND
+        supersededAt IS NULL
+    `, { tableName, recordId, supersededAt });
+    }
     /**
      * Batch update supersededAt timestamps for multiple changes.
      * More efficient than updating one at a time.

package/dist/data/orm/sql-db.d.ts

@@ -5,7 +5,9 @@ export interface ISqlDb {
         changes: number;
     }>;
     close: () => Promise<void>;
-    execSync?: (sql: string, params?: any) => void;
+    execSync?: (sql: string, params?: any) => {
+        changes: number;
+    };
     getSync?: (sql: string, params?: any) => any;
     allSync?: (sql: string, params?: any) => any[];
     /**

package/dist/data/orm/table.d.ts

@@ -4,6 +4,13 @@ import { type DataFilter, type ICursorIterable, type IDataQueryParams, type IDat
 import { type IDataChangedEvent } from "./subscribable.data-source";
 import type { ITableDependencies } from "./table-dependencies";
 import { type ITableMetaData } from "./types";
+/**
+ * ORM table over a data source, including change notifications and validation.
+ *
+ * Subclasses override {@link Table.resolveUniqueConflict} when a unique index can be
+ * settled from the two competing records alone. The base implementation declines so
+ * sync leaves the conflict queued instead of deleting either row.
+ */
 export declare class Table<T extends {
     [key: string]: any;
 }> implements IDataSource<T> {
@@ -37,7 +44,19 @@ export declare class Table<T extends {
     update(record: T): Promise<T>;
     delete(idOrRecord: string | T): Promise<void>;
     initRecord(data?: Partial<T>): T;
+    /**
+     * Choose which record should own a contested unique key.
+     *
+     * Return undefined to leave the conflict queued for an operator. Overrides must be a
+     * pure function of the two records so every device computes the same winner.
+     * `loserId` is the primary key of the record that should be tombstoned.
+     */
+    resolveUniqueConflict(_incoming: T, _existing: T): {
+        winner: T;
+        loserId: string;
+    } | undefined;
     initDoc(record: T): import("./doc").IDoc<T>;
     getDoc(id: string): import("./doc").IDoc<T>;
 }
+/** Bootstrap icon class for a table, falling back to a question mark. */
 export declare function getIconClassName(table: Table<any>): string;

package/dist/data/orm/table.js

@@ -13,6 +13,13 @@ const doc_1 = require("./doc");
 const sql_data_source_1 = require("./sql.data-source");
 const subscribable_data_source_1 = require("./subscribable.data-source");
 const types_1 = require("./types");
+/**
+ * ORM table over a data source, including change notifications and validation.
+ *
+ * Subclasses override {@link Table.resolveUniqueConflict} when a unique index can be
+ * settled from the two competing records alone. The base implementation declines so
+ * sync leaves the conflict queued instead of deleting either row.
+ */
 class Table {
     tableName;
     primaryKeyName;
@@ -241,6 +248,16 @@ class Table {
         }
         return { ...defaults, ...data };
     }
+    /**
+     * Choose which record should own a contested unique key.
+     *
+     * Return undefined to leave the conflict queued for an operator. Overrides must be a
+     * pure function of the two records so every device computes the same winner.
+     * `loserId` is the primary key of the record that should be tombstoned.
+     */
+    resolveUniqueConflict(_incoming, _existing) {
+        return undefined;
+    }
     initDoc(record) {
         return (0, doc_1.initDoc)(record, this);
     }
@@ -252,6 +269,7 @@ class Table {
     }
 }
 exports.Table = Table;
+/** Bootstrap icon class for a table, falling back to a question mark. */
 function getIconClassName(table) {
     return table.metaData.iconClassName ?? "bi bi-question";
 }

package/dist/data/persistent-vars.conflict.test.d.ts

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

package/dist/data/persistent-vars.conflict.test.js

@@ -0,0 +1,126 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const originalClientFlag = process.env.PEERS_IS_CLIENT;
+function createEventRegistry() {
+    return {
+        getEmitter: jest.fn().mockReturnValue({
+            event: { subscribe: jest.fn() },
+            emit: jest.fn(),
+        }),
+    };
+}
+function pvar(overrides) {
+    return {
+        name: "shared-name",
+        scope: "user",
+        value: { value: overrides.persistentVarId },
+        ...overrides,
+    };
+}
+afterEach(() => {
+    if (originalClientFlag === undefined) {
+        delete process.env.PEERS_IS_CLIENT;
+    }
+    else {
+        process.env.PEERS_IS_CLIENT = originalClientFlag;
+    }
+    jest.resetModules();
+});
+describe("PersistentVars unique-name conflict", () => {
+    async function table() {
+        delete process.env.PEERS_IS_CLIENT;
+        jest.resetModules();
+        let loaded;
+        await jest.isolateModulesAsync(async () => {
+            jest.doMock("../context/user-context-singleton", () => ({
+                getTableContainer: jest.fn(),
+                getUserContext: jest.fn(),
+            }));
+            const { PersistentVarsTable, persistentVarsMetaData } = await Promise.resolve().then(() => require("./persistent-vars"));
+            const { deterministicPvarId } = await Promise.resolve().then(() => require("../utils"));
+            loaded = {
+                deterministicPvarId,
+                vars: new PersistentVarsTable(persistentVarsMetaData, {
+                    dataSource: {},
+                    eventRegistry: createEventRegistry(),
+                }),
+            };
+        });
+        if (!loaded) {
+            throw new Error("PersistentVarsTable failed to load");
+        }
+        return loaded;
+    }
+    it("keeps the deterministic id and the newer value regardless of argument order", async () => {
+        const { deterministicPvarId, vars } = await table();
+        const legacy = pvar({
+            persistentVarId: "00mriijkhq94msfe9m2j6quwp",
+            value: { value: "from-legacy" },
+            modifiedAt: 20,
+            scope: "groupUser",
+            isSecret: true,
+        });
+        const deterministic = pvar({
+            persistentVarId: deterministicPvarId(legacy.name),
+            value: { value: "from-deterministic" },
+            modifiedAt: 10,
+        });
+        const forward = vars.resolveUniqueConflict(legacy, deterministic);
+        const reverse = vars.resolveUniqueConflict(deterministic, legacy);
+        expect(forward).toEqual(reverse);
+        expect(forward).toEqual({
+            loserId: legacy.persistentVarId,
+            winner: expect.objectContaining({
+                persistentVarId: deterministic.persistentVarId,
+                name: legacy.name,
+                scope: "groupUser",
+                isSecret: true,
+                value: { value: "from-legacy" },
+                modifiedAt: 20,
+            }),
+        });
+    });
+    it("keeps the identity winner's value when modifiedAt ties", async () => {
+        const { deterministicPvarId, vars } = await table();
+        const legacy = pvar({
+            persistentVarId: "00mriijkhq94msfe9m2j6quwp",
+            value: { value: "legacy-value" },
+            modifiedAt: 5,
+        });
+        const deterministic = pvar({
+            persistentVarId: deterministicPvarId(legacy.name),
+            value: { value: "deterministic-value" },
+            modifiedAt: 5,
+        });
+        expect(vars.resolveUniqueConflict(legacy, deterministic)?.winner.value).toEqual({
+            value: "deterministic-value",
+        });
+    });
+    it("uses the smaller id when neither record is deterministic", async () => {
+        const { vars } = await table();
+        const larger = pvar({
+            persistentVarId: "00mriijkhq94msfe9m2j6quwz",
+            value: { value: "larger-newer" },
+            modifiedAt: 9,
+        });
+        const smaller = pvar({
+            persistentVarId: "00mriijkhq94msfe9m2j6quwa",
+            value: { value: "smaller-older" },
+            modifiedAt: 1,
+        });
+        expect(vars.resolveUniqueConflict(larger, smaller)).toEqual({
+            loserId: larger.persistentVarId,
+            winner: expect.objectContaining({
+                persistentVarId: smaller.persistentVarId,
+                value: { value: "larger-newer" },
+                modifiedAt: 9,
+            }),
+        });
+    });
+    it("declines when the records are not two ids for one name", async () => {
+        const { vars } = await table();
+        const row = pvar({ persistentVarId: "00mriijkhq94msfe9m2j6quwp" });
+        expect(vars.resolveUniqueConflict(row, row)).toBeUndefined();
+        expect(vars.resolveUniqueConflict(row, pvar({ persistentVarId: "00mriijkhq94msfe9m2j6quwq", name: "other" }))).toBeUndefined();
+    });
+});

package/dist/data/persistent-vars.d.ts

@@ -70,6 +70,19 @@ export declare class PersistentVarsTable extends Table<IPersistentVar> {
      * deterministic record already exists, it wins and the duplicate legacy row is removed.
      */
     migrateLegacyId(persistentVar: IPersistentVar): Promise<IPersistentVar>;
+    /**
+     * Settle two rows that share a `name`.
+     *
+     * The deterministic id owns the name when either row has one; otherwise the
+     * lexicographically smaller id does. The value, scope, and secret flag come from
+     * the row with the greater `modifiedAt` (missing counts as 0). A tie keeps the
+     * identity winner's value. Both devices see the same two change records, so they
+     * pick the same winner and the loser can be tombstoned.
+     */
+    resolveUniqueConflict(incoming: IPersistentVar, existing: IPersistentVar): {
+        winner: IPersistentVar;
+        loserId: string;
+    } | undefined;
     /** Return a stored variable's raw value by name. */
     getPersistentVarValue<T>(name: string): Promise<T | undefined>;
 }

package/dist/data/persistent-vars.js

@@ -91,6 +91,20 @@ exports.persistentVarsMetaData = {
     iconClassName: "bi bi-braces",
     indexes: [{ fields: ["name"], unique: true }],
 };
+/**
+ * Pick the record id that should own a duplicated persistent-variable name.
+ *
+ * A deterministic id beats a legacy random id. When neither (or both) is
+ * deterministic, the lexicographically smaller id wins.
+ */
+function persistentVarIdentityWinner(left, right) {
+    const leftDeterministic = (0, utils_1.isDeterministicPvarId)(left.persistentVarId);
+    const rightDeterministic = (0, utils_1.isDeterministicPvarId)(right.persistentVarId);
+    if (leftDeterministic !== rightDeterministic) {
+        return leftDeterministic ? left : right;
+    }
+    return left.persistentVarId < right.persistentVarId ? left : right;
+}
 /** Persistent-variable table with deterministic IDs and secret-value handling. */
 let PersistentVarsTable = (() => {
     let _classSuper = table_1.Table;
@@ -156,6 +170,45 @@ let PersistentVarsTable = (() => {
                 throw error;
             }
         }
+        /**
+         * Settle two rows that share a `name`.
+         *
+         * The deterministic id owns the name when either row has one; otherwise the
+         * lexicographically smaller id does. The value, scope, and secret flag come from
+         * the row with the greater `modifiedAt` (missing counts as 0). A tie keeps the
+         * identity winner's value. Both devices see the same two change records, so they
+         * pick the same winner and the loser can be tombstoned.
+         */
+        resolveUniqueConflict(incoming, existing) {
+            if (incoming.name !== existing.name) {
+                return undefined;
+            }
+            if (incoming.persistentVarId === existing.persistentVarId) {
+                return undefined;
+            }
+            const identity = persistentVarIdentityWinner(incoming, existing);
+            const other = identity === incoming ? existing : incoming;
+            const identityModified = identity.modifiedAt ?? 0;
+            const otherModified = other.modifiedAt ?? 0;
+            const valueSource = otherModified > identityModified ? other : identity;
+            const winner = {
+                persistentVarId: identity.persistentVarId,
+                name: identity.name,
+                scope: valueSource.scope,
+                value: valueSource.value,
+                modifiedAt: Math.max(identityModified, otherModified) || undefined,
+            };
+            if (valueSource.description !== undefined) {
+                winner.description = valueSource.description;
+            }
+            if (valueSource.userCreated !== undefined) {
+                winner.userCreated = valueSource.userCreated;
+            }
+            if (valueSource.isSecret !== undefined) {
+                winner.isSecret = valueSource.isSecret;
+            }
+            return { winner, loserId: other.persistentVarId };
+        }
         /** Return a stored variable's raw value by name. */
         async getPersistentVarValue(name) {
             const pVars = await this.list({ name });

package/dist/data/sync-recovery-queue.d.ts

@@ -5,6 +5,14 @@
  */
 import { z } from "zod";
 import { type ISqlDb, type ITableMetaData, SQLDataSource } from "./orm";
+/** How many attempts mark a still-retrying entry as stuck. */
+export declare const SYNC_RECOVERY_STUCK_ATTEMPTS = 5;
+/** How long a still-retrying entry must have been failing before it is stuck. */
+export declare const SYNC_RECOVERY_STUCK_AGE_MS: number;
+/** Why automatic recovery stopped asking peers for an entry. */
+export declare const syncRecoveryParkedReasons: readonly ["schema", "unique-conflict", "unresolvable"];
+/** Why automatic recovery stopped asking peers for an entry. */
+export type SyncRecoveryParkedReason = (typeof syncRecoveryParkedReasons)[number];
 /** One recorded materialization failure for a synchronized record. */
 export declare const syncRecoveryFailureSchema: z.ZodObject<{
     error: z.ZodString;
@@ -40,6 +48,16 @@ export declare const syncRecoveryEntrySchema: z.ZodObject<{
         erroredAt: number;
         sourceDeviceId?: string | undefined;
     }>, "many">;
+    /** Set when peer retry has stopped. Absent while the entry is still retrying. */
+    parkedAt: z.ZodOptional<z.ZodNumber>;
+    parkedReason: z.ZodOptional<z.ZodEnum<["schema", "unique-conflict", "unresolvable"]>>;
+    /** Earliest time a retrying entry should ask peers again. */
+    nextAttemptAt: z.ZodOptional<z.ZodNumber>;
+    /**
+     * How many due peer sweeps have failed to clear this entry.
+     * Local only. Backoff uses this instead of the materialization attempt count.
+     */
+    sweepCount: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
     tableName: string;
     recordId: string;
@@ -52,6 +70,10 @@ export declare const syncRecoveryEntrySchema: z.ZodObject<{
         erroredAt: number;
         sourceDeviceId?: string | undefined;
     }[];
+    parkedAt?: number | undefined;
+    parkedReason?: "schema" | "unique-conflict" | "unresolvable" | undefined;
+    nextAttemptAt?: number | undefined;
+    sweepCount?: number | undefined;
 }, {
     tableName: string;
     recordId: string;
@@ -64,11 +86,29 @@ export declare const syncRecoveryEntrySchema: z.ZodObject<{
         erroredAt: number;
         sourceDeviceId?: string | undefined;
     }[];
+    parkedAt?: number | undefined;
+    parkedReason?: "schema" | "unique-conflict" | "unresolvable" | undefined;
+    nextAttemptAt?: number | undefined;
+    sweepCount?: number | undefined;
 }>;
 /** One recorded materialization failure for a synchronized record. */
 export type ISyncRecoveryFailure = z.infer<typeof syncRecoveryFailureSchema>;
 /** Durable local recovery state for one synchronized record. */
 export type ISyncRecoveryEntry = z.infer<typeof syncRecoveryEntrySchema>;
+/**
+ * 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}.
+ */
+export declare function isStuckSyncRecoveryEntry(entry: Pick<ISyncRecoveryEntry, "parkedAt" | "attemptCount" | "firstFailedAt">, now?: number): boolean;
+/**
+ * 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.
+ */
+export declare function nextStuckSyncRecoveryAt(entries: Array<Pick<ISyncRecoveryEntry, "parkedAt" | "attemptCount" | "firstFailedAt">>, now?: number): number | undefined;
 /** Input used to append a materialization failure to the recovery queue. */
 export interface IRecordSyncFailure {
     tableName: string;
@@ -106,7 +146,44 @@ export declare class SyncRecoveryQueueTable extends SQLDataSource<ISyncRecoveryE
      * The queue table must be initialized before this method is called.
      */
     clearRecordSync(tableName: string, recordId: string): void;
+    /**
+     * 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: string, attemptCount: number): void;
     private mergeFailure;
+    /**
+     * 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`.
+     */
+    park(tableName: string, recordId: string, reason: SyncRecoveryParkedReason): Promise<void>;
+    /**
+     * Return an entry to peer retry.
+     *
+     * Clears only the park marker and any scheduled next attempt.
+     */
+    unpark(tableName: string, recordId: string): Promise<void>;
+    /**
+     * Schedule the next peer retry for an entry that is still queued.
+     *
+     * Writes only `nextAttemptAt`.
+     */
+    setNextAttempt(tableName: string, recordId: string, nextAttemptAt: number): Promise<void>;
+    /**
+     * 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.
+     */
+    noteUnresolvedSweep(tableName: string, recordId: string): Promise<number | undefined>;
+    /** Apply a column-level update without rewriting the rest of the queue row. */
+    private patchEntry;
 }
 /** Return the single SyncRecoveryQueue table associated with a database instance. */
 export declare function syncRecoveryQueueTable(db: ISqlDb): SyncRecoveryQueueTable;

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/package.json

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