@peers-app/peers-sdk 0.26.0 → 0.26.1

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

@@ -7,6 +7,7 @@ const field_type_1 = require("../../types/field-type");
 const zod_types_1 = require("../../types/zod-types");
 const utils_1 = require("../../utils");
 const registry_1 = require("../registry");
+const tool_catalog_contract_1 = require("../system/tool-catalog-contract");
 const systemContracts = require("../system-contracts");
 const tool_catalog_1 = require("../tool-catalog");
 const tool_catalog_identity_1 = require("../tool-catalog-identity");
@@ -570,6 +571,280 @@ test("untargeted deterministic IDs and quarantined rows cannot be claimed by a p
     expect(() => (0, tool_catalog_1.validateToolCatalogWrite)({ ...row, catalogState: "quarantined" }, { ...row, catalogState: "resolved" })).toThrow(/Quarantined/);
     await f.catalog.dispose();
 });
+describe("bare deterministic row repair", () => {
+    const target = { contractId, version: 1, toolName: "read" };
+    const toolId = (0, tool_catalog_identity_1.deriveToolCatalogId)(target);
+    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: `Error: Missing tool catalog target: ${toolId}`,
+    };
+    const restored = {
+        ...bare,
+        contractId,
+        contractVersion: 1,
+        toolName: "read",
+        catalogIdentity: "deterministic",
+        catalogState: "resolved",
+        catalogReason: undefined,
+    };
+    test.each([undefined, "deterministic"].flatMap((catalogIdentity) => [undefined, "unresolved", "quarantined"].map((catalogState) => ({
+        catalogIdentity,
+        catalogState,
+    }))))("publication restores identity=$catalogIdentity state=$catalogState and preserves current policy", async (state) => {
+        const old = {
+            ...bare,
+            ...state,
+            packageId: (0, utils_1.newid)(),
+            codeRepository: "historical repository",
+            accessLevel: 70,
+            remoteAccessLevel: 60,
+            authorityPropagation: "cap",
+            isAssistantRunner: true,
+            detailedDescription: "saved details",
+            configSchema: { type: tools_1.IOSchemaType.none, fields: [] },
+        };
+        expect(() => (0, tool_catalog_1.validateToolCatalogWrite)(old, restored, toolId, true)).not.toThrow();
+        const f = fixture(new Map([[toolId, old]]));
+        const update = required(f.table.update.getMockImplementation());
+        f.table.update.mockImplementation(async (patch) => {
+            if (patch.toolId === toolId && patch.catalogState === "resolved") {
+                expect((0, tools_1.isToolCatalogPatch)(patch)).toBe(true);
+                expect(patch).toEqual({
+                    toolId,
+                    contractId,
+                    contractVersion: 1,
+                    toolName: "read",
+                    catalogIdentity: "deterministic",
+                    catalogState: "resolved",
+                    catalogReason: undefined,
+                });
+                f.rows.set(toolId, {
+                    ...required(f.rows.get(toolId)),
+                    accessLevel: 90,
+                    remoteAccessLevel: 80,
+                    authorityPropagation: "preserve",
+                });
+            }
+            return update(patch);
+        });
+        try {
+            await f.publish();
+            expect(f.rows.get(toolId)).toEqual({
+                ...old,
+                ...restored,
+                accessLevel: 90,
+                remoteAccessLevel: 80,
+                authorityPropagation: "preserve",
+            });
+            expect(f.registry.resolve(contractId, 1)?.name).toBe("Test");
+        }
+        finally {
+            await f.catalog.dispose();
+        }
+    });
+    test.each([
+        ["executable source", { code: "existing" }],
+        ["whitespace source", { code: " " }],
+        ["missing source", { code: undefined }],
+        ["another identity", { catalogIdentity: "legacy-alias" }],
+        ["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 }],
+        ["partial member name", { toolName: "read" }],
+    ])("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();
+    });
+    test.each([
+        ["missing target", { contractId: undefined, contractVersion: undefined, toolName: undefined }],
+        ["partial target", { contractVersion: undefined }],
+        ["invalid target", { contractVersion: 0 }],
+        ["nonmatching deterministic ID", { contractVersion: 2 }],
+        ["different member", { toolName: "write" }],
+        // A repair must resolve in the same write; it cannot retarget quarantine evidence.
+        ["quarantined state", { catalogState: "quarantined" }],
+        ["unset state", { catalogState: undefined }],
+        ["unset identity kind", { catalogIdentity: undefined }],
+    ])("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", () => {
+        for (const candidate of [
+            restored,
+            { ...bare, catalogState: "resolved" },
+            { ...bare, catalogState: undefined, usageDescription: "metadata" },
+        ])
+            expect(() => (0, tool_catalog_1.validateToolCatalogWrite)(bare, candidate)).toThrow(/Quarantined/);
+        const metadata = (0, tool_catalog_1.retainToolCatalogFields)(bare, {
+            ...legacy(toolId),
+            code: "",
+            name: "read",
+            usageDescription: "older peer metadata",
+        });
+        expect(() => (0, tool_catalog_1.validateToolCatalogWrite)(bare, metadata)).not.toThrow();
+        expect(metadata.catalogState).toBe("quarantined");
+    });
+    test("repair requires exactly one selected ID even when the first ID matches", async () => {
+        const ids = jest
+            .spyOn(await Promise.resolve().then(() => require("../tool-catalog-migrations")), "toolCatalogIds")
+            .mockReturnValue([toolId, (0, utils_1.newid)()]);
+        try {
+            expect(() => (0, tool_catalog_1.validateToolCatalogWrite)(bare, restored, toolId, true)).toThrow(/Quarantined/);
+        }
+        finally {
+            ids.mockRestore();
+        }
+    });
+    test.each([
+        { contractId, version: 1, toolName: "new-task" },
+        { contractId: "00muxgugn6xvs8f2r80ru205t", version: 1, toolName: "invoke" },
+    ])("aliases suppress deterministic repair for $toolName", async (aliasedTarget) => {
+        const deterministicId = (0, tool_catalog_identity_1.deriveToolCatalogId)(aliasedTarget);
+        const aliases = (0, tool_catalog_migrations_1.toolCatalogIds)(aliasedTarget);
+        const old = { ...bare, toolId: deterministicId, name: aliasedTarget.toolName };
+        const candidate = {
+            ...restored,
+            toolId: deterministicId,
+            contractId: aliasedTarget.contractId,
+            toolName: aliasedTarget.toolName,
+        };
+        expect(() => (0, tool_catalog_1.validateToolCatalogWrite)(old, candidate, deterministicId, true)).toThrow();
+        for (const alias of aliases)
+            expect(() => (0, tool_catalog_1.validateToolCatalogWrite)({ ...old, toolId: alias }, { ...candidate, toolId: alias, catalogIdentity: "legacy-alias" }, alias, true)).toThrow(/Quarantined/);
+        const f = fixture(new Map([[deterministicId, old]]));
+        try {
+            await f.publish({
+                ...definition([aliasedTarget.toolName]),
+                contractId: aliasedTarget.contractId,
+            });
+            expect(f.rows.get(deterministicId)).toEqual(old);
+            for (const alias of aliases)
+                expect(f.rows.get(alias)?.catalogIdentity).toBe("legacy-alias");
+            expect(f.table.save.mock.calls.some(([row]) => row.toolId === deterministicId)).toBe(false);
+        }
+        finally {
+            await f.catalog.dispose();
+        }
+    });
+    test.each([
+        "collision",
+        "quarantine",
+    ])("a later %s prevents all repair writes in the batch", async (failure) => {
+        const f = fixture();
+        await f.catalog.ready();
+        const hash = failure === "collision"
+            ? jest.spyOn(nacl, "hash").mockReturnValue(new Uint8Array(64))
+            : undefined;
+        const firstId = (0, tool_catalog_identity_1.deriveToolCatalogId)(target);
+        const old = { ...bare, toolId: firstId };
+        f.rows.set(firstId, old);
+        if (failure === "quarantine") {
+            const secondId = (0, tool_catalog_identity_1.deriveToolCatalogId)({ ...target, toolName: "write" });
+            f.rows.set(secondId, {
+                ...restored,
+                toolId: secondId,
+                toolName: "write",
+                catalogState: "quarantined",
+            });
+        }
+        f.table.update.mockClear();
+        f.table.save.mockClear();
+        try {
+            await expect(f.publish(definition(["read", "write"]))).rejects.toThrow(/collision|Quarantined/);
+            expect(f.rows.get(firstId)).toEqual(old);
+            expect(f.table.update).not.toHaveBeenCalled();
+            expect(f.table.save).not.toHaveBeenCalled();
+            expect(f.registry.resolve(contractId, 1)).toBeUndefined();
+        }
+        finally {
+            hash?.mockRestore();
+            await f.catalog.dispose();
+        }
+    });
+});
+test.each([
+    false,
+    true,
+])("system readiness restores the startup listTools row (quarantined=%s)", async (quarantined) => {
+    const definition = (0, tool_catalog_contract_1.getToolCatalogContractDefinition)();
+    const toolId = (0, tool_catalog_identity_1.deriveToolCatalogId)({
+        contractId: definition.contractId,
+        version: definition.version,
+        toolName: "listTools",
+    });
+    expect(toolId).toBe("000tool0ggg5rilyp6kbxevip");
+    const bare = {
+        ...legacy(toolId),
+        name: "listTools",
+        code: "",
+        catalogState: quarantined ? "quarantined" : undefined,
+        catalogReason: quarantined ? `Error: Missing tool catalog target: ${toolId}` : undefined,
+    };
+    const f = fixture(new Map([[toolId, bare]]));
+    try {
+        await f.catalog.ready();
+        expect(f.rows.get(toolId)).toMatchObject({
+            contractId: definition.contractId,
+            contractVersion: definition.version,
+            toolName: "listTools",
+            catalogIdentity: "deterministic",
+            catalogState: "resolved",
+            code: "",
+            accessLevel: 70,
+        });
+        expect(f.rows.get(toolId)?.catalogReason).toBeUndefined();
+        expect(f.registry.getProviderPackageId(definition.contractId, definition.version)).toBeDefined();
+        const writes = f.table.update.mock.calls.length;
+        await f.catalog.ready();
+        expect(f.table.update).toHaveBeenCalledTimes(writes);
+    }
+    finally {
+        await f.catalog.dispose();
+    }
+});
+test.each([
+    ["executable source", { code: "existing" }],
+    ["a different name", { name: "list-tools" }],
+    ["another identity", { catalogIdentity: "legacy-alias" }],
+])("system readiness still aborts on a real listTools quarantine with %s", async (_name, fields) => {
+    const definition = (0, tool_catalog_contract_1.getToolCatalogContractDefinition)();
+    const toolId = (0, tool_catalog_identity_1.deriveToolCatalogId)({
+        contractId: definition.contractId,
+        version: definition.version,
+        toolName: "listTools",
+    });
+    const quarantined = {
+        ...legacy(toolId),
+        name: "listTools",
+        code: "",
+        ...fields,
+        catalogState: "quarantined",
+        catalogReason: `Error: Missing tool catalog target: ${toolId}`,
+    };
+    const f = fixture(new Map([[toolId, quarantined]]));
+    const publish = jest.spyOn(f.registry, "replaceBatch");
+    try {
+        await expect(f.catalog.ready()).rejects.toThrow(`Quarantined tool identity: ${toolId}`);
+        expect(f.rows.get(toolId)).toEqual(quarantined);
+        expect(publish).not.toHaveBeenCalled();
+    }
+    finally {
+        await f.catalog.dispose();
+    }
+});
 test("host removal waits for publication and disposal cancels queued activation", async () => {
     const f = fixture();
     const provider = (0, utils_1.newid)();

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

@@ -26,9 +26,14 @@ export declare function retainToolCatalogFields<T extends Partial<ITool>>(existi
  *
  * Catalog identities are permanent. Unresolved legacy rows are a holdover until their
  * tools move to contracts: they stay ordinary rows that local writers and older
- * runtimes may delete.
+ * 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.
+ *
+ * @param catalogPatch - Only explicit local catalog patches may restore a bare
+ * deterministic row. Ordinary replacements and sync replay must leave it quarantined.
  */
-export declare function validateToolCatalogWrite(existing: Partial<ITool> | undefined, candidate: Partial<ITool> | undefined, recordId?: string | undefined): void;
+export declare function validateToolCatalogWrite(existing: Partial<ITool> | undefined, candidate: Partial<ITool> | undefined, recordId?: string | undefined, catalogPatch?: boolean): void;
 /**
  * Per-context runtime owner of permanent Tools identities. Construction is inert;
  * ready() explicitly initializes storage after UserContext construction completes.

package/dist/contracts/tool-catalog.js

@@ -62,6 +62,35 @@ function hasToolCatalogEvidence(row) {
         row.contractVersion !== undefined ||
         row.toolName !== undefined);
 }
+/**
+ * A catalog insert that lost its target columns, or was stored before those columns
+ * existed, still carries the member's deterministic ID, the member name and an empty
+ * executable. Publication may write the canonical target back, resolving the row in
+ * the same write; a repair cannot leave the target on a still-quarantined row. Any
+ * other bare `000tool0` row, including one that still holds executable source or a
+ * different name, stays unclaimable.
+ */
+function canRestoreBareDeterministicRow(existing, candidate) {
+    if (candidate.catalogState !== "resolved" || candidate.catalogIdentity !== "deterministic")
+        return false;
+    if (existing.code !== "")
+        return false;
+    if (existing.catalogIdentity !== undefined && existing.catalogIdentity !== "deterministic")
+        return false;
+    let target;
+    try {
+        if (toolCatalogTarget(existing))
+            return false;
+        target = toolCatalogTarget(candidate);
+    }
+    catch {
+        return false;
+    }
+    if (!target || !candidate.toolId || existing.name !== target.toolName)
+        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
@@ -70,9 +99,14 @@ function hasToolCatalogEvidence(row) {
  *
  * Catalog identities are permanent. Unresolved legacy rows are a holdover until their
  * tools move to contracts: they stay ordinary rows that local writers and older
- * runtimes may delete.
+ * 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.
+ *
+ * @param catalogPatch - Only explicit local catalog patches may restore a bare
+ * deterministic row. Ordinary replacements and sync replay must leave it quarantined.
  */
-function validateToolCatalogWrite(existing, candidate, recordId = candidate?.toolId ?? existing?.toolId) {
+function validateToolCatalogWrite(existing, candidate, recordId = candidate?.toolId ?? existing?.toolId, catalogPatch = false) {
     if (!candidate) {
         if ((recordId !== undefined && isReservedToolCatalogId(recordId)) ||
             (existing && hasToolCatalogEvidence(existing)))
@@ -83,7 +117,9 @@ 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");
-    if (existing?.catalogState === "quarantined" && candidate.catalogState !== "quarantined")
+    if (existing?.catalogState === "quarantined" &&
+        candidate.catalogState !== "quarantined" &&
+        !(catalogPatch && canRestoreBareDeterministicRow(existing, candidate)))
         throw new Error(`Quarantined tool identity: ${candidate.toolId}`);
     // Quarantine preserves the original evidence byte-for-byte; it cannot retarget it.
     if (existing &&
@@ -99,7 +135,10 @@ function validateToolCatalogWrite(existing, candidate, recordId = candidate?.too
     if (previous && (!target || (0, tool_catalog_identity_1.toolCatalogTargetKey)(previous) !== (0, tool_catalog_identity_1.toolCatalogTargetKey)(target)))
         throw new Error(`Tool catalog identity cannot change: ${candidate.toolId}`);
     if (target) {
-        if (existing && !previous && !legacy)
+        if (existing &&
+            !previous &&
+            !legacy &&
+            !(catalogPatch && canRestoreBareDeterministicRow(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}`);
@@ -364,9 +403,10 @@ class ToolCatalog {
                         ...resolvedFields(target, toolId),
                     };
                     const stored = existing.get(toolId);
-                    if (stored?.catalogState === "quarantined")
+                    if (stored?.catalogState === "quarantined" &&
+                        !canRestoreBareDeterministicRow(stored, row))
                         throw new Error(`Quarantined tool identity: ${toolId}`);
-                    validateToolCatalogWrite(stored, row);
+                    validateToolCatalogWrite(stored, row, toolId, true);
                     candidates.set(toolId, row);
                 }
             }
@@ -374,6 +414,18 @@ class ToolCatalog {
         // Validate the entire batch before the first write. Catalog metadata never
         // overwrites provider-specific policy or another provider's descriptions.
         for (const row of candidates.values()) {
+            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)) {
+                const restored = await table.update((0, tools_1.toolCatalogPatch)({
+                    toolId: row.toolId,
+                    ...resolvedFields(toolCatalogTarget(row), row.toolId),
+                }));
+                validateToolCatalogWrite(row, restored);
+                if (restored.catalogState === "quarantined")
+                    throw new Error(`Quarantined tool identity: ${row.toolId}`);
+            }
             // Older runtimes allowed provider removal to leave tombstones. Only a
             // validated public target may restore one; insert-only still preserves any
             // row that arrived concurrently, and the returned mapping is checked below.

package/package.json

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