@peers-app/peers-sdk 0.25.20 → 0.26.0

package/dist/package-installer/package-creator.test.js

@@ -1,14 +1,16 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+const system_ids_1 = require("../system-ids");
+const utils_1 = require("../utils");
 const package_creator_1 = require("./package-creator");
 const package_dev_tools_1 = require("./package-dev-tools");
 // --- Mocks for SDK internals ---
 const mockSignAndSavePkg = jest.fn();
 const mockGetPkg = jest.fn();
 jest.mock("../data/packages", () => ({
-    Packages: () => ({
-        signAndSave: mockSignAndSavePkg,
-        get: mockGetPkg,
+    Packages: (dataContext) => ({
+        signAndSave: (...args) => mockSignAndSavePkg(dataContext, ...args),
+        get: (packageId) => mockGetPkg(dataContext, packageId),
     }),
 }));
 const mockGroupDeviceVar = jest.fn();
@@ -36,6 +38,10 @@ jest.mock("./package-installer", () => ({
     installPackageFromBundles: (...args) => mockInstallPackageFromBundles(...args),
     getPackageInfo: (...args) => mockGetPackageInfo(...args),
 }));
+const { newKeys: realNewKeys } = jest.requireActual("../keys");
+const generatedKeys = realNewKeys();
+const sourceKeys = realNewKeys();
+const targetKeys = realNewKeys();
 // --- Test utilities ---
 function makeMockDeps(files, shellExec) {
     return {
@@ -67,6 +73,7 @@ function makeMockDeps(files, shellExec) {
 }
 function mockDataContext() {
     return {
+        dataContextId: (0, utils_1.newid)(),
         packageLoader: {
             loadPackage: jest.fn().mockResolvedValue(undefined),
         },
@@ -75,13 +82,10 @@ function mockDataContext() {
 // --- Tests ---
 beforeEach(() => {
     jest.clearAllMocks();
-    mockGetPkg.mockResolvedValue(undefined);
-    mockPersistentVarsFindOne.mockResolvedValue(undefined);
-    mockNewKeys.mockReturnValue({
-        publicKey: "test-public-key-abc",
-        secretKey: "test-secret-key-xyz",
-        publicBoxKey: "test-box-key",
-    });
+    mockGetPkg.mockReset().mockResolvedValue(undefined);
+    mockPersistentVarsFindOne.mockReset().mockResolvedValue(undefined);
+    mockNewKeys.mockReturnValue(generatedKeys);
+    mockPersistentVarsSave.mockReset();
 });
 describe("unwrapAddOrUpdatePackageResult", () => {
     it("accepts a legacy packageId string", () => {
@@ -204,7 +208,7 @@ describe("createPackage", () => {
             cwd: "/packages/my-widget",
         });
         // Verify package record was created
-        expect(mockSignAndSavePkg).toHaveBeenCalledWith(expect.objectContaining({
+        expect(mockSignAndSavePkg).toHaveBeenCalledWith(dc, expect.objectContaining({
             name: "My Widget",
             disabled: false,
         }), { restoreIfDeleted: true, saveAsSnapshot: true });
@@ -273,18 +277,18 @@ describe("createPackage", () => {
             personalContext: personalCtx,
         });
         expect(deps.shell.exec).not.toHaveBeenCalled();
-        expect(mockGetPkg).toHaveBeenCalledWith("00mnkoyo7mizav6tseubjzr3a");
+        expect(mockGetPkg).toHaveBeenCalledWith(dc, "00mnkoyo7mizav6tseubjzr3a");
         expect(mockNewKeys).toHaveBeenCalled();
         expect(mockPersistentVarsSave).toHaveBeenCalledWith(expect.objectContaining({
             name: "packageSigningKey_00mnkoyo7mizav6tseubjzr3a",
             isSecret: true,
-            value: { value: "test-secret-key-xyz" },
-        }));
-        expect(mockSignAndSavePkg).toHaveBeenCalledWith(expect.objectContaining({
+            value: { value: generatedKeys.secretKey },
+        }), { restoreIfDeleted: true });
+        expect(mockSignAndSavePkg).toHaveBeenCalledWith(dc, expect.objectContaining({
             packageId: "00mnkoyo7mizav6tseubjzr3a",
             name: "Existing Pkg",
             description: "Imported package",
-            publishPublicKey: "test-public-key-abc",
+            publishPublicKey: generatedKeys.publicKey,
         }), { restoreIfDeleted: true, saveAsSnapshot: true });
         expect(mockGroupDeviceVar).toHaveBeenCalledWith("packageLocalPath_00mnkoyo7mizav6tseubjzr3a", expect.any(Object));
         expect(pvarSetter).toHaveBeenCalledWith("/custom/path");
@@ -324,11 +328,145 @@ describe("createPackage", () => {
         });
         expect(mockNewKeys).not.toHaveBeenCalled();
         expect(mockPersistentVarsSave).not.toHaveBeenCalled();
-        expect(mockSignAndSavePkg).toHaveBeenCalledWith(expect.objectContaining({
+        expect(mockSignAndSavePkg).toHaveBeenCalledWith(dc, expect.objectContaining({
             publishPublicKey: "already-established-public-key",
             createdBy: "00m87fbwu96jzf8qnwllly0fd",
         }), expect.any(Object));
     });
+    describe("importing by name across contexts", () => {
+        const packageId = "00mnkoyo7mizav6tseubjzr3a";
+        let contexts;
+        let deps;
+        beforeEach(() => {
+            contexts = {
+                personal: mockDataContext(),
+                blankGroup: mockDataContext(),
+                group: mockDataContext(),
+                otherGroup: mockDataContext(),
+            };
+            const userContext = {
+                userId: contexts.personal.dataContextId,
+                userDataContext: contexts.personal,
+                groupDataContexts: new Map(Object.values(contexts)
+                    .slice(1)
+                    .map((dc) => [dc.dataContextId, dc])),
+            };
+            for (const dc of Object.values(contexts))
+                dc.userContext = userContext;
+            deps = makeMockDeps({ "/packages/existing-pkg/package.json": "{}" });
+            mockGetPackageInfo.mockResolvedValue({ packageId, description: "Imported package" });
+            mockGroupDeviceVar.mockReturnValue(jest.fn());
+            mockInstallPackageFromBundles.mockResolvedValue({ packageVersion: { packageId } });
+            mockPersistentVarsFindOne.mockResolvedValue({ value: { value: "unreadable-secret" } });
+        });
+        it.each([
+            ["group", "personal", ["personal", "blankGroup", "group"]],
+            ["group", "otherGroup", ["otherGroup", "personal", "blankGroup", "group"]],
+            ["personal", "group", ["group", "personal"]],
+        ])("reuses the key from %s when importing into %s", async (source, target, lookups) => {
+            mockGetPkg.mockImplementation(async (dc, id) => {
+                if (id !== packageId || dc === contexts[target])
+                    return undefined;
+                if (dc === contexts[source]) {
+                    return {
+                        publishPublicKey: sourceKeys.publicKey,
+                        name: "Source name",
+                        description: "Source description",
+                        createdBy: (0, utils_1.newid)(),
+                        disabled: true,
+                        activePackageVersionId: (0, utils_1.newid)(),
+                        versionFollowRange: "^1.0.0",
+                        followVersionTags: ["stable"],
+                        updateUrl: "source-url",
+                        remoteRepo: "source-repo",
+                        signature: "source-signature",
+                    };
+                }
+                if (dc === contexts.personal || dc === contexts.blankGroup) {
+                    return { publishPublicKey: " \t " };
+                }
+                return undefined;
+            });
+            const result = await (0, package_creator_1.createPackage)(contexts[target], deps, {
+                name: "Existing Pkg",
+                personalContext: contexts.personal,
+            });
+            expect(mockGetPkg.mock.calls).toEqual(lookups.map((name) => [contexts[name], packageId]));
+            expect(mockSignAndSavePkg).toHaveBeenCalledWith(contexts[target], expect.objectContaining({
+                packageId,
+                name: "Existing Pkg",
+                description: "Imported package",
+                publishPublicKey: sourceKeys.publicKey,
+                createdBy: system_ids_1.peersRootUserId,
+                disabled: false,
+                activePackageVersionId: undefined,
+                versionFollowRange: undefined,
+                followVersionTags: undefined,
+                updateUrl: undefined,
+                remoteRepo: undefined,
+                signature: "",
+            }), { restoreIfDeleted: true, saveAsSnapshot: true });
+            expect(mockInstallPackageFromBundles).toHaveBeenCalledWith(contexts[target], deps, packageId, {
+                localPath: "/packages/existing-pkg",
+            });
+            expect(result.packageVersion).toEqual({ packageId });
+            expect(mockNewKeys).not.toHaveBeenCalled();
+            expect(mockPersistentVarsSave).toHaveBeenCalledWith(expect.objectContaining({
+                value: { value: "unreadable-secret" },
+                description: expect.stringContaining(`v1:${packageId}:${sourceKeys.publicKey}`),
+            }));
+        });
+        it("keeps the target key without looking up a differing source key", async () => {
+            mockGetPkg.mockImplementation(async (dc) => ({
+                publishPublicKey: dc === contexts.otherGroup ? targetKeys.publicKey : sourceKeys.publicKey,
+            }));
+            await (0, package_creator_1.createPackage)(contexts.otherGroup, deps, {
+                name: "Existing Pkg",
+                personalContext: contexts.personal,
+            });
+            expect(mockGetPkg.mock.calls).toEqual([[contexts.otherGroup, packageId]]);
+            expect(mockSignAndSavePkg).toHaveBeenCalledWith(contexts.otherGroup, expect.objectContaining({ publishPublicKey: targetKeys.publicKey }), expect.any(Object));
+            expect(mockNewKeys).not.toHaveBeenCalled();
+            expect(mockPersistentVarsSave).toHaveBeenCalledWith(expect.objectContaining({
+                value: { value: "unreadable-secret" },
+                description: expect.stringContaining(`v1:${packageId}:${targetKeys.publicKey}`),
+            }));
+        });
+        it.each([
+            "missing",
+            "mismatch",
+            "lookup-error",
+            "empty-target",
+        ])("fails without installing or changing keys for %s", async (failure) => {
+            mockGetPkg.mockImplementation(async (dc) => {
+                if (dc === contexts.otherGroup) {
+                    return failure === "empty-target" ? { publishPublicKey: "" } : undefined;
+                }
+                if (failure === "lookup-error")
+                    throw new Error("source lookup failed");
+                return failure === "missing" ? undefined : { publishPublicKey: sourceKeys.publicKey };
+            });
+            if (failure === "mismatch") {
+                const { newKeys: realNewKeys } = jest.requireActual("../keys");
+                mockPersistentVarsFindOne.mockResolvedValue({ value: { value: realNewKeys().secretKey } });
+            }
+            await expect((0, package_creator_1.createPackage)(contexts.otherGroup, deps, {
+                name: "Existing Pkg",
+                personalContext: contexts.personal,
+            })).rejects.toThrow(failure === "mismatch"
+                ? "signing key mismatch"
+                : failure === "lookup-error"
+                    ? "source lookup failed"
+                    : "secret could not be hydrated");
+            if (failure === "empty-target") {
+                expect(mockGetPkg.mock.calls).toEqual([[contexts.otherGroup, packageId]]);
+            }
+            expect(mockSignAndSavePkg).not.toHaveBeenCalled();
+            expect(mockInstallPackageFromBundles).not.toHaveBeenCalled();
+            expect(mockNewKeys).not.toHaveBeenCalled();
+            expect(mockPersistentVarsSave).not.toHaveBeenCalled();
+        });
+    });
     it("throws when directory exists but has no valid package", async () => {
         const deps = makeMockDeps({});
         const dc = mockDataContext();
@@ -410,13 +548,13 @@ describe("createPackage", () => {
         expect(mockPersistentVarsSave).toHaveBeenCalledWith(expect.objectContaining({
             name: expect.stringMatching(/^packageSigningKey_[a-z0-9]{25}$/),
             scope: "user",
-            value: { value: "test-secret-key-xyz" },
+            value: { value: generatedKeys.secretKey },
             isSecret: true,
             description: expect.stringContaining("Signed Pkg"),
-        }));
+        }), { restoreIfDeleted: true });
         // Verify publishPublicKey was set on the package record
-        expect(mockSignAndSavePkg).toHaveBeenCalledWith(expect.objectContaining({
-            publishPublicKey: "test-public-key-abc",
+        expect(mockSignAndSavePkg).toHaveBeenCalledWith(dc, expect.objectContaining({
+            publishPublicKey: generatedKeys.publicKey,
         }), expect.any(Object));
     });
     it("skips key generation when personalContext is not provided", async () => {
@@ -441,7 +579,7 @@ describe("createPackage", () => {
         // Should NOT save any pvar
         expect(mockPersistentVarsSave).not.toHaveBeenCalled();
         // publishPublicKey should be empty string
-        expect(mockSignAndSavePkg).toHaveBeenCalledWith(expect.objectContaining({
+        expect(mockSignAndSavePkg).toHaveBeenCalledWith(dc, expect.objectContaining({
             publishPublicKey: "",
         }), expect.any(Object));
     });
@@ -454,9 +592,14 @@ describe("ensurePackageSigningKey", () => {
             packageId: "00mnkoyo7mizav6tseubjzr3a",
             packageName: "Test Pkg",
         });
-        expect(publicKey).toBe("test-public-key-abc");
+        expect(publicKey).toBe(generatedKeys.publicKey);
         expect(mockNewKeys).toHaveBeenCalledTimes(1);
         expect(mockPersistentVarsSave).toHaveBeenCalledTimes(1);
+        expect(mockPersistentVarsSave).toHaveBeenCalledWith(expect.objectContaining({
+            persistentVarId: (0, utils_1.deterministicPvarId)("packageSigningKey_00mnkoyo7mizav6tseubjzr3a"),
+            value: { value: generatedKeys.secretKey },
+            description: `Signing key for package "Test Pkg"\npeers-package-signing-key:v1:00mnkoyo7mizav6tseubjzr3a:${generatedKeys.publicKey}`,
+        }), { restoreIfDeleted: true });
     });
     it("reuses an established publishPublicKey without generating a new key", async () => {
         const personalCtx = mockDataContext();
@@ -489,6 +632,148 @@ describe("ensurePackageSigningKey", () => {
         expect(mockNewKeys).not.toHaveBeenCalled();
     });
 });
+describe("signing key recovery after uninstall", () => {
+    const packageId = "00mnkoyo7mizav6tseubjzr3a";
+    const marker = `peers-package-signing-key:v1:${packageId}:${generatedKeys.publicKey}`;
+    let record;
+    let deps;
+    let personalContext;
+    let target;
+    beforeEach(() => {
+        personalContext = mockDataContext();
+        target = mockDataContext();
+        record = {
+            persistentVarId: (0, utils_1.deterministicPvarId)(`packageSigningKey_${packageId}`),
+            name: `packageSigningKey_${packageId}`,
+            scope: "user",
+            isSecret: true,
+            value: { value: "encrypted-secret~nonce" },
+            description: 'Signing key for package "Test Pkg"',
+            modifiedAt: 123,
+        };
+        mockPersistentVarsFindOne.mockImplementation(async () => record);
+        mockPersistentVarsSave.mockImplementation(async (saved) => {
+            record = saved;
+        });
+        deps = makeMockDeps({ "/packages/test-pkg/package.json": "{}" });
+        mockGetPackageInfo.mockResolvedValue({ packageId, name: "test-pkg" });
+        mockGroupDeviceVar.mockReturnValue(jest.fn());
+        mockInstallPackageFromBundles.mockResolvedValue({ packageVersion: { packageId } });
+    });
+    async function importPackage(resolveSigningPublicKey) {
+        return (0, package_creator_1.createPackage)(target, deps, {
+            name: "Test Pkg",
+            personalContext,
+            resolveSigningPublicKey,
+        });
+    }
+    function expectNoWrites() {
+        expect(mockPersistentVarsSave).not.toHaveBeenCalled();
+        expect(mockNewKeys).not.toHaveBeenCalled();
+        expect(mockSignAndSavePkg).not.toHaveBeenCalled();
+        expect(mockGroupDeviceVar).not.toHaveBeenCalled();
+        expect(mockInstallPackageFromBundles).not.toHaveBeenCalled();
+    }
+    it("recovers a cached public key with no Packages row or decryption callback", async () => {
+        record.description += `\n${marker}`;
+        await importPackage();
+        expect(mockSignAndSavePkg).toHaveBeenCalledWith(target, expect.objectContaining({ publishPublicKey: generatedKeys.publicKey }), expect.any(Object));
+        expect(mockPersistentVarsSave).not.toHaveBeenCalled();
+        expect(mockNewKeys).not.toHaveBeenCalled();
+    });
+    it("recovers a legacy encrypted secret through the host and backfills only description once", async () => {
+        const original = { ...record };
+        const resolve = jest.fn(async () => generatedKeys.publicKey);
+        await importPackage(resolve);
+        expect(resolve).toHaveBeenCalledWith(original.value.value);
+        expect(mockPersistentVarsSave).toHaveBeenCalledWith({
+            ...original,
+            description: `${original.description}\n${marker}`,
+        });
+        await importPackage(resolve);
+        expect(mockPersistentVarsSave).toHaveBeenCalledTimes(1);
+        expect(record.value).toBe(original.value);
+        expect(mockNewKeys).not.toHaveBeenCalled();
+    });
+    it("retains raw-secret hydration and backfills its public key without invoking the host", async () => {
+        record.value = { value: generatedKeys.secretKey };
+        const resolve = jest.fn();
+        await importPackage(resolve);
+        expect(resolve).not.toHaveBeenCalled();
+        expect(record.description).toContain(marker);
+        expect(record.value.value).toBe(generatedKeys.secretKey);
+    });
+    it.each([
+        "absent",
+        "throws",
+        "undefined",
+        "invalid",
+    ])("fails safely when host recovery is %s", async (mode) => {
+        const resolve = mode === "absent"
+            ? undefined
+            : jest.fn(async () => {
+                if (mode === "throws")
+                    throw new Error(`sensitive ${record.value.value} ${generatedKeys.secretKey}`);
+                return mode === "invalid" ? "not-a-public-key" : undefined;
+            });
+        await expect(importPackage(resolve)).rejects.toThrow(`Package "Test Pkg" (${packageId}) has a signing secret pvar but no recoverable publishPublicKey, ` +
+            "and the secret could not be hydrated. Restore publishPublicKey or unlock the signing secret before importing.");
+        expectNoWrites();
+    });
+    it.each([
+        "established",
+        "cached",
+    ])("uses the %s key when host decryption fails", async (source) => {
+        if (source === "cached")
+            record.description += `\n${marker}`;
+        else
+            mockGetPkg.mockResolvedValue({ publishPublicKey: generatedKeys.publicKey });
+        await importPackage(async () => {
+            throw new Error("decryption unavailable");
+        });
+        expect(record.description).toContain(marker);
+        expect(record.value.value).toBe("encrypted-secret~nonce");
+        expect(mockNewKeys).not.toHaveBeenCalled();
+    });
+    it.each([
+        "",
+        `peers-package-signing-key:v2:${packageId}:${generatedKeys.publicKey}`,
+        `peers-package-signing-key:v1:${(0, utils_1.newid)()}:${generatedKeys.publicKey}`,
+        `peers-package-signing-key:v1:${packageId}:invalid-key`,
+        `${marker}:extra`,
+        `prefix ${marker}`,
+        `${marker}\n${marker}`,
+    ])("does not trust malformed or unrelated metadata: %s", async (description) => {
+        record.description = description;
+        await expect(importPackage()).rejects.toThrow("secret could not be hydrated");
+        expectNoWrites();
+    });
+    it("repairs malformed metadata after recovering a valid key", async () => {
+        record.description += `\npeers-package-signing-key:v1:${packageId}:invalid`;
+        await importPackage(async () => generatedKeys.publicKey);
+        expect(record.description).toBe(`Signing key for package "Test Pkg"\n${marker}`);
+        expect(record.value.value).toBe("encrypted-secret~nonce");
+    });
+    it.each([
+        "established/cache",
+        "raw/cache",
+        "host/cache",
+        "host/established",
+    ])("rejects a %s mismatch before writes", async (source) => {
+        if (source.endsWith("cache"))
+            record.description += `\n${marker}`;
+        if (source.startsWith("established") || source.endsWith("established")) {
+            mockGetPkg.mockResolvedValue({ publishPublicKey: sourceKeys.publicKey });
+        }
+        if (source === "raw/cache")
+            record.value = { value: sourceKeys.secretKey };
+        const resolve = source.startsWith("host")
+            ? async () => (source.endsWith("cache") ? sourceKeys.publicKey : generatedKeys.publicKey)
+            : undefined;
+        await expect(importPackage(resolve)).rejects.toThrow("signing key mismatch");
+        expectNoWrites();
+    });
+});
 describe("ensureTemplateCache", () => {
     it("clones template when cache directory does not exist", async () => {
         const deps = makeMockDeps({});

package/dist/package-installer/types.d.ts

@@ -83,6 +83,14 @@ export interface ICreatePackageOpts {
      * personal storage isn't available). The migration script backfills these.
      */
     personalContext?: import("../context/data-context").DataContext;
+    /**
+     * Optional host-only recovery for an encrypted personal signing secret. Return
+     * only its Ed25519 public key, or `undefined` when recovery is unavailable.
+     * Called after raw hydration fails, including when a public key is already known
+     * so mismatches can be rejected. Errors are suppressed without logging secret
+     * material; existing or cached public keys remain usable when decryption fails.
+     */
+    resolveSigningPublicKey?: (encryptedSecret: string) => Promise<string | undefined>;
 }
 /** Why a `git pull` of the cached package template did not succeed. */
 export type TemplateCacheRefreshFailure = "offline" | "could-not-refresh";

package/dist/package-loader/contract-package-loader.d.ts

@@ -1,18 +1,27 @@
 import type { DataContext } from "../context/data-context";
-import type { ContractRegistry } from "../contracts/registry";
+import { ContractRegistry } from "../contracts/registry";
 import type { IPackageDefinitionResult } from "../contracts/types";
 /**
  * Installs a contract-based package into a DataContext.
  *
  * Handles packages that export an `IPackageDefinitionResult` from `definePackage()`.
- * Registers contracts in the provided ContractRegistry, saves tools/assistants/workflows
- * with the `packageId` from the definition set, and registers table definitions.
+ * Materializes catalog identities and supplemental metadata, publishes contract providers,
+ * saves package assistants and registers table definitions after successful preparation.
  *
  * When a contract version was previously frozen (promoted to stable), the
  * installer preserves its stable status rather than re-registering it as dev.
+ * Without `opts.registry` or the context's PackageLoader registry, catalog rows
+ * are still written but no provider is published.
  */
 export declare function installContractPackage(dataContext: DataContext, packageDefinition: IPackageDefinitionResult, opts?: {
+    /** Registry to publish into; defaults to the context's PackageLoader registry. */
     registry?: ContractRegistry;
+    /** Complete fallible loader bookkeeping before provider publication. */
+    prepare?: () => Promise<void>;
+    /** Publish in-memory loader state in the same serialized activation turn. */
+    onActivated?: () => void;
+    /** Reject a load invalidated by unload, including after asynchronous preparation. */
+    assertCurrent?: () => void;
 }): Promise<void>;
 /**
  * Attempts to extract an `IPackageDefinitionResult` from a bundle's module exports.

package/dist/package-loader/contract-package-loader.js

@@ -4,68 +4,72 @@ exports.installContractPackage = installContractPackage;
 exports.extractPackageDefinition = extractPackageDefinition;
 exports.hasPackageDefinition = hasPackageDefinition;
 exports.finalizeContractsForPromotion = finalizeContractsForPromotion;
-const tools_1 = require("../data/tools");
-const tools_2 = require("../tools");
+const registry_1 = require("../contracts/registry");
+const tool_catalog_1 = require("../contracts/tool-catalog");
 /**
  * Installs a contract-based package into a DataContext.
  *
  * Handles packages that export an `IPackageDefinitionResult` from `definePackage()`.
- * Registers contracts in the provided ContractRegistry, saves tools/assistants/workflows
- * with the `packageId` from the definition set, and registers table definitions.
+ * Materializes catalog identities and supplemental metadata, publishes contract providers,
+ * saves package assistants and registers table definitions after successful preparation.
  *
  * When a contract version was previously frozen (promoted to stable), the
  * installer preserves its stable status rather than re-registering it as dev.
+ * Without `opts.registry` or the context's PackageLoader registry, catalog rows
+ * are still written but no provider is published.
  */
 async function installContractPackage(dataContext, packageDefinition, opts) {
     const { packageId } = packageDefinition;
-    const registry = opts?.registry;
-    const registrations = registry
-        ? packageDefinition.contracts.map((contract) => {
-            const key = `${contract.contractId}@${contract.version}`;
-            const alsoImpl = packageDefinition.alsoImplements.get(key) ?? [];
-            // If the contract is already frozen in the registry, re-register as
-            // stable instead of dev to preserve immutability.
-            const existing = registry.getDefinition(contract.contractId, contract.version);
-            let effectiveContract = contract;
-            if (existing && !existing.devTag && contract.devTag === "dev") {
-                effectiveContract = { ...contract, devTag: undefined };
+    const sharedRegistry = opts?.registry ?? dataContext.packageLoader?.contractRegistry;
+    // Without a context registry, providers go to a throwaway registry (none are
+    // published, as before) whose catalog is disposed with this call.
+    const registry = sharedRegistry ?? new registry_1.ContractRegistry();
+    const registrations = packageDefinition.contracts.map((contract) => {
+        const key = `${contract.contractId}@${contract.version}`;
+        const existing = registry.getDefinition(contract.contractId, contract.version);
+        const definition = existing && !existing.devTag && contract.devTag === "dev"
+            ? { ...contract, devTag: undefined }
+            : contract;
+        return { definition, alsoImplements: packageDefinition.alsoImplements.get(key) ?? [] };
+    });
+    const catalog = registry.toolCatalog ?? new tool_catalog_1.ToolCatalog(dataContext, registry);
+    const prepare = async () => {
+        opts?.assertCurrent?.();
+        // Install assistants with packageId
+        const { Assistants } = await Promise.resolve().then(() => require("../data/assistants"));
+        for (const assistant of packageDefinition.assistants) {
+            const assistantWithPackageId = { ...assistant, packageId };
+            await Assistants(dataContext).save(assistantWithPackageId);
+        }
+        await opts?.prepare?.();
+    };
+    const activate = () => {
+        opts?.assertCurrent?.();
+        // Publish table definitions in the guarded activation turn, after the
+        // coordinator's final catalog writes. Preparation must leave live tables alone.
+        if (packageDefinition.tableDefinitions.length) {
+            dataContext.tableContainer.registerTableDefinitions(packageDefinition.tableDefinitions, {
+                overwrite: true,
+            });
+        }
+        // Activate the new provider only after all fallible package-owned persistence
+        // has succeeded, so a failed update leaves the previous provider routable.
+        {
+            const result = registry.replaceBatch(packageId, registrations);
+            if (!result.valid) {
+                throw new Error(`Atomic contract registration failed for package ${packageId}: ${result.errors
+                    .map((error) => error.message)
+                    .join("; ")}`);
             }
-            return { definition: effectiveContract, alsoImplements: alsoImpl };
-        })
-        : undefined;
-    const validation = registrations ? registry?.validateBatch(packageId, registrations) : undefined;
-    if (validation && !validation.valid) {
-        throw new Error(`Atomic contract registration failed for package ${packageId}: ${validation.errors
-            .map((error) => error.message)
-            .join("; ")}`);
-    }
-    // Install tool instances with packageId
-    for (const toolInstance of packageDefinition.toolInstances) {
-        (0, tools_2.registerTool)(toolInstance);
-        const toolWithPackageId = { ...toolInstance.tool, packageId };
-        await (0, tools_1.Tools)(dataContext).save(toolWithPackageId);
-    }
-    // Install table definitions
-    for (const tableDefinition of packageDefinition.tableDefinitions) {
-        dataContext.tableContainer.registerTableDefinition(tableDefinition, {
-            overwrite: true,
-        });
-    }
-    // Install assistants with packageId
-    const { Assistants } = await Promise.resolve().then(() => require("../data/assistants"));
-    for (const assistant of packageDefinition.assistants) {
-        const assistantWithPackageId = { ...assistant, packageId };
-        await Assistants(dataContext).save(assistantWithPackageId);
-    }
-    // Activate the new provider only after all fallible package-owned persistence
-    // has succeeded, so a failed update leaves the previous provider routable.
-    if (registry && registrations) {
-        const result = registry.replaceBatch(packageId, registrations);
-        if (!result.valid) {
-            throw new Error(`Atomic contract registration failed for package ${packageId}: ${result.errors
-                .map((error) => error.message)
-                .join("; ")}`);
         }
+        opts?.onActivated?.();
+    };
+    try {
+        await catalog.publish(packageId, registrations, prepare, activate, packageDefinition.toolMetadata ?? []);
+    }
+    finally {
+        if (!sharedRegistry)
+            await catalog.dispose();
     }
 }
 /**

package/dist/package-loader/contract-package-loader.test.d.ts

@@ -1 +1 @@
-export {};
+import "../index";