@peers-app/peers-sdk 0.21.1 → 0.21.3

package/dist/contracts/system/logs-contract.d.ts

@@ -1,8 +1,25 @@
 import type { DataContext } from "../../context/data-context";
-import type { IContractResolution } from "../contract-proxy";
+import { ConsoleLogsTable } from "../../logging/console-logs.table";
+import type { IContractConsumerBase, IContractResolution, ITableProxy } from "../contract-proxy";
 import type { IContractDefinition } from "../types";
 /** Version of the built-in System Logs contract. */
 export declare const LOGS_CONTRACT_VERSION = 1;
+/**
+ * Consumer-side TypeScript shape for the System Logs contract.
+ *
+ * Hand-maintained for now so packages can narrow `pkg.consumes(...)` (e.g.
+ * `pkg.consumes<ILogsConsumer>(logsContractId, 1)`). Expect this to be
+ * replaced by types generated from package/contract definitions.
+ *
+ * Omits empty `tools` / `events` / `observables` bags. `ConsoleLogs` is an
+ * {@link ITableProxy} of the remotely callable table surface — not a literal
+ * {@link ConsoleLogsTable} instance.
+ */
+export interface ILogsConsumer extends IContractConsumerBase {
+    tables: {
+        ConsoleLogs: ITableProxy<ConsoleLogsTable, "deleteOldLogs">;
+    };
+}
 /**
  * The first built-in **system contract**: read and write the local device's console logs.
  *

package/dist/contracts/system/logs-contract.js

@@ -7,7 +7,7 @@ const user_context_singleton_1 = require("../../context/user-context-singleton")
 const types_1 = require("../../data/orm/types");
 const console_logs_table_1 = require("../../logging/console-logs.table");
 const system_ids_1 = require("../../system-ids");
-const contract_resolvers_1 = require("../contract-resolvers");
+const system_contracts_1 = require("../system-contracts");
 /** Version of the built-in System Logs contract. */
 exports.LOGS_CONTRACT_VERSION = 1;
 let _definition;
@@ -57,4 +57,10 @@ function resolveLogsContract(ctx) {
         tables: { [console_logs_table_1.consoleLogsMetaData.name]: consoleLogs },
     };
 }
-(0, contract_resolvers_1.registerContractResolver)(system_ids_1.logsContractId, exports.LOGS_CONTRACT_VERSION, resolveLogsContract);
+(0, system_contracts_1.registerSystemContract)({
+    providerPackageId: system_ids_1.peersSystemPackageId,
+    contractId: system_ids_1.logsContractId,
+    version: exports.LOGS_CONTRACT_VERSION,
+    getDefinition: getLogsContractDefinition,
+    resolve: resolveLogsContract,
+});

package/dist/contracts/system/network-contracts.d.ts

