@peers-app/peers-sdk 0.21.1 → 0.21.3

package/dist/contracts/contract-proxy.d.ts

@@ -89,8 +89,9 @@ export interface IContractNotification {
  * subscribable that rides the notify channel like a generic event (subscription-gated).
  *
  * Declared as an intersection so `dataChanged` type-checks as a subscribable while
- * `.list(...)`, `.save(...)`, etc. still type-check as async methods. This is a widening
- * of precise per-table typing (deferred to a later phase).
+ * `.list(...)`, `.save(...)`, etc. still type-check as async methods. Prefer
+ * {@link ITableProxy} when declaring typed contract consumers — this open form does
+ * not contribute named IntelliSense for table methods.
  */
 export type IContractTableProxy = Record<string, (...args: any[]) => Promise<any>> & {
     /**
@@ -102,14 +103,68 @@ export type IContractTableProxy = Record<string, (...args: any[]) => Promise<any
         subscribe(handler: (event: any) => void): ISubscriptionResult;
     };
 };
+/** Standard {@link Table} methods the contract provider allows over the wire. */
+type StandardRemoteTableMethodName = "get" | "list" | "count" | "findOne" | "save" | "insert" | "update" | "delete";
+/**
+ * Payload type of `TTable.dataChanged.subscribe` when the table exposes one.
+ */
+type TableDataChangedPayload<TTable> = TTable extends {
+    dataChanged: {
+        subscribe: (handler: (event: infer E) => any, ...args: any[]) => any;
+    };
+} ? E : unknown;
+/**
+ * Consumer-side view of a real table class over a contract proxy.
+ *
+ * Picks the remotely callable standard {@link Table} methods (and optional extras such
+ * as `@ProxyClientTableMethodCalls` methods) with their real signatures, plus a
+ * `dataChanged` subscribe surface. Does **not** claim to be a literal {@link Table}
+ * instance — non-remote members (`dataSource`, `metaData`, `cursor`, …) are omitted.
+ *
+ * No open string index signature, so IntelliSense lists the actual method names.
+ *
+ * @typeParam TTable - Concrete table class (e.g. `ConsoleLogsTable`).
+ * @typeParam TExtraMethods - Additional remotely callable method names on `TTable`.
+ */
+export type ITableProxy<TTable, TExtraMethods extends keyof TTable = never> = Pick<TTable, Extract<keyof TTable, StandardRemoteTableMethodName> | TExtraMethods> & {
+    /**
+     * Subscribe to the provider table's `dataChanged` event over the transport.
+     * Same subscribe shape as a local table, without Event helpers like `next` / `union`.
+     */
+    dataChanged: {
+        subscribe(handler: (event: TableDataChangedPayload<TTable>) => void): ISubscriptionResult;
+    };
+};
+/**
+ * Minimal contract-consumer identity shared by typed consumers and the open
+ * {@link IContractConsumer} runtime shape. Typed consumers may omit empty
+ * `tools` / `events` / `observables` bags.
+ */
+export interface IContractConsumerBase {
+    contractId: string;
+    version: number;
+    /**
+     * Resolves once every observable's initial snapshot has loaded (so reads are meaningful),
+     * then is re-chained on each local observable write so `await consumer.loadingPromise`
+     * also awaits write durability. Always resolves (never rejects).
+     */
+    loadingPromise: Promise<void>;
+    /**
+     * Idempotently detach everything this consumer opened. New remote calls and
+     * subscriptions reject after disposal.
+     */
+    dispose(): void;
+}
 /**
  * A live proxy over a contract, handed to a **consumer**. Every member access is
  * turned into an {@link IContractCall} and dispatched through the transport, so the
  * consumer interacts with the contract identically no matter where the provider runs.
+ *
+ * This is the open runtime shape from {@link createContractConsumer}. Prefer a
+ * hand-maintained (or later generated) typed consumer that extends
+ * {@link IContractConsumerBase} and lists only the members that contract exposes.
  */
-export interface IContractConsumer {
-    contractId: string;
-    version: number;
+export interface IContractConsumer extends IContractConsumerBase {
     /**
      * `tables[name].<method>(...args)` → the remote table method's result, or
      * `tables[name].dataChanged.subscribe(handler)` → a subscription to the remote table's
@@ -139,22 +194,6 @@ export interface IContractConsumer {
     events: Record<string, {
         subscribe: (handler: (value: any) => void) => ISubscriptionResult;
     }>;
-    /**
-     * Resolves once every observable's initial snapshot has loaded (so reads are meaningful),
-     * then is re-chained on each local observable write so `await consumer.loadingPromise`
-     * also awaits write durability. Mirrors the persistent-var `loadingPromise` pattern
-     * ([`persistent-vars.ts`](../data/persistent-vars.ts)). Always resolves (never rejects);
-     * a failed writable set is logged once and leaves the optimistic mirror in place until
-     * the next provider push reconciles it.
-     */
-    loadingPromise: Promise<void>;
-    /**
-     * Idempotently detach everything this consumer opened: generic events, table events,
-     * always-on observable streams, observable write observers, and its notify listener.
-     * New remote table/tool calls and subscriptions reject after disposal; cached observable
-     * reads remain available, but observable writes throw.
-     */
-    dispose(): void;
 }
 /**
  * Build the **consumer** side of a contract proxy from a contract definition and a
@@ -331,3 +370,4 @@ export declare function createContractProviderEndpoint(resolution: IContractReso
  * @param opts        Optional permission gate and default caller context.
  */
 export declare function createContractProviderSession(resolution: IContractResolution, transport: IContractTransport, opts?: IContractProviderSessionOptions): IContractProviderSession;
+export {};

package/dist/contracts/contract-resolvers.d.ts

@@ -30,6 +30,26 @@ export declare function getContractResolver(contractId: string, version: number)
  * {@link TrustLevel.Self}. Unsigned discovery stubs and key mismatches fail closed.
  */
 export declare function isSelfTrustedContractCaller(userContext: UserContext, remoteIdentity: ContractRemoteIdentity): Promise<boolean>;
+/**
+ * Create a provider router for one authenticated UI-to-local-host session.
+ *
+ * The request listener is registered synchronously while user-context loading is
+ * deferred until each call. This prevents renderer startup from racing provider
+ * registration. Calls may target only the local user's personal context or a
+ * currently known group context; arbitrary valid IDs are rejected before
+ * `UserContext.getDataContext` can create a new context.
+ *
+ * This helper trusts the host transport's session authentication. It does not
+ * infer package-level authority from renderer-supplied data.
+ *
+ * @param transport Contract transport backed by an authenticated local session.
+ * @param opts.getUserContext Lazy accessor for the host's loaded user context.
+ * @param opts.allowedContractIds Optional contract allowlist for this session.
+ */
+export declare function createLocalUserContextContractProviderRouter(transport: IContractTransport, opts: {
+    getUserContext: () => Promise<UserContext>;
+    allowedContractIds?: ReadonlySet<string>;
+}): IContractProviderRouter;
 /**
  * Create the local-object provider router for one verified device connection.
  *

package/dist/contracts/contract-resolvers.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerContractResolver = registerContractResolver;
 exports.getContractResolver = getContractResolver;
 exports.isSelfTrustedContractCaller = isSelfTrustedContractCaller;
+exports.createLocalUserContextContractProviderRouter = createLocalUserContextContractProviderRouter;
 exports.createUserContextContractProviderRouter = createUserContextContractProviderRouter;
 exports.handleContractCall = handleContractCall;
 const user_permissions_1 = require("../data/user-permissions");
@@ -74,6 +75,62 @@ async function authorizeUserContextCall(call, userContext, remoteIdentity) {
         context,
     };
 }
+function getAuthorizedLocalDataContext(userContext, requestedId) {
+    const dataContextId = requestedId || userContext.userId;
+    if (dataContextId === userContext.userId) {
+        return userContext.userDataContext;
+    }
+    if (!userContext.groupIds().includes(dataContextId)) {
+        throw new Error(`Permission denied: data context '${dataContextId}' is not available locally`);
+    }
+    return userContext.getDataContext(dataContextId);
+}
+/**
+ * Create a provider router for one authenticated UI-to-local-host session.
+ *
+ * The request listener is registered synchronously while user-context loading is
+ * deferred until each call. This prevents renderer startup from racing provider
+ * registration. Calls may target only the local user's personal context or a
+ * currently known group context; arbitrary valid IDs are rejected before
+ * `UserContext.getDataContext` can create a new context.
+ *
+ * This helper trusts the host transport's session authentication. It does not
+ * infer package-level authority from renderer-supplied data.
+ *
+ * @param transport Contract transport backed by an authenticated local session.
+ * @param opts.getUserContext Lazy accessor for the host's loaded user context.
+ * @param opts.allowedContractIds Optional contract allowlist for this session.
+ */
+function createLocalUserContextContractProviderRouter(transport, opts) {
+    const { getUserContext, allowedContractIds } = opts;
+    return (0, contract_provider_router_1.createContractProviderRouter)(transport, {
+        authorizeCall: async (call) => {
+            if (allowedContractIds && !allowedContractIds.has(call.contractId)) {
+                throw new Error(`Permission denied: contract ${call.contractId} is not available locally`);
+            }
+            const userContext = await getUserContext();
+            const dataContext = getAuthorizedLocalDataContext(userContext, call.dataContextId);
+            const context = {
+                callerUserId: userContext.userId,
+                localUserId: userContext.userId,
+            };
+            return {
+                dataContextId: dataContext.dataContextId,
+                context,
+            };
+        },
+        resolveEndpoint: async ({ contractId, version, dataContextId, context, notify }) => {
+            const userContext = await getUserContext();
+            const resolver = getContractResolver(contractId, version);
+            if (!resolver) {
+                throw new Error(`No contract provider registered for ${contractId} v${version}`);
+            }
+            const dataContext = getAuthorizedLocalDataContext(userContext, dataContextId);
+            const resolution = await resolver({ dataContext });
+            return (0, contract_proxy_1.createContractProviderEndpoint)(resolution, { context, notify });
+        },
+    });
+}
 /**
  * Create the local-object provider router for one verified device connection.
  *

package/dist/contracts/create-local-consumer.d.ts

@@ -0,0 +1,12 @@
+import { type IContractConsumer, type IContractResolution } from "./contract-proxy";
+import type { IContractDefinition } from "./types";
+/**
+ * Build a same-process contract consumer wired to a live provider resolution.
+ *
+ * Creates an {@link inProcessTransportPair}, attaches a provider session on one
+ * end and a consumer proxy on the other. Intended for package-loader settlement
+ * of `consumes` handles when the provider runs in the same process.
+ */
+export declare function createLocalContractConsumer(definition: IContractDefinition, resolution: IContractResolution, opts?: {
+    dataContextId?: string;
+}): IContractConsumer;

package/dist/contracts/create-local-consumer.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createLocalContractConsumer = createLocalContractConsumer;
+const contract_proxy_1 = require("./contract-proxy");
+const contract_transport_1 = require("./contract-transport");
+/**
+ * Build a same-process contract consumer wired to a live provider resolution.
+ *
+ * Creates an {@link inProcessTransportPair}, attaches a provider session on one
+ * end and a consumer proxy on the other. Intended for package-loader settlement
+ * of `consumes` handles when the provider runs in the same process.
+ */
+function createLocalContractConsumer(definition, resolution, opts) {
+    const [consumerTransport, providerTransport] = (0, contract_transport_1.inProcessTransportPair)();
+    (0, contract_proxy_1.createContractProviderSession)(resolution, providerTransport);
+    return (0, contract_proxy_1.createContractConsumer)(definition, consumerTransport, {
+        dataContextId: opts?.dataContextId,
+    });
+}

package/dist/contracts/host-contract-transport.d.ts

@@ -0,0 +1,38 @@
+import type { IContractTransport } from "./contract-transport";
+/** Listener notified whenever the active UI-to-host contract transport changes. */
+export type HostContractTransportListener = (transport: IContractTransport | undefined) => void;
+/**
+ * Register the transport used by renderer code to call its trusted local host.
+ *
+ * A newer registration replaces the previous active transport. The returned
+ * disposer clears only its own registration, so disposing a stale Electron
+ * connection cannot remove a transport installed by a later reconnect.
+ *
+ * @param transport UI-side transport connected to the local host provider router.
+ * @returns A disposer for this exact registration.
+ */
+export declare function registerHostContractTransport(transport: IContractTransport): () => void;
+/** Return the currently registered UI-to-host contract transport, if ready. */
+export declare function getHostContractTransport(): IContractTransport | undefined;
+/**
+ * Subscribe to UI-to-host contract transport lifecycle changes.
+ *
+ * The current value is delivered synchronously by default so a consumer owner
+ * can create or dispose its proxy immediately.
+ *
+ * @param listener Callback receiving the active transport or `undefined`.
+ * @param opts.emitCurrent Whether to deliver the current value immediately.
+ * @returns An idempotent unsubscribe function.
+ */
+export declare function subscribeHostContractTransport(listener: HostContractTransportListener, opts?: {
+    emitCurrent?: boolean;
+}): () => void;
+/**
+ * Wait for the next available UI-to-host contract transport.
+ *
+ * @param opts.timeoutMs Optional deadline; rejects if no transport registers in time.
+ * @returns The current transport immediately, or the next registered transport.
+ */
+export declare function waitForHostContractTransport(opts?: {
+    timeoutMs?: number;
+}): Promise<IContractTransport>;

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

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerHostContractTransport = registerHostContractTransport;
+exports.getHostContractTransport = getHostContractTransport;
+exports.subscribeHostContractTransport = subscribeHostContractTransport;
+exports.waitForHostContractTransport = waitForHostContractTransport;
+let activeRegistration;
+const listeners = new Set();
+function notifyListeners() {
+    const transport = activeRegistration?.transport;
+    for (const listener of [...listeners]) {
+        listener(transport);
+    }
+}
+/**
+ * Register the transport used by renderer code to call its trusted local host.
+ *
+ * A newer registration replaces the previous active transport. The returned
+ * disposer clears only its own registration, so disposing a stale Electron
+ * connection cannot remove a transport installed by a later reconnect.
+ *
+ * @param transport UI-side transport connected to the local host provider router.
+ * @returns A disposer for this exact registration.
+ */
+function registerHostContractTransport(transport) {
+    const registration = { id: Symbol("host-contract-transport"), transport };
+    activeRegistration = registration;
+    notifyListeners();
+    let disposed = false;
+    return () => {
+        if (disposed) {
+            return;
+        }
+        disposed = true;
+        if (activeRegistration?.id === registration.id) {
+            activeRegistration = undefined;
+            notifyListeners();
+        }
+    };
+}
+/** Return the currently registered UI-to-host contract transport, if ready. */
+function getHostContractTransport() {
+    return activeRegistration?.transport;
+}
+/**
+ * Subscribe to UI-to-host contract transport lifecycle changes.
+ *
+ * The current value is delivered synchronously by default so a consumer owner
+ * can create or dispose its proxy immediately.
+ *
+ * @param listener Callback receiving the active transport or `undefined`.
+ * @param opts.emitCurrent Whether to deliver the current value immediately.
+ * @returns An idempotent unsubscribe function.
+ */
+function subscribeHostContractTransport(listener, opts = {}) {
+    listeners.add(listener);
+    if (opts.emitCurrent !== false) {
+        listener(activeRegistration?.transport);
+    }
+    let subscribed = true;
+    return () => {
+        if (!subscribed) {
+            return;
+        }
+        subscribed = false;
+        listeners.delete(listener);
+    };
+}
+/**
+ * Wait for the next available UI-to-host contract transport.
+ *
+ * @param opts.timeoutMs Optional deadline; rejects if no transport registers in time.
+ * @returns The current transport immediately, or the next registered transport.
+ */
+function waitForHostContractTransport(opts = {}) {
+    const current = getHostContractTransport();
+    if (current) {
+        return Promise.resolve(current);
+    }
+    const { timeoutMs } = opts;
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        let timer;
+        const finish = (action) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            if (timer !== undefined) {
+                clearTimeout(timer);
+            }
+            unsubscribe();
+            action();
+        };
+        const unsubscribe = subscribeHostContractTransport((transport) => {
+            if (!transport) {
+                return;
+            }
+            finish(() => resolve(transport));
+        }, { emitCurrent: false });
+        if (timeoutMs !== undefined) {
+            timer = setTimeout(() => {
+                finish(() => reject(new Error(`Timed out waiting for host contract transport after ${timeoutMs}ms`)));
+            }, timeoutMs);
+        }
+    });
+}

