@peers-app/peers-sdk 0.27.1 → 0.27.3

package/dist/contracts/__tests__/tool-catalog.test.js

@@ -665,7 +665,6 @@ describe("bare deterministic row repair", () => {
         ["invalid empty identity", { catalogIdentity: "" }],
         ["different name", { name: "write" }],
         ["different name case", { name: "Read" }],
-        ["matching stored target", { contractId, contractVersion: 1, toolName: "read" }],
         ["conflicting stored target", { contractId, contractVersion: 1, toolName: "write" }],
         ["partial contract ID", { contractId }],
         ["partial version", { contractVersion: 1 }],
@@ -673,9 +672,7 @@ describe("bare deterministic row repair", () => {
     ])("rejects %s even for an explicit catalog patch", (_name, fields) => {
         expect(() => (0, tool_catalog_1.validateToolCatalogWrite)({ ...bare, ...fields }, restored, toolId, true)).toThrow(/Quarantined/);
         // Exercise the cannot-be-claimed branch without a quarantine early-out too.
-        // A matching established target is already a valid mapping in this case.
-        if (_name !== "matching stored target")
-            expect(() => (0, tool_catalog_1.validateToolCatalogWrite)({ ...bare, ...fields, catalogState: undefined }, restored, toolId, true)).toThrow();
+        expect(() => (0, tool_catalog_1.validateToolCatalogWrite)({ ...bare, ...fields, catalogState: undefined }, restored, toolId, true)).toThrow();
     });
     test.each([
         ["missing target", { contractId: undefined, contractVersion: undefined, toolName: undefined }],
@@ -690,9 +687,9 @@ describe("bare deterministic row repair", () => {
     ])("rejects a candidate with %s", (_name, fields) => {
         expect(() => (0, tool_catalog_1.validateToolCatalogWrite)(bare, { ...restored, ...fields }, toolId, true)).toThrow();
     });
-    test("ordinary saves and replay cannot clear quarantine, even with the canonical target", () => {
+    test("ordinary saves and replay clear a missing-target quarantine only with the canonical target", () => {
+        expect(() => (0, tool_catalog_1.validateToolCatalogWrite)(bare, restored)).not.toThrow();
         for (const candidate of [
-            restored,
             { ...bare, catalogState: "resolved" },
             { ...bare, catalogState: undefined, usageDescription: "metadata" },
         ])
@@ -931,3 +928,272 @@ test("ready upgrades unresolved host aliases, keeps policy, refreshes descriptio
     expect(restarted.rows.get(old.toolId)?.catalogState).toBe("resolved");
     await restarted.catalog.dispose();
 });
+describe("missing-target quarantine resolution", () => {
+    const target = { contractId, version: 1, toolName: "read" };
+    const toolId = (0, tool_catalog_identity_1.deriveToolCatalogId)(target);
+    const missingTarget = `Error: Missing tool catalog target: ${toolId}`;
+    // The shape found on Mark's Family Hub (2026-10-26): a bare deterministic row that reconcile()
+    // quarantined, while peers hold the published root plus the synced quarantine patches.
+    const bare = {
+        toolId,
+        name: "read",
+        usageDescription: "stale",
+        code: "",
+        inputSchema: { type: tools_1.IOSchemaType.none, fields: [] },
+        outputSchema: { type: tools_1.IOSchemaType.none, fields: [] },
+        catalogState: "quarantined",
+        catalogReason: missingTarget,
+    };
+    const published = {
+        ...bare,
+        contractId,
+        contractVersion: 1,
+        toolName: "read",
+        catalogIdentity: "deterministic",
+        catalogState: "resolved",
+        catalogReason: undefined,
+    };
+    const replayed = {
+        ...published,
+        catalogState: "quarantined",
+        catalogReason: missingTarget,
+    };
+    test("sync replay may give a bare row its own target, still quarantined, and reconcile resolves it", async () => {
+        expect(() => (0, tool_catalog_1.validateToolCatalogWrite)(bare, replayed)).not.toThrow();
+        expect(() => (0, tool_catalog_1.validateToolCatalogWrite)(bare, published)).not.toThrow();
+        const f = fixture(new Map([[toolId, replayed]]));
+        try {
+            await f.catalog.ready();
+            expect(f.rows.get(toolId)).toMatchObject({
+                contractId,
+                contractVersion: 1,
+                toolName: "read",
+                catalogIdentity: "deterministic",
+                catalogState: "resolved",
+            });
+            expect(f.rows.get(toolId)?.catalogReason).toBeUndefined();
+        }
+        finally {
+            await f.catalog.dispose();
+        }
+    });
+    test("publication resolves a row left half-restored with its target", async () => {
+        const f = fixture();
+        try {
+            await f.catalog.ready();
+            f.rows.set(toolId, replayed);
+            await f.publish();
+            expect(f.rows.get(toolId)?.catalogState).toBe("resolved");
+            expect(f.registry.resolve(contractId, 1)?.name).toBe("Test");
+        }
+        finally {
+            await f.catalog.dispose();
+        }
+    });
+    test.each([
+        ["another quarantine reason", { catalogReason: "Error: Tool catalog identity cannot change" }],
+        ["no quarantine reason", { catalogReason: undefined }],
+        ["a reason mentioning missing targets", { catalogReason: `Conflict; ${missingTarget}` }],
+        ["a reason with a suffix", { catalogReason: `${missingTarget}; identity collision` }],
+        [
+            "another row's missing target",
+            { catalogReason: `Error: Missing tool catalog target: ${(0, utils_1.newid)()}` },
+        ],
+        ["executable source", { code: "existing" }],
+        ["a different name", { name: "write" }],
+        ["another identity kind", { catalogIdentity: "legacy-alias" }],
+        ["a partial target", { contractVersion: undefined }],
+        ["a target its ID doesn't derive from", { contractVersion: 2 }],
+    ])("a quarantined row with %s stays quarantined", async (_name, fields) => {
+        const stuck = { ...replayed, ...fields };
+        expect(() => (0, tool_catalog_1.validateToolCatalogWrite)(stuck, published)).toThrow(/Quarantined/);
+        const f = fixture(new Map([[toolId, stuck]]));
+        try {
+            await f.catalog.ready();
+            expect(f.rows.get(toolId)?.catalogState).toBe("quarantined");
+        }
+        finally {
+            await f.catalog.dispose();
+        }
+    });
+    test.each([
+        ["another quarantine reason", { catalogReason: "Error: Tool catalog identity cannot change" }],
+        ["no quarantine reason", { catalogReason: undefined }],
+        ["a reason mentioning missing targets", { catalogReason: `Conflict; ${missingTarget}` }],
+        [
+            "another row's missing target",
+            { catalogReason: `Error: Missing tool catalog target: ${(0, utils_1.newid)()}` },
+        ],
+        ["unset identity kind", { catalogIdentity: undefined }],
+        ["a target its ID doesn't derive from", { contractVersion: 2 }],
+        ["executable source", { code: "existing" }],
+    ])("a replayed candidate with %s cannot claim a bare row", (_name, fields) => {
+        expect(() => (0, tool_catalog_1.validateToolCatalogWrite)(bare, { ...replayed, ...fields })).toThrow();
+    });
+    test("reviewed aliases suppress resolution of an aliased member's quarantined rows", async () => {
+        const aliased = { contractId, version: 1, toolName: "new-task" };
+        const rows = [(0, tool_catalog_identity_1.deriveToolCatalogId)(aliased), ...(0, tool_catalog_migrations_1.toolCatalogIds)(aliased)].map((id) => ({
+            ...replayed,
+            toolId: id,
+            name: "new-task",
+            toolName: "new-task",
+            catalogReason: `Error: Missing tool catalog target: ${id}`,
+        }));
+        for (const row of rows)
+            expect(() => (0, tool_catalog_1.validateToolCatalogWrite)(row, {
+                ...row,
+                catalogState: "resolved",
+                catalogReason: undefined,
+            })).toThrow(/Quarantined/);
+        const f = fixture(new Map(rows.map((row) => [row.toolId, row])));
+        try {
+            await f.catalog.ready();
+            for (const row of rows)
+                expect(f.rows.get(row.toolId)).toEqual(row);
+        }
+        finally {
+            await f.catalog.dispose();
+        }
+    });
+    test.each([
+        bare,
+        replayed,
+    ])("sync cannot relabel another quarantine as a missing target (%#)", (row) => {
+        const stuck = { ...row, catalogReason: "Error: Tool catalog identity collision" };
+        expect(() => (0, tool_catalog_1.validateToolCatalogWrite)(stuck, { ...stuck, catalogReason: missingTarget })).toThrow(/Quarantined/);
+        expect(() => (0, tool_catalog_1.validateToolCatalogWrite)(stuck, { ...stuck, usageDescription: "metadata" })).not.toThrow();
+    });
+    test.each([
+        undefined,
+        "deterministic",
+    ])("sync cannot replace a quarantined identity kind with %s to enable repair", (catalogIdentity) => {
+        const stuck = { ...replayed, catalogIdentity: "legacy-alias" };
+        expect(() => (0, tool_catalog_1.validateToolCatalogWrite)(stuck, { ...stuck, catalogIdentity })).toThrow(/Quarantined/);
+        expect(() => (0, tool_catalog_1.validateToolCatalogWrite)(stuck, { ...stuck, usageDescription: "metadata" })).not.toThrow();
+    });
+    test.each([
+        undefined,
+        "unresolved",
+    ])("sync can claim a bare row in state %s", (catalogState) => {
+        expect(() => (0, tool_catalog_1.validateToolCatalogWrite)({ ...bare, catalogState }, published)).not.toThrow();
+        expect(() => (0, tool_catalog_1.validateToolCatalogWrite)({ ...bare, catalogState }, replayed)).not.toThrow();
+    });
+    test("reconciliation patches only identity and state, preserving concurrent policy and history", async () => {
+        const stored = {
+            ...replayed,
+            packageId: (0, utils_1.newid)(),
+            codeRepository: "historical repository",
+            accessLevel: 70,
+            detailedDescription: "saved details",
+        };
+        const f = fixture(new Map([[toolId, stored]]));
+        const update = required(f.table.update.getMockImplementation());
+        f.table.update.mockImplementationOnce(async (patch) => {
+            expect((0, tools_1.isToolCatalogPatch)(patch)).toBe(true);
+            expect(patch).toEqual({
+                toolId,
+                contractId,
+                contractVersion: 1,
+                toolName: "read",
+                catalogIdentity: "deterministic",
+                catalogState: "resolved",
+                catalogReason: undefined,
+            });
+            const current = {
+                ...stored,
+                accessLevel: 90,
+                remoteAccessLevel: 80,
+                authorityPropagation: "preserve",
+            };
+            f.rows.set(toolId, current);
+            (0, tool_catalog_1.validateToolCatalogWrite)(current, { ...current, ...patch }, toolId, true);
+            return update(patch);
+        });
+        try {
+            await f.catalog.ready();
+            expect(f.rows.get(toolId)).toEqual({
+                ...stored,
+                catalogState: "resolved",
+                catalogReason: undefined,
+                accessLevel: 90,
+                remoteAccessLevel: 80,
+                authorityPropagation: "preserve",
+            });
+        }
+        finally {
+            await f.catalog.dispose();
+        }
+    });
+    test("a concurrent conflicting quarantine rejects a stale reconciliation patch", async () => {
+        const f = fixture(new Map([[toolId, replayed]]));
+        const conflict = { ...replayed, catalogReason: "Error: Tool catalog identity collision" };
+        f.table.update.mockImplementationOnce(async (patch) => {
+            f.rows.set(toolId, conflict);
+            (0, tool_catalog_1.validateToolCatalogWrite)(conflict, { ...conflict, ...patch }, toolId, true);
+            throw new Error("Conflict was not rejected");
+        });
+        try {
+            await expect(f.catalog.ready()).rejects.toThrow(/Quarantined/);
+            expect(f.rows.get(toolId)).toEqual(conflict);
+            expect(f.registry.resolve(contractId, 1)).toBeUndefined();
+        }
+        finally {
+            await f.catalog.dispose();
+        }
+    });
+    test("resolved and bare peers converge after replay without recursive repair writes", async () => {
+        const peers = [fixture(new Map([[toolId, published]])), fixture(new Map([[toolId, bare]]))];
+        try {
+            for (const f of peers) {
+                await f.catalog.ready();
+                f.table.update.mockClear();
+                (0, tool_catalog_1.validateToolCatalogWrite)(f.rows.get(toolId), replayed);
+                await f.table.save(replayed);
+            }
+            await new Promise((resolve) => setImmediate(resolve));
+            for (const f of peers) {
+                expect(f.rows.get(toolId)).toEqual(published);
+                expect(f.table.update).toHaveBeenCalledTimes(1);
+                (0, tool_catalog_1.validateToolCatalogWrite)(f.rows.get(toolId), published);
+                await f.table.save(published);
+            }
+            await new Promise((resolve) => setImmediate(resolve));
+            for (const f of peers) {
+                expect(f.table.update).toHaveBeenCalledTimes(1);
+                expect(f.registry.resolve(contractId, 1)).toBeUndefined();
+            }
+        }
+        finally {
+            await Promise.all(peers.map((f) => f.catalog.dispose()));
+        }
+    });
+    test("a hash collision cannot retarget retained missing-target quarantine evidence", () => {
+        const hash = jest.spyOn(nacl, "hash").mockReturnValue(new Uint8Array(64));
+        try {
+            const collisionId = (0, tool_catalog_identity_1.deriveToolCatalogId)(target);
+            expect((0, tool_catalog_identity_1.deriveToolCatalogId)({ ...target, version: 2 })).toBe(collisionId);
+            const stored = {
+                ...replayed,
+                toolId: collisionId,
+                catalogReason: `Error: Missing tool catalog target: ${collisionId}`,
+            };
+            for (const catalogState of ["resolved", "quarantined"])
+                expect(() => (0, tool_catalog_1.validateToolCatalogWrite)(stored, { ...stored, contractVersion: 2, catalogState })).toThrow();
+        }
+        finally {
+            hash.mockRestore();
+        }
+    });
+    test("an established mapping is not re-patched on each publish", async () => {
+        const f = fixture(new Map([[toolId, { ...published, catalogReason: undefined }]]));
+        try {
+            await f.publish();
+            const updates = f.table.update.mock.calls.length;
+            await f.publish(definition(), (0, utils_1.newid)());
+            expect(f.table.update).toHaveBeenCalledTimes(updates);
+        }
+        finally {
+            await f.catalog.dispose();
+        }
+    });
+});

package/dist/contracts/tool-catalog.d.ts

@@ -28,10 +28,12 @@ export declare function retainToolCatalogFields<T extends Partial<ITool>>(existi
  * tools move to contracts: they stay ordinary rows that local writers and older
  * runtimes may delete. A bare deterministic row with an empty executable and the
  * member's own name may receive that member's canonical target; every other
- * untargeted or quarantined identity stays rejected.
+ * untargeted or quarantined identity stays rejected, except that a row quarantined only
+ * for its missing target takes the one target its deterministic ID derives from, from
+ * publication or sync (see `canResolveMissingTarget`).
  *
- * @param catalogPatch - Only explicit local catalog patches may restore a bare
- * deterministic row. Ordinary replacements and sync replay must leave it quarantined.
+ * @param catalogPatch - Explicit local catalog patches may also restore a bare deterministic
+ * row whatever its quarantine reason (`canRestoreBareDeterministicRow`).
  */
 export declare function validateToolCatalogWrite(existing: Partial<ITool> | undefined, candidate: Partial<ITool> | undefined, recordId?: string | undefined, catalogPatch?: boolean): void;
 /**

package/dist/contracts/tool-catalog.js

@@ -28,6 +28,15 @@ function toolCatalogTarget(row) {
     (0, tool_catalog_identity_1.validateToolCatalogTarget)(target);
     return target;
 }
+/** {@link toolCatalogTarget}, or undefined for a partial or invalid target. */
+function toolCatalogTargetOrUndefined(row) {
+    try {
+        return toolCatalogTarget(row);
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * Mixed-version sync: runtimes that predate the catalog columns reconstruct and write
  * full rows without them. When a synced candidate carries none of the catalog-owned
@@ -92,6 +101,51 @@ function canRestoreBareDeterministicRow(existing, candidate) {
     const ids = (0, tool_catalog_migrations_1.toolCatalogIds)(target);
     return ids.length === 1 && ids[0] === candidate.toolId && candidate.toolId.startsWith("000tool0");
 }
+/** The quarantine reason reconcile() records for a deterministic row stored without its target. */
+function isMissingTargetQuarantine(row) {
+    return (row.catalogState === "quarantined" &&
+        row.catalogReason === `Error: Missing tool catalog target: ${row.toolId}`);
+}
+/**
+ * A bare deterministic catalog row (empty executable, the member's own name), or one quarantined
+ * only because its target was missing, takes the target its ID derives from, through publication
+ * or sync. The candidate must derive this ID and match any retained target. It may still
+ * carry that same missing-target quarantine (sync replays
+ * the quarantine patches that peers recorded); reconcile() then resolves the row. Any other
+ * quarantine reason, executable source, name, identity kind or target stays rejected.
+ */
+function canResolveMissingTarget(existing, candidate) {
+    if (existing.code !== "" || (candidate.code !== undefined && candidate.code !== ""))
+        return false;
+    // Only rows that still need resolving: an established mapping has nothing to restore.
+    if (existing.catalogState === "resolved")
+        return false;
+    if (existing.catalogState === "quarantined" && !isMissingTargetQuarantine(existing))
+        return false;
+    if (candidate.catalogState === "quarantined" && !isMissingTargetQuarantine(candidate))
+        return false;
+    if (candidate.catalogState !== "resolved" && candidate.catalogState !== "quarantined")
+        return false;
+    if (candidate.catalogIdentity !== "deterministic")
+        return false;
+    if (existing.catalogIdentity !== undefined && existing.catalogIdentity !== "deterministic")
+        return false;
+    let existingTarget;
+    let target;
+    try {
+        existingTarget = toolCatalogTarget(existing);
+        target = toolCatalogTarget(candidate);
+    }
+    catch {
+        return false;
+    }
+    if (!target || !candidate.toolId || existing.name !== target.toolName)
+        return false;
+    if (existingTarget && (0, tool_catalog_identity_1.toolCatalogTargetKey)(existingTarget) !== (0, tool_catalog_identity_1.toolCatalogTargetKey)(target))
+        return false;
+    const ids = (0, tool_catalog_migrations_1.toolCatalogIds)(target);
+    return ids.length === 1 && ids[0] === candidate.toolId && candidate.toolId.startsWith("000tool0");
+}
 /**
  * Shared pre-persistence identity guard for local writes and reconstructed sync rows.
  * Existing mappings cannot be retargeted, stripped or deleted. Rejected sync evidence
@@ -102,10 +156,12 @@ function canRestoreBareDeterministicRow(existing, candidate) {
  * tools move to contracts: they stay ordinary rows that local writers and older
  * runtimes may delete. A bare deterministic row with an empty executable and the
  * member's own name may receive that member's canonical target; every other
- * untargeted or quarantined identity stays rejected.
+ * untargeted or quarantined identity stays rejected, except that a row quarantined only
+ * for its missing target takes the one target its deterministic ID derives from, from
+ * publication or sync (see `canResolveMissingTarget`).
  *
- * @param catalogPatch - Only explicit local catalog patches may restore a bare
- * deterministic row. Ordinary replacements and sync replay must leave it quarantined.
+ * @param catalogPatch - Explicit local catalog patches may also restore a bare deterministic
+ * row whatever its quarantine reason (`canRestoreBareDeterministicRow`).
  */
 function validateToolCatalogWrite(existing, candidate, recordId = candidate?.toolId ?? existing?.toolId, catalogPatch = false) {
     if (!candidate) {
@@ -118,9 +174,10 @@ function validateToolCatalogWrite(existing, candidate, recordId = candidate?.too
         !(0, tool_catalog_identity_1.isCatalogToolId)(candidate.toolId) ||
         (existing && existing.toolId !== candidate.toolId))
         throw new Error("Tool catalog primary key mismatch");
+    // Relabeling another quarantine must not enable a later missing-target repair.
     if (existing?.catalogState === "quarantined" &&
-        candidate.catalogState !== "quarantined" &&
-        !(catalogPatch && canRestoreBareDeterministicRow(existing, candidate)))
+        !isMissingTargetQuarantine(existing) &&
+        isMissingTargetQuarantine(candidate))
         throw new Error(`Quarantined tool identity: ${candidate.toolId}`);
     // Quarantine preserves the original evidence byte-for-byte; it cannot retarget it.
     if (existing &&
@@ -130,6 +187,12 @@ function validateToolCatalogWrite(existing, candidate, recordId = candidate?.too
         existing.toolName === candidate.toolName &&
         existing.catalogIdentity === candidate.catalogIdentity)
         return;
+    // Changing quarantined identity evidence also requires an approved repair, even
+    // when the candidate stays quarantined and would be resolved by reconciliation.
+    if (existing?.catalogState === "quarantined" &&
+        !(catalogPatch && canRestoreBareDeterministicRow(existing, candidate)) &&
+        !canResolveMissingTarget(existing, candidate))
+        throw new Error(`Quarantined tool identity: ${candidate.toolId}`);
     const target = toolCatalogTarget(candidate);
     const legacy = (0, tool_catalog_migrations_1.resolveLegacyToolId)(candidate.toolId);
     const previous = existing && toolCatalogTarget(existing);
@@ -139,7 +202,8 @@ function validateToolCatalogWrite(existing, candidate, recordId = candidate?.too
         if (existing &&
             !previous &&
             !legacy &&
-            !(catalogPatch && canRestoreBareDeterministicRow(existing, candidate)))
+            !(catalogPatch && canRestoreBareDeterministicRow(existing, candidate)) &&
+            !canResolveMissingTarget(existing, candidate))
             throw new Error(`Unresolved tool identity cannot be claimed: ${candidate.toolId}`);
         if (!(0, tool_catalog_migrations_1.toolCatalogIds)(target).includes(candidate.toolId))
             throw new Error(`Unknown tool catalog mapping: ${candidate.toolId}`);
@@ -407,7 +471,8 @@ class ToolCatalog {
                     };
                     const stored = existing.get(toolId);
                     if (stored?.catalogState === "quarantined" &&
-                        !canRestoreBareDeterministicRow(stored, row))
+                        !canRestoreBareDeterministicRow(stored, row) &&
+                        !canResolveMissingTarget(stored, row))
                         throw new Error(`Quarantined tool identity: ${toolId}`);
                     validateToolCatalogWrite(stored, row, toolId, true);
                     candidates.set(toolId, row);
@@ -420,7 +485,8 @@ class ToolCatalog {
             const previous = existing.get(row.toolId);
             // Restore missing identity columns only after validating the entire batch.
             // This marked patch leaves concurrent policy and historical fields intact.
-            if (previous && canRestoreBareDeterministicRow(previous, row)) {
+            if (previous &&
+                (canRestoreBareDeterministicRow(previous, row) || canResolveMissingTarget(previous, row))) {
                 const restored = await table.update((0, tools_1.toolCatalogPatch)({
                     toolId: row.toolId,
                     ...resolvedFields(toolCatalogTarget(row), row.toolId),
@@ -460,9 +526,19 @@ class ToolCatalog {
         const table = (0, tools_1.Tools)(this.dataContext);
         for (const row of await table.list()) {
             let fields;
-            // Quarantine is sticky: conflicting evidence is never silently rehabilitated.
-            if (row.catalogState === "quarantined")
+            // Quarantine is sticky: conflicting evidence is never silently rehabilitated. The one
+            // exception is a row quarantined for its missing target that has since received the
+            // target its deterministic ID derives from (from publication or sync).
+            if (row.catalogState === "quarantined") {
+                const target = toolCatalogTargetOrUndefined(row);
+                if (!target)
+                    continue;
+                const resolved = { ...row, ...resolvedFields(target, row.toolId) };
+                if (!canResolveMissingTarget(row, resolved))
+                    continue;
+                await table.update((0, tools_1.toolCatalogPatch)({ toolId: row.toolId, ...resolvedFields(target, row.toolId) }));
                 continue;
+            }
             try {
                 validateToolCatalogWrite(undefined, row);
                 const target = (0, tool_catalog_migrations_1.resolveLegacyToolId)(row.toolId) ?? toolCatalogTarget(row);

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

@@ -131,11 +131,13 @@ interface IPersistentVarOptionsWithoutDefault<T> extends IPersistentVarOptionsBa
  * A persistent variable that is stored only on this device, in the user's personal db
  */
 export declare function deviceVar<T = string>(name: string, opts: Omit<IPersistentVarOptionsWithDefault<T>, "scope" | "dataContext">): PersistentVar<T>;
+/** Create or reuse a {@link deviceVar} observable for this name and context. */
 export declare function deviceVar<T = string>(name: string, opts?: Omit<IPersistentVarOptionsWithoutDefault<T>, "scope" | "dataContext">): PersistentVar<T | undefined>;
 /**
  * A persistent variable that is stored in the user's personal db and synced across all their devices
  */
 export declare function userVar<T = string>(name: string, opts: Omit<IPersistentVarOptionsWithDefault<T>, "scope" | "dataContext">): PersistentVar<T>;
+/** Create or reuse a {@link userVar} observable for this name and context. */
 export declare function userVar<T = string>(name: string, opts?: Omit<IPersistentVarOptionsWithoutDefault<T>, "scope" | "dataContext">): PersistentVar<T | undefined>;
 /**
  * A persistent variable that is shared by all users in a group. It is stored in the group's db and synced across all users and devices in the group.
@@ -143,6 +145,7 @@ export declare function userVar<T = string>(name: string, opts?: Omit<IPersisten
  * If secret=true, it is encrypted with the group's secret key
  */
 export declare function groupVar<T = string>(name: string, opts: Omit<IPersistentVarOptionsWithDefault<T>, "scope">): PersistentVar<T>;
+/** Create or reuse a {@link groupVar} observable for this name and context. */
 export declare function groupVar<T = string>(name: string, opts?: Omit<IPersistentVarOptionsWithoutDefault<T>, "scope">): PersistentVar<T | undefined>;
 /**
  * A persistent variable that is stored only on this device, in the user's personal db.
@@ -154,6 +157,7 @@ export declare function groupVar<T = string>(name: string, opts?: Omit<IPersiste
  * renderer callers that follow the default group share one row.
  */
 export declare function groupDeviceVar<T = string>(name: string, opts: Omit<IPersistentVarOptionsWithDefault<T>, "scope">): PersistentVar<T>;
+/** Create or reuse a {@link groupDeviceVar} observable for this name and context. */
 export declare function groupDeviceVar<T = string>(name: string, opts?: Omit<IPersistentVarOptionsWithoutDefault<T>, "scope">): PersistentVar<T | undefined>;
 /**
  * A persistent variable that is stored in the user's personal db and synced across all their devices in the group.
@@ -163,4 +167,5 @@ export declare function groupDeviceVar<T = string>(name: string, opts?: Omit<IPe
  * only selects the group whose value is addressed.
  */
 export declare function groupUserVar<T = string>(name: string, opts: Omit<IPersistentVarOptionsWithDefault<T>, "scope">): PersistentVar<T>;
+/** Create or reuse a {@link groupUserVar} observable for this name and context. */
 export declare function groupUserVar<T = string>(name: string, opts?: Omit<IPersistentVarOptionsWithoutDefault<T>, "scope">): PersistentVar<T | undefined>;

package/dist/data/persistent-vars.js

@@ -278,6 +278,7 @@ function userContextCacheId(userContext) {
     }
     return String(id);
 }
+/** Create or reuse a {@link deviceVar} observable for this name and context. */
 function deviceVar(name, opts) {
     const fullOpts = { ...opts, scope: "device" };
     if (opts?.defaultValue !== undefined) {
@@ -287,6 +288,7 @@ function deviceVar(name, opts) {
         return persistentVarFactory(name, fullOpts);
     }
 }
+/** Create or reuse a {@link userVar} observable for this name and context. */
 function userVar(name, opts) {
     const fullOpts = { ...opts, scope: "user" };
     if (opts?.defaultValue !== undefined) {
@@ -296,6 +298,7 @@ function userVar(name, opts) {
         return persistentVarFactory(name, fullOpts);
     }
 }
+/** Create or reuse a {@link groupVar} observable for this name and context. */
 function groupVar(name, opts) {
     const fullOpts = { ...opts, scope: "group" };
     if (opts?.defaultValue !== undefined) {
@@ -305,6 +308,7 @@ function groupVar(name, opts) {
         return persistentVarFactory(name, fullOpts);
     }
 }
+/** Create or reuse a {@link groupDeviceVar} observable for this name and context. */
 function groupDeviceVar(name, opts) {
     const fullOpts = { ...opts, scope: "groupDevice" };
     if (opts?.defaultValue !== undefined) {
@@ -314,6 +318,7 @@ function groupDeviceVar(name, opts) {
         return persistentVarFactory(name, fullOpts);
     }
 }
+/** Create or reuse a {@link groupUserVar} observable for this name and context. */
 function groupUserVar(name, opts) {
     const fullOpts = { ...opts, scope: "groupUser" };
     if (opts?.defaultValue !== undefined) {
@@ -416,12 +421,21 @@ function persistentVarFactory(name, opts) {
                     if (!dbRec) {
                         dbRec = await migrateLegacyRec(table, name);
                     }
-                    if (dbRec) {
-                        if (dbRec.scope !== scope) {
-                            console.warn(`${name}: deleting old persistent var record because scopes don't match.  If this is unexpected there could be two different persistent variables using the same name`);
-                            await table.delete(dbRec);
-                            dbRec = undefined;
-                        }
+                    // Preserve an existing secret unless the caller explicitly changes that setting.
+                    if (dbRec?.isSecret !== undefined && opts.isSecret === undefined) {
+                        isSecret = dbRec.isSecret;
+                    }
+                    if (dbRec && dbRec.scope !== scope) {
+                        console.warn(`${name}: resetting the persistent var to its default under scope ${scope} (it was stored as ${dbRec.scope}).  If this is unexpected there could be two different persistent variables using the same name`);
+                        // Re-save under the new scope rather than deleting: names share one ID across scopes,
+                        // and change tracking turns the move into a tombstone (to a device scope, which isn't
+                        // tracked) or a fresh root snapshot (back to a synced scope) that peers apply.
+                        dbRec = await table.save({
+                            ...dbRec,
+                            scope,
+                            isSecret,
+                            value: { value: defaultValue },
+                        });
                     }
                     if (dbRec && !(0, utils_1.isDeterministicPvarId)(dbRec.persistentVarId)) {
                         dbRec = await table.migrateLegacyId(dbRec);
@@ -503,6 +517,10 @@ function persistentVarFactory(name, opts) {
                         rec = dbRec;
                     }
                     if (dbRec.persistentVarId === rec?.persistentVarId) {
+                        // A later declaration of this scope must reload and perform its own transition.
+                        if (dbRec.scope !== scope && pvarCache.get(cacheKey) === persistentVar) {
+                            pvarCache.delete(cacheKey);
+                        }
                         if (evt.data.op === "delete") {
                             rec = undefined;
                             if (defaultValue !== undefined) {

package/package.json

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