@@ -0,0 +1,231 @@
+import type { TrustLevel } from "../../device/socket.type";
+import type { IConsoleLog } from "../../logging/console-logs.table";
+import type { Observable } from "../../observable";
+import type { INetworkInfo } from "../../types/peer-device";
+import type { IContractConsumerBase } from "../contract-proxy";
+import type { IContractDefinition } from "../types";
+/** Version of the built-in System Network Diagnostics contract. */
+export declare const NETWORK_DIAGNOSTICS_CONTRACT_VERSION = 1;
+/** Version of the built-in System Network Control contract. */
+export declare const NETWORK_CONTROL_CONTRACT_VERSION = 1;
+/** Stable IDs for tools in System Network Diagnostics v1. */
+export declare const networkDiagnosticsToolIds: {
+    readonly getOverview: "00ms1yb50ym353ads0gel5jpv";
+    readonly getConnections: "00ms1yb50ykny9kdgiclpa1t4";
+    readonly getGroupSyncStatus: "00ms1yb50yp2q7jr0jglzsztq";
+    readonly getDeviceDetails: "00ms1yb50yw792rslve1q99qg";
+    readonly getGroupDetails: "00ms1yb50yuru8h1fg4t9na3e";
+    readonly getDisconnectedDevices: "00ms1yb50y3jpoby5zomltahr";
+    readonly queryRemoteLogs: "00ms1yb50y2fbfnth22yz52eu";
+};
+/** Stable IDs for tools in System Network Control v1. */
+export declare const networkControlToolIds: {
+    readonly refreshNetworkInfo: "00ms1yb50y9rsdyqmr81vjoli";
+    readonly connectToDevice: "00ms1yb50y40ty8tr0sic875x";
+    readonly disconnectDevice: "00ms1yb50yqvboqmhshqvlibr";
+    readonly deleteDevice: "00ms1yb50y5mc448nuavlex86";
+    readonly syncGroupNow: "00ms1yb50ylnqlra26jx232py";
+    readonly resetChangeTracking: "00ms1yb50yfuackpl1w37hmxc";
+};
+/** Overall status shown by the shell's compact network indicator. */
+export type NetworkStatusState = "offline" | "syncing" | "synced" | "error";
+/** Runtime synchronization state for one personal or shared-group context. */
+export type NetworkSyncState = "idle" | "syncing" | "error";
+/** Safe, bounded synchronization error detail suitable for local UI display. */
+export interface INetworkSyncError {
+    dataContextId: string;
+    message: string;
+    occurredAt: number;
+}
+/** Reactive summary consumed by the tabs-strip Network Status indicator. */
+export interface INetworkStatusSummary {
+    state: NetworkStatusState;
+    connectionCount: number;
+    syncingContextCount: number;
+    errorCount: number;
+    lastSuccessfulSyncAt?: number;
+    errors: INetworkSyncError[];
+}
+/** Current synchronization lifecycle for one data context. */
+export interface IDataContextSyncStatus {
+    dataContextId: string;
+    state: NetworkSyncState;
+    lastSuccessfulSyncAt?: number;
+    lastErrorAt?: number;
+    lastError?: string;
+}
+/** Connection/member counts for one personal or shared group. */
+export interface INetworkGroupSummary {
+    groupId: string;
+    groupName: string;
+    connectedDevices: number;
+    totalMembers: number;
+}
+/** Portable overview of the local device's network state. */
+export interface INetworkOverview {
+    localDeviceId: string;
+    localUserId: string;
+    totalConnections: number;
+    availableSlots: number;
+    maxConnections: number;
+    cpuPercent: number;
+    memPercent: number;
+    groups: INetworkGroupSummary[];
+}
+/** Detailed portable information about one active device connection. */
+export interface INetworkConnectionInfo {
+    deviceId: string;
+    userId: string;
+    userName?: string;
+    deviceName?: string;
+    userTrustLevel: TrustLevel;
+    deviceTrustLevel: TrustLevel;
+    connectionState: "connected" | "syncing" | "idle";
+    sharedGroups: string[];
+    roles: Record<string, string>;
+    pathType: "direct" | "indirect" | "unknown";
+    throughDeviceIds?: string[];
+    latencyMs: number;
+    errorRate: number;
+    isServer: boolean;
+    connectionAddress?: string;
+    bytesSent?: number;
+    bytesReceived?: number;
+    sendRateMBps?: number;
+    receiveRateMBps?: number;
+}
+/** Serializable synchronization connection detail for one group. */
+export interface INetworkSyncConnection {
+    deviceId: string;
+    latencyMs: number;
+    errorRate: number;
+    timestampLastApplied?: number;
+    closed?: boolean;
+}
+/** Synchronization status and topology for one data context. */
+export interface INetworkGroupSyncInfo {
+    groupId: string;
+    groupName: string;
+    connectedDevices: INetworkSyncConnection[];
+    preferredDeviceIds: string[];
+    lastSyncTimestamp: number;
+    totalMembers: number;
+    syncStatus: IDataContextSyncStatus;
+}
+/** Detailed portable information about one connected device. */
+export interface INetworkDeviceDetails extends INetworkConnectionInfo {
+    canReadRemoteLogs: boolean;
+    networkInfo?: INetworkInfo;
+    syncStatsByGroup: Record<string, {
+        lastSyncTime: number;
+        isPreferred: boolean;
+    }>;
+}
+/** A known device that does not currently have an active connection. */
+export interface INetworkDisconnectedDevice {
+    deviceId: string;
+    userId: string;
+    userName?: string;
+    trustLevel: TrustLevel;
+    firstSeen: Date;
+    lastSeen: Date;
+    name?: string;
+    serverUrl?: string;
+}
+/** One member shown in Network Viewer's group detail. */
+export interface INetworkGroupMember {
+    userId: string;
+    userName?: string;
+    role: string;
+    trustLevel: TrustLevel;
+}
+/** Detailed portable membership information for one data context. */
+export interface INetworkGroupDetails {
+    groupId: string;
+    groupName: string;
+    founderUserId: string;
+    founderUserName?: string;
+    members: INetworkGroupMember[];
+}
+/** Filters and bounds for a directly connected device's System Logs query. */
+export interface INetworkRemoteLogsQuery {
+    sinceTimestamp?: number;
+    level?: IConsoleLog["level"];
+    process?: string;
+    search?: string;
+    pageSize?: number;
+    timeoutMs?: number;
+}
+/** Bounded remote logs returned through System Network Diagnostics. */
+export interface INetworkRemoteLogsResult {
+    deviceId: string;
+    truncated: boolean;
+    logs: IConsoleLog[];
+    queriedAt: number;
+}
+/** Structured result returned by every System Network Control operation. */
+export interface INetworkControlResult {
+    success: boolean;
+    message: string;
+}
+/** Typed consumer proxy for System Network Diagnostics v1. */
+export interface INetworkDiagnosticsConsumer extends IContractConsumerBase {
+    tools: {
+        getOverview(): Promise<{
+            overview: INetworkOverview;
+        }>;
+        getConnections(): Promise<{
+            connections: INetworkConnectionInfo[];
+        }>;
+        getGroupSyncStatus(input?: {
+            groupId?: string;
+        }): Promise<{
+            groups: INetworkGroupSyncInfo[];
+        }>;
+        getDeviceDetails(input: {
+            deviceId: string;
+        }): Promise<{
+            device?: INetworkDeviceDetails;
+        }>;
+        getGroupDetails(input: {
+            groupId: string;
+        }): Promise<{
+            group?: INetworkGroupDetails;
+        }>;
+        getDisconnectedDevices(): Promise<{
+            devices: INetworkDisconnectedDevice[];
+        }>;
+        queryRemoteLogs(input: {
+            deviceId: string;
+            query?: INetworkRemoteLogsQuery;
+        }): Promise<INetworkRemoteLogsResult>;
+    };
+    observables: {
+        status: Observable<INetworkStatusSummary>;
+    };
+}
+/** Typed consumer proxy for System Network Control v1. */
+export interface INetworkControlConsumer extends IContractConsumerBase {
+    tools: {
+        refreshNetworkInfo(): Promise<INetworkControlResult>;
+        connectToDevice(input: {
+            deviceId: string;
+        }): Promise<INetworkControlResult>;
+        disconnectDevice(input: {
+            deviceId: string;
+        }): Promise<INetworkControlResult>;
+        deleteDevice(input: {
+            deviceId: string;
+        }): Promise<INetworkControlResult>;
+        syncGroupNow(input: {
+            groupId: string;
+        }): Promise<INetworkControlResult>;
+        resetChangeTracking(input: {
+            dataContextId: string;
+        }): Promise<INetworkControlResult>;
+    };
+}
+/** Return the portable read-only network diagnostics contract shape. */
+export declare function getNetworkDiagnosticsContractDefinition(): IContractDefinition;
+/** Return the explicit mutating local network control contract shape. */
+export declare function getNetworkControlContractDefinition(): IContractDefinition;