package/dist/contracts/index.d.ts

@@ -1,15 +1,19 @@
 export { ContractBuilder, definePackage, PackageBuilder } from "./builder";
 export { type ContractCallAuthorizer, type ContractProviderEndpointResolver, createContractProviderRouter, type IAuthorizedContractRoute, type IContractProviderEndpointRequest, type IContractProviderRouter, type IContractProviderRouterOptions, } from "./contract-provider-router";
 export { ContractProviders, ContractProvidersTable, contractProvidersMetaData, contractProvidersSchema, type IContractProviderRecord, } from "./contract-providers.table";
-export { CONTRACT_CALL_RPC, type ContractMemberType, type ContractNotificationSink, type ContractPermissionCheck, createContractConsumer, createContractProvider, createContractProviderEndpoint, createContractProviderSession, type IContractCall, type IContractCallContext, type IContractConsumer, type IContractNotification, type IContractProviderEndpoint, type IContractProviderEndpointOptions, type IContractProviderSession, type IContractProviderSessionOptions, type IContractResolution, sameUserContractPermissionCheck, } from "./contract-proxy";
-export { type ContractRemoteIdentity, type ContractResolver, createUserContextContractProviderRouter, getContractResolver, handleContractCall, isSelfTrustedContractCaller, registerContractResolver, } from "./contract-resolvers";
+export { CONTRACT_CALL_RPC, type ContractMemberType, type ContractNotificationSink, type ContractPermissionCheck, createContractConsumer, createContractProvider, createContractProviderEndpoint, createContractProviderSession, type IContractCall, type IContractCallContext, type IContractConsumer, type IContractConsumerBase, type IContractNotification, type IContractProviderEndpoint, type IContractProviderEndpointOptions, type IContractProviderSession, type IContractProviderSessionOptions, type IContractResolution, type IContractTableProxy, type ITableProxy, sameUserContractPermissionCheck, } from "./contract-proxy";
+export { type ContractRemoteIdentity, type ContractResolver, createLocalUserContextContractProviderRouter, createUserContextContractProviderRouter, getContractResolver, handleContractCall, isSelfTrustedContractCaller, registerContractResolver, } from "./contract-resolvers";
 export { CONTRACT_NOTIFY_CHANNEL, CONTRACT_REQUEST_CHANNEL, connectionContractTransport, type IContractTransport, type IDuplexEmitter, inProcessTransportPair, } from "./contract-transport";
 export { Contracts, ContractsTable, contractsMetaData, contractsSchema, type IContractRecord, } from "./contracts.table";
