@peers-app/peers-sdk 0.26.6 → 0.27.1

package/dist/contracts/__tests__/host-contract-transport.test.js

@@ -36,6 +36,21 @@ describe("host contract transport", () => {
         disposers.push(dispose);
         await expect(pending).resolves.toBe(transport);
     });
+    it("cancels waits and clears their deadline", async () => {
+        jest.useFakeTimers();
+        try {
+            const controller = new AbortController();
+            const pending = (0, index_1.waitForHostContractTransport)({ signal: controller.signal, timeoutMs: 25 });
+            const rejected = expect(pending).rejects.toThrow("cancelled");
+            controller.abort(new Error("cancelled"));
+            await rejected;
+            expect(jest.getTimerCount()).toBe(0);
+            await expect((0, index_1.waitForHostContractTransport)({ signal: controller.signal })).rejects.toThrow("cancelled");
+        }
+        finally {
+            jest.useRealTimers();
+        }
+    });
     it("rejects when no transport arrives before timeoutMs", async () => {
         jest.useFakeTimers();
         try {

package/dist/contracts/__tests__/registry.test.js

@@ -168,3 +168,71 @@ describe("ContractRegistry.replaceBatch", () => {
         expect(registry.getRegisteredProviderIds(rejectedContractId, 1)).toEqual([]);
     });
 });
+describe("ContractRegistry exposes", () => {
+    const hubId = (0, utils_1.newid)();
+    const newsId = (0, utils_1.newid)();
+    const provider = (0, utils_1.newid)();
+    const other = (0, utils_1.newid)();
+    it("keeps each provider's exposures, outside the contract's definition", () => {
+        const registry = new registry_1.ContractRegistry();
+        const result = registry.registerBatch(provider, [
+            { definition: makeDefinition(newsId, 1, "News") },
+            {
+                definition: makeDefinition(hubId, 2, "Hub"),
+                exposes: [{ contractId: newsId, version: 1 }],
+            },
+        ]);
+        expect(result.valid).toBe(true);
+        registry.registerBatch(other, [{ definition: makeDefinition(hubId, 2, "Hub") }]);
+        expect(registry.getExposedContracts(hubId, 2, provider)).toEqual([
+            { contractId: newsId, version: 1 },
+        ]);
+        expect(registry.getExposedContracts(hubId, 2, other)).toEqual([]);
+        expect(registry.getExposedContracts(newsId, 1, provider)).toEqual([]);
+        expect(registry.getExposedContracts(hubId, 2, (0, utils_1.newid)())).toEqual([]);
+        expect(registry.getDefinition(hubId, 2)).not.toHaveProperty("exposes");
+        expect(registry.getProviderDefinition(newsId, 1, provider)?.name).toBe("News");
+        expect(registry.getProviderDefinition(newsId, 1, other)).toBeUndefined();
+        // A caller can't change what the registry holds through the returned list.
+        registry.getExposedContracts(hubId, 2, provider).pop();
+        expect(registry.getExposedContracts(hubId, 2, provider)).toHaveLength(1);
+    });
+    it("carries exposures to an alsoImplements alias, and drops them on replacement", () => {
+        const registry = new registry_1.ContractRegistry();
+        registry.register(other, makeDefinition(hubId, 1, "Hub v1"));
+        registry.registerBatch(provider, [
+            { definition: makeDefinition(newsId, 1, "News") },
+            {
+                definition: makeDefinition(hubId, 2, "Hub"),
+                alsoImplements: [{ contractId: hubId, version: 1 }],
+                exposes: [{ contractId: newsId, version: 1 }],
+            },
+        ]);
+        expect(registry.getExposedContracts(hubId, 1, provider)).toEqual([
+            { contractId: newsId, version: 1 },
+        ]);
+        registry.replaceBatch(provider, [
+            { definition: makeDefinition(newsId, 1, "News") },
+            { definition: makeDefinition(hubId, 2, "Hub") },
+        ]);
+        expect(registry.getExposedContracts(hubId, 2, provider)).toEqual([]);
+    });
+    it("refuses an exposure the batch doesn't provide, of itself, or twice", () => {
+        const registry = new registry_1.ContractRegistry();
+        const hub = (exposes) => [
+            { definition: makeDefinition(newsId, 1, "News") },
+            { definition: makeDefinition(hubId, 2, "Hub"), exposes },
+        ];
+        expect(registry.validateBatch(provider, hub([{ contractId: (0, utils_1.newid)(), version: 1 }]))).toEqual(expect.objectContaining({
+            valid: false,
+            errors: [expect.objectContaining({ message: expect.stringMatching(/doesn't provide/) })],
+        }));
+        expect(registry.validateBatch(provider, hub([{ contractId: hubId, version: 2 }])).errors[0].message).toMatch(/can't expose itself/);
+        expect(registry.validateBatch(provider, hub([
+            { contractId: newsId, version: 1 },
+            { contractId: newsId, version: 1 },
+        ])).errors[0].message).toMatch(/twice/);
+        expect(registry.registerBatch(provider, hub([{ contractId: newsId, version: 2 }])).valid).toBe(false);
+        expect(registry.getRegisteredProviderIds(newsId, 1)).toEqual([]);
+    });
+});

package/dist/contracts/__tests__/target-dispatch.d.ts

@@ -0,0 +1,11 @@
+import type { IToolInstance } from "../../data/tools";
+import { type ContractToolDispatch } from "../contract-proxy";
+/**
+ * The host's `dispatchTool`, for tests: runs `tools` as the provider of `contractId` v1 with the
+ * frame the calling tool's provider bound, so each target is admitted as the host would admit
+ * it. Targets can dispatch further through the same bridge.
+ *
+ * @param contractId - The contract the targets are provided under.
+ * @param tools - The target tools, by name.
+ */
+export declare function targetDispatch(contractId: string, tools: Record<string, IToolInstance>): ContractToolDispatch;

package/dist/contracts/__tests__/target-dispatch.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.targetDispatch = targetDispatch;
+const contract_proxy_1 = require("../contract-proxy");
+/**
+ * The host's `dispatchTool`, for tests: runs `tools` as the provider of `contractId` v1 with the
+ * frame the calling tool's provider bound, so each target is admitted as the host would admit
+ * it. Targets can dispatch further through the same bridge.
+ *
+ * @param contractId - The contract the targets are provided under.
+ * @param tools - The target tools, by name.
+ */
+function targetDispatch(contractId, tools) {
+    const dispatch = (target, args, context) => provider({
+        contractId: target.contractId,
+        version: target.version,
+        member: "tool",
+        name: target.toolName,
+        operation: "run",
+        args: [args],
+    }, context);
+    const provider = (0, contract_proxy_1.createContractProvider)({ contractId, version: 1, tools, forwardCallContext: true }, { dispatchTool: dispatch });
+    return dispatch;
+}

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

@@ -203,9 +203,11 @@ test("validates arguments, converts dates, and forwards original nested objects
     expect(forwarded).toEqual({ ...args, when: new Date(args.when) });
     expect(forwarded.object).toBe(object);
     expect(forwarded).not.toHaveProperty("defaulted");
+    await expect(invoke({ ...args, defaulted: null })).resolves.toBe("ok");
+    expect(f.endpoint.handleCall.mock.calls[1][0].args[0]).not.toHaveProperty("defaulted");
     expect(args.when).toBe("2026-10-16");
     await expect(invoke({ ...args, when: "not-a-date" })).rejects.toThrow("argument validation");
-    expect(f.endpoint.dispose).toHaveBeenCalledTimes(1);
+    expect(f.endpoint.dispose).toHaveBeenCalledTimes(2);
 });
 test("selects strict, preferred and fallback providers and observes active changes under the same ID", async () => {
     const f = fixture();
@@ -252,6 +254,40 @@ test("host alsoImplements validates the requested v1 schema and resolves v2 code
     f.host(f.provider, 2);
     expect((0, tool_catalog_service_1.describeToolCatalogRow)(f.dataContext, f.row).provider?.implementation?.version).toBe(2);
     await expect((0, tool_catalog_service_1.invokeToolCatalogTool)(f.dataContext, { toolId: f.row.toolId, args: { value: "v1", new: "not a v2 number" } }, f.context)).resolves.toBe("ok");
+    // By name, the v1 row and the v2 row run the same tool: the v2 row is chosen, not "ambiguous".
+    const v2Target = { ...f.target, version: 2 };
+    const v2Row = {
+        ...f.row,
+        toolId: (0, tool_catalog_identity_1.deriveToolCatalogId)(v2Target),
+        contractVersion: 2,
+    };
+    f.rows.set(v2Row.toolId, v2Row);
+    await expect((0, tool_catalog_service_1.findToolCatalogEntry)(f.dataContext, { toolIdOrName: "run", runnableOnly: true })).resolves.toMatchObject({ toolId: v2Row.toolId });
+});
+test("name lookup keeps aliases ambiguous when the implementing version selects another provider", async () => {
+    const f = fixture();
+    const newer = { ...f.definition, version: 2 };
+    expect(f.registry.register(f.provider, newer, [
+        { contractId: f.target.contractId, version: 1, definition: f.definition },
+    ]).valid).toBe(true);
+    f.host(f.provider, 2);
+    const other = (0, utils_1.newid)();
+    expect(f.registry.register(other, newer).valid).toBe(true);
+    f.host(other, 2);
+    expect(f.registry.setActiveProvider(f.target.contractId, 2, other)).toBe(true);
+    const v2Row = {
+        ...f.row,
+        toolId: (0, tool_catalog_identity_1.deriveToolCatalogId)({ ...f.target, version: 2 }),
+        contractVersion: 2,
+    };
+    f.rows.set(v2Row.toolId, v2Row);
+    await expect((0, tool_catalog_service_1.findToolCatalogEntry)(f.dataContext, { toolIdOrName: "run", runnableOnly: true })).rejects.toThrow('Ambiguous tool "run": matched 2 tools');
+    for (const [row, provider] of [
+        [f.row, f.provider],
+        [v2Row, other],
+    ]) {
+        await expect((0, tool_catalog_service_1.findToolCatalogEntry)(f.dataContext, { toolIdOrName: row.toolId, runnableOnly: true })).resolves.toMatchObject({ provider: { activePackageId: provider } });
+    }
 });
 test("rejects self targets, unresolved and quarantined rows, and never uses legacy invocation", async () => {
     const f = fixture();

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

@@ -465,13 +465,22 @@ describe("per-context catalog lifecycle", () => {
         await expect(f.publish()).rejects.toThrow(/identity cannot change/);
         await f.catalog.dispose();
     });
-    test("alsoImplements indexes only older public members, and removal retains history", async () => {
+    test.each([
+        false,
+        true,
+    ])("alsoImplements indexes only older public members, and removal retains history (carried=%s)", async (carried) => {
         const f = fixture();
         const provider = (0, utils_1.newid)();
         const older = definition(["old"]);
         const newer = definition(["old", "new"], 2);
-        f.registry.register((0, utils_1.newid)(), older);
-        const regs = [{ definition: newer, alsoImplements: [{ contractId, version: 1 }] }];
+        if (!carried)
+            f.registry.register((0, utils_1.newid)(), older);
+        const regs = [
+            {
+                definition: newer,
+                alsoImplements: [{ contractId, version: 1, ...(carried ? { definition: older } : {}) }],
+            },
+        ];
         await f.catalog.publish(provider, regs, async () => { }, () => f.registry.replaceBatch(provider, regs));
         expect([...f.rows.values()]
             .filter((r) => r.contractId === contractId)

package/dist/contracts/__tests__/validate.test.js

@@ -1,8 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+const zod_1 = require("zod");
+const types_1 = require("../../data/orm/types");
 const field_type_1 = require("../../types/field-type");
 const utils_1 = require("../../utils");
-const types_1 = require("../types");
+const types_2 = require("../types");
 const validate_1 = require("../validate");
 const DEFAULT_CONTRACT_ID = (0, utils_1.newid)();
 /** Helper to build a minimal contract definition for tests. */
@@ -666,13 +668,181 @@ describe("validateImmutability", () => {
         expect(result.errors[0].message).toContain("frozen");
     });
 });
+describe("validateImmutability compares shapes, not text", () => {
+    const tool = (inputFields) => ({
+        name: "setMode",
+        usageDescription: "Set the mode.",
+        inputFields,
+        outputFields: [{ name: "ok", type: field_type_1.FieldType.boolean }],
+    });
+    const mode = { name: "mode", type: field_type_1.FieldType.string, enumValues: ["on", "off"] };
+    const note = { name: "note", type: field_type_1.FieldType.string, optional: true, description: "A note." };
+    const frozen = makeContract({
+        tools: [tool([mode, note])],
+        observables: [
+            {
+                name: "state",
+                description: "The state.",
+                valueType: field_type_1.FieldType.object,
+                value: { type: field_type_1.FieldType.object, fields: [{ name: "on", type: field_type_1.FieldType.boolean }] },
+                writable: false,
+            },
+        ],
+    });
+    it("allows new descriptions and any member, field, or key order", () => {
+        const incoming = makeContract({
+            observables: [
+                {
+                    writable: false,
+                    value: { fields: [{ type: field_type_1.FieldType.boolean, name: "on" }], type: field_type_1.FieldType.object },
+                    valueType: field_type_1.FieldType.object,
+                    description: "Deprecated: use v2.",
+                    name: "state",
+                },
+            ],
+            tools: [
+                {
+                    ...tool([
+                        { ...note, description: "Don't use this." },
+                        { ...mode, enumValues: ["off", "on"] },
+                    ]),
+                    usageDescription: "Deprecated: use v2.",
+                },
+            ],
+        });
+        expect((0, validate_1.validateImmutability)(frozen, incoming).valid).toBe(true);
+    });
+    it("matches a shape built before fields, enumValues, and value existed", () => {
+        const older = makeContract({
+            tools: [
+                tool([
+                    { name: "mode", type: field_type_1.FieldType.string },
+                    { name: "note", type: field_type_1.FieldType.string, optional: true },
+                ]),
+            ],
+            observables: [
+                { name: "state", description: "", valueType: field_type_1.FieldType.object, writable: false },
+            ],
+        });
+        expect((0, validate_1.validateImmutability)(frozen, older).valid).toBe(true);
+        expect((0, validate_1.validateImmutability)(older, frozen).valid).toBe(true);
+    });
+    it("ignores duplicate enum entries when comparing sets", () => {
+        const incoming = makeContract({
+            tools: [tool([{ ...mode, enumValues: ["off", "on", "on"] }, note])],
+            observables: frozen.observables,
+        });
+        expect((0, validate_1.validateImmutability)(frozen, incoming).valid).toBe(true);
+        expect((0, validate_1.validateImmutability)(incoming, frozen).valid).toBe(true);
+    });
+    it("matches unchanged legacy default factories across schema rebuilds and JSON storage", () => {
+        const factory = jest.fn(() => "generated");
+        const legacy = () => makeContract({
+            tables: [
+                {
+                    name: "Records",
+                    description: "",
+                    primaryKeyName: "id",
+                    fields: (0, types_1.schemaToFields)(zod_1.z.object({
+                        id: zod_1.z.string().default(() => factory()),
+                        label: zod_1.z.string().default("untitled"),
+                    })),
+                },
+            ],
+        });
+        const first = legacy();
+        const rebuilt = legacy();
+        const stored = JSON.parse(JSON.stringify(first));
+        expect((0, validate_1.validateImmutability)(first, rebuilt).valid).toBe(true);
+        expect((0, validate_1.validateImmutability)(stored, rebuilt).valid).toBe(true);
+        expect((0, validate_1.validateImmutability)(rebuilt, stored).valid).toBe(true);
+        expect(factory).not.toHaveBeenCalled();
+    });
+    it("compares default objects as data, including descriptions and array order", () => {
+        const contract = (defaultValue) => makeContract({
+            tools: [tool([{ ...mode, defaultValue }])],
+        });
+        const first = contract({ description: "data", values: ["a", "b"] });
+        expect((0, validate_1.validateImmutability)(first, contract({ values: ["a", "b"], description: "data" })).valid).toBe(true);
+        expect((0, validate_1.validateImmutability)(first, contract({ description: "changed", values: ["a", "b"] })).valid).toBe(false);
+        expect((0, validate_1.validateImmutability)(first, contract({ description: "data", values: ["b", "a"] })).valid).toBe(false);
+    });
+    it.each([
+        ["an enum value", tool([{ ...mode, enumValues: ["on"] }, note])],
+        ["optional", tool([mode, { ...note, optional: false }])],
+        ["a default value", tool([{ ...mode, defaultValue: "on" }, note])],
+        ["a type", tool([mode, { ...note, type: field_type_1.FieldType.number }])],
+    ])("rejects a changed %s", (_change, changed) => {
+        const result = (0, validate_1.validateImmutability)(frozen, makeContract({ tools: [changed], observables: frozen.observables }));
+        expect(result.valid).toBe(false);
+    });
+    it("rejects a changed observable value shape when both have one", () => {
+        const [state] = frozen.observables;
+        const incoming = makeContract({
+            tools: frozen.tools,
+            observables: [
+                {
+                    ...state,
+                    value: { type: field_type_1.FieldType.object, fields: [{ name: "on", type: field_type_1.FieldType.string }] },
+                },
+            ],
+        });
+        expect((0, validate_1.validateImmutability)(frozen, incoming).valid).toBe(false);
+    });
+    it("ignores a tool's policy, which isn't part of its shape", () => {
+        const tool = {
+            name: "run",
+            usageDescription: "Run.",
+            inputFields: [{ name: "id", type: field_type_1.FieldType.id }],
+            outputFields: [],
+        };
+        const frozen = makeContract({ tools: [{ ...tool, remoteAccessLevel: 40 }] });
+        const incoming = makeContract({
+            tools: [{ ...tool, remoteAccessLevel: 60, requiresWorkflowRun: true }],
+        });
+        expect((0, validate_1.validateImmutability)(frozen, incoming)).toEqual({ valid: true, errors: [] });
+    });
+    it("names what changed", () => {
+        const field = { name: "id", type: field_type_1.FieldType.id };
+        const tool = (name, inputFields = [field]) => ({
+            name,
+            usageDescription: name,
+            inputFields,
+            outputFields: [],
+        });
+        const frozen = makeContract({ tools: [tool("keep"), tool("change"), tool("drop")] });
+        const incoming = makeContract({
+            tools: [tool("keep"), tool("change", [{ ...field, type: field_type_1.FieldType.string }]), tool("new")],
+        });
+        expect((0, validate_1.contractShapeChanges)(frozen, incoming)).toEqual([
+            "tool change changed",
+            "tool drop was removed",
+            "tool new was added",
+        ]);
+        expect((0, validate_1.validateImmutability)(frozen, incoming).errors[0].message).toContain("(tool change changed; tool drop was removed; tool new was added)");
+    });
+    it.each([
+        "tables",
+        "tools",
+        "observables",
+        "events",
+    ])("does not hide added or changed duplicate %s behind the last member", (kind) => {
+        const member = { name: "duplicate", description: "Original" };
+        const before = makeContract({ [kind]: [member] });
+        const after = makeContract({ [kind]: [{ ...member, extra: true }, member] });
+        expect((0, validate_1.validateImmutability)(before, after).valid).toBe(false);
+        expect((0, validate_1.validateImmutability)(after, before).valid).toBe(false);
+        const changedDuplicate = makeContract({ [kind]: [{ ...member, extra: false }, member] });
+        expect((0, validate_1.validateImmutability)(after, changedDuplicate).valid).toBe(false);
+    });
+});
 describe("validateAlsoImplements", () => {
     const contractStore = new Map();
     const TASKS_CONTRACT_ID = (0, utils_1.newid)();
     const FANCY_TASKS_CONTRACT_ID = (0, utils_1.newid)();
     const NONEXISTENT_ID = (0, utils_1.newid)();
     function getContract(id, ver) {
-        return contractStore.get((0, types_1.contractKey)(id, ver));
+        return contractStore.get((0, types_2.contractKey)(id, ver));
     }
     beforeEach(() => {
         contractStore.clear();
@@ -693,7 +863,7 @@ describe("validateAlsoImplements", () => {
                 },
             ],
         });
-        contractStore.set((0, types_1.contractKey)(TASKS_CONTRACT_ID, 1), targetV1);
+        contractStore.set((0, types_2.contractKey)(TASKS_CONTRACT_ID, 1), targetV1);
         const impl = makeContract({
             contractId: FANCY_TASKS_CONTRACT_ID,
             version: 1,
@@ -745,8 +915,8 @@ describe("validateAlsoImplements", () => {
                 },
             ],
         });
-        contractStore.set((0, types_1.contractKey)(TASKS_CONTRACT_ID, 1), v1);
-        contractStore.set((0, types_1.contractKey)(TASKS_CONTRACT_ID, 2), v2);
+        contractStore.set((0, types_2.contractKey)(TASKS_CONTRACT_ID, 1), v1);
+        contractStore.set((0, types_2.contractKey)(TASKS_CONTRACT_ID, 2), v2);
         // Implementation satisfies both: has all fields from both versions.
         // 'status' is optional so v1 consumers can still write valid rows.
         const impl = makeContract({
@@ -794,8 +964,8 @@ describe("validateAlsoImplements", () => {
                 },
             ],
         });
-        contractStore.set((0, types_1.contractKey)(TASKS_CONTRACT_ID, 1), v1);
-        contractStore.set((0, types_1.contractKey)(TASKS_CONTRACT_ID, 2), v2);
+        contractStore.set((0, types_2.contractKey)(TASKS_CONTRACT_ID, 1), v1);
+        contractStore.set((0, types_2.contractKey)(TASKS_CONTRACT_ID, 2), v2);
         // Implementation only satisfies v1 (missing 'assignee')
         const impl = makeContract({
             tables: [

package/dist/contracts/__tests__/workflow-context.test.js

@@ -5,19 +5,10 @@ const contract_proxy_1 = require("../contract-proxy");
 test("only the directly invoked tool receives workflow capability", async () => {
     const workflow = { dataContextId: "group" };
     const nested = jest.fn();
-    const action = jest.fn((_args, context) => {
-        expect(context.workflow).toBeUndefined();
-        expect(context.callContext.workflow).toBeUndefined();
-        expect(context.incomingCallContext.workflow).toBeUndefined();
-    });
     const resolution = {
         contractId: "contract",
         version: 1,
         forwardCallContext: true,
-        actionAliases: { do: "action" },
-        actionTools: {
-            action: { tool: { name: "action", usageDescription: "", accessLevel: 0 }, toolFn: action },
-        },
         tools: {
             run: {
                 tool: { name: "run", usageDescription: "", accessLevel: 0 },
@@ -26,7 +17,6 @@ test("only the directly invoked tool receives workflow capability", async () =>
                     expect(context.callContext.workflow).toBeUndefined();
                     expect(context.incomingCallContext.workflow).toBeUndefined();
                     await context.dispatchTool({ contractId: "other", version: 1, toolName: "target" }, {});
-                    await context.dispatchAction("do", {});
                 },
             },
         },
@@ -51,7 +41,6 @@ test("only the directly invoked tool receives workflow capability", async () =>
         args: [{}],
     }, { dataContext, callerUserId: "u", workflow });
     expect(nested.mock.calls[0][2].workflow).toBeUndefined();
-    expect(action).toHaveBeenCalled();
     expect(() => (0, contract_proxy_1.requireWorkflowRunContext)({ dataContextId: "other", workflow }, "run")).toThrow("same data context");
 });
 test("workflow policy is retained by shape extraction", () => {

package/dist/contracts/builder.d.ts

@@ -2,7 +2,7 @@ import type { ITableDefinition } from "../data/orm/table-definitions.type";
 import type { IContractConsumer, IContractConsumerBase } from "./contract-proxy";
 import type { IExtractableTableDef, IExtractableToolInstance } from "./extract";
 import type { IToolCatalogMetadata } from "./tool-catalog";
-import type { IAlsoImplementsDeclaration, IConsumedContractHandle, IConsumedContractOptions, IContractDefinition, IContractEvent, IContractObservable, IPackageDefinitionResult, IRemoteContractHandle } from "./types";
+import type { IAlsoImplementsDeclaration, IConsumedContractHandle, IConsumedContractOptions, IContractDefinition, IContractEvent, IContractObservable, IExposedContract, IPackageDefinitionResult, IRemoteContractHandle } from "./types";
 /**
  * Scoped builder for a single contract within a package. Returned by
  * `PackageBuilder.contract()`.
@@ -17,6 +17,7 @@ export declare class ContractBuilder {
     private _observables;
     private _events;
     private _alsoImplements;
+    private _exposes;
     private warnedAboutToolInstances;
     /** Full table definitions for this contract (used by the install flow). */
     private _tableDefinitions;
@@ -50,10 +51,20 @@ export declare class ContractBuilder {
         from: number;
         to: number;
     }): void;
+    /**
+     * Expose another contract this package provides through this one: this contract's consumers
+     * may call that contract's tools on this provider without consuming it. Use it when this
+     * contract is a hub's, such as Voice Skill.
+     *
+     * @param contractId - A contract this package also provides.
+     * @param version - Its version.
+     */
+    exposes(contractId: string, version: number): void;
     /** @internal Build the contract definition by extracting shapes. */
     _build(): {
         definition: IContractDefinition;
         alsoImplements: IAlsoImplementsDeclaration[];
+        exposes: IExposedContract[];
         toolMetadata: IToolCatalogMetadata[];
         tableDefinitions: ITableDefinition[];
     };
@@ -141,8 +152,11 @@ export declare class PackageBuilder {
      * @param contractId - Must be a valid peer ID (25-char alphanumeric from `newid()`).
      * @param version - Positive integer version number.
      * @param name - Human-readable contract name. This is the meaningful identifier that creators can change over time.
+     * @param description - What the contract is for, for people and models reading it. Hubs such
+     *   as Voice Hub show it for a contract a provider exposes. A description may change at any
+     *   time, also on a frozen contract.
      */
-    contract(contractId: string, version: number, name: string): ContractBuilder;
+    contract(contractId: string, version: number, name: string, description?: string): ContractBuilder;
     /**
      * Declare a dependency on another package's contract.
      *

package/dist/contracts/builder.js

@@ -25,6 +25,7 @@ class ContractBuilder {
     _observables = [];
     _events = [];
     _alsoImplements = [];
+    _exposes = [];
     warnedAboutToolInstances = false;
     /** Full table definitions for this contract (used by the install flow). */
     _tableDefinitions = [];
@@ -90,6 +91,23 @@ class ContractBuilder {
         }
         this._alsoImplements.push({ contractId: targetContractId, version: versionOrRange });
     }
+    /**
+     * Expose another contract this package provides through this one: this contract's consumers
+     * may call that contract's tools on this provider without consuming it. Use it when this
+     * contract is a hub's, such as Voice Skill.
+     *
+     * @param contractId - A contract this package also provides.
+     * @param version - Its version.
+     */
+    exposes(contractId, version) {
+        if (!(0, utils_1.isid)(contractId)) {
+            throw new Error(`exposes contractId must be a valid peer ID (25-char alphanumeric), got "${contractId}"`);
+        }
+        if (!Number.isInteger(version) || version < 1) {
+            throw new Error(`exposes version must be a positive integer, got ${version}`);
+        }
+        this._exposes.push({ contractId, version });
+    }
     /** @internal Build the contract definition by extracting shapes. */
     _build() {
         return {
@@ -105,6 +123,7 @@ class ContractBuilder {
                 events: [...this._events],
             },
             alsoImplements: [...this._alsoImplements],
+            exposes: [...this._exposes],
             toolMetadata: this._tools.flatMap(({ tool }) => {
                 const { isAssistantRunner, configSchema, detailedDescription } = tool;
                 return isAssistantRunner !== undefined ||
@@ -249,8 +268,11 @@ class PackageBuilder {
      * @param contractId - Must be a valid peer ID (25-char alphanumeric from `newid()`).
      * @param version - Positive integer version number.
      * @param name - Human-readable contract name. This is the meaningful identifier that creators can change over time.
+     * @param description - What the contract is for, for people and models reading it. Hubs such
+     *   as Voice Hub show it for a contract a provider exposes. A description may change at any
+     *   time, also on a frozen contract.
      */
-    contract(contractId, version, name) {
+    contract(contractId, version, name, description) {
         if (!(0, utils_1.isid)(contractId)) {
             throw new Error(`contractId must be a valid peer ID (25-char alphanumeric), got "${contractId}"`);
         }
@@ -261,7 +283,7 @@ class PackageBuilder {
         if (existing) {
             throw new Error(`Duplicate contract: ${contractId} v${version} is already defined in this package`);
         }
-        const builder = new ContractBuilder(contractId, version, name);
+        const builder = new ContractBuilder(contractId, version, name, description);
         this._contracts.push(builder);
         return builder;
     }
@@ -330,17 +352,35 @@ class PackageBuilder {
         }
         const contracts = [];
         const alsoImplementsMap = new Map();
+        const exposesMap = new Map();
         const allToolMetadata = [];
         const allTableDefinitions = [];
         for (const cb of this._contracts) {
-            const { definition, alsoImplements, toolMetadata, tableDefinitions } = cb._build();
+            const { definition, alsoImplements, exposes, toolMetadata, tableDefinitions } = cb._build();
             contracts.push(definition);
             if (alsoImplements.length > 0) {
                 alsoImplementsMap.set((0, types_1.contractKey)(cb.contractId, cb.version), alsoImplements);
             }
+            if (exposes.length > 0) {
+                exposesMap.set((0, types_1.contractKey)(cb.contractId, cb.version), exposes);
+            }
             allToolMetadata.push(...toolMetadata);
             allTableDefinitions.push(...tableDefinitions);
         }
+        const providedKeys = new Set(contracts.map((contract) => (0, types_1.contractKey)(contract.contractId, contract.version)));
+        for (const [hub, exposes] of exposesMap) {
+            const seen = new Set();
+            for (const target of exposes) {
+                const key = (0, types_1.contractKey)(target.contractId, target.version);
+                if (key === hub)
+                    throw new Error(`Contract ${hub} can't expose itself`);
+                if (seen.has(key))
+                    throw new Error(`Contract ${hub} exposes ${key} twice`);
+                if (!providedKeys.has(key))
+                    throw new Error(`Contract ${hub} exposes ${key}, which the package doesn't provide`);
+                seen.add(key);
+            }
+        }
         if (contracts.length === 0 && allTableDefinitions.length > 0) {
             throw new Error("Tables must be declared on a contract (use pkg.contract(...), then assign .tables or .tableDefinitions on that builder). UI-only packages omit contracts and do not register tables.");
         }
@@ -351,6 +391,7 @@ class PackageBuilder {
             consumes: [...this._consumes],
             remotes: [...this._remotes],
             alsoImplements: alsoImplementsMap,
+            exposes: exposesMap,
             assistants: [...this.assistants],
             appNavs: [...this.appNavs],
             ...(allToolMetadata.length ? { toolMetadata: allToolMetadata } : {}),