@peers-app/peers-sdk 0.25.20 → 0.26.0

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

@@ -0,0 +1,649 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+require("../../index");
+const nacl = require("tweetnacl");
+const tools_1 = require("../../data/tools");
+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 systemContracts = require("../system-contracts");
+const tool_catalog_1 = require("../tool-catalog");
+const tool_catalog_identity_1 = require("../tool-catalog-identity");
+const tool_catalog_migrations_1 = require("../tool-catalog-migrations");
+function required(value) {
+    if (value === undefined)
+        throw new Error("Missing fixture value");
+    return value;
+}
+const contractId = "00mp287gdl5atltgs5bh0vm9z";
+function definition(names = ["read"], version = 1) {
+    return {
+        contractId,
+        version,
+        name: "Test",
+        description: "",
+        devTag: "dev",
+        tables: [],
+        observables: [],
+        tools: names.map((name) => ({
+            name,
+            usageDescription: name,
+            inputFields: [],
+            outputFields: [],
+        })),
+    };
+}
+function legacy(toolId = (0, utils_1.newid)()) {
+    return {
+        toolId,
+        name: "legacy",
+        usageDescription: "preserve",
+        code: "existing",
+        inputSchema: { type: tools_1.IOSchemaType.none, fields: [] },
+        outputSchema: { type: tools_1.IOSchemaType.none, fields: [] },
+        accessLevel: 70,
+    };
+}
+function fixture(rows = new Map()) {
+    const listeners = new Set();
+    const table = {
+        list: async () => [...rows.values()],
+        get: async (id) => rows.get(id),
+        update: jest.fn(async (patch) => {
+            const row = tools_1.toolSchema.parse({ ...rows.get(patch.toolId), ...patch });
+            rows.set(row.toolId, row);
+            for (const listener of listeners)
+                listener({ dataObject: row, op: "update", source: "local" });
+            return row;
+        }),
+        save: jest.fn(async (row, options) => {
+            if (!options?.insertOnly || !rows.has(row.toolId))
+                rows.set(row.toolId, tools_1.toolSchema.parse(row));
+            for (const listener of listeners)
+                listener({ dataObject: rows.get(row.toolId), op: "insert", source: "local" });
+            return rows.get(row.toolId);
+        }),
+        dataChanged: {
+            subscribe: (fn) => {
+                listeners.add(fn);
+                return { unsubscribe: () => listeners.delete(fn) };
+            },
+        },
+    };
+    const context = {
+        dataContextId: (0, utils_1.newid)(),
+        tableContainer: { getTable: () => table },
+    };
+    const registry = new registry_1.ContractRegistry();
+    const catalog = new tool_catalog_1.ToolCatalog(context, registry);
+    const publish = async (def = definition(), provider = (0, utils_1.newid)(), prepare = async () => { }) => catalog.publish(provider, [{ definition: def }], prepare, () => registry.replaceBatch(provider, [{ definition: def }]));
+    return { rows, table, registry, catalog, publish, listeners };
+}
+test.each([
+    "save",
+    "snapshot",
+])("system readiness rejects quarantine during a later %s before publishing any provider", async (boundary) => {
+    const first = definition();
+    const second = { ...definition(), contractId: (0, utils_1.newid)() };
+    const inventory = jest.spyOn(systemContracts, "listSystemContracts").mockReturnValue([
+        { providerPackageId: (0, utils_1.newid)(), getDefinition: () => first },
+        { providerPackageId: (0, utils_1.newid)(), getDefinition: () => second },
+    ]);
+    const f = fixture();
+    const publish = jest.spyOn(f.registry, "replaceBatch");
+    const firstId = (0, tool_catalog_migrations_1.toolCatalogIds)({ contractId: first.contractId, version: 1, toolName: "read" })[0];
+    const secondId = (0, tool_catalog_migrations_1.toolCatalogIds)({
+        contractId: second.contractId,
+        version: 1,
+        toolName: "read",
+    })[0];
+    const quarantine = () => f.table.update({ toolId: firstId, catalogState: "quarantined" });
+    if (boundary === "save") {
+        const save = f.table.save.getMockImplementation();
+        if (!save)
+            throw new Error("Missing fixture save");
+        f.table.save.mockImplementation(async (row, options) => {
+            const saved = await save(row, options);
+            if (row.toolId === secondId)
+                await quarantine();
+            return saved;
+        });
+    }
+    else {
+        const get = f.table.get;
+        jest.spyOn(f.table, "get").mockImplementation(async (id) => {
+            if (id === secondId)
+                await quarantine();
+            return get(id);
+        });
+    }
+    try {
+        await expect(f.catalog.ready()).rejects.toThrow(/quarantined/i);
+        expect(publish).not.toHaveBeenCalled();
+        expect(f.registry.getProviderPackageId(first.contractId, 1)).toBeUndefined();
+        expect(f.registry.getProviderPackageId(second.contractId, 1)).toBeUndefined();
+        expect(f.rows.get(firstId)?.catalogState).toBe("quarantined");
+        expect(f.rows.has(secondId)).toBe(true);
+        expect(f.listeners.size).toBe(0);
+    }
+    finally {
+        await f.catalog.dispose();
+        inventory.mockRestore();
+    }
+});
+describe("permanent Tools identity", () => {
+    test("delete validation protects reserved identities before rows exist", () => {
+        for (const id of [
+            tool_catalog_migrations_1.toolCatalogMigrations[0].toolId,
+            (0, tool_catalog_identity_1.deriveToolCatalogId)({ contractId, version: 1, toolName: "read" }),
+        ]) {
+            expect(() => (0, tool_catalog_1.validateToolCatalogWrite)(undefined, undefined, id)).toThrow(/permanent/);
+        }
+        expect(() => (0, tool_catalog_1.validateToolCatalogWrite)(undefined, undefined, (0, utils_1.newid)())).not.toThrow();
+        const target = { contractId, contractVersion: 1, toolName: "read" };
+        for (const row of [
+            { ...legacy(), ...target },
+            { ...legacy(), catalogState: "quarantined" },
+        ])
+            expect(() => (0, tool_catalog_1.validateToolCatalogWrite)(row, undefined)).toThrow(/permanent/);
+    });
+    test("unresolved legacy rows are ordinary rows that may be deleted", () => {
+        expect(() => (0, tool_catalog_1.validateToolCatalogWrite)(legacy(), undefined)).not.toThrow();
+        expect(() => (0, tool_catalog_1.validateToolCatalogWrite)({ ...legacy(), catalogState: "unresolved" }, undefined)).not.toThrow();
+    });
+    test.each([
+        [contractId, 1, "read", "000tool0m6n9qqflttd2vhqt0"],
+        [contractId, 2, "read", "000tool0hz4s7a3bzw0hx7h6e"],
+        [contractId, 1, "Read", "000tool0tkbtut20wcn4p2n9c"],
+        [contractId, 1, "é🛠", "000tool0w8lfnvvspj7cl3u9x"],
+        [contractId, 1, "é", "000tool0hcab9lwucf1sls3uk"],
+        [contractId, 1, "e\u0301", "000tool0m71grpdum3oh5ak0e"],
+        [contractId, 1, " read ", "000tool03ja6984o18ycrskkz"],
+        [contractId, 1, 'quote"\n\\', "000tool007ny5nm141nkk5puv"],
+        ["00MP287GDL5ATLTGS5BH0VM9Z", 1, "read", "000tool0xd9tnb6xvxcvtrojg"],
+        [contractId, Number.MAX_SAFE_INTEGER, "read", "000tool0yk5ipn4g8azf6c6yt"],
+    ])("golden %s v%s %s", (id, version, toolName, expected) => {
+        const target = {
+            contractId: id,
+            version: version,
+            toolName: toolName,
+        };
+        expect(Buffer.from((0, tool_catalog_identity_1.encodeToolCatalogTarget)(target)).toString()).toBe(JSON.stringify(["peers.tools-catalog.v1", id, version, toolName]));
+        expect((0, tool_catalog_identity_1.deriveToolCatalogId)(target)).toBe(expected);
+        expect((0, utils_1.isid)(expected)).toBe(true);
+        expect(zod_types_1.zodPeerId.safeParse(expected).success).toBe(true);
+    });
+    test("rejects malformed Unicode, unsafe versions and invalid time prefixes", () => {
+        for (const toolName of ["\ud800", "x\udfff", "\ud800x", ""])
+            expect(() => (0, tool_catalog_identity_1.validateToolCatalogTarget)({ contractId, version: 1, toolName })).toThrow();
+        for (const version of [0, -1, 1.1, Number.MAX_SAFE_INTEGER + 1])
+            expect(() => (0, tool_catalog_identity_1.validateToolCatalogTarget)({ contractId, version, toolName: "ok" })).toThrow();
+        expect(() => (0, tool_catalog_identity_1.validateToolCatalogTarget)({ contractId: "z".repeat(25), version: 1, toolName: "ok" })).toThrow();
+        expect(() => (0, tool_catalog_identity_1.validateToolCatalogTarget)({
+            contractId: { toString: () => contractId },
+            version: 1,
+            toolName: "ok",
+        })).toThrow();
+        expect((0, tool_catalog_identity_1.deriveToolCatalogId)({ contractId, version: 1, toolName: " read " })).not.toBe((0, tool_catalog_identity_1.deriveToolCatalogId)({ contractId, version: 1, toolName: "read" }));
+    });
+    test("canonical bytes preserve UTF-8 and JSON escaping exactly", () => {
+        expect(Buffer.from((0, tool_catalog_identity_1.encodeToolCatalogTarget)({ contractId, version: 1, toolName: "é🛠" })).toString("hex")).toBe("5b2270656572732e746f6f6c732d636174616c6f672e7631222c2230306d7032383767646c3561746c74677335626830766d397a222c312c22c3a9f09f9ba0225d");
+        expect(Buffer.from((0, tool_catalog_identity_1.encodeToolCatalogTarget)({ contractId, version: 1, toolName: 'quote"\n\\' })).toString("hex")).toBe("5b2270656572732e746f6f6c732d636174616c6f672e7631222c2230306d7032383767646c3561746c74677335626830766d397a222c312c2271756f74655c225c6e5c5c225d");
+    });
+    test("reserves literal inventory and preserves narrow shipped exceptions", () => {
+        for (const entry of tool_catalog_migrations_1.toolCatalogMigrations) {
+            expect((0, tool_catalog_migrations_1.resolveLegacyToolId)(entry.toolId)).toEqual({
+                contractId: entry.contractId,
+                version: entry.version,
+                toolName: entry.toolName,
+            });
+            expect(tools_1.toolSchema.safeParse(legacy(entry.toolId)).success).toBe(true);
+            (0, tool_catalog_identity_1.validateToolCatalogTarget)(entry);
+        }
+        expect(zod_types_1.zodPeerId.safeParse("000peers0toolaccessctl0001").success).toBe(false);
+        expect(zod_types_1.zodPeerId.safeParse("00muxgugn661g0qmpuwafrmsi4").success).toBe(false);
+        expect((0, tool_catalog_migrations_1.resolveLegacyToolId)("000peers0tool00querydb001")?.toolName).toBe("query-database");
+    });
+    test("many-to-one aliases have no winner; ambiguity fails closed", () => {
+        const target = { contractId: "00muxgugn6xvs8f2r80ru205t", version: 1, toolName: "invoke" };
+        expect((0, tool_catalog_migrations_1.toolCatalogIds)(target)).toEqual([
+            "00muxoa8xeet2lpi8bdq55q03",
+            "00muxob3hbo3f6g49mipy1hyt",
+        ]);
+        const entry = tool_catalog_migrations_1.toolCatalogMigrations[0];
+        expect(() => (0, tool_catalog_migrations_1.resolveLegacyToolId)(entry.toolId, [entry, { ...entry, toolName: "other" }])).toThrow(/Ambiguous/);
+    });
+});
+describe("per-context catalog lifecycle", () => {
+    test("system metadata changes only supplemental fields, preserving policy and history", async () => {
+        const f = fixture();
+        await f.catalog.ready();
+        const toolId = "000peers0tool00000runner1";
+        const stored = {
+            ...required(f.rows.get(toolId)),
+            code: "user source",
+            packageId: (0, utils_1.newid)(),
+            accessLevel: 90,
+            remoteAccessLevel: 80,
+            authorityPropagation: "cap",
+        };
+        f.rows.set(toolId, stored);
+        const metadata = {
+            ...stored,
+            code: "replacement",
+            packageId: (0, utils_1.newid)(),
+            name: "replacement",
+            accessLevel: 0,
+            remoteAccessLevel: 0,
+            authorityPropagation: "preserve",
+            isAssistantRunner: true,
+            configSchema: { type: tools_1.IOSchemaType.simple, fields: [] },
+            detailedDescription: "runner details",
+        };
+        await f.catalog.saveToolMetadata([metadata]);
+        expect(f.rows.get(toolId)).toEqual({
+            ...stored,
+            isAssistantRunner: true,
+            configSchema: metadata.configSchema,
+            detailedDescription: metadata.detailedDescription,
+        });
+        const count = f.table.update.mock.calls.length;
+        await f.catalog.saveToolMetadata([metadata]);
+        expect(f.table.update).toHaveBeenCalledTimes(count);
+        await f.catalog.dispose();
+    });
+    test("system metadata rejects unresolved, quarantined, missing and non-system targets", async () => {
+        const f = fixture();
+        await f.publish();
+        const id = "000peers0tool00000runner1";
+        const stored = required(f.rows.get(id));
+        for (const catalogState of ["unresolved", "quarantined"]) {
+            f.rows.set(id, { ...stored, catalogState });
+            await expect(f.catalog.saveToolMetadata([{ toolId: id }])).rejects.toThrow(/resolved system member/);
+        }
+        f.rows.delete(id);
+        for (const toolId of [
+            id,
+            (0, utils_1.newid)(),
+            (0, tool_catalog_identity_1.deriveToolCatalogId)({ contractId, version: 1, toolName: "read" }),
+        ])
+            await expect(f.catalog.saveToolMetadata([{ toolId }])).rejects.toThrow(/resolved system member/);
+        await f.catalog.dispose();
+    });
+    test("publication refreshes runner metadata only after successful preparation", async () => {
+        const f = fixture();
+        const def = definition();
+        const provider = (0, utils_1.newid)();
+        const metadata = { contractId, version: 1, toolName: "read", isAssistantRunner: true };
+        const id = (0, tool_catalog_migrations_1.toolCatalogIds)(metadata)[0];
+        await f.publish(def, provider);
+        const before = f.rows.get(id);
+        await expect(f.catalog.publish(provider, [{ definition: def }], async () => {
+            throw new Error("prepare failed");
+        }, () => { }, [metadata])).rejects.toThrow("prepare failed");
+        expect(f.rows.get(id)).toEqual(before);
+        await f.catalog.publish(provider, [{ definition: def }], async () => { }, () => { }, [metadata]);
+        expect(f.rows.get(id)?.isAssistantRunner).toBe(true);
+        await f.catalog.dispose();
+    });
+    test("contract upgrades and dev members refresh unclaimed descriptions only after preparation", async () => {
+        const f = fixture();
+        const provider = (0, utils_1.newid)();
+        const toolId = (0, tool_catalog_identity_1.deriveToolCatalogId)({ contractId, version: 1, toolName: "read" });
+        await f.publish(definition(), provider);
+        f.rows.set(toolId, { ...f.rows.get(toolId), accessLevel: 40 });
+        const changed = definition();
+        changed.tools[0] = {
+            ...changed.tools[0],
+            usageDescription: "changed",
+            inputFields: [{ name: "path", type: field_type_1.FieldType.string }],
+        };
+        const before = f.rows.get(toolId);
+        await expect(f.publish(changed, provider, async () => {
+            throw new Error("prepare failed");
+        })).rejects.toThrow("prepare failed");
+        expect(f.rows.get(toolId)).toEqual(before);
+        await f.publish(changed, provider);
+        expect(f.rows.get(toolId)).toMatchObject({
+            usageDescription: "changed",
+            inputSchema: { type: tools_1.IOSchemaType.simple, fields: changed.tools[0].inputFields },
+            accessLevel: 40,
+            catalogIdentity: "deterministic",
+        });
+        const updates = f.table.update.mock.calls.length;
+        await f.publish(changed, (0, utils_1.newid)());
+        expect(f.table.update).toHaveBeenCalledTimes(updates);
+        await f.catalog.dispose();
+    });
+    test("historical provenance limits description refresh to its provider", async () => {
+        const owner = (0, utils_1.newid)();
+        const old = { ...legacy("00muxoa8xeet2lpi8bdq55q03"), packageId: owner };
+        const f = fixture(new Map([[old.toolId, old]]));
+        const def = { ...definition(["invoke"]), contractId: "00muxgugn6xvs8f2r80ru205t" };
+        await f.publish(def, (0, utils_1.newid)());
+        expect(f.rows.get(old.toolId)?.usageDescription).toBe("preserve");
+        await f.publish(def, owner);
+        expect(f.rows.get(old.toolId)?.usageDescription).toBe("invoke");
+        await f.catalog.dispose();
+    });
+    test.each([
+        0, 1,
+    ])("disposal during initialization neither publishes %s system providers nor subscribes", async (count) => {
+        const system = definition();
+        const inventory = jest
+            .spyOn(systemContracts, "listSystemContracts")
+            .mockReturnValue(count ? [{ providerPackageId: (0, utils_1.newid)(), getDefinition: () => system }] : []);
+        const f = fixture();
+        let release;
+        let entered;
+        const held = new Promise((resolve) => {
+            release = resolve;
+        });
+        const entering = new Promise((resolve) => {
+            entered = resolve;
+        });
+        const list = f.table.list;
+        jest.spyOn(f.table, "list").mockImplementationOnce(async () => {
+            entered();
+            await held;
+            return list();
+        });
+        try {
+            const ready = f.catalog.ready();
+            await entering;
+            const disposing = f.catalog.dispose();
+            release();
+            await expect(ready).rejects.toThrow(/disposed/);
+            await disposing;
+            expect(f.registry.resolve(contractId, 1)).toBeUndefined();
+            expect(f.listeners.size).toBe(0);
+        }
+        finally {
+            inventory.mockRestore();
+        }
+    });
+    test("identical targets across providers and contexts; reversed install order", async () => {
+        const a = fixture();
+        const b = fixture();
+        const providers = [(0, utils_1.newid)(), (0, utils_1.newid)()];
+        for (const provider of providers)
+            await a.publish(definition(), provider);
+        for (const provider of [...providers].reverse())
+            await b.publish(definition(), provider);
+        expect([...a.rows.keys()].sort()).toEqual([...b.rows.keys()].sort());
+        await a.catalog.dispose();
+        await b.catalog.dispose();
+    });
+    test.each([false, true])("both aliases on fresh/upgraded database: %s", async (upgraded) => {
+        const old = legacy("00muxob3hbo3f6g49mipy1hyt");
+        const f = fixture(new Map(upgraded ? [[old.toolId, old]] : []));
+        await f.publish({ ...definition(["invoke"]), contractId: "00muxgugn6xvs8f2r80ru205t" });
+        expect(f.rows.has("00muxoa8xeet2lpi8bdq55q03")).toBe(true);
+        expect(f.rows.get(old.toolId)?.catalogIdentity).toBe("legacy-alias");
+        // No package claims the upgraded row, so the definition describes it; the
+        // primary key, legacy code and policy are preserved.
+        if (upgraded)
+            expect(f.rows.get(old.toolId)).toMatchObject({
+                ...old,
+                name: "invoke",
+                usageDescription: "invoke",
+                inputSchema: { type: tools_1.IOSchemaType.simple, fields: [] },
+                outputSchema: { type: tools_1.IOSchemaType.simple, fields: [] },
+            });
+        expect([...f.rows.values()].filter((r) => r.toolName === "invoke")).toHaveLength(2);
+        await f.catalog.dispose();
+    });
+    test("backfills unknown legacy rows without inventing targets and quarantines unknown mappings", async () => {
+        const old = legacy();
+        const bad = { ...legacy(), contractId, contractVersion: 1, toolName: "read" };
+        const f = fixture(new Map([
+            [old.toolId, old],
+            [bad.toolId, bad],
+        ]));
+        await f.catalog.ready();
+        expect(f.rows.get(old.toolId)).toMatchObject({ catalogState: "unresolved", code: "existing" });
+        expect(f.rows.get(bad.toolId)?.catalogState).toBe("quarantined");
+        await f.catalog.dispose();
+    });
+    test("persistence failures retry; replacement failure leaves active metadata untouched", async () => {
+        const f = fixture();
+        const provider = (0, utils_1.newid)();
+        await f.catalog.ready();
+        f.table.save.mockRejectedValueOnce(new Error("disk full"));
+        await expect(f.publish(definition(), provider)).rejects.toThrow("disk full");
+        expect(f.registry.resolve(contractId, 1)).toBeUndefined();
+        await f.publish(definition(), provider);
+        const before = [...f.rows.values()];
+        await expect(f.publish(definition(["read", "new"]), provider, async () => {
+            throw new Error("prepare failed");
+        })).rejects.toThrow("prepare failed");
+        expect(f.registry.resolve(contractId, 1)?.tools.map((t) => t.name)).toEqual(["read"]);
+        for (const row of before)
+            expect(f.rows.get(row.toolId)).toEqual(row);
+        expect([...f.rows.values()].some((r) => r.toolName === "new")).toBe(true);
+        await f.catalog.dispose();
+        const restarted = fixture(f.rows);
+        await restarted.publish();
+        await restarted.catalog.dispose();
+    });
+    test("concurrent providers cannot activate before serialized preparation finishes", async () => {
+        const f = fixture();
+        const order = [];
+        let release;
+        const held = new Promise((resolve) => {
+            release = resolve;
+        });
+        const first = f.publish(definition(), (0, utils_1.newid)(), async () => {
+            order.push("first");
+            await held;
+        });
+        const second = f.publish(definition(), (0, utils_1.newid)(), async () => {
+            order.push("second");
+        });
+        await new Promise((resolve) => setTimeout(resolve, 10));
+        expect(order).toEqual(["first"]);
+        expect(f.registry.resolve(contractId, 1)).toBeUndefined();
+        release();
+        await Promise.all([first, second]);
+        expect(order).toEqual(["first", "second"]);
+        await f.catalog.dispose();
+    });
+    test("forced hash collision and insert-only loser fail closed", async () => {
+        const f = fixture();
+        await f.catalog.ready();
+        const hash = jest.spyOn(nacl, "hash").mockReturnValue(new Uint8Array(64));
+        try {
+            await expect(f.publish(definition(["one", "two"]))).rejects.toThrow(/collision/);
+        }
+        finally {
+            hash.mockRestore();
+        }
+        expect(f.registry.resolve(contractId, 1)).toBeUndefined();
+        f.table.save.mockImplementationOnce(async (row) => ({ ...row, toolName: "wrong" }));
+        await expect(f.publish()).rejects.toThrow(/identity cannot change/);
+        await f.catalog.dispose();
+    });
+    test("alsoImplements indexes only older public members, and removal retains history", async () => {
+        const f = fixture();
+        const provider = (0, utils_1.newid)();
+        const older = definition(["old"]);
+        const newer = definition(["old", "new"], 2);
+        f.registry.register((0, utils_1.newid)(), older);
+        const regs = [{ definition: newer, alsoImplements: [{ contractId, version: 1 }] }];
+        await f.catalog.publish(provider, regs, async () => { }, () => f.registry.replaceBatch(provider, regs));
+        expect([...f.rows.values()]
+            .filter((r) => r.contractId === contractId)
+            .map((r) => [r.contractVersion, r.toolName])
+            .sort()).toEqual([
+            [1, "old"],
+            [2, "new"],
+            [2, "old"],
+        ]);
+        await f.publish(definition([], 2), provider);
+        f.registry.unregister(provider);
+        const count = f.rows.size;
+        await f.catalog.dispose();
+        expect(f.rows.size).toBe(count);
+        expect(f.listeners.size).toBe(0);
+    });
+    test("shared write guard rejects retargeting, stripping, deletion, and unverified aliases", () => {
+        const target = { contractId, version: 1, toolName: "read" };
+        const row = {
+            ...legacy((0, tool_catalog_identity_1.deriveToolCatalogId)(target)),
+            contractId,
+            contractVersion: 1,
+            toolName: "read",
+            catalogState: "resolved",
+        };
+        for (const candidate of [
+            undefined,
+            legacy(row.toolId),
+            { ...row, toolName: "other" },
+            { ...row, toolId: (0, utils_1.newid)() },
+        ])
+            expect(() => (0, tool_catalog_1.validateToolCatalogWrite)(row, candidate)).toThrow();
+        expect(() => (0, tool_catalog_1.validateToolCatalogWrite)(row, { ...row, usageDescription: "updated" })).not.toThrow();
+    });
+    test("pre-catalog full rows keep established identity; partial stripping still fails", () => {
+        const target = { contractId, version: 1, toolName: "read" };
+        const row = {
+            ...legacy((0, tool_catalog_identity_1.deriveToolCatalogId)(target)),
+            contractId,
+            contractVersion: 1,
+            toolName: "read",
+            catalogIdentity: "deterministic",
+            catalogState: "quarantined",
+            catalogReason: "conflict",
+        };
+        const older = { ...legacy(row.toolId), usageDescription: "from an older peer" };
+        const retained = (0, tool_catalog_1.retainToolCatalogFields)(row, older);
+        expect(retained).toEqual({ ...row, usageDescription: "from an older peer" });
+        expect(() => (0, tool_catalog_1.validateToolCatalogWrite)(row, retained)).not.toThrow();
+        const stripped = { ...row, contractId: undefined };
+        expect((0, tool_catalog_1.retainToolCatalogFields)(row, stripped)).toBe(stripped);
+        expect(() => (0, tool_catalog_1.validateToolCatalogWrite)(row, stripped)).toThrow();
+        expect((0, tool_catalog_1.retainToolCatalogFields)(undefined, older)).toBe(older);
+    });
+});
+test("Tools dataChanged reconciles new legacy evidence without recursive writes or provider activation", async () => {
+    const f = fixture();
+    await f.catalog.ready();
+    const row = legacy();
+    const count = f.table.save.mock.calls.length;
+    await f.table.save(row);
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    expect(f.rows.get(row.toolId)?.catalogState).toBe("unresolved");
+    expect(f.table.save.mock.calls.length - count).toBe(1);
+    expect(f.table.update).toHaveBeenCalledTimes(1);
+    expect(f.registry.resolve(contractId, 1)).toBeUndefined();
+    await f.catalog.dispose();
+});
+test("reconciliation does not overwrite metadata changed after its snapshot", async () => {
+    const old = legacy();
+    const f = fixture(new Map([[old.toolId, old]]));
+    f.table.update.mockImplementationOnce(async (patch) => {
+        expect(Object.keys(patch).sort()).toEqual(["catalogState", "toolId"]);
+        const current = { ...old, usageDescription: "synced while reconciling", accessLevel: 90 };
+        const saved = { ...current, ...patch };
+        f.rows.set(old.toolId, saved);
+        return saved;
+    });
+    await f.catalog.ready();
+    expect(f.rows.get(old.toolId)).toMatchObject({
+        catalogState: "unresolved",
+        usageDescription: "synced while reconciling",
+        accessLevel: 90,
+    });
+    await f.catalog.dispose();
+});
+test("untargeted deterministic IDs and quarantined rows cannot be claimed by a provider", async () => {
+    const target = { contractId, version: 1, toolName: "read" };
+    const old = legacy((0, tool_catalog_identity_1.deriveToolCatalogId)(target));
+    const f = fixture(new Map([[old.toolId, old]]));
+    await f.catalog.ready();
+    expect(f.rows.get(old.toolId)?.catalogState).toBe("quarantined");
+    await expect(f.publish()).rejects.toThrow(/Quarantined/);
+    expect(f.registry.resolve(contractId, 1)).toBeUndefined();
+    const row = { ...old, contractId, contractVersion: 1, toolName: "read" };
+    expect(() => (0, tool_catalog_1.validateToolCatalogWrite)(old, row)).toThrow(/cannot be claimed/);
+    expect(() => (0, tool_catalog_1.validateToolCatalogWrite)({ ...row, catalogState: "quarantined" }, { ...row, catalogState: "resolved" })).toThrow(/Quarantined/);
+    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)();
+    let release;
+    let prepared;
+    const preparing = new Promise((resolve) => {
+        prepared = resolve;
+    });
+    const held = new Promise((resolve) => {
+        release = resolve;
+    });
+    const installing = f.publish(definition(), provider, async () => {
+        prepared();
+        await held;
+    });
+    await preparing;
+    const deactivate = jest.fn();
+    const removing = f.catalog.removeProvider(provider, deactivate);
+    expect(deactivate).not.toHaveBeenCalled();
+    release();
+    await installing;
+    await removing;
+    expect(deactivate).toHaveBeenCalledTimes(1);
+    expect(f.registry.resolve(contractId, 1)).toBeUndefined();
+    expect(f.rows.has((0, tool_catalog_identity_1.deriveToolCatalogId)({ contractId, version: 1, toolName: "read" }))).toBe(true);
+    await f.catalog.dispose();
+    await expect(f.publish()).rejects.toThrow(/disposed/);
+});
+test("activation guard rejects quarantine after asynchronous activation work", async () => {
+    const f = fixture();
+    const toolId = (0, tool_catalog_identity_1.deriveToolCatalogId)({ contractId, version: 1, toolName: "read" });
+    const commit = jest.fn();
+    try {
+        await expect(f.catalog.publish((0, utils_1.newid)(), [{ definition: definition() }], async () => { }, async (assertCurrent) => {
+            await f.table.update({ toolId, catalogState: "quarantined" });
+            assertCurrent();
+            commit();
+        })).rejects.toThrow(/quarantined/);
+        expect(commit).not.toHaveBeenCalled();
+    }
+    finally {
+        await f.catalog.dispose();
+        expect(f.listeners.size).toBe(0);
+    }
+});
+test("removal requested during cold initialization follows the earlier publication", async () => {
+    const f = fixture();
+    const provider = (0, utils_1.newid)();
+    const installing = f.publish(definition(), provider);
+    const removing = f.catalog.removeProvider(provider, () => { });
+    await Promise.all([installing, removing]);
+    expect(f.registry.getProviderPackageId(contractId, 1)).toBeUndefined();
+    expect([...f.rows.values()].some((row) => row.contractId === contractId)).toBe(true);
+    await f.catalog.dispose();
+});
+test("ready upgrades unresolved host aliases, keeps policy, refreshes descriptions and restores missing rows", async () => {
+    const old = {
+        ...legacy("000peers0tool0creategroup"),
+        accessLevel: 40,
+        catalogState: "unresolved",
+    };
+    const f = fixture(new Map([[old.toolId, old]]));
+    await f.catalog.ready();
+    expect(f.rows.get(old.toolId)).toMatchObject({
+        catalogState: "resolved",
+        catalogIdentity: "legacy-alias",
+        name: "create-group",
+        accessLevel: 40,
+    });
+    expect(f.rows.get(old.toolId)?.usageDescription).not.toBe(old.usageDescription);
+    f.rows.delete(old.toolId);
+    await f.catalog.dispose();
+    const restarted = fixture(f.rows);
+    await restarted.catalog.ready();
+    expect(restarted.rows.get(old.toolId)?.catalogState).toBe("resolved");
+    await restarted.catalog.dispose();
+});

package/dist/contracts/__tests__/workflow-context.test.d.ts

@@ -0,0 +1 @@
+import "../../index";