+export { createLocalContractConsumer } from "./create-local-consumer";
 export { extractTableShape, extractToolShape, type IExtractableTableDef, type IExtractableToolInstance, setSchemaToFieldsFn, } from "./extract";
+export { getHostContractTransport, type HostContractTransportListener, registerHostContractTransport, subscribeHostContractTransport, waitForHostContractTransport, } from "./host-contract-transport";
 export { PersistentContractRegistry } from "./persistent-registry";
 export { ContractRegistry } from "./registry";
 export { DEVICE_OPERATIONS_CONTRACT_VERSION, DEVICE_OPERATIONS_MAX_QUERY_LENGTH, DEVICE_OPERATIONS_MAX_RESULT_BYTES, DEVICE_OPERATIONS_MAX_ROWS, DEVICE_OPERATIONS_MAX_TOOLS, type DeviceOperationCapability, deviceOperationsProviderPackageId, deviceOperationsToolIds, getDeviceOperationsContractDefinition, type IDeviceDatabaseQueryInput, type IDeviceDatabaseQueryResult, type IDeviceOperationStatus, type IDeviceToolListInput, type IDeviceToolLookupInput, type IDeviceToolLookupResult, type IDeviceToolRunInput, } from "./system/device-operations-contract";
-export { getLogsContractDefinition, LOGS_CONTRACT_VERSION, resolveLogsContract, } from "./system/logs-contract";
-export type { IAlsoImplementsDeclaration, IConsumedContract, IContractDefinition, IContractEvent, IContractObservable, IContractTable, IContractTool, IPackageDefinitionResult, IResolvedContract, IValidationError, IValidationResult, } from "./types";
+export { getLogsContractDefinition, type ILogsConsumer, LOGS_CONTRACT_VERSION, resolveLogsContract, } from "./system/logs-contract";
+export * from "./system/network-contracts";
+export { type ISystemContractRegistration, installSystemContracts, listSystemContracts, registerSystemContract, } from "./system-contracts";
+export type { IAlsoImplementsDeclaration, IConsumedContract, IConsumedContractHandle, IConsumedContractOptions, IContractDefinition, IContractEvent, IContractObservable, IContractTable, IContractTool, IPackageDefinitionResult, IResolvedContract, IValidationError, IValidationResult, } from "./types";
 export { contractKey } from "./types";
 export { validateAlsoImplements, validateImmutability, validateProviderSatisfiesContract, } from "./validate";

