@peers-app/peers-sdk 0.25.20 → 0.26.0

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

@@ -2,6 +2,7 @@ import type { DataContext } from "../context/data-context";
 import { type IContractProviderEndpointRequest } from "../contracts/contract-provider-router";
 import { type IContractConsumer, type IContractProviderEndpoint } from "../contracts/contract-proxy";
 import { ContractRegistry } from "../contracts/registry";
+import { ToolCatalog } from "../contracts/tool-catalog";
 import type { IConsumedContract, IRemoteContract, IRemoteContractConsumer } from "../contracts/types";
 import { type IPackage } from "../data/packages";
 import type { IPeersPackage } from "../types/peers-package";
@@ -29,17 +30,25 @@ export declare class PackageLoader {
     /** Host-injected Zod module used as the `zod` require. */
     static Zod: any;
     private hostConsumes;
+    private loadGenerations;
+    private hostActivationGenerations;
+    private consumedContractRouters;
+    private disposed;
     private packageInstances;
-    /** Packages that were installed via the contract-based path (tools/assistants/tables already saved with packageId). */
+    /** Packages installed through definePackage or isolation; providers own their executable members. */
     private contractInstalledPackages;
     /** Packages installed through the isolated runtime (no host eval). */
     private isolatedPackageIds;
     /**
      * In-memory contract providers for this data context. Seeded with system
-     * contracts at construction; package providers are added via
+     * contracts after catalog readiness; package providers are added via
      * {@link installContractPackage} or the isolated runtime.
      */
     readonly contractRegistry: ContractRegistry;
+    /** Permanent tool metadata owner for this context. */
+    readonly toolCatalog: ToolCatalog;
+    /** Lazy, retryable readiness boundary; performs no constructor-time database work. */
+    get catalogReady(): Promise<void>;
     /** Optional isolated-provider supervisor created from the host factory. */
     readonly isolatedRuntime?: IIsolatedPackageRuntime;
     /** Optional host `require` used when reading local bundles or evaluating legacy packages. */
@@ -87,6 +96,7 @@ export declare class PackageLoader {
      * @throws If no provider or matching endpoint implementation is available.
      */
     resolveContractEndpoint(request: IContractProviderEndpointRequest, opts?: IPackageContractEndpointOptions): Promise<IContractProviderEndpoint>;
+    private guardResolutionTools;
     /**
      * Bind a legacy package's declared consume to its selected provider.
      *
@@ -129,6 +139,7 @@ export declare class PackageLoader {
      * Dispose the isolated runtime for this data context.
      */
     dispose(): Promise<void>;
+    private retireHostEndpoints;
     /**
      * Resolve and load every non-disabled package in this data context.
      * Disabled packages that were previously loaded are unloaded.
@@ -156,6 +167,7 @@ export declare class PackageLoader {
         packageVersionId?: string;
     }): Promise<IPeersPackage | undefined>;
     private _readLocalBundle;
+    private guardLoad;
     /**
      * Post-correction: if the package definition carries a version string,
      * update the selected IPackageVersion record to match — but only when that

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

@@ -8,13 +8,11 @@ const contract_resolvers_1 = require("../contracts/contract-resolvers");
 const contract_transport_1 = require("../contracts/contract-transport");
 const registry_1 = require("../contracts/registry");
 const remote_contract_transport_1 = require("../contracts/remote-contract-transport");
-const system_contracts_1 = require("../contracts/system-contracts");
+const tool_catalog_1 = require("../contracts/tool-catalog");
 const files_1 = require("../data/files");
 const package_version_resolver_1 = require("../data/package-version-resolver");
 const package_versions_1 = require("../data/package-versions");
 const packages_1 = require("../data/packages");
-const tools_1 = require("../data/tools");
-const tools_2 = require("../tools");
 const contract_package_loader_1 = require("./contract-package-loader");
 const isolated_artifact_1 = require("./isolated-artifact");
 const isolated_persistent_var_gateway_1 = require("./isolated-persistent-var-gateway");
@@ -46,17 +44,27 @@ class PackageLoader {
     /** Host-injected Zod module used as the `zod` require. */
     static Zod;
     hostConsumes = new Map();
+    loadGenerations = new Map();
+    hostActivationGenerations = new Map();
+    consumedContractRouters = new Set();
+    disposed = false;
     packageInstances = {};
-    /** Packages that were installed via the contract-based path (tools/assistants/tables already saved with packageId). */
+    /** Packages installed through definePackage or isolation; providers own their executable members. */
     contractInstalledPackages = new Set();
     /** Packages installed through the isolated runtime (no host eval). */
     isolatedPackageIds = new Set();
     /**
      * In-memory contract providers for this data context. Seeded with system
-     * contracts at construction; package providers are added via
+     * contracts after catalog readiness; package providers are added via
      * {@link installContractPackage} or the isolated runtime.
      */
     contractRegistry;
+    /** Permanent tool metadata owner for this context. */
+    toolCatalog;
+    /** Lazy, retryable readiness boundary; performs no constructor-time database work. */
+    get catalogReady() {
+        return this.toolCatalog.ready();
+    }
     /** Optional isolated-provider supervisor created from the host factory. */
     isolatedRuntime;
     /** Optional host `require` used when reading local bundles or evaluating legacy packages. */
@@ -69,7 +77,7 @@ class PackageLoader {
     constructor(dataContext) {
         this.dataContext = dataContext;
         this.contractRegistry = new registry_1.ContractRegistry();
-        (0, system_contracts_1.installSystemContracts)(this.contractRegistry);
+        this.toolCatalog = new tool_catalog_1.ToolCatalog(dataContext, this.contractRegistry);
         const factory = (0, isolated_runtime_1.getIsolatedPackageRuntimeFactory)();
         if (factory) {
             this.isolatedRuntime = factory({
@@ -194,6 +202,7 @@ class PackageLoader {
      * @throws If no provider or matching endpoint implementation is available.
      */
     async resolveContractEndpoint(request, opts = {}) {
+        await this.catalogReady;
         // A route that names another device is forwarded over the mesh instead of being
         // resolved against a local provider. Only routers serving local principals set
         // targetDeviceId; remote-caller routers reject it before reaching this point.
@@ -208,7 +217,7 @@ class PackageLoader {
             request.providerPackageId ??
             this.contractRegistry.getProviderPackageId(request.contractId, request.version);
         if (!providerPackageId) {
-            const legacyResolver = (0, contract_resolvers_1.getContractResolver)(request.contractId, request.version);
+            const legacyResolver = (0, contract_resolvers_1.getContractResolver)(request.contractId, request.version, undefined, this.dataContext);
             if (!legacyResolver) {
                 throw new Error(`No contract provider registered for ${request.contractId} v${request.version}`);
             }
@@ -222,10 +231,28 @@ class PackageLoader {
                     },
                 }
                 : resolution;
-            return (0, contract_proxy_1.createContractProviderEndpoint)(localResolution, {
-                context: request.context,
-                notify: request.notify,
-            });
+            const assertProviderCurrent = () => {
+                if (this.disposed ||
+                    this.contractRegistry.getProviderPackageId(request.contractId, request.version) ||
+                    (0, contract_resolvers_1.getContractResolver)(request.contractId, request.version, undefined, this.dataContext) !==
+                        legacyResolver)
+                    throw new contract_provider_router_1.RetiredContractProviderEndpointError(guardedEndpoint);
+            };
+            const endpoint = (0, contract_proxy_1.createContractProviderEndpoint)(this.guardResolutionTools(localResolution, request, assertProviderCurrent), { context: request.context, notify: request.notify });
+            const guardedEndpoint = {
+                handleCall: async (call, context) => {
+                    if (call.member === "tool")
+                        await this.toolCatalog.assertTargetUsable({
+                            contractId: request.contractId,
+                            version: request.version,
+                            toolName: call.name,
+                        });
+                    assertProviderCurrent();
+                    return endpoint.handleCall(call, context);
+                },
+                dispose: () => endpoint.dispose(),
+            };
+            return guardedEndpoint;
         }
         if (!this.contractRegistry
             .getRegisteredProviderIds(request.contractId, request.version)
@@ -247,10 +274,11 @@ class PackageLoader {
             contractId: request.contractId,
             version: request.version,
         };
-        const resolver = (0, contract_resolvers_1.getContractResolver)(implementation.contractId, implementation.version, providerPackageId);
+        const resolver = (0, contract_resolvers_1.getContractResolver)(implementation.contractId, implementation.version, providerPackageId, this.dataContext);
         if (!resolver) {
             throw new Error(`Provider ${providerPackageId} has no live resolver for ${request.contractId} v${request.version}`);
         }
+        const generation = this.hostActivationGenerations.get(providerPackageId);
         const resolution = await resolver({ dataContext: this.dataContext });
         const localResolution = opts.resolveVariable
             ? {
@@ -261,7 +289,16 @@ class PackageLoader {
                 },
             }
             : resolution;
-        const endpoint = (0, contract_proxy_1.createContractProviderEndpoint)(localResolution, {
+        const assertProviderCurrent = () => {
+            const current = this.contractRegistry.getProviderImplementation(request.contractId, request.version, providerPackageId);
+            if (this.disposed ||
+                this.hostActivationGenerations.get(providerPackageId) !== generation ||
+                current?.contractId !== implementation.contractId ||
+                current?.version !== implementation.version ||
+                (0, contract_resolvers_1.getContractResolver)(implementation.contractId, implementation.version, providerPackageId, this.dataContext) !== resolver)
+                throw new contract_provider_router_1.RetiredContractProviderEndpointError(guardedEndpoint);
+        };
+        const endpoint = (0, contract_proxy_1.createContractProviderEndpoint)(this.guardResolutionTools(localResolution, request, assertProviderCurrent), {
             dispatchTool: (target, args, context) => this.dispatchToolFromProvider(providerPackageId, target, args, context),
             context: request.context,
             notify: (notification) => request.notify({
@@ -269,18 +306,45 @@ class PackageLoader {
                 contractId: request.contractId,
             }),
         });
-        if (implementation.contractId === request.contractId &&
-            implementation.version === request.version) {
-            return endpoint;
-        }
-        return {
-            handleCall: (call, context) => endpoint.handleCall({
-                ...call,
-                contractId: implementation.contractId,
-                version: implementation.version,
-            }, context),
+        const guardedEndpoint = {
+            handleCall: async (call, context) => {
+                if (call.member === "tool")
+                    await this.toolCatalog.assertTargetUsable({
+                        contractId: request.contractId,
+                        version: request.version,
+                        toolName: call.name,
+                    });
+                assertProviderCurrent();
+                return endpoint.handleCall({ ...call, contractId: implementation.contractId, version: implementation.version }, context);
+            },
             dispose: () => endpoint.dispose(),
         };
+        return guardedEndpoint;
+    }
+    guardResolutionTools(resolution, request, assertProviderCurrent) {
+        const guard = (instances) => instances &&
+            Object.fromEntries(Object.entries(instances).map(([name, instance]) => [
+                name,
+                {
+                    ...instance,
+                    // The dispatcher awaits authorization before calling toolFn. Check again
+                    // here so those awaits cannot retain old code. Once provider code has
+                    // started, its nested action errors must not request a router replay.
+                    toolFn: async (...args) => {
+                        await this.toolCatalog.assertTargetUsable({
+                            contractId: request.contractId,
+                            version: request.version,
+                            toolName: name,
+                        });
+                        assertProviderCurrent();
+                        return instance.toolFn(...args);
+                    },
+                },
+            ]));
+        return {
+            ...resolution,
+            tools: guard(resolution.tools),
+        };
     }
     /**
      * Bind a legacy package's declared consume to its selected provider.
@@ -293,6 +357,7 @@ class PackageLoader {
      * @returns A live consumer proxy, or `undefined` when no provider matches.
      */
     async resolveConsumedContract(dependency) {
+        await this.catalogReady;
         const selected = this.contractRegistry.selectProvider(dependency);
         if (!selected) {
             return undefined;
@@ -310,10 +375,12 @@ class PackageLoader {
         const consumer = (0, contract_proxy_1.createContractConsumer)(selected.definition, consumerTransport, {
             dataContextId: this.dataContext.dataContextId,
         });
+        this.consumedContractRouters.add(router);
         const dispose = consumer.dispose.bind(consumer);
         consumer.dispose = () => {
             dispose();
             router.dispose();
+            this.consumedContractRouters.delete(router);
         };
         return consumer;
     }
@@ -331,6 +398,7 @@ class PackageLoader {
      * @returns A per-device consumer factory, or `undefined` when the contract is unknown.
      */
     async resolveRemoteContract(declaration) {
+        await this.catalogReady;
         const definition = this.contractRegistry.getDefinition(declaration.contractId, declaration.version);
         if (!definition) {
             return undefined;
@@ -376,26 +444,50 @@ class PackageLoader {
      * @param packageId - Package to unload.
      */
     async unloadPackage(packageId) {
-        this.hostConsumes.delete(packageId);
-        if (this.isolatedRuntime?.isInstalled(packageId)) {
-            await this.isolatedRuntime.uninstall(packageId);
-        }
-        this.contractRegistry.unregister(packageId);
-        this.isolatedPackageIds.delete(packageId);
-        this.contractInstalledPackages.delete(packageId);
-        delete this.packageInstances[packageId];
+        // Invalidate loads before the first await, including those still resolving
+        // bundles or consumed contracts outside the catalog publication queue.
+        this.loadGenerations.set(packageId, (this.loadGenerations.get(packageId) ?? 0) + 1);
+        // Uninstall also queues behind an install that has not published yet.
+        await this.isolatedRuntime?.uninstall(packageId);
+        await this.toolCatalog.removeProvider(packageId, () => {
+            this.retireHostEndpoints(packageId);
+            (0, contract_resolvers_1.unregisterPackageContractResolvers)(this.dataContext, packageId);
+            this.hostConsumes.delete(packageId);
+            this.isolatedPackageIds.delete(packageId);
+            this.contractInstalledPackages.delete(packageId);
+            delete this.packageInstances[packageId];
+        });
     }
     /**
      * Dispose the isolated runtime for this data context.
      */
     async dispose() {
+        this.disposed = true;
+        for (const router of this.consumedContractRouters)
+            router.dispose();
+        this.consumedContractRouters.clear();
+        await this.toolCatalog.dispose();
         if (this.isolatedRuntime) {
             await this.isolatedRuntime.dispose();
         }
+        for (const packageId of new Set([
+            ...Object.keys(this.packageInstances),
+            ...this.contractInstalledPackages,
+            ...this.hostConsumes.keys(),
+        ])) {
+            this.contractRegistry.unregister(packageId);
+            (0, contract_resolvers_1.unregisterPackageContractResolvers)(this.dataContext, packageId);
+        }
+        this.hostConsumes.clear();
         this.isolatedPackageIds.clear();
         this.contractInstalledPackages.clear();
         this.packageInstances = {};
     }
+    retireHostEndpoints(packageId) {
+        this.hostActivationGenerations.set(packageId, (this.hostActivationGenerations.get(packageId) ?? 0) + 1);
+        for (const router of this.consumedContractRouters)
+            router.invalidateProvider(packageId);
+    }
     /**
      * Resolve and load every non-disabled package in this data context.
      * Disabled packages that were previously loaded are unloaded.
@@ -403,6 +495,7 @@ class PackageLoader {
      * @param opts - Forwarded to {@link resolveDevicePackageVersion}.
      */
     async loadAllPackages(opts) {
+        await this.catalogReady;
         const packages = await (0, packages_1.Packages)(this.dataContext).list();
         await Promise.all(packages.map(async (pkg) => {
             if (pkg.disabled) {
@@ -434,6 +527,7 @@ class PackageLoader {
             await this.unloadPackage(pkg.packageId);
             return undefined;
         }
+        const assertCurrent = this.guardLoad(pkg.packageId);
         if (this.packageInstances[pkg.packageId] && !opts?.force) {
             return this.packageInstances[pkg.packageId];
         }
@@ -478,7 +572,7 @@ class PackageLoader {
             }
             if (!bundleCode)
                 return;
-            return await this._loadBundle(pkg, bundleCode, selectedPackageVersion, usingLocalBundle, opts?.force === true);
+            return await this._loadBundle(pkg, bundleCode, selectedPackageVersion, usingLocalBundle, opts?.force === true, assertCurrent);
         }
         catch (err) {
             if (isIsolatedArtifactError(err)) {
@@ -489,7 +583,7 @@ class PackageLoader {
                 try {
                     const localBundleCode = this._readLocalBundle(localPath);
                     if (localBundleCode) {
-                        return await this._loadBundle(pkg, localBundleCode, selectedPackageVersion, true, opts?.force === true);
+                        return await this._loadBundle(pkg, localBundleCode, selectedPackageVersion, true, opts?.force === true, assertCurrent);
                     }
                 }
                 catch (localErr) {
@@ -516,6 +610,13 @@ class PackageLoader {
             return;
         }
     }
+    guardLoad(packageId) {
+        const generation = this.loadGenerations.get(packageId) ?? 0;
+        return () => {
+            if (this.disposed || generation !== (this.loadGenerations.get(packageId) ?? 0))
+                throw new Error(`Package load invalidated: ${packageId}`);
+        };
+    }
     /**
      * Post-correction: if the package definition carries a version string,
      * update the selected IPackageVersion record to match — but only when that
@@ -546,18 +647,21 @@ class PackageLoader {
             console.warn(`[PackageLoader] Failed to correct version for ${pkg.name}:`, error instanceof Error ? error.message : String(error));
         }
     }
-    async _loadBundle(pkg, bundleCode, selectedPackageVersion, usingLocalBundle, force) {
+    async _loadBundle(pkg, bundleCode, selectedPackageVersion, usingLocalBundle, force, assertCurrent = this.guardLoad(pkg.packageId)) {
+        assertCurrent();
         if ((0, isolated_artifact_1.looksLikeIsolatedPackageArtifact)(bundleCode)) {
             try {
                 const artifact = (0, isolated_artifact_1.parseIsolatedPackageArtifact)(bundleCode);
-                return await this._installIsolated(pkg, artifact, selectedPackageVersion, usingLocalBundle, force);
+                return await this._installIsolated(pkg, artifact, selectedPackageVersion, usingLocalBundle, force, assertCurrent);
             }
             catch (err) {
                 throw wrapIsolatedArtifactError(err);
             }
         }
+        await this.catalogReady;
+        assertCurrent();
         const replacingIsolated = this.isolatedRuntime?.isInstalled(pkg.packageId) ?? false;
-        const instance = await this._evaluateBundle(pkg, bundleCode, selectedPackageVersion, force);
+        const instance = await this._evaluateBundle(pkg, bundleCode, selectedPackageVersion, force, assertCurrent);
         if (!instance) {
             return undefined;
         }
@@ -569,7 +673,8 @@ class PackageLoader {
         }
         return instance;
     }
-    async _installIsolated(pkg, artifact, selectedPackageVersion, usingLocalBundle, force) {
+    async _installIsolated(pkg, artifact, selectedPackageVersion, usingLocalBundle, force, assertCurrent) {
+        assertCurrent();
         if (artifact.manifest.packageId !== pkg.packageId) {
             throw wrapIsolatedArtifactError(new Error(`Isolated packageId mismatch: artifact has "${artifact.manifest.packageId}" but DB record has "${pkg.packageId}"`));
         }
@@ -579,6 +684,7 @@ class PackageLoader {
         if (artifact.manifest.version !== selectedPackageVersion.version) {
             if (usingLocalBundle && selectedPackageVersion.versionTag === "dev") {
                 await this.correctPackageVersion(pkg, selectedPackageVersion, artifact.manifest.version);
+                assertCurrent();
                 if (artifact.manifest.version !== selectedPackageVersion.version) {
                     throw wrapIsolatedArtifactError(new Error(`Could not correct selected dev PackageVersion to isolated artifact version "${artifact.manifest.version}"`));
                 }
@@ -592,7 +698,8 @@ class PackageLoader {
             console.warn(`[PackageLoader] Skipping isolated package "${pkg.name}" because this host does not provide an isolated runtime.`);
             return undefined;
         }
-        const installOptions = isolatedContractLifecycle(selectedPackageVersion);
+        assertCurrent();
+        const installOptions = { ...isolatedContractLifecycle(selectedPackageVersion), assertCurrent };
         if (this.isolatedRuntime.isInstalled(pkg.packageId)) {
             if (!force) {
                 return this.packageInstances[pkg.packageId];
@@ -602,6 +709,9 @@ class PackageLoader {
         else {
             await this.isolatedRuntime.install(artifact, installOptions);
         }
+        assertCurrent();
+        this.retireHostEndpoints(pkg.packageId);
+        (0, contract_resolvers_1.unregisterPackageContractResolvers)(this.dataContext, pkg.packageId);
         this.isolatedPackageIds.add(pkg.packageId);
         this.contractInstalledPackages.add(pkg.packageId);
         const instance = {
@@ -611,7 +721,7 @@ class PackageLoader {
         this.packageInstances[pkg.packageId] = instance;
         return instance;
     }
-    async _evaluateBundle(pkg, bundleCode, selectedPackageVersion, force) {
+    async _evaluateBundle(pkg, bundleCode, selectedPackageVersion, force, assertCurrent = this.guardLoad(pkg.packageId)) {
         // Node.js built-in modules that do not exist in React Native (and would cause
         // a fatal native error if passed through to RN's require). We block them here
         // and throw a descriptive JS Error instead, which the surrounding try/catch
@@ -675,8 +785,9 @@ class PackageLoader {
             }
         };
         try {
+            assertCurrent();
             const bundleFunction = new Function("module", "exports", "require", bundleCode);
-            bundleFunction(module, moduleExports, customRequire);
+            const activateResolvers = (0, contract_resolvers_1.stagePackageContractResolvers)(this.dataContext, pkg.packageId, () => bundleFunction(module, moduleExports, customRequire));
             const bundleExports = module.exports;
             // Check for contract-based package definition (new path)
             const packageDefinition = (0, contract_package_loader_1.extractPackageDefinition)(bundleExports);
@@ -684,42 +795,53 @@ class PackageLoader {
                 if (packageDefinition.packageId !== pkg.packageId) {
                     console.warn(`[PackageLoader] packageId mismatch: definition has "${packageDefinition.packageId}" but DB record has "${pkg.packageId}"`);
                 }
-                await (0, resolve_consumed_contracts_1.resolveConsumedContracts)(this.dataContext, this.contractRegistry, packageDefinition);
-                await (0, contract_package_loader_1.installContractPackage)(this.dataContext, packageDefinition, {
-                    registry: this.contractRegistry,
-                });
-                this.hostConsumes.set(packageDefinition.packageId, packageDefinition.consumes);
-                this.contractInstalledPackages.add(packageDefinition.packageId);
-                await this.correctPackageVersion(pkg, selectedPackageVersion, packageDefinition.version);
                 // Build a proper IPeersPackage from the contract definition so callers
                 // (e.g. package-installer) can read appNavs, assistants, etc.
                 const contractPackageInstance = {
                     packageId: packageDefinition.packageId,
                     appNavs: packageDefinition.appNavs,
                     assistants: packageDefinition.assistants,
-                    toolInstances: packageDefinition.toolInstances,
                     tableDefinitions: packageDefinition.tableDefinitions,
                 };
-                this.packageInstances[pkg.packageId] = contractPackageInstance;
+                await (0, contract_package_loader_1.installContractPackage)(this.dataContext, packageDefinition, {
+                    registry: this.contractRegistry,
+                    assertCurrent,
+                    prepare: () => this.correctPackageVersion(pkg, selectedPackageVersion, packageDefinition.version),
+                    onActivated: () => {
+                        activateResolvers();
+                        this.retireHostEndpoints(pkg.packageId);
+                        this.hostConsumes.set(packageDefinition.packageId, packageDefinition.consumes);
+                        this.contractInstalledPackages.add(packageDefinition.packageId);
+                        this.packageInstances[pkg.packageId] = contractPackageInstance;
+                    },
+                });
+                // A package may declare remote/consume handles for its own contracts.
+                // Settle only after guarded activation makes those definitions and
+                // resolvers visible, outside the catalog's serialized publication turn.
+                await (0, resolve_consumed_contracts_1.resolveConsumedContracts)(this.dataContext, this.contractRegistry, packageDefinition);
+                assertCurrent();
                 return contractPackageInstance;
             }
             // Legacy path: extract IPeersPackage for backward compat
             const packageInstance = bundleExports?.exports || bundleExports?.package || bundleExports?.default || bundleExports;
             if (packageInstance && typeof packageInstance === "object") {
-                packageInstance.toolInstances?.forEach((toolInstance) => {
-                    (0, tools_2.registerTool)(toolInstance);
-                    (0, tools_1.Tools)(this.dataContext).save(toolInstance.tool);
-                });
-                packageInstance.tableDefinitions?.forEach((tableDefinition) => {
-                    this.dataContext.tableContainer.registerTableDefinition(tableDefinition, {
-                        overwrite: true,
-                    });
+                const tools = packageInstance.toolInstances;
+                if (Array.isArray(tools) && tools.length)
+                    throw new Error(`Package '${pkg.name}' (${pkg.packageId}) ships legacy executable tools, which this runtime no longer runs; upgrade it to definePackage() contract tools (docs/Packages/contracts.md#migrating-from-toolinstances)`);
+                await this.toolCatalog.publish(pkg.packageId, [], async () => assertCurrent(), () => {
+                    assertCurrent();
+                    // Final catalog writes must succeed before changing active host tables.
+                    if (packageInstance.tableDefinitions?.length) {
+                        this.dataContext.tableContainer.registerTableDefinitions(packageInstance.tableDefinitions, { overwrite: true });
+                    }
+                    activateResolvers();
+                    this.retireHostEndpoints(pkg.packageId);
+                    if (force && this.contractInstalledPackages.has(pkg.packageId)) {
+                        this.contractRegistry.unregister(pkg.packageId);
+                        this.contractInstalledPackages.delete(pkg.packageId);
+                    }
+                    this.packageInstances[pkg.packageId] = packageInstance;
                 });
-                if (force && this.contractInstalledPackages.has(pkg.packageId)) {
-                    this.contractRegistry.unregister(pkg.packageId);
-                    this.contractInstalledPackages.delete(pkg.packageId);
-                }
-                this.packageInstances[pkg.packageId] = packageInstance;
                 return packageInstance;
             }
             return;