@peers-app/peers-sdk 0.25.21 → 0.26.0

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

@@ -1,19 +1,49 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-jest.mock("../data/tools", () => ({
-    Tools: () => ({
-        save: jest.fn().mockResolvedValue(undefined),
-    }),
-}));
-jest.mock("../tools", () => ({
-    registerTool: jest.fn(),
-}));
+require("../index");
+const mockBeforeToolSave = jest.fn();
+jest.mock("../data/tools", () => {
+    const actual = jest.requireActual("../data/tools");
+    const contexts = new WeakMap();
+    return {
+        ...actual,
+        Tools: (context) => {
+            let rows = contexts.get(context);
+            if (!rows) {
+                rows = new Map();
+                contexts.set(context, rows);
+            }
+            const records = rows;
+            return {
+                list: async () => [...records.values()],
+                get: async (id) => records.get(id),
+                save: async (row, opts) => {
+                    await mockBeforeToolSave(row);
+                    if (!opts?.insertOnly || !records.has(row.toolId))
+                        records.set(row.toolId, row);
+                    return records.get(row.toolId);
+                },
+                update: async (patch) => {
+                    const row = { ...records.get(patch.toolId), ...patch };
+                    records.set(patch.toolId, row);
+                    return row;
+                },
+                dataChanged: { subscribe: () => ({ unsubscribe: () => true }) },
+            };
+        },
+    };
+});
 jest.mock("../data/assistants", () => ({
     Assistants: () => ({
         save: jest.fn().mockResolvedValue(undefined),
     }),
 }));
 const registry_1 = require("../contracts/registry");