package/dist/contracts/index.js

@@ -1,6 +1,21 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.validateProviderSatisfiesContract = exports.validateImmutability = exports.validateAlsoImplements = exports.contractKey = exports.resolveLogsContract = exports.LOGS_CONTRACT_VERSION = exports.getLogsContractDefinition = exports.getDeviceOperationsContractDefinition = exports.deviceOperationsToolIds = exports.deviceOperationsProviderPackageId = exports.DEVICE_OPERATIONS_MAX_TOOLS = exports.DEVICE_OPERATIONS_MAX_ROWS = exports.DEVICE_OPERATIONS_MAX_RESULT_BYTES = exports.DEVICE_OPERATIONS_MAX_QUERY_LENGTH = exports.DEVICE_OPERATIONS_CONTRACT_VERSION = exports.ContractRegistry = exports.PersistentContractRegistry = exports.setSchemaToFieldsFn = exports.extractToolShape = exports.extractTableShape = exports.contractsSchema = exports.contractsMetaData = exports.ContractsTable = exports.Contracts = exports.inProcessTransportPair = exports.connectionContractTransport = exports.CONTRACT_REQUEST_CHANNEL = exports.CONTRACT_NOTIFY_CHANNEL = exports.registerContractResolver = exports.isSelfTrustedContractCaller = exports.handleContractCall = exports.getContractResolver = exports.createUserContextContractProviderRouter = exports.sameUserContractPermissionCheck = exports.createContractProviderSession = exports.createContractProviderEndpoint = exports.createContractProvider = exports.createContractConsumer = exports.CONTRACT_CALL_RPC = exports.contractProvidersSchema = exports.contractProvidersMetaData = exports.ContractProvidersTable = exports.ContractProviders = exports.createContractProviderRouter = exports.PackageBuilder = exports.definePackage = exports.ContractBuilder = void 0;
+exports.installSystemContracts = exports.resolveLogsContract = exports.LOGS_CONTRACT_VERSION = exports.getLogsContractDefinition = exports.getDeviceOperationsContractDefinition = exports.deviceOperationsToolIds = exports.deviceOperationsProviderPackageId = exports.DEVICE_OPERATIONS_MAX_TOOLS = exports.DEVICE_OPERATIONS_MAX_ROWS = exports.DEVICE_OPERATIONS_MAX_RESULT_BYTES = exports.DEVICE_OPERATIONS_MAX_QUERY_LENGTH = exports.DEVICE_OPERATIONS_CONTRACT_VERSION = exports.ContractRegistry = exports.PersistentContractRegistry = exports.waitForHostContractTransport = exports.subscribeHostContractTransport = exports.registerHostContractTransport = exports.getHostContractTransport = exports.setSchemaToFieldsFn = exports.extractToolShape = exports.extractTableShape = exports.createLocalContractConsumer = exports.contractsSchema = exports.contractsMetaData = exports.ContractsTable = exports.Contracts = exports.inProcessTransportPair = exports.connectionContractTransport = exports.CONTRACT_REQUEST_CHANNEL = exports.CONTRACT_NOTIFY_CHANNEL = exports.registerContractResolver = exports.isSelfTrustedContractCaller = exports.handleContractCall = exports.getContractResolver = exports.createUserContextContractProviderRouter = exports.createLocalUserContextContractProviderRouter = exports.sameUserContractPermissionCheck = exports.createContractProviderSession = exports.createContractProviderEndpoint = exports.createContractProvider = exports.createContractConsumer = exports.CONTRACT_CALL_RPC = exports.contractProvidersSchema = exports.contractProvidersMetaData = exports.ContractProvidersTable = exports.ContractProviders = exports.createContractProviderRouter = exports.PackageBuilder = exports.definePackage = exports.ContractBuilder = void 0;
+exports.validateProviderSatisfiesContract = exports.validateImmutability = exports.validateAlsoImplements = exports.contractKey = exports.registerSystemContract = exports.listSystemContracts = void 0;
 var builder_1 = require("./builder");
 Object.defineProperty(exports, "ContractBuilder", { enumerable: true, get: function () { return builder_1.ContractBuilder; } });
 Object.defineProperty(exports, "definePackage", { enumerable: true, get: function () { return builder_1.definePackage; } });
