@peers-app/peers-sdk 0.27.0 → 0.27.2

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/create-group.js

@@ -51,7 +51,7 @@ async function createGroup(userContext, input) {
     });
     await (0, groups_1.Groups)(groupDataContext).signAndSave(group);
     await (0, group_members_1.GroupMembers)(groupDataContext).signAndSave({
-        groupMemberId: (0, utils_1.newid)(),
+        groupMemberId: (0, utils_1.deterministicGroupMemberId)(groupId, me.userId),
         groupId,
         userId: me.userId,
         role: group_member_roles_1.GroupMemberRole.Founder,

package/dist/data/group-members.d.ts

@@ -36,6 +36,20 @@ export declare class GroupMembersTable extends Table<IGroupMember> {
     save(groupMember: IGroupMember, opts?: ISaveOptions): Promise<IGroupMember>;
     signAndSave(groupMember: IGroupMember, opts?: ISaveOptions): Promise<IGroupMember>;
     delete(groupMemberId: string): Promise<void>;
+    /**
+     * Settle two membership rows for the same user in the same group: devices that approved the
+     * same join at once could each write one, under a different id.
+     *
+     * Merged only when both rows grant the same access (role and deleted state), so nothing about
+     * the member's access changes. The id {@link deterministicGroupMemberId} gives wins if either
+     * row has it, otherwise the lexicographically smaller id; the winner is kept as it is, signature
+     * included. Rows that disagree stay queued for a person. A pure function of the two rows, so
+     * every device keeps the same one.
+     */
+    resolveUniqueConflict(incoming: IGroupMember, existing: IGroupMember): {
+        winner: IGroupMember;
+        loserId: string;
+    } | undefined;
     /** Registers the signer for all SDK copies in this JavaScript realm. Replaces any prior signer. */
     static enableGroupMemberSigning(fn: (groupMember: IGroupMember) => IGroupMember): void;
     /** @deprecated Forbidden on GroupsTable; use save() */

package/dist/data/group-members.js

@@ -40,6 +40,7 @@ const zod_1 = require("zod");
 const user_context_singleton_1 = require("../context/user-context-singleton");
 const decorators_1 = require("../data/orm/decorators");
 const zod_types_1 = require("../types/zod-types");
+const utils_1 = require("../utils");
 const group_member_roles_1 = require("./group-member-roles");
 const group_permissions_1 = require("./group-permissions");
 const table_1 = require("./orm/table");
@@ -125,6 +126,41 @@ let GroupMembersTable = (() => {
                 await this.signAndSave(groupMember);
             }
         }
+        /**
+         * Settle two membership rows for the same user in the same group: devices that approved the
+         * same join at once could each write one, under a different id.
+         *
+         * Merged only when both rows grant the same access (role and deleted state), so nothing about
+         * the member's access changes. The id {@link deterministicGroupMemberId} gives wins if either
+         * row has it, otherwise the lexicographically smaller id; the winner is kept as it is, signature
+         * included. Rows that disagree stay queued for a person. A pure function of the two rows, so
+         * every device keeps the same one.
+         */
+        resolveUniqueConflict(incoming, existing) {
+            if (incoming.groupId !== existing.groupId || incoming.userId !== existing.userId) {
+                return undefined;
+            }
+            if (incoming.groupMemberId === existing.groupMemberId) {
+                return undefined;
+            }
+            if (incoming.role !== existing.role ||
+                Boolean(incoming.deleted) !== Boolean(existing.deleted)) {
+                return undefined;
+            }
+            const derivedId = (0, utils_1.deterministicGroupMemberId)(incoming.groupId, incoming.userId);
+            let winner;
+            if (incoming.groupMemberId === derivedId) {
+                winner = incoming;
+            }
+            else if (existing.groupMemberId === derivedId) {
+                winner = existing;
+            }
+            else {
+                winner = incoming.groupMemberId < existing.groupMemberId ? incoming : existing;
+            }
+            const loser = winner === incoming ? existing : incoming;
+            return { winner, loserId: loser.groupMemberId };
+        }
         /** Registers the signer for all SDK copies in this JavaScript realm. Replaces any prior signer. */
         static enableGroupMemberSigning(fn) {
             signingGlobals[signingKey] = fn;

package/dist/data/group-members.test.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const keys_1 = require("../keys");
+const utils_1 = require("../utils");
+const group_members_1 = require("./group-members");
 const group_permissions_1 = require("./group-permissions");
 // Test the group members signature logic directly without ORM dependencies
 describe("Group Members Signature Logic", () => {
@@ -285,3 +287,50 @@ describe("Group Members Signature Logic", () => {
         });
     });
 });
+describe("GroupMembersTable.resolveUniqueConflict", () => {
+    const groupId = (0, utils_1.newid)();
+    const userId = (0, utils_1.newid)();
+    const resolve = (incoming, existing) => group_members_1.GroupMembersTable.prototype.resolveUniqueConflict.call({}, incoming, existing);
+    const row = (groupMemberId, overrides = {}) => ({
+        groupMemberId,
+        groupId,
+        userId,
+        role: group_permissions_1.GroupMemberRole.Writer,
+        signature: `sig-${groupMemberId}`,
+        ...overrides,
+    });
+    it("keeps the smaller id, unchanged, whichever row arrives", () => {
+        const [low, high] = [(0, utils_1.newid)(), (0, utils_1.newid)()].sort();
+        const a = row(low);
+        const b = row(high);
+        expect(resolve(a, b)).toEqual({ winner: a, loserId: high });
+        expect(resolve(b, a)).toEqual({ winner: a, loserId: high });
+        expect(resolve(b, a)?.winner.signature).toBe(`sig-${low}`);
+    });
+    it("prefers the id derived from the group and user", () => {
+        const derived = row((0, utils_1.deterministicGroupMemberId)(groupId, userId));
+        const other = row("00000000000000000000000001");
+        expect(resolve(other, derived)).toEqual({ winner: derived, loserId: other.groupMemberId });
+        expect(resolve(derived, other)).toEqual({ winner: derived, loserId: other.groupMemberId });
+    });
+    it("leaves rows that grant different access for a person to settle", () => {
+        const a = row((0, utils_1.newid)());
+        expect(resolve(a, row((0, utils_1.newid)(), { role: group_permissions_1.GroupMemberRole.Admin }))).toBeUndefined();
+        expect(resolve(a, row((0, utils_1.newid)(), { deleted: true }))).toBeUndefined();
+        expect(resolve(a, row((0, utils_1.newid)(), { userId: (0, utils_1.newid)() }))).toBeUndefined();
+        expect(resolve(a, row((0, utils_1.newid)(), { groupId: (0, utils_1.newid)() }))).toBeUndefined();
+        expect(resolve(a, { ...a })).toBeUndefined();
+    });
+    it("treats a missing deleted flag as not deleted", () => {
+        const a = row((0, utils_1.newid)());
+        const b = row((0, utils_1.newid)(), { deleted: false });
+        expect(resolve(a, b)).toBeDefined();
+    });
+    it("depends only on the two signed rows and never modifies either one", () => {
+        const a = Object.freeze(row((0, utils_1.newid)()));
+        const b = Object.freeze(row((0, utils_1.newid)()));
+        const before = [structuredClone(a), structuredClone(b)];
+        expect(resolve(a, b)).toEqual(resolve(b, a));
+        expect([a, b]).toEqual(before);
+    });
+});

package/dist/invites/group-approval.js

@@ -31,7 +31,7 @@ async function buildGroupApproval(userContext, input) {
         // Groups created before founders got an explicit membership row: the founder role is
         // implicit (see `getUserRole`). Write the row now so it seeds to joiners like any admin.
         approvingMember = await groupMembersTable.signAndSave({
-            groupMemberId: (0, utils_1.newid)(),
+            groupMemberId: (0, utils_1.deterministicGroupMemberId)(input.groupId, userContext.userId),
             groupId: input.groupId,
             userId: userContext.userId,
             role: data_1.GroupMemberRole.Founder,
@@ -65,8 +65,10 @@ async function buildGroupApproval(userContext, input) {
         membership = await groupMembersTable.signAndSave(existingMember);
     }
     else {
+        // The same id on each of the approver's devices: a join several of them approve at once
+        // is one row, not rows that collide on (groupId, userId).
         membership = await groupMembersTable.signAndSave({
-            groupMemberId: (0, utils_1.newid)(),
+            groupMemberId: (0, utils_1.deterministicGroupMemberId)(input.groupId, input.joiner.userId),
             groupId: input.groupId,
             userId: input.joiner.userId,
             role: input.role,

package/dist/invites/group-approval.test.js

@@ -149,6 +149,8 @@ describe("group approval payloads", () => {
             role: group_member_roles_1.GroupMemberRole.Writer,
         });
         expect(approval.membership.signature).toContain(":");
+        // Each of the approver's devices writes the same row for this join.
+        expect(approval.membership.groupMemberId).toBe((0, utils_1.deterministicGroupMemberId)(group.groupId, joiner.userId));
         expect(approval.seed.groupMembers.map((member) => member.userId)).toContain(admin.userId);
         expect(approval.seed.devices[0]).toMatchObject({
             deviceId: admin.deviceId,

package/dist/utils.d.ts

@@ -37,6 +37,23 @@ export declare function deterministicTableId(identity: string): string;
  * @param id Peer ID to inspect.
  */
 export declare function isDeterministicTableId(id: string): boolean;
+/**
+ * The ID of a user's membership row in a group, the same on every device.
+ *
+ * Several of an admin's devices can approve the same join at once; with this ID they write one
+ * row, which merges as an ordinary update, instead of rows that collide on the
+ * `(groupId, userId)` unique index.
+ *
+ * @param groupId The group.
+ * @param userId The member.
+ */
+export declare function deterministicGroupMemberId(groupId: string, userId: string): string;
+/**
+ * Return whether a peer ID was generated by {@link deterministicGroupMemberId}.
+ *
+ * @param id Peer ID to inspect.
+ */
+export declare function isDeterministicGroupMemberId(id: string): boolean;
 /** Resolves after `ms` milliseconds (0 yields a microtask-yield on most runtimes). */
 export declare function sleep(ms?: number): Promise<void>;
 /** Turns `fooBar` into `Foo Bar` for labels (also replaces `_` with space). */
@@ -93,6 +110,8 @@ export declare function getTimestamp(): number;
  * @param opts.timeout Clamped timeout; defaults to {@link PeerDeviceConsts} min/max
  * @param opts.retriesOnError Max error retries
  * @param opts.retriesOnTimeout Max “timed out” races before giving up
+ * @param opts.shouldRetry Return false for a terminal error that must be reported immediately.
+ * @param opts.logFailure Log exhausted error retries; defaults to `console.error`.
  * @throws Last error, timeout exhaustion, or if the connection is closed
  */
 export declare function retryOnErrorOrTimeout<T>({ fn, connection, opts, }: {
@@ -102,6 +121,8 @@ export declare function retryOnErrorOrTimeout<T>({ fn, connection, opts, }: {
         timeout?: number;
         retriesOnError?: number;
         retriesOnTimeout?: number;
+        shouldRetry?: (error: unknown) => boolean;
+        logFailure?: (message: string, error: unknown) => void;
     };
 }): Promise<T>;
 /**

package/dist/utils.js

@@ -7,6 +7,8 @@ exports.deterministicPvarId = deterministicPvarId;
 exports.isDeterministicPvarId = isDeterministicPvarId;
 exports.deterministicTableId = deterministicTableId;
 exports.isDeterministicTableId = isDeterministicTableId;
+exports.deterministicGroupMemberId = deterministicGroupMemberId;
+exports.isDeterministicGroupMemberId = isDeterministicGroupMemberId;
 exports.sleep = sleep;
 exports.camelCaseToSpaces = camelCaseToSpaces;
 exports.camelCaseToHyphens = camelCaseToHyphens;
@@ -48,6 +50,8 @@ function simpleObjectHash(obj) {
 const DETERMINISTIC_PVAR_PREFIX = "000pvar0";
 /** Well-known prefix for deterministic package-table IDs. */
 const DETERMINISTIC_TABLE_PREFIX = "000tbl00";
+/** Well-known prefix for deterministic group-membership IDs. */
+const DETERMINISTIC_GROUP_MEMBER_PREFIX = "000gmbr0";
 /**
  * Converts a byte array to a base-36 string of the requested length, using unbiased modular reduction.
  * Bytes >= 252 are skipped to avoid bias (same technique as {@link cryptoRandomString}).
@@ -105,6 +109,27 @@ function deterministicTableId(identity) {
 function isDeterministicTableId(id) {
     return id.startsWith(DETERMINISTIC_TABLE_PREFIX);
 }
+/**
+ * The ID of a user's membership row in a group, the same on every device.
+ *
+ * Several of an admin's devices can approve the same join at once; with this ID they write one
+ * row, which merges as an ordinary update, instead of rows that collide on the
+ * `(groupId, userId)` unique index.
+ *
+ * @param groupId The group.
+ * @param userId The member.
+ */
+function deterministicGroupMemberId(groupId, userId) {
+    return deterministicPeerId(DETERMINISTIC_GROUP_MEMBER_PREFIX, `${groupId}:${userId}`);
+}
+/**
+ * Return whether a peer ID was generated by {@link deterministicGroupMemberId}.
+ *
+ * @param id Peer ID to inspect.
+ */
+function isDeterministicGroupMemberId(id) {
+    return id.startsWith(DETERMINISTIC_GROUP_MEMBER_PREFIX);
+}
 /** Resolves after `ms` milliseconds (0 yields a microtask-yield on most runtimes). */
 function sleep(ms = 0) {
     return new Promise((resolve) => setTimeout(resolve, ms));
@@ -243,6 +268,8 @@ function getTimestamp() {
  * @param opts.timeout Clamped timeout; defaults to {@link PeerDeviceConsts} min/max
  * @param opts.retriesOnError Max error retries
  * @param opts.retriesOnTimeout Max “timed out” races before giving up
+ * @param opts.shouldRetry Return false for a terminal error that must be reported immediately.
+ * @param opts.logFailure Log exhausted error retries; defaults to `console.error`.
  * @throws Last error, timeout exhaustion, or if the connection is closed
  */
 async function retryOnErrorOrTimeout({ fn, connection, opts = {}, }) {
@@ -258,8 +285,8 @@ async function retryOnErrorOrTimeout({ fn, connection, opts = {}, }) {
     let resultSet = false;
     let finalError;
     while (errorCount <= retriesOnError && timeoutCount <= retriesOnTimeout) {
+        let sleepTimeout = null;
         try {
-            let sleepTimeout = null;
             const sleepPromise = new Promise((resolve) => {
                 sleepTimeout = setTimeout(() => {
                     resolve();
@@ -292,14 +319,20 @@ async function retryOnErrorOrTimeout({ fn, connection, opts = {}, }) {
             finalError = error;
             connection.errorRate = connection.errorRate * 0.9 + 0.1;
             errorCount++;
+            if (opts.shouldRetry?.(error) === false)
+                throw error;
             if (connection.closed) {
                 throw new Error(`connection has been closed`);
             }
         }
+        finally {
+            if (sleepTimeout !== null)
+                clearTimeout(sleepTimeout);
+        }
         console.warn(`Call failed, retrying: timeout is ${timeout}ms, errorCount: ${errorCount} of ${retriesOnError}, timeoutCount: ${timeoutCount} of ${retriesOnTimeout + 1}. Last error:`, finalError);
     }
     if (finalError) {
-        console.error(`Retry failed after ${errorCount} errors and ${timeoutCount} timeouts. Last error:`, finalError);
+        (opts.logFailure ?? console.error)(`Retry failed after ${errorCount} errors and ${timeoutCount} timeouts. Last error:`, finalError);
         throw finalError;
     }
     else {

package/dist/utils.test.js

@@ -2,6 +2,25 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 const lodash_1 = require("lodash");
 const utils_1 = require("./utils");
+describe("retryOnErrorOrTimeout", () => {
+    it("reports a terminal error after one call and clears its timeout", async () => {
+        jest.useFakeTimers();
+        const error = new Error("No handler registered for event: listChanges_group");
+        const fn = jest.fn().mockRejectedValue(error);
+        try {
+            await expect((0, utils_1.retryOnErrorOrTimeout)({
+                fn,
+                connection: { deviceId: (0, utils_1.newid)(), latencyMs: 1, errorRate: 0, timestampLastApplied: 0 },
+                opts: { shouldRetry: () => false },
+            })).rejects.toBe(error);
+            expect(fn).toHaveBeenCalledTimes(1);
+            expect(jest.getTimerCount()).toBe(0);
+        }
+        finally {
+            jest.useRealTimers();
+        }
+    });
+});
 describe("readResponseTextCapped", () => {
     it("returns a body within the cap and refuses one over it", async () => {
         await expect((0, utils_1.readResponseTextCapped)(new Response("hello"), 5)).resolves.toBe("hello");
@@ -132,6 +151,23 @@ describe("newid", () => {
         });
     });
 });
+describe("deterministicGroupMemberId", () => {
+    it("preserves the membership identity protocol across SDK versions", () => {
+        expect((0, utils_1.deterministicGroupMemberId)("00000000000000000000000001", "00000000000000000000000002")).toBe("000gmbr0jzkpw7vuc2ew84u8c");
+    });
+    it("is a stable peer id per group and user", () => {
+        const groupId = (0, utils_1.newid)();
+        const userId = (0, utils_1.newid)();
+        const id = (0, utils_1.deterministicGroupMemberId)(groupId, userId);
+        expect(id).toMatch(/^[a-z0-9]{25}$/);
+        expect((0, utils_1.isid)(id)).toBe(true);
+        expect((0, utils_1.isDeterministicGroupMemberId)(id)).toBe(true);
+        expect((0, utils_1.deterministicGroupMemberId)(groupId, userId)).toBe(id);
+        expect((0, utils_1.deterministicGroupMemberId)(groupId, (0, utils_1.newid)())).not.toBe(id);
+        expect((0, utils_1.deterministicGroupMemberId)(userId, groupId)).not.toBe(id);
+        expect((0, utils_1.isDeterministicGroupMemberId)((0, utils_1.newid)())).toBe(false);
+    });
+});
 describe("debounceByArgs", () => {
     beforeEach(() => {
         jest.useFakeTimers();

package/package.json

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