+const tool_catalog_1 = require("../contracts/tool-catalog");
+const tool_catalog_identity_1 = require("../contracts/tool-catalog-identity");
+const table_container_1 = require("../data/orm/table-container");
+const tools_1 = require("../data/tools");
+const field_type_1 = require("../types/field-type");
 const utils_1 = require("../utils");
 const contract_package_loader_1 = require("./contract-package-loader");
 describe("installContractPackage registry wiring", () => {
@@ -40,7 +70,6 @@ describe("installContractPackage registry wiring", () => {
             alsoImplements: new Map(),
             assistants: [],
             appNavs: [],
-            toolInstances: [],
             tableDefinitions: [],
             ...overrides,
         };
@@ -49,7 +78,7 @@ describe("installContractPackage registry wiring", () => {
         return {
             dataContextId: "test-ctx",
             tableContainer: {
-                registerTableDefinition: jest.fn(),
+                registerTableDefinitions: jest.fn(),
             },
         };
     }
@@ -62,9 +91,59 @@ describe("installContractPackage registry wiring", () => {
         expect(registry.getProviderPackageId(contractId, 1)).toBe(packageId);
         expect(registry.getContractKeysForPackage(packageId)).toEqual([`${contractId}@1`]);
     });
+    it("persists CLI runner metadata without executable registration", async () => {
+        const registry = new registry_1.ContractRegistry();
+        const context = mockDataContext();
+        const tool = {
+            toolId: "00mlwl2km0iymo1hwhtvqij2n",
+            name: "cli_assistant_runner",
+            usageDescription: "CLI",
+            code: "",
+            inputSchema: { type: tools_1.IOSchemaType.none, fields: [] },
+            outputSchema: { type: tools_1.IOSchemaType.none, fields: [] },
+            isAssistantRunner: true,
+            configSchema: { type: tools_1.IOSchemaType.simple, fields: [] },
+        };
+        const definition = makeDefinition({
+            toolMetadata: [
+                {
+                    contractId: "00mp287gdomtx12ald8oelyp0",
+                    version: 1,
+                    toolName: tool.name,
+                    isAssistantRunner: true,
+                    configSchema: tool.configSchema,
+                },
+            ],
+        });
+        definition.contracts[0] = {
+            ...definition.contracts[0],
+            contractId: "00mp287gdomtx12ald8oelyp0",
+            tools: [{ name: tool.name, usageDescription: "CLI", inputFields: [], outputFields: [] }],
+        };
+        await (0, contract_package_loader_1.installContractPackage)(context, definition, { registry });
+        expect(await (0, tools_1.Tools)(context).get(tool.toolId)).toMatchObject({
+            isAssistantRunner: true,
+            configSchema: tool.configSchema,
+            catalogState: "resolved",
+        });
+        await registry.toolCatalog?.dispose();
+        jest.clearAllMocks();
+    });
     it("does not register providers when no registry is provided", async () => {
         const dataContext = mockDataContext();
-        await expect((0, contract_package_loader_1.installContractPackage)(dataContext, makeDefinition())).resolves.toBeUndefined();
+        const dispose = jest.spyOn(tool_catalog_1.ToolCatalog.prototype, "dispose");
+        try {
+            await expect((0, contract_package_loader_1.installContractPackage)(dataContext, makeDefinition())).resolves.toBeUndefined();
+            // The throwaway registry's catalog must not outlive the call.
+            expect(dispose).toHaveBeenCalledTimes(1);
+            const registry = new registry_1.ContractRegistry();
+            await (0, contract_package_loader_1.installContractPackage)(dataContext, makeDefinition(), { registry });
+            expect(dispose).toHaveBeenCalledTimes(1);
+            await registry.toolCatalog?.dispose();
+        }
+        finally {
+            dispose.mockRestore();
+        }
     });
     it("keeps the previous provider active when package persistence fails", async () => {
         const registry = new registry_1.ContractRegistry();
@@ -72,7 +151,7 @@ describe("installContractPackage registry wiring", () => {
         previous.contracts[0] = { ...previous.contracts[0], name: "Previous Contract" };
         await (0, contract_package_loader_1.installContractPackage)(mockDataContext(), previous, { registry });
         const dataContext = mockDataContext();
-        dataContext.tableContainer.registerTableDefinition.mockImplementation(() => {
+        dataContext.tableContainer.registerTableDefinitions.mockImplementation(() => {
             throw new Error("table registration failed");
         });
         const replacement = makeDefinition({
@@ -82,6 +161,87 @@ describe("installContractPackage registry wiring", () => {
         expect(registry.resolve(contractId, 1)?.name).toBe("Previous Contract");
         expect(registry.getProviderPackageId(contractId, 1)).toBe(packageId);
     });
+    it.each([
+        "catalog-write",
+        "invalid-table",
+    ])("keeps active host tables through %s failure and permits retry", async (failure) => {
+        const registry = new registry_1.ContractRegistry();
+        const container = new table_container_1.TableContainer((metaData) => ({ metaData }));
+        const context = { dataContextId: (0, utils_1.newid)(), tableContainer: container };
+        const definition = makeDefinition();
+        definition.contracts[0].tools = [
+            { name: "read", usageDescription: "Read", inputFields: [], outputFields: [] },
+        ];
+        const tableId = (0, utils_1.newid)();
+        const tableDefinition = (primaryKeyName) => ({
+            metaData: {
+                tableId,
+                name: "State",
+                description: "State",
+                primaryKeyName,
+                fields: [{ name: primaryKeyName, type: field_type_1.FieldType.id }],
+            },
+        });
+        definition.tableDefinitions = [tableDefinition("oldId")];
+        const warn = jest.spyOn(console, "warn").mockImplementation(() => { });
+        try {
+            await (0, contract_package_loader_1.installContractPackage)(context, definition, { registry });
+            const previous = registry.resolve(contractId, 1);
+            const oldTable = container.getTableByName(`State_${tableId}`);
+            let saves = 0;
+            mockBeforeToolSave.mockImplementation(async (row) => {
+                if (failure === "catalog-write" && row.contractId === contractId && ++saves === 2) {
+                    expect(container.getTableByName(`State_${tableId}`)).toBe(oldTable);
+                    throw new Error("final catalog disk failure");
+                }
+            });
+            const replacement = { ...definition, tableDefinitions: [tableDefinition("newId")] };
+            if (failure === "invalid-table") {
+                const invalid = tableDefinition("invalidId");
+                invalid.metaData.tableId = "invalid";
+                replacement.tableDefinitions.push(invalid);
+            }
+            await expect((0, contract_package_loader_1.installContractPackage)(context, replacement, { registry })).rejects.toThrow(failure === "catalog-write" ? "final catalog disk failure" : "Invalid tableId");
+            expect(registry.resolve(contractId, 1)).toBe(previous);
+            expect(container.getTableByName(`State_${tableId}`)).toBe(oldTable);
+            expect(oldTable.metaData.primaryKeyName).toBe("oldId");
+            mockBeforeToolSave.mockReset();
+            replacement.tableDefinitions = [tableDefinition("newId")];
+            await (0, contract_package_loader_1.installContractPackage)(context, replacement, { registry });
+            expect(container.getTableByName(`State_${tableId}`).metaData.primaryKeyName).toBe("newId");
+        }
+        finally {
+            mockBeforeToolSave.mockReset();
+            warn.mockRestore();
+            await registry.toolCatalog?.dispose();
+        }
+    });
+    it("indexes public host definitions without instances and activates only after loader preparation", async () => {
+        const registry = new registry_1.ContractRegistry();
+        const dataContext = mockDataContext();
+        const definition = makeDefinition();
+        definition.contracts[0].tools = [
+            { name: "read", usageDescription: "Read", inputFields: [], outputFields: [] },
+        ];
+        const toolId = (0, tool_catalog_identity_1.deriveToolCatalogId)({ contractId, version: 1, toolName: "read" });
+        const activated = jest.fn();
+        const prepare = jest.fn(async () => {
+            expect(await (0, tools_1.Tools)(dataContext).get(toolId)).toMatchObject({ catalogState: "resolved" });
+            expect(registry.resolve(contractId, 1)).toBeUndefined();
+            throw new Error("loader preparation failed");
+        });
+        await expect((0, contract_package_loader_1.installContractPackage)(dataContext, definition, {
+            registry,
+            prepare,
+            onActivated: activated,
+        })).rejects.toThrow(/loader preparation failed/);
+        expect(activated).not.toHaveBeenCalled();
+        expect(registry.resolve(contractId, 1)).toBeUndefined();
+        await (0, contract_package_loader_1.installContractPackage)(dataContext, definition, { registry, onActivated: activated });
+        expect(activated).toHaveBeenCalledTimes(1);
+        expect((await (0, tools_1.Tools)(dataContext).list()).filter((row) => row.contractId === contractId)).toHaveLength(1);
+        await registry.toolCatalog?.dispose();
+    });
 });
 describe("extractPackageDefinition", () => {
     it("returns a package definition when packageId and contracts are present", () => {
@@ -93,7 +253,6 @@ describe("extractPackageDefinition", () => {
             alsoImplements: new Map(),
             assistants: [],
             appNavs: [],
-            toolInstances: [],
             tableDefinitions: [],
         };
         expect((0, contract_package_loader_1.extractPackageDefinition)({ packageDefinition: def })).toBe(def);

package/dist/package-loader/host-authority-loading.test.js

@@ -6,13 +6,26 @@ test("host-backed package endpoints honor declared propagation and reread live m
     const contractId = (0, index_1.newid)();
     const userId = (0, index_1.newid)();
     const groupId = (0, index_1.newid)();
+    const rows = new Map();
+    const tools = {
+        list: async () => [...rows.values()],
+        get: async (id) => rows.get(id),
+        save: async (row, opts) => {
+            if (!opts?.insertOnly || !rows.has(row.toolId))
+                rows.set(row.toolId, row);
+            return rows.get(row.toolId);
+        },
+        dataChanged: { subscribe: () => ({ unsubscribe: () => true }) },
+    };
     const dataContext = {
         dataContextId: groupId,
         groupId,
         tableContainer: {
-            getTable: (meta) => meta.name === "Groups"
-                ? { get: async () => ({ founderUserId: (0, index_1.newid)() }) }
-                : { findOne: async () => ({ userId, role: index_1.GroupMemberRole.Admin }) },
+            getTable: (meta) => meta.name === "Tools"
+                ? tools
+                : meta.name === "Groups"
+                    ? { get: async () => ({ founderUserId: (0, index_1.newid)() }) }
+                    : { findOne: async () => ({ userId, role: index_1.GroupMemberRole.Admin }) },
         },
     };
     Object.assign(dataContext, {

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

@@ -28,6 +28,8 @@ export interface IIsolatedCallPrincipal {
 }
 /** Trusted lifecycle metadata supplied when an isolated artifact is installed. */
 export interface IIsolatedPackageInstallOptions {
+    /** Host load-generation guard, rechecked before publication after asynchronous preparation. */
+    assertCurrent?: () => void;
     /**
      * Contract maturity derived from the trusted active PackageVersion.
      * Guest artifacts cannot select or change this value.
@@ -82,6 +84,12 @@ export interface IIsolatedPackageRuntime {
     provides(contractId: string, version: number): boolean;
     /** True when this runtime has installed `packageId`. */
     isInstalled(packageId: string): boolean;
+    /** Read effective policy without starting a worker. */
+    getEffectiveToolLevel?(ref: {
+        contractId: string;
+        version: number;
+        toolName: string;
+    }, providerPackageId?: string): number;
     /**
      * Run a tool the package provides, starting its worker if needed.
      *
@@ -142,9 +150,13 @@ export interface IIsolatedPackageTableGateway {
     register(declaration: IIsolatedPackageTableDeclaration): Promise<void>;
     /**
      * Validate and bind a package's complete table set as one registration.
-     * Validation failure must not publish any declaration from the batch.
+     * Run `activate` synchronously after all awaited schema persistence, immediately
+     * before publishing the prepared bindings. The callback must check cancellation
+     * before changing provider state and must not return a promise. No awaited work
+     * may separate it from binding publication. If preparation or the callback fails,
+     * restore persisted definitions and retain all previous bindings before rejecting.
      */
-    registerBatch(declarations: readonly IIsolatedPackageTableDeclaration[]): Promise<void>;
+    registerBatch(declarations: readonly IIsolatedPackageTableDeclaration[], activate?: () => void): Promise<void>;
     /** Return a copied record, or `undefined` when it does not exist. */
     get(ref: IIsolatedPackageTableRef, recordId: string): Promise<Record<string, unknown> | undefined>;
     /** Insert or replace a copied record and return the stored copy. */

package/dist/package-loader/isolated-table-gateway.d.ts

@@ -9,7 +9,9 @@ import { type IIsolatedPackageTableGateway } from "./isolated-runtime";
 export declare function createMemoryIsolatedPackageTableGateway(): IIsolatedPackageTableGateway;
 /**
  * Create a per-data-context gateway that registers isolated table schemas in
- * `TableContainer` and performs host-owned `get` / `save`.
+ * `TableContainer` and performs host-owned `get` / `save`. Registration serializes
+ * schema persistence with synchronous provider activation; a rejected activation
+ * restores the stored definitions before subsequent gateway calls can proceed.
  *
  * @param dataContext - Owning personal or group data context.
  */

package/dist/package-loader/isolated-table-gateway.js

@@ -190,12 +190,13 @@ function createMemoryIsolatedPackageTableGateway() {
     const emitChange = (key, op, dataObject) => {
         void emitterFor(key).emit({ dataObject, op, source: "local" });
     };
-    const registerBatch = async (batch) => {
+    const registerBatch = async (batch, activate) => {
         const candidateDeclarations = new Map(declarations);
         const candidateByTableId = new Map(byTableId);
         for (const declaration of batch) {
             registerDeclaration(candidateDeclarations, candidateByTableId, declaration);
         }
+        activate?.();
         declarations.clear();
         byTableId.clear();
         for (const [key, declaration] of candidateDeclarations) {
@@ -317,7 +318,9 @@ function createMemoryIsolatedPackageTableGateway() {
 }
 /**
  * Create a per-data-context gateway that registers isolated table schemas in
- * `TableContainer` and performs host-owned `get` / `save`.
+ * `TableContainer` and performs host-owned `get` / `save`. Registration serializes
+ * schema persistence with synchronous provider activation; a rejected activation
+ * restores the stored definitions before subsequent gateway calls can proceed.
  *
  * @param dataContext - Owning personal or group data context.
  */
@@ -357,7 +360,7 @@ function createIsolatedPackageTableGateway(dataContext) {
         return dataContext.tableContainer.getTable(activeMetaData);
     };
     const ensureTable = async (declaration) => activateTable(await prepareTable(declaration));
-    const registerBatch = (batch) => {
+    const registerBatch = (batch, activate) => {
         const registration = registrationQueue.then(async () => {
             const candidateDeclarations = new Map(declarations);
             const candidateByTableId = new Map(byTableId);
@@ -372,8 +375,54 @@ function createIsolatedPackageTableGateway(dataContext) {
                     plans.push(await prepareTable(declaration));
                 }
             }
-            for (const plan of plans) {
-                await activateTable(plan);
+            // Prepare schemas before touching durable or live definitions. Do not create
+            // Table instances here: that also schedules unguarded definition persistence.
+            const definitions = plans.map(({ activeMetaData }) => ({
+                metaData: activeMetaData,
+                schema: (0, types_1.fieldsToSchema)(activeMetaData.fields),
+            }));
+            const definitionsTable = (0, table_definitions_table_1.TableDefinitions)(dataContext);
+            const attempted = [];
+            try {
+                for (const plan of plans) {
+                    if (!plan.existingRecord || plan.activeMetaData === plan.incomingMetaData) {
+                        // Include the current write in rollback even if storage writes then rejects.
+                        attempted.push(plan);
+                        await definitionsTable.save({
+                            tableId: requiredTableId(plan.activeMetaData),
+                            name: (0, package_table_identity_1.packageScopedTableName)(requiredPackageId(plan.activeMetaData), plan.activeMetaData.name),
+                            metaData: plan.activeMetaData,
+                            versionNumber: plan.activeMetaData.versionNumber ?? 0,
+                        }, { restoreIfDeleted: true });
+                    }
+                }
+                // Cancellation/registry validation and provider activation happen in the
+                // same synchronous turn as binding publication. An unload cannot slip
+                // between a completed registration promise and the runtime's guard.
+                activate?.();
+            }
+            catch (error) {
+                const failures = [];
+                for (const plan of attempted.reverse()) {
+                    try {
+                        if (plan.existingRecord) {
+                            await definitionsTable.save(plan.existingRecord, { restoreIfDeleted: true });
+                        }
+                        else {
+                            await definitionsTable.delete(requiredTableId(plan.activeMetaData));
+                        }
+                    }
+                    catch (rollbackError) {
+                        failures.push(rollbackError);
+                    }
+                }
+                if (failures.length) {
+                    throw new AggregateError([error, ...failures], "Isolated table registration rollback failed");
+                }
+                throw error;
+            }
+            for (const definition of definitions) {
+                dataContext.tableContainer.registerTableDefinition(definition, { overwrite: true });
             }
             declarations.clear();
             byTableId.clear();

package/dist/package-loader/isolated-table-gateway.test.js

@@ -1,6 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+const SQLiteDB = require("better-sqlite3");
+const sql_data_source_1 = require("../data/orm/sql.data-source");
+const table_container_1 = require("../data/orm/table-container");
 const package_table_identity_1 = require("../data/package-table-identity");
+const table_definitions_table_1 = require("../data/table-definitions-table");
 const field_type_1 = require("../types/field-type");
 const utils_1 = require("../utils");
 const isolated_table_gateway_1 = require("./isolated-table-gateway");
@@ -265,3 +269,122 @@ describe("isolated package table gateway", () => {
         expect(handlers.size).toBe(0);
     });
 });
+describe("guarded isolated schema activation", () => {
+    test("memory bindings remain unchanged when activation rejects", async () => {
+        const gateway = (0, isolated_table_gateway_1.createMemoryIsolatedPackageTableGateway)();
+        const old = makeDeclaration({ versionNumber: 1 });
+        const next = {
+            ...old,
+            versionNumber: 2,
+            primaryKeyName: "newId",
+            fields: [{ name: "newId", type: field_type_1.FieldType.id }],
+        };
+        await gateway.register(old);
+        await expect(gateway.registerBatch([next], () => {
+            throw new Error("load invalidated");
+        })).rejects.toThrow("load invalidated");
+        const record = { stateId: (0, utils_1.newid)(), count: 1 };
+        await expect(gateway.save(old, record)).resolves.toEqual(record);
+        await expect(gateway.register(old)).resolves.toBeUndefined();
+    });
+    test.each([
+        "invalidation",
+        "storage",
+    ])("restores SQLite definitions after %s during registration, including fresh tables and restart", async (failure) => {
+        const db = new SQLiteDB(":memory:");
+        const sql = {
+            async close() {
+                db.close();
+            },
+            async get(query, params = []) {
+                return db.prepare(query).get(params);
+            },
+            async all(query, params = []) {
+                return db.prepare(query).all(params);
+            },
+            async exec(query, params = []) {
+                return { changes: db.prepare(query).run(params).changes };
+            },
+        };
+        const context = () => ({
+            dataContextId: (0, utils_1.newid)(),
+            tableContainer: new table_container_1.TableContainer((metaData, schema) => new sql_data_source_1.SQLDataSource(sql, metaData, schema)),
+        });
+        const dataContext = context();
+        const gateway = (0, isolated_table_gateway_1.createIsolatedPackageTableGateway)(dataContext);
+        const old = makeDeclaration({ versionNumber: 1 });
+        const next = {
+            ...old,
+            versionNumber: 2,
+            primaryKeyName: "newId",
+            fields: [{ name: "newId", type: field_type_1.FieldType.id }],
+        };
+        const added = makeDeclaration({
+            packageId: old.packageId,
+            tableName: "Added",
+            versionNumber: 1,
+        });
+        const definitions = (0, table_definitions_table_1.TableDefinitions)(dataContext);
+        const oldId = (0, package_table_identity_1.packageScopedTableId)(old.packageId, old.tableName);
+        const addedId = (0, package_table_identity_1.packageScopedTableId)(added.packageId, added.tableName);
+        const warn = jest.spyOn(console, "warn").mockImplementation(() => { });
+        let release;
+        let arrived;
+        const gate = new Promise((resolve) => {
+            release = resolve;
+        });
+        const saving = new Promise((resolve) => {
+            arrived = resolve;
+        });
+        let saveSpy;
+        try {
+            await gateway.register(old);
+            const record = { stateId: (0, utils_1.newid)(), count: 1 };
+            await gateway.save(old, record);
+            const original = await definitions.get(oldId);
+            const oldTable = dataContext.tableContainer.getTableByName(`${old.tableName}_${old.packageId}`);
+            const save = definitions.save.bind(definitions);
+            let current = true;
+            saveSpy = jest.spyOn(definitions, "save").mockImplementation(async (row, opts) => {
+                const result = await save(row, opts);
+                if (row.tableId === addedId) {
+                    arrived();
+                    await gate;
+                    if (failure === "storage")
+                        throw new Error("storage failed after write");
+                }
+                return result;
+            });
+            const activated = jest.fn(() => {
+                if (!current)
+                    throw new Error("load invalidated");
+            });
+            const registering = gateway.registerBatch([next, added], activated);
+            const rejected = expect(registering).rejects.toThrow(failure === "storage" ? "storage failed after write" : "load invalidated");
+            await saving;
+            expect(dataContext.tableContainer.getTableByName(`${old.tableName}_${old.packageId}`)).toBe(oldTable);
+            current = false;
+            release();
+            await rejected;
+            expect(activated).toHaveBeenCalledTimes(failure === "storage" ? 0 : 1);
+            expect(await definitions.get(oldId)).toEqual(original);
+            expect(await definitions.get(addedId)).toBeUndefined();
+            expect(dataContext.tableContainer.getTableByName(`${old.tableName}_${old.packageId}`)).toBe(oldTable);
+            await expect(gateway.save(old, record)).resolves.toEqual(record);
+            await expect(gateway.get(added, (0, utils_1.newid)())).rejects.toThrow(/Undeclared/);
+            // A cold gateway reads the restored durable version, so v1 can reinstall.
+            const restarted = (0, isolated_table_gateway_1.createIsolatedPackageTableGateway)(context());
+            await expect(restarted.register(old)).resolves.toBeUndefined();
+            await expect(restarted.get(old, record.stateId)).resolves.toEqual(record);
+            saveSpy.mockRestore();
+            await expect(gateway.registerBatch([next, added])).resolves.toBeUndefined();
+            expect((await definitions.get(oldId))?.versionNumber).toBe(2);
+        }
+        finally {
+            release();
+            saveSpy?.mockRestore();
+            warn.mockRestore();
+            db.close();
+        }
+    });
+});

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