@@ -20,6 +35,7 @@ Object.defineProperty(exports, "createContractProviderEndpoint", { enumerable: t
 Object.defineProperty(exports, "createContractProviderSession", { enumerable: true, get: function () { return contract_proxy_1.createContractProviderSession; } });
 Object.defineProperty(exports, "sameUserContractPermissionCheck", { enumerable: true, get: function () { return contract_proxy_1.sameUserContractPermissionCheck; } });
 var contract_resolvers_1 = require("./contract-resolvers");
+Object.defineProperty(exports, "createLocalUserContextContractProviderRouter", { enumerable: true, get: function () { return contract_resolvers_1.createLocalUserContextContractProviderRouter; } });
 Object.defineProperty(exports, "createUserContextContractProviderRouter", { enumerable: true, get: function () { return contract_resolvers_1.createUserContextContractProviderRouter; } });
 Object.defineProperty(exports, "getContractResolver", { enumerable: true, get: function () { return contract_resolvers_1.getContractResolver; } });
 Object.defineProperty(exports, "handleContractCall", { enumerable: true, get: function () { return contract_resolvers_1.handleContractCall; } });
@@ -35,10 +51,17 @@ Object.defineProperty(exports, "Contracts", { enumerable: true, get: function ()
 Object.defineProperty(exports, "ContractsTable", { enumerable: true, get: function () { return contracts_table_1.ContractsTable; } });
 Object.defineProperty(exports, "contractsMetaData", { enumerable: true, get: function () { return contracts_table_1.contractsMetaData; } });
 Object.defineProperty(exports, "contractsSchema", { enumerable: true, get: function () { return contracts_table_1.contractsSchema; } });
+var create_local_consumer_1 = require("./create-local-consumer");
+Object.defineProperty(exports, "createLocalContractConsumer", { enumerable: true, get: function () { return create_local_consumer_1.createLocalContractConsumer; } });
 var extract_1 = require("./extract");
 Object.defineProperty(exports, "extractTableShape", { enumerable: true, get: function () { return extract_1.extractTableShape; } });
 Object.defineProperty(exports, "extractToolShape", { enumerable: true, get: function () { return extract_1.extractToolShape; } });
 Object.defineProperty(exports, "setSchemaToFieldsFn", { enumerable: true, get: function () { return extract_1.setSchemaToFieldsFn; } });
+var host_contract_transport_1 = require("./host-contract-transport");
+Object.defineProperty(exports, "getHostContractTransport", { enumerable: true, get: function () { return host_contract_transport_1.getHostContractTransport; } });
+Object.defineProperty(exports, "registerHostContractTransport", { enumerable: true, get: function () { return host_contract_transport_1.registerHostContractTransport; } });
+Object.defineProperty(exports, "subscribeHostContractTransport", { enumerable: true, get: function () { return host_contract_transport_1.subscribeHostContractTransport; } });
+Object.defineProperty(exports, "waitForHostContractTransport", { enumerable: true, get: function () { return host_contract_transport_1.waitForHostContractTransport; } });
 var persistent_registry_1 = require("./persistent-registry");
 Object.defineProperty(exports, "PersistentContractRegistry", { enumerable: true, get: function () { return persistent_registry_1.PersistentContractRegistry; } });
 var registry_1 = require("./registry");
@@ -56,6 +79,11 @@ var logs_contract_1 = require("./system/logs-contract");
 Object.defineProperty(exports, "getLogsContractDefinition", { enumerable: true, get: function () { return logs_contract_1.getLogsContractDefinition; } });
 Object.defineProperty(exports, "LOGS_CONTRACT_VERSION", { enumerable: true, get: function () { return logs_contract_1.LOGS_CONTRACT_VERSION; } });
 Object.defineProperty(exports, "resolveLogsContract", { enumerable: true, get: function () { return logs_contract_1.resolveLogsContract; } });
+__exportStar(require("./system/network-contracts"), exports);
+var system_contracts_1 = require("./system-contracts");
+Object.defineProperty(exports, "installSystemContracts", { enumerable: true, get: function () { return system_contracts_1.installSystemContracts; } });
+Object.defineProperty(exports, "listSystemContracts", { enumerable: true, get: function () { return system_contracts_1.listSystemContracts; } });
+Object.defineProperty(exports, "registerSystemContract", { enumerable: true, get: function () { return system_contracts_1.registerSystemContract; } });
 var types_1 = require("./types");
 Object.defineProperty(exports, "contractKey", { enumerable: true, get: function () { return types_1.contractKey; } });
 var validate_1 = require("./validate");

package/dist/contracts/registry.d.ts

@@ -39,6 +39,23 @@ export declare class ContractRegistry {
     resolve(contractId: string, version: number): IContractDefinition | undefined;
     /** Get the active provider's package ID for a contract. */
     getProviderPackageId(contractId: string, version: number): string | undefined;
+    /**
+     * Package IDs registered as providers for a contract version (registration order).
+     * Includes inactive providers.
+     */
+    getRegisteredProviderIds(contractId: string, version: number): string[];
+    /**
+     * Pick a provider for a consumed-contract declaration.
+     *
+     * - No `providerPackageIds` → active provider
+     * - With `providerPackageIds` → first listed id that is registered
+     * - If none match and `fallbackToDefaultProvider === true` → active provider
+     * - Otherwise → `undefined` (missing)
+     */
+    selectProvider(dep: IConsumedContract): {
+        providerPackageId: string;
+        definition: IContractDefinition;
+    } | undefined;
     /** Get the stored contract definition (regardless of active provider). */
     getDefinition(contractId: string, version: number): IContractDefinition | undefined;
     /** Replace the stored definition for a contract (e.g. to freeze a dev contract). */

package/dist/contracts/registry.js

@@ -98,6 +98,42 @@ class ContractRegistry {
         const key = (0, types_1.contractKey)(contractId, version);
         return this.activeProviders.get(key)?.providerPackageId;
     }
+    /**
+     * Package IDs registered as providers for a contract version (registration order).
+     * Includes inactive providers.
+     */
+    getRegisteredProviderIds(contractId, version) {
+        const key = (0, types_1.contractKey)(contractId, version);
+        return (this.allProviders.get(key) ?? []).map((p) => p.providerPackageId);
+    }
+    /**
+     * Pick a provider for a consumed-contract declaration.
+     *
+     * - No `providerPackageIds` → active provider
+     * - With `providerPackageIds` → first listed id that is registered
+     * - If none match and `fallbackToDefaultProvider === true` → active provider
+     * - Otherwise → `undefined` (missing)
+     */
+    selectProvider(dep) {
+        const key = (0, types_1.contractKey)(dep.contractId, dep.version);
+        const providers = this.allProviders.get(key) ?? [];
+        const active = this.activeProviders.get(key);
+        if (!dep.providerPackageIds || dep.providerPackageIds.length === 0) {
+            return active
+                ? { providerPackageId: active.providerPackageId, definition: active.definition }
+                : undefined;
+        }
+        for (const preferredId of dep.providerPackageIds) {
+            const match = providers.find((p) => p.providerPackageId === preferredId);
+            if (match) {
+                return { providerPackageId: match.providerPackageId, definition: match.definition };
+            }
+        }
+        if (dep.fallbackToDefaultProvider === true && active) {
+            return { providerPackageId: active.providerPackageId, definition: active.definition };
+        }
+        return undefined;
+    }
     /** Get the stored contract definition (regardless of active provider). */
     getDefinition(contractId, version) {
         return this.definitions.get((0, types_1.contractKey)(contractId, version));

package/dist/contracts/system/device-operations-contract.js

@@ -4,6 +4,7 @@ exports.deviceOperationsProviderPackageId = exports.deviceOperationsToolIds = ex
 exports.getDeviceOperationsContractDefinition = getDeviceOperationsContractDefinition;
 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 Device Operations contract. */
 exports.DEVICE_OPERATIONS_CONTRACT_VERSION = 1;
 /** Maximum SQL text accepted by the remote database operation. */
@@ -108,3 +109,9 @@ function getDeviceOperationsContractDefinition() {
 }
 /** Package ID used by live System Device Operations tool instances. */
 exports.deviceOperationsProviderPackageId = system_ids_1.peersSystemPackageId;
+(0, system_contracts_1.registerSystemContract)({
+    providerPackageId: system_ids_1.peersSystemPackageId,
+    contractId: system_ids_1.deviceOperationsContractId,
+    version: exports.DEVICE_OPERATIONS_CONTRACT_VERSION,
+    getDefinition: getDeviceOperationsContractDefinition,
+});

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

@@ -0,0 +1,10 @@
+/**
+ * Built-in system contracts. Importing this barrel runs each module's
+ * {@link registerSystemContract} side effect so the catalog is populated.
+ */
+import "./device-operations-contract";
+import "./logs-contract";
+import "./network-contracts";
+export { DEVICE_OPERATIONS_CONTRACT_VERSION, DEVICE_OPERATIONS_MAX_QUERY_LENGTH, DEVICE_OPERATIONS_MAX_RESULT_BYTES, DEVICE_OPERATIONS_MAX_ROWS, DEVICE_OPERATIONS_MAX_TOOLS, type DeviceOperationCapability, deviceOperationsProviderPackageId, deviceOperationsToolIds, getDeviceOperationsContractDefinition, type IDeviceDatabaseQueryInput, type IDeviceDatabaseQueryResult, type IDeviceOperationStatus, type IDeviceToolListInput, type IDeviceToolLookupInput, type IDeviceToolLookupResult, type IDeviceToolRunInput, } from "./device-operations-contract";
+export { getLogsContractDefinition, type ILogsConsumer, LOGS_CONTRACT_VERSION, resolveLogsContract, } from "./logs-contract";
+export * from "./network-contracts";

package/dist/contracts/system/index.js

@@ -0,0 +1,38 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveLogsContract = exports.LOGS_CONTRACT_VERSION = exports.getLogsContractDefinition = exports.getDeviceOperationsContractDefinition = exports.deviceOperationsToolIds = exports.deviceOperationsProviderPackageId = exports.DEVICE_OPERATIONS_MAX_TOOLS = exports.DEVICE_OPERATIONS_MAX_ROWS = exports.DEVICE_OPERATIONS_MAX_RESULT_BYTES = exports.DEVICE_OPERATIONS_MAX_QUERY_LENGTH = exports.DEVICE_OPERATIONS_CONTRACT_VERSION = void 0;
+/**
+ * Built-in system contracts. Importing this barrel runs each module's
+ * {@link registerSystemContract} side effect so the catalog is populated.
+ */
+require("./device-operations-contract");
+require("./logs-contract");
+require("./network-contracts");
+var device_operations_contract_1 = require("./device-operations-contract");
+Object.defineProperty(exports, "DEVICE_OPERATIONS_CONTRACT_VERSION", { enumerable: true, get: function () { return device_operations_contract_1.DEVICE_OPERATIONS_CONTRACT_VERSION; } });
+Object.defineProperty(exports, "DEVICE_OPERATIONS_MAX_QUERY_LENGTH", { enumerable: true, get: function () { return device_operations_contract_1.DEVICE_OPERATIONS_MAX_QUERY_LENGTH; } });
+Object.defineProperty(exports, "DEVICE_OPERATIONS_MAX_RESULT_BYTES", { enumerable: true, get: function () { return device_operations_contract_1.DEVICE_OPERATIONS_MAX_RESULT_BYTES; } });
+Object.defineProperty(exports, "DEVICE_OPERATIONS_MAX_ROWS", { enumerable: true, get: function () { return device_operations_contract_1.DEVICE_OPERATIONS_MAX_ROWS; } });
+Object.defineProperty(exports, "DEVICE_OPERATIONS_MAX_TOOLS", { enumerable: true, get: function () { return device_operations_contract_1.DEVICE_OPERATIONS_MAX_TOOLS; } });
+Object.defineProperty(exports, "deviceOperationsProviderPackageId", { enumerable: true, get: function () { return device_operations_contract_1.deviceOperationsProviderPackageId; } });
+Object.defineProperty(exports, "deviceOperationsToolIds", { enumerable: true, get: function () { return device_operations_contract_1.deviceOperationsToolIds; } });
+Object.defineProperty(exports, "getDeviceOperationsContractDefinition", { enumerable: true, get: function () { return device_operations_contract_1.getDeviceOperationsContractDefinition; } });
+var logs_contract_1 = require("./logs-contract");
+Object.defineProperty(exports, "getLogsContractDefinition", { enumerable: true, get: function () { return logs_contract_1.getLogsContractDefinition; } });
+Object.defineProperty(exports, "LOGS_CONTRACT_VERSION", { enumerable: true, get: function () { return logs_contract_1.LOGS_CONTRACT_VERSION; } });
+Object.defineProperty(exports, "resolveLogsContract", { enumerable: true, get: function () { return logs_contract_1.resolveLogsContract; } });
+__exportStar(require("./network-contracts"), exports);