@peers-app/peers-sdk 0.21.0 → 0.21.2

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() {

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/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/index.d.ts

@@ -1,15 +1,17 @@
 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 { 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, 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 { 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 { 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,7 @@
 "use strict";
 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.validateImmutability = exports.validateAlsoImplements = exports.contractKey = exports.registerSystemContract = exports.listSystemContracts = 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.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.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 = 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; } });
@@ -35,6 +36,8 @@ 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; } });
@@ -56,6 +59,10 @@ 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; } });
+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,8 @@
+/**
+ * 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";
+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";

package/dist/contracts/system/index.js

@@ -0,0 +1,22 @@
+"use strict";
+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");
+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; } });

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-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;