package/dist/contracts/system/network-contracts.js

@@ -0,0 +1,192 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.networkControlToolIds = exports.networkDiagnosticsToolIds = exports.NETWORK_CONTROL_CONTRACT_VERSION = exports.NETWORK_DIAGNOSTICS_CONTRACT_VERSION = void 0;
+exports.getNetworkDiagnosticsContractDefinition = getNetworkDiagnosticsContractDefinition;
+exports.getNetworkControlContractDefinition = getNetworkControlContractDefinition;
+const system_ids_1 = require("../../system-ids");
+const field_type_1 = require("../../types/field-type");
+const system_contracts_1 = require("../system-contracts");
+/** Version of the built-in System Network Diagnostics contract. */
+exports.NETWORK_DIAGNOSTICS_CONTRACT_VERSION = 1;
+/** Version of the built-in System Network Control contract. */
+exports.NETWORK_CONTROL_CONTRACT_VERSION = 1;
+/** Stable IDs for tools in System Network Diagnostics v1. */
+exports.networkDiagnosticsToolIds = {
+    getOverview: "00ms1yb50ym353ads0gel5jpv",
+    getConnections: "00ms1yb50ykny9kdgiclpa1t4",
+    getGroupSyncStatus: "00ms1yb50yp2q7jr0jglzsztq",
+    getDeviceDetails: "00ms1yb50yw792rslve1q99qg",
+    getGroupDetails: "00ms1yb50yuru8h1fg4t9na3e",
+    getDisconnectedDevices: "00ms1yb50y3jpoby5zomltahr",
+    queryRemoteLogs: "00ms1yb50y2fbfnth22yz52eu",
+};
+/** Stable IDs for tools in System Network Control v1. */
+exports.networkControlToolIds = {
+    refreshNetworkInfo: "00ms1yb50y9rsdyqmr81vjoli",
+    connectToDevice: "00ms1yb50y40ty8tr0sic875x",
+    disconnectDevice: "00ms1yb50yqvboqmhshqvlibr",
+    deleteDevice: "00ms1yb50y5mc448nuavlex86",
+    syncGroupNow: "00ms1yb50ylnqlra26jx232py",
+    resetChangeTracking: "00ms1yb50yfuackpl1w37hmxc",
+};
+const field = (name, type, description, opts = {}) => ({ name, type, description, ...opts });
+let diagnosticsDefinition;
+let controlDefinition;
+/** Return the portable read-only network diagnostics contract shape. */
+function getNetworkDiagnosticsContractDefinition() {
+    diagnosticsDefinition ??= {
+        contractId: system_ids_1.networkDiagnosticsContractId,
+        version: exports.NETWORK_DIAGNOSTICS_CONTRACT_VERSION,
+        devTag: "dev",
+        name: "System Network Diagnostics",
+        description: "Portable local network, connection, and synchronization diagnostics.",
+        tables: [],
+        tools: [
+            {
+                name: "getOverview",
+                usageDescription: "Return aggregate network and group information.",
+                inputFields: [],
+                outputFields: [field("overview", field_type_1.FieldType.object, "Local network overview.")],
+            },
+            {
+                name: "getConnections",
+                usageDescription: "List active device connections and their health.",
+                inputFields: [],
+                outputFields: [
+                    field("connections", field_type_1.FieldType.object, "Active connection details.", { isArray: true }),
+                ],
+            },
+            {
+                name: "getGroupSyncStatus",
+                usageDescription: "Return sync status for one context or every local context.",
+                inputFields: [
+                    field("groupId", field_type_1.FieldType.id, "Optional personal or group context ID.", {
+                        optional: true,
+                    }),
+                ],
+                outputFields: [
+                    field("groups", field_type_1.FieldType.object, "Group synchronization details.", { isArray: true }),
+                ],
+            },
+            {
+                name: "getDeviceDetails",
+                usageDescription: "Return details for one currently connected device.",
+                inputFields: [field("deviceId", field_type_1.FieldType.id, "Connected device ID.")],
+                outputFields: [
+                    field("device", field_type_1.FieldType.object, "Connected device details.", { optional: true }),
+                ],
+            },
+            {
+                name: "getGroupDetails",
+                usageDescription: "Return membership details for one local data context.",
+                inputFields: [field("groupId", field_type_1.FieldType.id, "Personal or group context ID.")],
+                outputFields: [
+                    field("group", field_type_1.FieldType.object, "Group membership details.", { optional: true }),
+                ],
+            },
+            {
+                name: "getDisconnectedDevices",
+                usageDescription: "List known devices without an active connection.",
+                inputFields: [],
+                outputFields: [
+                    field("devices", field_type_1.FieldType.object, "Disconnected device details.", { isArray: true }),
+                ],
+            },
+            {
+                name: "queryRemoteLogs",
+                usageDescription: "Query bounded logs from a directly connected authorized device.",
+                inputFields: [
+                    field("deviceId", field_type_1.FieldType.id, "Connected device ID."),
+                    field("query", field_type_1.FieldType.object, "Optional remote log filters.", { optional: true }),
+                ],
+                outputFields: [
+                    field("deviceId", field_type_1.FieldType.id, "Queried device ID."),
+                    field("truncated", field_type_1.FieldType.boolean, "Whether matching rows were omitted."),
+                    field("logs", field_type_1.FieldType.object, "Matching console logs.", { isArray: true }),
+                    field("queriedAt", field_type_1.FieldType.number, "Local completion timestamp."),
+                ],
+            },
+        ],
+        observables: [
+            {
+                name: "status",
+                description: "Reactive connection and synchronization status summary.",
+                valueType: field_type_1.FieldType.object,
+                writable: false,
+            },
+        ],
+        events: [],
+    };
+    return diagnosticsDefinition;
+}
+/** Return the explicit mutating local network control contract shape. */
+function getNetworkControlContractDefinition() {
+    const deviceInput = [field("deviceId", field_type_1.FieldType.id, "Target device ID.")];
+    const resultFields = [
+        field("success", field_type_1.FieldType.boolean, "Whether the operation completed successfully."),
+        field("message", field_type_1.FieldType.string, "Human-readable operation result."),
+    ];
+    controlDefinition ??= {
+        contractId: system_ids_1.networkControlContractId,
+        version: exports.NETWORK_CONTROL_CONTRACT_VERSION,
+        devTag: "dev",
+        name: "System Network Control",
+        description: "Explicit local device connection and synchronization control operations.",
+        tables: [],
+        tools: [
+            {
+                name: "refreshNetworkInfo",
+                usageDescription: "Refresh network information and preferred connection choices.",
+                inputFields: [],
+                outputFields: resultFields,
+            },
+            {
+                name: "connectToDevice",
+                usageDescription: "Start a connection attempt to one known device.",
+                inputFields: deviceInput,
+                outputFields: resultFields,
+            },
+            {
+                name: "disconnectDevice",
+                usageDescription: "Close the active connection to one device.",
+                inputFields: deviceInput,
+                outputFields: resultFields,
+            },
+            {
+                name: "deleteDevice",
+                usageDescription: "Forget one known, disconnected device.",
+                inputFields: deviceInput,
+                outputFields: resultFields,
+            },
+            {
+                name: "syncGroupNow",
+                usageDescription: "Notify connected devices of changes in one data context.",
+                inputFields: [field("groupId", field_type_1.FieldType.id, "Personal or group context ID.")],
+                outputFields: resultFields,
+            },
+            {
+                name: "resetChangeTracking",
+                usageDescription: "Reset one data context's change tracking for an expensive full sync.",
+                inputFields: [
+                    field("dataContextId", field_type_1.FieldType.id, "Personal or group context ID to reset."),
+                ],
+                outputFields: resultFields,
+            },
+        ],
+        observables: [],
+        events: [],
+    };
+    return controlDefinition;
+}
+(0, system_contracts_1.registerSystemContract)({
+    providerPackageId: system_ids_1.peersSystemPackageId,
+    contractId: system_ids_1.networkDiagnosticsContractId,
+    version: exports.NETWORK_DIAGNOSTICS_CONTRACT_VERSION,
+    getDefinition: getNetworkDiagnosticsContractDefinition,
+});
+(0, system_contracts_1.registerSystemContract)({
+    providerPackageId: system_ids_1.peersSystemPackageId,
+    contractId: system_ids_1.networkControlContractId,
+    version: exports.NETWORK_CONTROL_CONTRACT_VERSION,
+    getDefinition: getNetworkControlContractDefinition,
+});

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

