@peers-app/peers-sdk 0.21.1 → 0.21.3

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

@@ -1,324 +1,66 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-const field_type_1 = require("../../types/field-type");
 const utils_1 = require("../../utils");
 const registry_1 = require("../registry");
-const DEFAULT_CONTRACT_ID = (0, utils_1.newid)();
-function makeContract(overrides = {}) {
+function makeDefinition(contractId, version, name = "Test Contract") {
     return {
-        contractId: DEFAULT_CONTRACT_ID,
-        version: 1,
-        name: "Test Contract",
-        description: "A test contract",
+        contractId,
+        version,
+        devTag: "dev",
+        name,
+        description: "test",
         tables: [],
         tools: [],
         observables: [],
-        ...overrides,
+        events: [],
     };
 }
-describe("ContractRegistry", () => {
+describe("ContractRegistry.selectProvider", () => {
+    const contractId = (0, utils_1.newid)();
+    const packageA = (0, utils_1.newid)();
+    const packageB = (0, utils_1.newid)();
+    const packageC = (0, utils_1.newid)();
     let registry;
     beforeEach(() => {
         registry = new registry_1.ContractRegistry();
+        registry.register(packageA, makeDefinition(contractId, 1, "A"));
+        registry.register(packageB, makeDefinition(contractId, 1, "B"));
     });
-    describe("register and resolve", () => {
-        it("registers a provider and resolves it", () => {
-            const def = makeContract({
-                tables: [
-                    {
-                        name: "Tasks",
-                        description: "d",
-                        primaryKeyName: "taskId",
-                        fields: [{ name: "taskId", type: field_type_1.FieldType.id }],
-                    },
-                ],
-            });
-            const pkgId = (0, utils_1.newid)();
-            const result = registry.register(pkgId, def);
-            expect(result.valid).toBe(true);
-            const resolved = registry.resolve(DEFAULT_CONTRACT_ID, 1);
-            expect(resolved).toBeDefined();
-            expect(resolved?.tables[0].name).toBe("Tasks");
-        });
-        it("returns the provider package ID", () => {
-            const def = makeContract();
-            const pkgId = (0, utils_1.newid)();
-            registry.register(pkgId, def);
-            expect(registry.getProviderPackageId(DEFAULT_CONTRACT_ID, 1)).toBe(pkgId);
-        });
-        it("returns undefined for unregistered contracts", () => {
-            const unknownId = (0, utils_1.newid)();
-            expect(registry.resolve(unknownId, 1)).toBeUndefined();
-            expect(registry.getProviderPackageId(unknownId, 1)).toBeUndefined();
-        });
-        it("auto-activates the first registered provider", () => {
-            const def = makeContract();
-            const pkgA = (0, utils_1.newid)();
-            registry.register(pkgA, def);
-            expect(registry.getProviderPackageId(DEFAULT_CONTRACT_ID, 1)).toBe(pkgA);
-        });
-        it("does not auto-switch when a second provider is registered", () => {
-            const def = makeContract();
-            const pkgA = (0, utils_1.newid)();
-            const pkgB = (0, utils_1.newid)();
-            registry.register(pkgA, def);
-            registry.register(pkgB, def);
-            expect(registry.getProviderPackageId(DEFAULT_CONTRACT_ID, 1)).toBe(pkgA);
-        });
+    it("returns registered provider ids in registration order", () => {
+        expect(registry.getRegisteredProviderIds(contractId, 1)).toEqual([packageA, packageB]);
     });
-    describe("setActiveProvider", () => {
-        it("switches the active provider", () => {
-            const def = makeContract();
-            const pkgA = (0, utils_1.newid)();
-            const pkgB = (0, utils_1.newid)();
-            registry.register(pkgA, def);
-            registry.register(pkgB, def);
-            const switched = registry.setActiveProvider(DEFAULT_CONTRACT_ID, 1, pkgB);
-            expect(switched).toBe(true);
-            expect(registry.getProviderPackageId(DEFAULT_CONTRACT_ID, 1)).toBe(pkgB);
-        });
-        it("returns false if the target package is not registered", () => {
-            const def = makeContract();
-            const pkgA = (0, utils_1.newid)();
-            const unknownPkg = (0, utils_1.newid)();
-            registry.register(pkgA, def);
-            const switched = registry.setActiveProvider(DEFAULT_CONTRACT_ID, 1, unknownPkg);
-            expect(switched).toBe(false);
-            expect(registry.getProviderPackageId(DEFAULT_CONTRACT_ID, 1)).toBe(pkgA);
-        });
-        it("returns false for unknown contracts", () => {
-            const unknownId = (0, utils_1.newid)();
-            const pkgA = (0, utils_1.newid)();
-            expect(registry.setActiveProvider(unknownId, 1, pkgA)).toBe(false);
-        });
+    it("selects the active provider when no preference is given", () => {
+        const selected = registry.selectProvider({ contractId, version: 1 });
+        expect(selected?.providerPackageId).toBe(packageA);
     });
-    describe("unregister", () => {
-        it("removes a provider and its resolution", () => {
-            const def = makeContract();
-            const pkgA = (0, utils_1.newid)();
-            registry.register(pkgA, def);
-            registry.unregister(pkgA);
-            expect(registry.resolve(DEFAULT_CONTRACT_ID, 1)).toBeUndefined();
-            expect(registry.getProviderPackageId(DEFAULT_CONTRACT_ID, 1)).toBeUndefined();
-        });
-        it("falls back to next provider when active is removed", () => {
-            const def = makeContract();
-            const pkgA = (0, utils_1.newid)();
-            const pkgB = (0, utils_1.newid)();
-            registry.register(pkgA, def);
-            registry.register(pkgB, def);
-            registry.unregister(pkgA);
-            expect(registry.getProviderPackageId(DEFAULT_CONTRACT_ID, 1)).toBe(pkgB);
-        });
-        it("is a no-op for unknown packages", () => {
-            const unknownPkg = (0, utils_1.newid)();
-            expect(() => registry.unregister(unknownPkg)).not.toThrow();
-        });
-        it("handles a package that provides multiple contracts", () => {
-            const contractId1 = (0, utils_1.newid)();
-            const contractId2 = (0, utils_1.newid)();
-            const def1 = makeContract({ contractId: contractId1 });
-            const def2 = makeContract({ contractId: contractId2 });
-            const pkgA = (0, utils_1.newid)();
-            registry.register(pkgA, def1);
-            registry.register(pkgA, def2);
-            registry.unregister(pkgA);
-            expect(registry.resolve(contractId1, 1)).toBeUndefined();
-            expect(registry.resolve(contractId2, 1)).toBeUndefined();
-        });
+    it("selects the first preferred provider that is registered", () => {
+        const dep = {
+            contractId,
+            version: 1,
+            providerPackageIds: [packageC, packageB, packageA],
+        };
+        expect(registry.selectProvider(dep)?.providerPackageId).toBe(packageB);
     });
-    describe("checkConsumerDependencies", () => {
-        it("reports all satisfied when providers exist", () => {
-            const tasksId = (0, utils_1.newid)();
-            const authId = (0, utils_1.newid)();
-            const pkgA = (0, utils_1.newid)();
-            const pkgB = (0, utils_1.newid)();
-            registry.register(pkgA, makeContract({ contractId: tasksId }));
-            registry.register(pkgB, makeContract({ contractId: authId }));
-            const result = registry.checkConsumerDependencies([
-                { contractId: tasksId, version: 1 },
-                { contractId: authId, version: 1 },
-            ]);
-            expect(result.satisfied).toHaveLength(2);
-            expect(result.missing).toHaveLength(0);
-        });
-        it("reports missing when no provider exists", () => {
-            const tasksId = (0, utils_1.newid)();
-            const authId = (0, utils_1.newid)();
-            const pkgA = (0, utils_1.newid)();
-            registry.register(pkgA, makeContract({ contractId: tasksId }));
-            const result = registry.checkConsumerDependencies([
-                { contractId: tasksId, version: 1 },
-                { contractId: authId, version: 1 },
-            ]);
-            expect(result.satisfied).toHaveLength(1);
-            expect(result.missing).toHaveLength(1);
-            expect(result.missing[0].contractId).toBe(authId);
-        });
-        it("reports all missing when registry is empty", () => {
-            const tasksId = (0, utils_1.newid)();
-            const result = registry.checkConsumerDependencies([{ contractId: tasksId, version: 1 }]);
-            expect(result.satisfied).toHaveLength(0);
-            expect(result.missing).toHaveLength(1);
-        });
-        it("returns empty lists for empty consumer list", () => {
-            const result = registry.checkConsumerDependencies([]);
-            expect(result.satisfied).toHaveLength(0);
-            expect(result.missing).toHaveLength(0);
-        });
+    it("falls back to the active provider when preferred are missing and fallback is enabled", () => {
+        const dep = {
+            contractId,
+            version: 1,
+            providerPackageIds: [packageC],
+            fallbackToDefaultProvider: true,
+        };
+        expect(registry.selectProvider(dep)?.providerPackageId).toBe(packageA);
     });
-    describe("immutability enforcement", () => {
-        it("rejects re-registration of a frozen contract with a different shape", () => {
-            const def1 = makeContract({
-                tables: [
-                    {
-                        name: "T",
-                        description: "d",
-                        primaryKeyName: "id",
-                        fields: [{ name: "id", type: field_type_1.FieldType.id }],
-                    },
-                ],
-            });
-            const pkgA = (0, utils_1.newid)();
-            registry.register(pkgA, def1);
-            const def2 = makeContract({
-                tables: [
-                    {
-                        name: "T",
-                        description: "d",
-                        primaryKeyName: "id",
-                        fields: [
-                            { name: "id", type: field_type_1.FieldType.id },
-                            { name: "extra", type: field_type_1.FieldType.string },
-                        ],
-                    },
-                ],
-            });
-            const pkgB = (0, utils_1.newid)();
-            const result = registry.register(pkgB, def2);
-            expect(result.valid).toBe(false);
-            expect(result.errors[0].message).toContain("frozen");
-        });
-        it("allows re-registration of a dev contract with a different shape", () => {
-            const def1 = makeContract({
-                devTag: "dev",
-                tables: [
-                    {
-                        name: "T",
-                        description: "d",
-                        primaryKeyName: "id",
-                        fields: [{ name: "id", type: field_type_1.FieldType.id }],
-                    },
-                ],
-            });
-            const pkgA = (0, utils_1.newid)();
-            registry.register(pkgA, def1);
-            const def2 = makeContract({
-                devTag: "dev",
-                tables: [
-                    {
-                        name: "T",
-                        description: "d",
-                        primaryKeyName: "id",
-                        fields: [
-                            { name: "id", type: field_type_1.FieldType.id },
-                            { name: "extra", type: field_type_1.FieldType.string },
-                        ],
-                    },
-                ],
-            });
-            const pkgB = (0, utils_1.newid)();
-            const result = registry.register(pkgB, def2);
-            expect(result.valid).toBe(true);
-        });
-        it("rejects dev registration after a stable version exists", () => {
-            const stableDef = makeContract({
-                tables: [
-                    {
-                        name: "T",
-                        description: "d",
-                        primaryKeyName: "id",
-                        fields: [{ name: "id", type: field_type_1.FieldType.id }],
-                    },
-                ],
-            });
-            const pkgA = (0, utils_1.newid)();
-            registry.register(pkgA, stableDef);
-            const devDef = makeContract({
-                devTag: "dev",
-                tables: [
-                    {
-                        name: "T",
-                        description: "d",
-                        primaryKeyName: "id",
-                        fields: [{ name: "id", type: field_type_1.FieldType.id }],
-                    },
-                ],
-            });
-            const pkgB = (0, utils_1.newid)();
-            const result = registry.register(pkgB, devDef);
-            expect(result.valid).toBe(false);
-            expect(result.errors[0].message).toContain("frozen");
-        });
-        it("allows dev-to-stable transition, then rejects subsequent dev registration", () => {
-            const devDef = makeContract({
-                devTag: "dev",
-                tables: [
-                    {
-                        name: "T",
-                        description: "d",
-                        primaryKeyName: "id",
-                        fields: [{ name: "id", type: field_type_1.FieldType.id }],
-                    },
-                ],
-            });
-            const pkgA = (0, utils_1.newid)();
-            registry.register(pkgA, devDef);
-            const stableDef = makeContract({
-                tables: [
-                    {
-                        name: "T",
-                        description: "d",
-                        primaryKeyName: "id",
-                        fields: [
-                            { name: "id", type: field_type_1.FieldType.id },
-                            { name: "title", type: field_type_1.FieldType.string },
-                        ],
-                    },
-                ],
-            });
-            const pkgB = (0, utils_1.newid)();
-            const stableResult = registry.register(pkgB, stableDef);
-            expect(stableResult.valid).toBe(true);
-            const devDef2 = makeContract({
-                devTag: "dev",
-                tables: [
-                    {
-                        name: "T",
-                        description: "d",
-                        primaryKeyName: "id",
-                        fields: [{ name: "id", type: field_type_1.FieldType.id }],
-                    },
-                ],
-            });
-            const pkgC = (0, utils_1.newid)();
-            const devResult = registry.register(pkgC, devDef2);
-            expect(devResult.valid).toBe(false);
-            expect(devResult.errors[0].message).toContain("frozen");
-        });
+    it("returns undefined when preferred are missing and fallback is disabled", () => {
+        const dep = {
+            contractId,
+            version: 1,
+            providerPackageIds: [packageC],
+            fallbackToDefaultProvider: false,
+        };
+        expect(registry.selectProvider(dep)).toBeUndefined();
     });
-    describe("getDefinition", () => {
-        it("returns the stored definition", () => {
-            const def = makeContract({ name: "My Contract" });
-            const pkgA = (0, utils_1.newid)();
-            registry.register(pkgA, def);
-            const stored = registry.getDefinition(DEFAULT_CONTRACT_ID, 1);
-            expect(stored).toBeDefined();
-            expect(stored?.name).toBe("My Contract");
-        });
-        it("returns undefined for unknown contracts", () => {
-            const unknownId = (0, utils_1.newid)();
-            expect(registry.getDefinition(unknownId, 1)).toBeUndefined();
-        });
+    it("returns undefined when no providers are registered", () => {
+        const empty = new registry_1.ContractRegistry();
+        expect(empty.selectProvider({ contractId, version: 1 })).toBeUndefined();
     });
 });

package/dist/contracts/__tests__/system-contracts.test.d.ts

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

package/dist/contracts/__tests__/system-contracts.test.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const system_ids_1 = require("../../system-ids");
+const utils_1 = require("../../utils");
+const contract_resolvers_1 = require("../contract-resolvers");
+const registry_1 = require("../registry");
+const system_contracts_1 = require("../system-contracts");
+// Populate the catalog with built-in system contracts.
+require("../system");
+describe("system contract catalog", () => {
+    it("self-registers the built-in system contracts", () => {
+        const ids = (0, system_contracts_1.listSystemContracts)()
+            .map((entry) => entry.contractId)
+            .filter(Boolean);
+        expect(ids).toEqual(expect.arrayContaining([
+            system_ids_1.logsContractId,
+            system_ids_1.deviceOperationsContractId,
+            system_ids_1.networkDiagnosticsContractId,
+            system_ids_1.networkControlContractId,
+        ]));
+    });
+    it("registers the Logs live resolver", async () => {
+        await new Promise((resolve) => queueMicrotask(resolve));
+        expect((0, contract_resolvers_1.getContractResolver)(system_ids_1.logsContractId, 1)).toEqual(expect.any(Function));
+    });
+    it("installSystemContracts seeds a registry with system providers", () => {
+        const registry = new registry_1.ContractRegistry();
+        (0, system_contracts_1.installSystemContracts)(registry);
+        expect(registry.resolve(system_ids_1.logsContractId, 1)?.name).toBe("System Logs");
+        expect(registry.getProviderPackageId(system_ids_1.logsContractId, 1)).toBe(system_ids_1.peersSystemPackageId);
+        expect(registry.resolve(system_ids_1.deviceOperationsContractId, 1)?.name).toBe("System Device Operations");
+        expect(registry.getProviderPackageId(system_ids_1.deviceOperationsContractId, 1)).toBe(system_ids_1.peersSystemPackageId);
+        expect(registry.resolve(system_ids_1.networkDiagnosticsContractId, 1)?.name).toBe("System Network Diagnostics");
+        expect(registry.getProviderPackageId(system_ids_1.networkDiagnosticsContractId, 1)).toBe(system_ids_1.peersSystemPackageId);
+        expect(registry.resolve(system_ids_1.networkControlContractId, 1)?.name).toBe("System Network Control");
+        expect(registry.getProviderPackageId(system_ids_1.networkControlContractId, 1)).toBe(system_ids_1.peersSystemPackageId);
+    });
+    it("registerSystemContract makes new contracts installable without loader changes", () => {
+        const fakeContractId = (0, utils_1.newid)();
+        const providerPackageId = (0, utils_1.newid)();
+        (0, system_contracts_1.registerSystemContract)({
+            providerPackageId,
+            contractId: fakeContractId,
+            version: 1,
+            getDefinition: () => ({
+                contractId: fakeContractId,
+                version: 1,
+                devTag: "dev",
+                name: "Fake System Contract",
+                description: "test",
+                tables: [],
+                tools: [],
+                observables: [],
+                events: [],
+            }),
+        });
+        const registry = new registry_1.ContractRegistry();
+        (0, system_contracts_1.installSystemContracts)(registry);
+        expect(registry.getProviderPackageId(fakeContractId, 1)).toBe(providerPackageId);
+    });
+});

package/dist/contracts/builder.d.ts

@@ -1,7 +1,8 @@
 import type { ITableDefinition } from "../data/orm/table-definitions.type";
 import type { IToolInstance } from "../data/tools";
+import type { IContractConsumer, IContractConsumerBase } from "./contract-proxy";
 import type { IExtractableTableDef, IExtractableToolInstance } from "./extract";
-import type { IAlsoImplementsDeclaration, IContractDefinition, IContractEvent, IContractObservable, IPackageDefinitionResult } from "./types";
+import type { IAlsoImplementsDeclaration, IConsumedContractHandle, IConsumedContractOptions, IContractDefinition, IContractEvent, IContractObservable, IPackageDefinitionResult } from "./types";
 /**
  * Scoped builder for a single contract within a package. Returned by
  * `PackageBuilder.contract()`.
@@ -56,6 +57,27 @@ export declare class ContractBuilder {
         tableDefinitions: ITableDefinition[];
     };
 }
+/**
+ * Create a deferred consumed-contract handle. Settlement is SDK-owned via
+ * {@link settleConsumedContractHandle} / {@link rejectConsumedContractHandle}.
+ *
+ * @internal
+ */
+export declare function createConsumedContractHandle<T extends IContractConsumerBase | undefined = IContractConsumerBase | undefined>(): IConsumedContractHandle<T>;
+/**
+ * Resolve a consumed-contract handle with a live proxy, or `undefined` for an
+ * unmatched optional dependency. One-shot — throws if already settled.
+ *
+ * @internal Used by the package-loader when settling `consumes` handles.
+ */
+export declare function settleConsumedContractHandle(handle: IConsumedContractHandle<IContractConsumerBase | undefined>, consumer: IContractConsumerBase | undefined): void;
+/**
+ * Reject a consumed-contract handle (e.g. required dependency missing).
+ * One-shot — throws if already settled.
+ *
+ * @internal Used by the package-loader when settling `consumes` handles.
+ */
+export declare function rejectConsumedContractHandle(handle: IConsumedContractHandle<IContractConsumerBase | undefined>, reason: unknown): void;
 /**
  * Top-level builder passed to the `definePackage` callback.
  *
@@ -95,8 +117,27 @@ export declare class PackageBuilder {
     contract(contractId: string, version: number, name: string): ContractBuilder;
     /**
      * Declare a dependency on another package's contract.
+     *
+     * Returns a deferred handle immediately. Await `handle.consumer` from
+     * runtime code after package definition — not inside this callback — so
+     * package loading stays non-blocking. The package-loader settles the
+     * promise once providers are registered (follow-up work).
+     *
+     * Pass a type argument to narrow the resolved consumer beyond the default
+     * {@link IContractConsumer} shape, e.g. `pkg.consumes<ILogsConsumer>(id, 1)`.
+     * Typed consumers need only extend {@link IContractConsumerBase}.
+     *
+     * @typeParam T - Consumer proxy type (defaults to {@link IContractConsumer}).
+     * @param contractId - Must be a valid peer ID (25-char alphanumeric from `newid()`).
+     * @param version - Positive integer version number.
+     * @param opts - Optional dependency and provider-preference options.
      */
-    consumes(contractId: string, version: number): void;
+    consumes<T extends IContractConsumerBase = IContractConsumer>(contractId: string, version: number, opts: IConsumedContractOptions & {
+        optional: true;
+    }): IConsumedContractHandle<T | undefined>;
+    consumes<T extends IContractConsumerBase = IContractConsumer>(contractId: string, version: number, opts?: Omit<IConsumedContractOptions, "optional"> & {
+        optional?: false;
+    }): IConsumedContractHandle<T>;
     /** @internal Finalize and return the package definition result. */
     _build(): IPackageDefinitionResult;
 }

package/dist/contracts/builder.js

@@ -1,6 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PackageBuilder = exports.ContractBuilder = void 0;
+exports.createConsumedContractHandle = createConsumedContractHandle;
+exports.settleConsumedContractHandle = settleConsumedContractHandle;
+exports.rejectConsumedContractHandle = rejectConsumedContractHandle;
 exports.definePackage = definePackage;
 const utils_1 = require("../utils");
 const extract_1 = require("./extract");
@@ -103,6 +106,61 @@ class ContractBuilder {
     }
 }
 exports.ContractBuilder = ContractBuilder;
+const consumedContractDeferreds = new WeakMap();
+/**
+ * Create a deferred consumed-contract handle. Settlement is SDK-owned via
+ * {@link settleConsumedContractHandle} / {@link rejectConsumedContractHandle}.
+ *
+ * @internal
+ */
+function createConsumedContractHandle() {
+    let resolve;
+    let reject;
+    const consumer = new Promise((res, rej) => {
+        resolve = res;
+        reject = rej;
+    });
+    // Avoid unhandled-rejection noise when the package-loader settles with an
+    // error before any package code awaits the handle.
+    consumer.catch(() => { });
+    const handle = { consumer };
+    consumedContractDeferreds.set(handle, { resolve, reject, settled: false });
+    return handle;
+}
+/**
+ * Resolve a consumed-contract handle with a live proxy, or `undefined` for an
+ * unmatched optional dependency. One-shot — throws if already settled.
+ *
+ * @internal Used by the package-loader when settling `consumes` handles.
+ */
+function settleConsumedContractHandle(handle, consumer) {
+    const deferred = consumedContractDeferreds.get(handle);
+    if (!deferred) {
+        throw new Error("Unknown consumed-contract handle");
+    }
+    if (deferred.settled) {
+        throw new Error("Consumed-contract handle has already been settled");
+    }
+    deferred.settled = true;
+    deferred.resolve(consumer);
+}
+/**
+ * Reject a consumed-contract handle (e.g. required dependency missing).
+ * One-shot — throws if already settled.
+ *
+ * @internal Used by the package-loader when settling `consumes` handles.
+ */
+function rejectConsumedContractHandle(handle, reason) {
+    const deferred = consumedContractDeferreds.get(handle);
+    if (!deferred) {
+        throw new Error("Unknown consumed-contract handle");
+    }
+    if (deferred.settled) {
+        throw new Error("Consumed-contract handle has already been settled");
+    }
+    deferred.settled = true;
+    deferred.reject(reason);
+}
 /**
  * Top-level builder passed to the `definePackage` callback.
  *
@@ -165,14 +223,30 @@ class PackageBuilder {
         this._contracts.push(builder);
         return builder;
     }
-    /**
-     * Declare a dependency on another package's contract.
-     */
-    consumes(contractId, version) {
+    consumes(contractId, version, opts) {
         if (!(0, utils_1.isid)(contractId)) {
             throw new Error(`consumes contractId must be a valid peer ID (25-char alphanumeric), got "${contractId}"`);
         }
-        this._consumes.push({ contractId, version });
+        if (version < 1 || !Number.isInteger(version)) {
+            throw new Error(`consumes version must be a positive integer, got ${version}`);
+        }
+        if (opts?.providerPackageIds) {
+            for (const providerPackageId of opts.providerPackageIds) {
+                if (!(0, utils_1.isid)(providerPackageId)) {
+                    throw new Error(`consumes providerPackageIds entries must be valid peer IDs (25-char alphanumeric), got "${providerPackageId}"`);
+                }
+            }
+        }
+        const handle = createConsumedContractHandle();
+        this._consumes.push({
+            contractId,
+            version,
+            optional: opts?.optional,
+            providerPackageIds: opts?.providerPackageIds ? [...opts.providerPackageIds] : undefined,
+            fallbackToDefaultProvider: opts?.fallbackToDefaultProvider,
+            handle,
+        });
+        return handle;
     }
     /** @internal Finalize and return the package definition result. */
     _build() {