@@ -0,0 +1,47 @@
+import type { ContractResolver } from "./contract-resolvers";
+import type { ContractRegistry } from "./registry";
+import type { IContractDefinition } from "./types";
+/**
+ * A built-in system contract that should appear in every data context's
+ * {@link ContractRegistry} without being installed as a user package.
+ */
+export interface ISystemContractRegistration {
+    /** Synthetic provider package id (typically `peersSystemPackageId`). */
+    providerPackageId: string;
+    /**
+     * Lazy definition builder. Kept lazy so contracts like Logs can defer schema
+     * access until after module initialization completes.
+     */
+    getDefinition: () => IContractDefinition;
+    /**
+     * Optional live resolver for contract calls. When provided, `contractId` and
+     * `version` must also be set so the resolver can be keyed without building
+     * the definition at registration time.
+     */
+    resolve?: ContractResolver;
+    /** Required when {@link resolve} is set — resolver map key without calling `getDefinition`. */
+    contractId?: string;
+    /** Required when {@link resolve} is set. */
+    version?: number;
+}
+/**
+ * Self-register a built-in system contract.
+ *
+ * Call once from the contract module (side effect at import). Later
+ * {@link installSystemContracts} installs every registered entry into a
+ * concrete registry. New system contracts only need this one call.
+ */
+export declare function registerSystemContract(registration: ISystemContractRegistration): void;
+/**
+ * Register every known system contract into `registry` as a provider.
+ * Safe to call more than once for the same registry (provider updates in place).
+ */
+export declare function installSystemContracts(registry: ContractRegistry): void;
+/** Snapshot of registered system contracts (for tests and diagnostics). */
+export declare function listSystemContracts(): readonly ISystemContractRegistration[];
+/**
+ * Clear the system-contract catalog. Test-only — production code must not call this.
+ *
+ * @internal
+ */
+export declare function _clearSystemContractsForTests(): void;

package/dist/contracts/system-contracts.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerSystemContract = registerSystemContract;
+exports.installSystemContracts = installSystemContracts;
+exports.listSystemContracts = listSystemContracts;
+exports._clearSystemContractsForTests = _clearSystemContractsForTests;
+const systemContracts = [];
+function systemContractKey(contractId, version) {
+    return `${contractId}@${version}`;
+}
+/**
+ * Self-register a built-in system contract.
+ *
+ * Call once from the contract module (side effect at import). Later
+ * {@link installSystemContracts} installs every registered entry into a
+ * concrete registry. New system contracts only need this one call.
+ */
+function registerSystemContract(registration) {
+    if (registration.resolve) {
+        if (!registration.contractId || registration.version == null) {
+            throw new Error("registerSystemContract: contractId and version are required when resolve is provided");
+        }
+        // Defer resolver registration so self-registration during SDK barrel / package-loader
+        // import cannot re-enter contract-resolvers mid-initialization.
+        const { contractId, version, resolve } = registration;
+        queueMicrotask(() => {
+            const { registerContractResolver } = require("./contract-resolvers");
+            registerContractResolver(contractId, version, resolve);
+        });
+    }
+    const key = registration.contractId && registration.version != null
+        ? systemContractKey(registration.contractId, registration.version)
+        : undefined;
+    if (key) {
+        const existingIdx = systemContracts.findIndex((entry) => entry.contractId &&
+            entry.version != null &&
+            systemContractKey(entry.contractId, entry.version) === key);
+        if (existingIdx >= 0) {
+            systemContracts[existingIdx] = registration;
+            return;
+        }
+    }
+    systemContracts.push(registration);
+}
+/**
+ * Register every known system contract into `registry` as a provider.
+ * Safe to call more than once for the same registry (provider updates in place).
+ */
+function installSystemContracts(registry) {
+    for (const entry of systemContracts) {
+        const definition = entry.getDefinition();
+        const result = registry.register(entry.providerPackageId, definition);
+        if (!result.valid) {
+            console.error(`[SystemContracts] Failed to register ${definition.name} (${definition.contractId}@${definition.version}):`, result.errors);
+        }
+    }
+}
+/** Snapshot of registered system contracts (for tests and diagnostics). */
+function listSystemContracts() {
+    return systemContracts;
+}
+/**
+ * Clear the system-contract catalog. Test-only — production code must not call this.
+ *
+ * @internal
+ */
+function _clearSystemContractsForTests() {
+    systemContracts.length = 0;
+}

package/dist/contracts/types.d.ts

@@ -4,6 +4,7 @@ import type { IToolInstance } from "../data/tools";
 import type { Event } from "../events";
 import type { Observable } from "../observable";
 import type { FieldType, IField } from "../types/field-type";
+import type { IContractConsumer, IContractConsumerBase } from "./contract-proxy";
 /**
  * A versioned interface definition declaring the shape of tables, tools,
  * observables, and events that a package provides. Pure data — no executable code.
@@ -58,6 +59,43 @@ export interface IContractEvent {
     /** Shape of the payload delivered to subscribers when the event fires. */
     payloadFields: IField[];
 }
+/**
+ * Options for {@link PackageBuilder.consumes}.
+ *
+ * Provider selection (`providerPackageIds`, `fallbackToDefaultProvider`) is
+ * recorded here for the package-loader; wiring that resolves the deferred
+ * handle is a follow-up step.
+ */
+export interface IConsumedContractOptions {
+    /**
+     * When true, a missing provider settles the handle with `undefined` instead
+     * of rejecting. Defaults to false (required).
+     */
+    optional?: boolean;
+    /**
+     * Ordered preference of provider package IDs. The loader tries these in
+     * order before considering the active/default provider.
+     */
+    providerPackageIds?: string[];
+    /**
+     * When true and none of {@link providerPackageIds} is available, fall back
+     * to the active/default provider for the contract. Ignored when
+     * `providerPackageIds` is omitted (default provider is used directly).
+     */
+    fallbackToDefaultProvider?: boolean;
+}
+/**
+ * Deferred handle returned by {@link PackageBuilder.consumes}.
+ *
+ * The handle itself is not thenable — await {@link consumer} from runtime
+ * code after `definePackage` finishes, not inside the define callback.
+ * Settlement is owned by the SDK (package-loader); package code cannot
+ * resolve or reject the promise.
+ */
+export interface IConsumedContractHandle<T extends IContractConsumerBase | undefined = IContractConsumer> {
+    /** Resolves to the live consumer proxy, or `undefined` when optional and unmatched. */
+    readonly consumer: Promise<T>;
+}
 /**
  * A reference to a contract that a package wants to consume.
  * Recorded during `definePackage` and checked at install time.
@@ -66,6 +104,12 @@ export interface IConsumedContract {
     contractId: string;
     version: number;
     optional?: boolean;
+    /** Ordered preferred provider package IDs, if any. */
+    providerPackageIds?: string[];
+    /** Whether to fall back to the default provider when preferred ones are missing. */
+    fallbackToDefaultProvider?: boolean;
+    /** Deferred handle returned by `consumes()` for this dependency. */
+    handle?: IConsumedContractHandle<IContractConsumerBase | undefined>;
 }
 /**
  * Declares that the owning contract's implementation also satisfies another

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

@@ -0,0 +1 @@
+export {};