@peers-app/peers-sdk 0.26.5 → 0.27.0

package/dist/contracts/index.d.ts

@@ -2,19 +2,21 @@ export * from "./action-dispatch";
 export { ContractBuilder, definePackage, PackageBuilder } from "./builder";
 export { type ContractCallAuthorizer, type ContractProviderEndpointResolver, type ContractProviderPackageResolver, createContractProviderRouter, type IAuthorizedContractRoute, type IContractProviderEndpointRequest, type IContractProviderRouter, type IContractProviderRouterOptions, RetiredContractProviderEndpointError, } from "./contract-provider-router";
 export { ContractProviders, ContractProvidersTable, contractProvidersMetaData, contractProvidersSchema, type IContractProviderRecord, } from "./contract-providers.table";
-export { authorizedContractActionNames, CONTRACT_CALL_RPC, type ContractMemberType, type ContractNotificationSink, type ContractPermissionCheck, type ContractToolDispatch, createContractConsumer, createContractProvider, createContractProviderEndpoint, createContractProviderSession, createRemoteContractConsumer, type IContractCall, type IContractCallContext, type IContractConsumer, type IContractConsumerBase, type IContractNotification, type IContractProviderEndpoint, type IContractProviderEndpointOptions, type IContractProviderSession, type IContractProviderSessionOptions, type IContractResolution, type IContractTableProxy, type IContractToolContext, type IContractToolImplementation, type IContractToolTarget, type ITableProxy, requireWorkflowRunContext, sameUserContractPermissionCheck, validateContractActions, } from "./contract-proxy";
+export { CONTRACT_CALL_RPC, type ContractMemberType, type ContractNotificationSink, type ContractPermissionCheck, type ContractToolDispatch, createContractConsumer, createContractProvider, createContractProviderEndpoint, createContractProviderSession, createRemoteContractConsumer, type IContractCall, type IContractCallContext, type IContractConsumer, type IContractConsumerBase, type IContractNotification, type IContractProviderEndpoint, type IContractProviderEndpointOptions, type IContractProviderSession, type IContractProviderSessionOptions, type IContractResolution, type IContractSubscription, type IContractTableProxy, type IContractToolContext, type IContractToolImplementation, type IContractToolTarget, type ITableProxy, requireWorkflowRunContext, sameUserContractPermissionCheck, } from "./contract-proxy";
 export { authorizeRemoteContractCall, type ContractRemoteIdentity, type ContractResolver, createLocalUserContextContractProviderRouter, createUserContextContractProviderRouter, getContractResolver, handleContractCall, type IContractResolverRegistrationOptions, type ILocalContractVariableRequest, isLocalOnlyContractId, isSelfTrustedContractCaller, type LocalContractVariableResolver, registerContractResolver, verifyRemoteContractIdentity, } 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 { checkFrozenContracts, describeFrozenContractChanges, FROZEN_CONTRACTS_FILE, freezeContracts, type IFrozenContract, type IFrozenContractChange, type IFrozenContracts, type IFrozenContractsCheck, } from "./frozen-contracts";
+export { hostContract, type IHostContractClient, type IHostContractEvent, type IHostContractOptions, type IHostContractTable, type IHostSubscribeOptions, } from "./host-contract-client";
 export { hostContractConsumer, type IHostContractConsumer, type IHostContractConsumerOptions, } from "./host-contract-consumer";
 export { getHostContractTransport, type HostContractTransportListener, registerHostContractTransport, subscribeHostContractTransport, waitForHostContractTransport, } from "./host-contract-transport";
 export { PersistentContractRegistry } from "./persistent-registry";
 export { ContractRegistry, type IContractProviderRegistration } from "./registry";
 export { createRemoteContractEndpoint, getRemoteContractTransportFactory, type IRemoteContractHost, type IRemoteContractTarget, type RemoteContractTransportFactory, resolveRemoteTargetEndpoint, setRemoteContractTransportFactory, } from "./remote-contract-transport";
 export * from "./system/app-updates-contract";
-export { CONTRACT_CATALOG_VERSION, contractCatalogProviderPackageId, getContractCatalogDefinition, type IContractCatalogConsumer, type IContractProviderInfo, type IListContractProvidersInput, } from "./system/contract-catalog-contract";
+export { CONTRACT_CATALOG_VERSION, contractCatalogProviderPackageId, getContractCatalogDefinition, type IContractCatalogConsumer, type IContractDefinitionWithPolicy, type IContractProviderInfo, type IContractToolPolicy, type IExposedContractInfo, type IExposedToolInfo, type IGetContractDefinitionInput, type IListContractProvidersInput, } from "./system/contract-catalog-contract";
 export * from "./system/desktop-tools-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 "./system/device-operations-contract";
 export * from "./system/host-shell-contract";
@@ -34,6 +36,6 @@ export * from "./tool-catalog";
 export * from "./tool-catalog-identity";
 export * from "./tool-catalog-migrations";
 export * from "./tool-catalog-service";
-export type { IAlsoImplementsDeclaration, IConsumedContract, IConsumedContractHandle, IConsumedContractOptions, IContractDefinition, IContractEvent, IContractObservable, IContractTable, IContractTool, IPackageDefinitionResult, IRemoteContract, IRemoteContractConsumer, IRemoteContractHandle, IResolvedContract, IValidationError, IValidationResult, } from "./types";
+export type { IAlsoImplementsDeclaration, IConsumedContract, IConsumedContractHandle, IConsumedContractOptions, IContractDefinition, IContractEvent, IContractObservable, IContractTable, IContractTool, IExposedContract, IPackageDefinitionResult, IRemoteContract, IRemoteContractConsumer, IRemoteContractHandle, IResolvedContract, IValidationError, IValidationResult, } from "./types";
 export { contractKey } from "./types";
-export { validateAlsoImplements, validateImmutability, validateProviderSatisfiesContract, } from "./validate";
+export { contractShapeChanges, validateAlsoImplements, validateImmutability, validateProviderSatisfiesContract, } from "./validate";

package/dist/contracts/index.js

@@ -14,9 +14,9 @@ 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.resolveRemoteTargetEndpoint = exports.getRemoteContractTransportFactory = exports.createRemoteContractEndpoint = exports.ContractRegistry = exports.PersistentContractRegistry = exports.waitForHostContractTransport = exports.subscribeHostContractTransport = exports.registerHostContractTransport = exports.getHostContractTransport = exports.hostContractConsumer = 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.verifyRemoteContractIdentity = exports.registerContractResolver = exports.isSelfTrustedContractCaller = exports.isLocalOnlyContractId = exports.handleContractCall = exports.getContractResolver = exports.createUserContextContractProviderRouter = exports.createLocalUserContextContractProviderRouter = exports.authorizeRemoteContractCall = exports.validateContractActions = exports.sameUserContractPermissionCheck = exports.requireWorkflowRunContext = exports.createRemoteContractConsumer = exports.createContractProviderSession = exports.createContractProviderEndpoint = exports.createContractProvider = exports.createContractConsumer = exports.CONTRACT_CALL_RPC = exports.authorizedContractActionNames = exports.contractProvidersSchema = exports.contractProvidersMetaData = exports.ContractProvidersTable = exports.ContractProviders = exports.RetiredContractProviderEndpointError = exports.createContractProviderRouter = exports.PackageBuilder = exports.definePackage = exports.ContractBuilder = void 0;
-exports.validateAlsoImplements = exports.contractKey = exports.registerSystemContract = exports.listSystemContracts = exports.isSystemContractId = exports.installSystemContracts = exports.TOOL_ACCESS_CONTROL_CONTRACT_VERSION = exports.getToolAccessControlContractDefinition = exports.schedulerProviderPackageId = exports.SCHEDULER_MAX_DELAY_MS = exports.SCHEDULER_CONTRACT_VERSION = exports.getSchedulerContractDefinition = exports.resolveLogsContract = exports.LOGS_CONTRACT_VERSION = exports.getLogsContractDefinition = exports.localFoldersProviderPackageId = exports.LOCAL_FOLDERS_RESERVED_DIR = exports.LOCAL_FOLDERS_READ_RANGE_MAX = exports.LOCAL_FOLDERS_JOB_TTL_MS = exports.LOCAL_FOLDERS_HAVE_BATCH = exports.LOCAL_FOLDERS_GETBLOCKS_MAX_BYTES = exports.LOCAL_FOLDERS_GETBLOCKS_MAX_BLOCKS = exports.LOCAL_FOLDERS_CONTRACT_VERSION = exports.LOCAL_FOLDERS_CHUNK_MIN = exports.LOCAL_FOLDERS_CHUNK_MAX = exports.LOCAL_FOLDERS_CHUNK_AVG = exports.LOCAL_FOLDERS_ASSEMBLE_STALL_MS = exports.getLocalFoldersContractDefinition = exports.INVITES_CONTRACT_VERSION = exports.getInvitesContractDefinition = exports.IDENTITY_CONTRACT_VERSION = exports.getIdentityContractDefinition = exports.httpProviderPackageId = exports.HTTP_MAX_TIMEOUT_MS = exports.HTTP_MAX_BODY_BYTES = exports.HTTP_DEFAULT_TIMEOUT_MS = exports.HTTP_CONTRACT_VERSION = exports.getHttpContractDefinition = 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.getContractCatalogDefinition = exports.contractCatalogProviderPackageId = exports.CONTRACT_CATALOG_VERSION = exports.setRemoteContractTransportFactory = void 0;
-exports.validateProviderSatisfiesContract = exports.validateImmutability = void 0;
+exports.ContractRegistry = exports.PersistentContractRegistry = exports.waitForHostContractTransport = exports.subscribeHostContractTransport = exports.registerHostContractTransport = exports.getHostContractTransport = exports.hostContractConsumer = exports.hostContract = exports.freezeContracts = exports.FROZEN_CONTRACTS_FILE = exports.describeFrozenContractChanges = exports.checkFrozenContracts = 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.verifyRemoteContractIdentity = exports.registerContractResolver = exports.isSelfTrustedContractCaller = exports.isLocalOnlyContractId = exports.handleContractCall = exports.getContractResolver = exports.createUserContextContractProviderRouter = exports.createLocalUserContextContractProviderRouter = exports.authorizeRemoteContractCall = exports.sameUserContractPermissionCheck = exports.requireWorkflowRunContext = exports.createRemoteContractConsumer = exports.createContractProviderSession = exports.createContractProviderEndpoint = exports.createContractProvider = exports.createContractConsumer = exports.CONTRACT_CALL_RPC = exports.contractProvidersSchema = exports.contractProvidersMetaData = exports.ContractProvidersTable = exports.ContractProviders = exports.RetiredContractProviderEndpointError = exports.createContractProviderRouter = exports.PackageBuilder = exports.definePackage = exports.ContractBuilder = void 0;
+exports.listSystemContracts = exports.isSystemContractId = exports.installSystemContracts = exports.TOOL_ACCESS_CONTROL_CONTRACT_VERSION = exports.getToolAccessControlContractDefinition = exports.schedulerProviderPackageId = exports.SCHEDULER_MAX_DELAY_MS = exports.SCHEDULER_CONTRACT_VERSION = exports.getSchedulerContractDefinition = exports.resolveLogsContract = exports.LOGS_CONTRACT_VERSION = exports.getLogsContractDefinition = exports.localFoldersProviderPackageId = exports.LOCAL_FOLDERS_RESERVED_DIR = exports.LOCAL_FOLDERS_READ_RANGE_MAX = exports.LOCAL_FOLDERS_JOB_TTL_MS = exports.LOCAL_FOLDERS_HAVE_BATCH = exports.LOCAL_FOLDERS_GETBLOCKS_MAX_BYTES = exports.LOCAL_FOLDERS_GETBLOCKS_MAX_BLOCKS = exports.LOCAL_FOLDERS_CONTRACT_VERSION = exports.LOCAL_FOLDERS_CHUNK_MIN = exports.LOCAL_FOLDERS_CHUNK_MAX = exports.LOCAL_FOLDERS_CHUNK_AVG = exports.LOCAL_FOLDERS_ASSEMBLE_STALL_MS = exports.getLocalFoldersContractDefinition = exports.INVITES_CONTRACT_VERSION = exports.getInvitesContractDefinition = exports.IDENTITY_CONTRACT_VERSION = exports.getIdentityContractDefinition = exports.httpProviderPackageId = exports.HTTP_MAX_TIMEOUT_MS = exports.HTTP_MAX_BODY_BYTES = exports.HTTP_DEFAULT_TIMEOUT_MS = exports.HTTP_CONTRACT_VERSION = exports.getHttpContractDefinition = 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.getContractCatalogDefinition = exports.contractCatalogProviderPackageId = exports.CONTRACT_CATALOG_VERSION = exports.setRemoteContractTransportFactory = exports.resolveRemoteTargetEndpoint = exports.getRemoteContractTransportFactory = exports.createRemoteContractEndpoint = void 0;
+exports.validateProviderSatisfiesContract = exports.validateImmutability = exports.validateAlsoImplements = exports.contractShapeChanges = exports.contractKey = exports.registerSystemContract = void 0;
 __exportStar(require("./action-dispatch"), exports);
 var builder_1 = require("./builder");
 Object.defineProperty(exports, "ContractBuilder", { enumerable: true, get: function () { return builder_1.ContractBuilder; } });
@@ -31,7 +31,6 @@ Object.defineProperty(exports, "ContractProvidersTable", { enumerable: true, get
 Object.defineProperty(exports, "contractProvidersMetaData", { enumerable: true, get: function () { return contract_providers_table_1.contractProvidersMetaData; } });
 Object.defineProperty(exports, "contractProvidersSchema", { enumerable: true, get: function () { return contract_providers_table_1.contractProvidersSchema; } });
 var contract_proxy_1 = require("./contract-proxy");
-Object.defineProperty(exports, "authorizedContractActionNames", { enumerable: true, get: function () { return contract_proxy_1.authorizedContractActionNames; } });
 Object.defineProperty(exports, "CONTRACT_CALL_RPC", { enumerable: true, get: function () { return contract_proxy_1.CONTRACT_CALL_RPC; } });
 Object.defineProperty(exports, "createContractConsumer", { enumerable: true, get: function () { return contract_proxy_1.createContractConsumer; } });
 Object.defineProperty(exports, "createContractProvider", { enumerable: true, get: function () { return contract_proxy_1.createContractProvider; } });
@@ -40,7 +39,6 @@ Object.defineProperty(exports, "createContractProviderSession", { enumerable: tr
 Object.defineProperty(exports, "createRemoteContractConsumer", { enumerable: true, get: function () { return contract_proxy_1.createRemoteContractConsumer; } });
 Object.defineProperty(exports, "requireWorkflowRunContext", { enumerable: true, get: function () { return contract_proxy_1.requireWorkflowRunContext; } });
 Object.defineProperty(exports, "sameUserContractPermissionCheck", { enumerable: true, get: function () { return contract_proxy_1.sameUserContractPermissionCheck; } });
-Object.defineProperty(exports, "validateContractActions", { enumerable: true, get: function () { return contract_proxy_1.validateContractActions; } });
 var contract_resolvers_1 = require("./contract-resolvers");
 Object.defineProperty(exports, "authorizeRemoteContractCall", { enumerable: true, get: function () { return contract_resolvers_1.authorizeRemoteContractCall; } });
 Object.defineProperty(exports, "createLocalUserContextContractProviderRouter", { enumerable: true, get: function () { return contract_resolvers_1.createLocalUserContextContractProviderRouter; } });
@@ -67,6 +65,13 @@ 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 frozen_contracts_1 = require("./frozen-contracts");
+Object.defineProperty(exports, "checkFrozenContracts", { enumerable: true, get: function () { return frozen_contracts_1.checkFrozenContracts; } });
+Object.defineProperty(exports, "describeFrozenContractChanges", { enumerable: true, get: function () { return frozen_contracts_1.describeFrozenContractChanges; } });
+Object.defineProperty(exports, "FROZEN_CONTRACTS_FILE", { enumerable: true, get: function () { return frozen_contracts_1.FROZEN_CONTRACTS_FILE; } });
+Object.defineProperty(exports, "freezeContracts", { enumerable: true, get: function () { return frozen_contracts_1.freezeContracts; } });
+var host_contract_client_1 = require("./host-contract-client");
+Object.defineProperty(exports, "hostContract", { enumerable: true, get: function () { return host_contract_client_1.hostContract; } });
 var host_contract_consumer_1 = require("./host-contract-consumer");
 Object.defineProperty(exports, "hostContractConsumer", { enumerable: true, get: function () { return host_contract_consumer_1.hostContractConsumer; } });
 var host_contract_transport_1 = require("./host-contract-transport");
@@ -154,6 +159,7 @@ __exportStar(require("./tool-catalog-service"), exports);
 var types_1 = require("./types");
 Object.defineProperty(exports, "contractKey", { enumerable: true, get: function () { return types_1.contractKey; } });
 var validate_1 = require("./validate");
+Object.defineProperty(exports, "contractShapeChanges", { enumerable: true, get: function () { return validate_1.contractShapeChanges; } });
 Object.defineProperty(exports, "validateAlsoImplements", { enumerable: true, get: function () { return validate_1.validateAlsoImplements; } });
 Object.defineProperty(exports, "validateImmutability", { enumerable: true, get: function () { return validate_1.validateImmutability; } });
 Object.defineProperty(exports, "validateProviderSatisfiesContract", { enumerable: true, get: function () { return validate_1.validateProviderSatisfiesContract; } });

package/dist/contracts/registry.d.ts

@@ -1,5 +1,5 @@
 import type { ToolCatalog } from "./tool-catalog";
-import type { IAlsoImplementsDeclaration, IConsumedContract, IContractDefinition, IValidationResult } from "./types";
+import type { IAlsoImplementsDeclaration, IConsumedContract, IContractDefinition, IExposedContract, IValidationResult } from "./types";
 /**
  * One contract-provider registration in an atomic
  * {@link ContractRegistry.registerBatch} operation.
@@ -9,6 +9,11 @@ export interface IContractProviderRegistration {
     definition: IContractDefinition;
     /** Older contract shapes this implementation also satisfies. */
     alsoImplements?: IAlsoImplementsDeclaration[];
+    /**
+     * Other contracts in the same batch whose tools this contract's consumers may call on this
+     * provider. Not part of the contract's shape.
+     */
+    exposes?: IExposedContract[];
 }
 /**
  * Per-group contract registry. Maps contract identities (contractId + version)
@@ -106,6 +111,24 @@ export declare class ContractRegistry {
         contractId: string;
         version: number;
     } | undefined;
+    /**
+     * The contracts one provider exposes through its implementation of a contract: their tools
+     * are callable on that provider by the contract's consumers. Empty when it exposes none.
+     *
+     * @param contractId - The hub contract's id.
+     * @param version - The hub contract's version.
+     * @param providerPackageId - A registered provider of it.
+     */
+    getExposedContracts(contractId: string, version: number, providerPackageId: string): IExposedContract[];
+    /**
+     * The definition one provider registered for a contract version, which may differ from the
+     * latest registration's while the contract is dev.
+     *
+     * @param contractId - Contract id.
+     * @param version - Contract version.
+     * @param providerPackageId - A registered provider of it.
+     */
+    getProviderDefinition(contractId: string, version: number, providerPackageId: string): IContractDefinition | undefined;
     /**
      * Pick a provider for a consumed-contract declaration.
      *
@@ -139,3 +162,10 @@ export declare class ContractRegistry {
         missing: IConsumedContract[];
     };
 }
+/**
+ * The target definition an `alsoImplements` declaration carries for `version`, if any.
+ *
+ * @param declaration - The declaration.
+ * @param version - The target version being registered.
+ */
+export declare function carriedDefinition(declaration: IAlsoImplementsDeclaration, version: number): IContractDefinition | undefined;

package/dist/contracts/registry.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ContractRegistry = void 0;
+exports.carriedDefinition = carriedDefinition;
 const types_1 = require("./types");
 const validate_1 = require("./validate");
 /**
@@ -120,6 +121,60 @@ class ContractRegistry {
             }
             candidateDefinitions.set(key, definition);
         }
+        for (const { definition, exposes = [] } of registrations) {
+            const key = (0, types_1.contractKey)(definition.contractId, definition.version);
+            const exposed = new Set();
+            for (const target of exposes) {
+                const targetKey = (0, types_1.contractKey)(target.contractId, target.version);
+                const problem = targetKey === key
+                    ? "can't expose itself"
+                    : exposed.has(targetKey)
+                        ? `exposes ${targetKey} twice`
+                        : !batchKeys.has(targetKey)
+                            ? `exposes ${targetKey}, which provider ${providerPackageId} doesn't provide`
+                            : undefined;
+                if (problem) {
+                    return {
+                        valid: false,
+                        errors: [{ kind: "contract", name: key, message: `Contract ${key} ${problem}` }],
+                    };
+                }
+                exposed.add(targetKey);
+            }
+        }
+        // A target the registry doesn't have comes from the definition the provider carries; one it
+        // has frozen must match what the provider carries.
+        for (const { alsoImplements = [] } of registrations) {
+            for (const { contractId, version, definition: carried } of alsoImplements) {
+                if (!carried)
+                    continue;
+                const key = (0, types_1.contractKey)(contractId, version);
+                const mismatch = typeof version !== "number" ||
+                    carried.contractId !== contractId ||
+                    carried.version !== version;
+                if (mismatch) {
+                    return {
+                        valid: false,
+                        errors: [
+                            {
+                                kind: "contract",
+                                name: key,
+                                message: `alsoImplements carries a definition that isn't ${contractId} v${String(version)}`,
+                            },
+                        ],
+                    };
+                }
+                const existing = candidateDefinitions.get(key);
+                if (!existing) {
+                    candidateDefinitions.set(key, carried);
+                    continue;
+                }
+                const immutability = (0, validate_1.validateImmutability)(existing, carried);
+                if (!immutability.valid) {
+                    return immutability;
+                }
+            }
+        }
         for (const { definition, alsoImplements = [] } of registrations) {
             if (alsoImplements.length === 0) {
                 continue;
@@ -133,10 +188,10 @@ class ContractRegistry {
     }
     commitRegistrations(providerPackageId, registrations) {
         const explicitKeys = new Set(registrations.map(({ definition }) => (0, types_1.contractKey)(definition.contractId, definition.version)));
-        for (const { definition } of registrations) {
-            this.commitProvider(providerPackageId, definition, definition);
+        for (const { definition, exposes = [] } of registrations) {
+            this.commitProvider(providerPackageId, definition, definition, exposes);
         }
-        for (const { definition, alsoImplements = [] } of registrations) {
+        for (const { definition, alsoImplements = [], exposes = [] } of registrations) {
             for (const declaration of alsoImplements) {
                 const declaredVersion = declaration.version;
                 const versions = typeof declaredVersion === "number"
@@ -147,15 +202,15 @@ class ContractRegistry {
                     if (explicitKeys.has(key)) {
                         continue;
                     }
-                    const target = this.definitions.get(key);
+                    const target = this.definitions.get(key) ?? carriedDefinition(declaration, version);
                     if (target) {
-                        this.commitProvider(providerPackageId, target, definition);
+                        this.commitProvider(providerPackageId, target, definition, exposes);
                     }
                 }
             }
         }
     }
-    commitProvider(providerPackageId, definition, implementation) {
+    commitProvider(providerPackageId, definition, implementation, exposes) {
         const key = (0, types_1.contractKey)(definition.contractId, definition.version);
         this.definitions.set(key, definition);
         const provider = {
@@ -163,6 +218,7 @@ class ContractRegistry {
             definition,
             implementationContractId: implementation.contractId,
             implementationVersion: implementation.version,
+            exposes: exposes.map(({ contractId, version }) => ({ contractId, version })),
         };
         const providers = this.allProviders.get(key) ?? [];
         const existingIdx = providers.findIndex((item) => item.providerPackageId === providerPackageId);
@@ -238,6 +294,29 @@ class ContractRegistry {
             }
             : undefined;
     }
+    /**
+     * The contracts one provider exposes through its implementation of a contract: their tools
+     * are callable on that provider by the contract's consumers. Empty when it exposes none.
+     *
+     * @param contractId - The hub contract's id.
+     * @param version - The hub contract's version.
+     * @param providerPackageId - A registered provider of it.
+     */
+    getExposedContracts(contractId, version, providerPackageId) {
+        const provider = (this.allProviders.get((0, types_1.contractKey)(contractId, version)) ?? []).find((candidate) => candidate.providerPackageId === providerPackageId);
+        return (provider?.exposes ?? []).map((exposed) => ({ ...exposed }));
+    }
+    /**
+     * The definition one provider registered for a contract version, which may differ from the
+     * latest registration's while the contract is dev.
+     *
+     * @param contractId - Contract id.
+     * @param version - Contract version.
+     * @param providerPackageId - A registered provider of it.
+     */
+    getProviderDefinition(contractId, version, providerPackageId) {
+        return (this.allProviders.get((0, types_1.contractKey)(contractId, version)) ?? []).find((candidate) => candidate.providerPackageId === providerPackageId)?.definition;
+    }
     /**
      * Pick a provider for a consumed-contract declaration.
      *
@@ -337,3 +416,18 @@ class ContractRegistry {
     }
 }
 exports.ContractRegistry = ContractRegistry;
+/**
+ * The target definition an `alsoImplements` declaration carries for `version`, if any.
+ *
+ * @param declaration - The declaration.
+ * @param version - The target version being registered.
+ */
+function carriedDefinition(declaration, version) {
+    const carried = declaration.definition;
+    return carried &&
+        carried.contractId === declaration.contractId &&
+        carried.version === version &&
+        declaration.version === version
+        ? carried
+        : undefined;
+}

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

@@ -11,30 +11,85 @@ export interface IContractProviderInfo {
     name: string;
     /** True when this package is the active provider for the contract version. */
     active: boolean;
-    /** Executable package selectors for this trusted turn. Missing metadata grants no actions. */
-    authorizedActions?: string[];
+    /**
+     * The contracts this provider exposes through the listed contract, when it's a hub's: their
+     * tools are callable on this provider by the listed contract's consumers. Each lists only the
+     * tools this caller may run.
+     */
+    exposes?: IExposedContractInfo[];
+}
+/** A contract one provider exposes through a hub's contract, as {@link IContractProviderInfo} lists it. */
+export interface IExposedContractInfo {
+    /** The exposed contract's id. */
+    contractId: string;
+    /** Its version. */
+    version: number;
+    /** Its name. */
+    name: string;
+    /** What it's for. */
+    description?: string;
+    /** Its tools this caller may run on the provider, in the contract's order. */
+    tools: IExposedToolInfo[];
+}
+/** One tool on an exposed contract that the caller may run. */
+export interface IExposedToolInfo {
+    /** The tool's name, for `contractRef(contractId, version)(ctx, { providerPackageId }).tools[name]`. */
+    name: string;
+    /** What it does: the tool's usage description. */
+    description: string;
+    /** The level a caller needs to run it on this provider. */
+    accessLevel: number;
+    /** JSON Schema for its arguments. */
+    inputSchema: Record<string, unknown>;
 }
 /** Input for listing providers of one contract version. */
 export interface IListContractProvidersInput {
     contractId: string;
     version: number;
 }
+/** Input for reading one registered contract version's definition. */
+export interface IGetContractDefinitionInput {
+    contractId: string;
+    version: number;
+}
+/** One tool's policy on a contract's active provider. */
+export interface IContractToolPolicy {
+    /** The tool's name. */
+    name: string;
+    /** The level a caller needs. */
+    accessLevel?: number;
+    /** Whether the tool keeps the caller's level for its outgoing calls. */
+    authorityPropagation?: "cap" | "preserve";
+}
+/**
+ * A registered contract definition, with each tool's policy on the active provider (which the
+ * definition itself doesn't carry): what `peers-package contract add` generates a declaration
+ * from.
+ */
+export interface IContractDefinitionWithPolicy {
+    /** The registered definition. */
+    definition: IContractDefinition;
+    /** Each tool's policy, where the Runtime knows it. */
+    tools?: IContractToolPolicy[];
+}
 /**
  * Consumer shape for the System Contract Catalog.
  *
- * Hub packages use this to discover every provider of a shared contract.
+ * Hub packages use this to discover every provider of a shared contract; package authors and
+ * agents read a contract's definition with it.
  */
 export interface IContractCatalogConsumer extends IContractConsumerBase {
     tools: {
         listContractProviders(input: IListContractProvidersInput): Promise<{
             providers: IContractProviderInfo[];
         }>;
+        getContractDefinition(input: IGetContractDefinitionInput): Promise<IContractDefinitionWithPolicy>;
     };
 }
 /**
- * Return the local-only catalog contract that lists providers of another contract.
+ * Return the local-only catalog contract for discovering providers and reading definitions.
  *
- * The active provider remains the default for ordinary calls. This tool exists so a
- * consumer can address every registered provider, not only the active one.
+ * The active provider remains the default for ordinary calls. Consumers can discover every
+ * registered provider; authors can read a definition with its active provider's tool policy.
  */
 export declare function getContractCatalogDefinition(): IContractDefinition;

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

@@ -12,10 +12,10 @@ exports.contractCatalogProviderPackageId = system_ids_1.peersSystemPackageId;
 const field = (name, type, description, opts = {}) => ({ name, type, description, ...opts });
 let definition;
 /**
- * Return the local-only catalog contract that lists providers of another contract.
+ * Return the local-only catalog contract for discovering providers and reading definitions.
  *
- * The active provider remains the default for ordinary calls. This tool exists so a
- * consumer can address every registered provider, not only the active one.
+ * The active provider remains the default for ordinary calls. Consumers can discover every
+ * registered provider; authors can read a definition with its active provider's tool policy.
  */
 function getContractCatalogDefinition() {
     definition ??= {
@@ -23,7 +23,7 @@ function getContractCatalogDefinition() {
         version: exports.CONTRACT_CATALOG_VERSION,
         devTag: "dev",
         name: "System Contract Catalog",
-        description: "Lists the packages registered as providers of a contract version.",
+        description: "Lists registered contract providers and returns contract definitions with active tool policy.",
         tables: [],
         tools: [
             {
@@ -34,7 +34,19 @@ function getContractCatalogDefinition() {
                     field("version", field_type_1.FieldType.number, "Contract version."),
                 ],
                 outputFields: [
-                    field("providers", field_type_1.FieldType.object, "Registered providers in registration order, with packageId, name, and active.", { isArray: true }),
+                    field("providers", field_type_1.FieldType.object, "Registered providers in registration order, with packageId, name, active, and the contracts each exposes through this one.", { isArray: true }),
+                ],
+            },
+            {
+                name: "getContractDefinition",
+                usageDescription: "Return a registered contract version's definition, with each tool's access level on its active provider. Save the result and run `peers-package contract add <file>` to generate a declaration of the contract.",
+                inputFields: [
+                    field("contractId", field_type_1.FieldType.id, "Contract to read."),
+                    field("version", field_type_1.FieldType.number, "Contract version."),
+                ],
+                outputFields: [
+                    field("definition", field_type_1.FieldType.object, "The registered definition, in Peers IR."),
+                    field("tools", field_type_1.FieldType.object, "Each tool's name, accessLevel, and authorityPropagation on the active provider.", { isArray: true, optional: true }),
                 ],
             },
         ],

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

@@ -124,13 +124,32 @@ async function findToolCatalogEntry(dataContext, input, callerContext) {
         const entries = rows
             .map((row) => describeToolCatalogRow(dataContext, row))
             .filter((entry) => !input.runnableOnly || entry.availability.dispatch !== "unavailable");
-        const groups = new Map(entries.map((entry) => [
-            entry.target ? (0, tool_catalog_identity_1.toolCatalogTargetKey)(entry.target) : entry.toolId,
-            entry,
-        ]));
+        // A version a provider also implements runs the same tool as the version implementing it
+        // only when both select that provider. Count them once and choose its implementing row.
+        const ranTool = (entry) => {
+            const implementation = entry.provider?.implementation;
+            return entry.target && implementation
+                ? JSON.stringify([
+                    entry.provider?.activePackageId,
+                    (0, tool_catalog_identity_1.toolCatalogTargetKey)({ ...entry.target, ...implementation }),
+                ])
+                : entry.target
+                    ? (0, tool_catalog_identity_1.toolCatalogTargetKey)(entry.target)
+                    : entry.toolId;
+        };
+        const implementing = (entry) => !entry.provider?.implementation ||
+            (entry.target?.contractId === entry.provider.implementation.contractId &&
+                entry.target?.version === entry.provider.implementation.version);
+        const groups = new Map();
+        for (const entry of entries) {
+            const key = ranTool(entry);
+            const chosen = groups.get(key);
+            if (!chosen || (!implementing(chosen) && implementing(entry)))
+                groups.set(key, entry);
+        }
         if (groups.size > 1)
             throw new Error(`Ambiguous tool "${input.toolIdOrName}": matched ${groups.size} tools (${entries.map((entry) => entry.toolId).join(", ")}); use a tool ID`);
-        return entries[0];
+        return groups.values().next().value;
     };
     const entry = exact
         ? describeToolCatalogRow(dataContext, exact)
@@ -241,7 +260,8 @@ async function invokeToolCatalogTool(dataContext, input, context, opts = {}) {
         }
         const source = input.args === undefined ? {} : input.args;
         requirePlainObject(source, "Tool args");
-        const args = { ...source };
+        // An optional argument that is null (as models often send) or undefined is left out.
+        const args = (0, types_1.withoutEmptyFields)(tool.inputFields, { ...source });
         for (const field of tool.inputFields)
             if (field.type === field_type_1.FieldType.Date && !field.isArray && typeof args[field.name] === "string")
                 args[field.name] = new Date(args[field.name]);

package/dist/contracts/tool-catalog.d.ts

@@ -1,6 +1,6 @@
 import type { DataContext } from "../context/data-context";
 import { type ITool } from "../data/tools";
-import type { ContractRegistry, IContractProviderRegistration } from "./registry";
+import { type ContractRegistry, type IContractProviderRegistration } from "./registry";
 import { type ToolCatalogTarget } from "./tool-catalog-identity";
 /** Supplemental metadata keyed by a declared public contract member, never by executable IDs. */
 export type IToolCatalogMetadata = ToolCatalogTarget & Pick<Partial<ITool>, "isAssistantRunner" | "configSchema" | "detailedDescription">;

package/dist/contracts/tool-catalog.js

@@ -6,6 +6,7 @@ exports.retainToolCatalogFields = retainToolCatalogFields;
 exports.validateToolCatalogWrite = validateToolCatalogWrite;
 const lodash_1 = require("lodash");
 const tools_1 = require("../data/tools");
+const registry_1 = require("./registry");
 const system_contracts_1 = require("./system-contracts");
 const tool_catalog_identity_1 = require("./tool-catalog-identity");
 const tool_catalog_migrations_1 = require("./tool-catalog-migrations");
@@ -357,7 +358,9 @@ class ToolCatalog {
                 const to = typeof range === "number" ? range : range.to;
                 for (let version = from; version <= to; version++) {
                     const key = `${declaration.contractId}@${version}`;
-                    const definition = definitions.get(key) ?? this.registry.getDefinition(declaration.contractId, version);
+                    const definition = definitions.get(key) ??
+                        this.registry.getDefinition(declaration.contractId, version) ??
+                        (0, registry_1.carriedDefinition)(declaration, version);
                     if (!definition)
                         throw new Error(`Missing alsoImplements definition: ${key}`);
                     definitions.set(key, definition);

package/dist/contracts/types.d.ts

@@ -2,7 +2,7 @@ import type { Table } from "../data/orm/table";
 import type { ITableDefinition } from "../data/orm/table-definitions.type";
 import type { Event } from "../events";
 import type { Observable } from "../observable";
-import type { FieldType, IField } from "../types/field-type";
+import type { FieldType, IField, IFieldShape } from "../types/field-type";
 import type { IContractConsumer, IContractConsumerBase, IContractToolImplementation } from "./contract-proxy";
 import type { IToolCatalogMetadata } from "./tool-catalog";
 /**
@@ -52,14 +52,25 @@ export interface IContractTool {
      * account) are never gated by this value. Policy only — not part of shape validation.
      */
     remoteAccessLevel?: number;
-    /** Host-only invocation policy, excluded from shape identity. Requires an in-process workflow. */
+    /**
+     * Host-only invocation policy, not part of shape validation: requires an in-process workflow.
+     */
     requiresWorkflowRun?: boolean;
 }
 /** Observable value exposed by a contract. */
 export interface IContractObservable {
     name: string;
     description: string;
+    /** The value's type, which the Runtime checks values against. */
     valueType: FieldType;
+    /**
+     * The value's full shape (nested fields and enum values), when the provider declared a schema.
+     * It describes; the provider's schema enforces. It follows field rules, so it can differ from
+     * `valueType`: an array of strings is `{ type: "string", isArray: true }` (its `valueType` is
+     * `object`), and a value that may be null is `optional` (a nullable object's `valueType` is
+     * `any`).
+     */
+    value?: IFieldShape;
     writable: boolean;
 }
 /**
@@ -181,6 +192,20 @@ export interface IAlsoImplementsDeclaration {
         from: number;
         to: number;
     };
+    /**
+     * The target's definition, carried by the provider (a single version only). The registry
+     * registers it when it has no definition of the target, so the alias survives a cold start
+     * without another package providing the target; a frozen registered definition must match it.
+     */
+    definition?: IContractDefinition;
+}
+/**
+ * Another contract a provider exposes through its implementation of a hub contract: the hub
+ * contract's consumers may call that contract's tools on this provider without consuming it.
+ */
+export interface IExposedContract {
+    contractId: string;
+    version: number;
 }
 /** The result of calling `definePackage()`. */
 export interface IPackageDefinitionResult {
@@ -199,6 +224,11 @@ export interface IPackageDefinitionResult {
     remotes?: IRemoteContract[];
     /** `alsoImplements` declarations keyed by the owning contractId+version. */
     alsoImplements: Map<string, IAlsoImplementsDeclaration[]>;
+    /**
+     * Contracts each hub implementation exposes, keyed by the hub contract's contractId+version.
+     * Optional so bundles built with an older SDK still load.
+     */
+    exposes?: Map<string, IExposedContract[]>;
     /** Package-level items not part of any contract. */
     assistants: unknown[];
     appNavs: unknown[];

package/dist/contracts/validate.d.ts

@@ -5,12 +5,27 @@ import type { IAlsoImplementsDeclaration, IContractDefinition, IValidationResult
  * observables, and events must be present with compatible shapes.
  */
 export declare function validateProviderSatisfiesContract(impl: IContractDefinition, contract: IContractDefinition): IValidationResult;
+/**
+ * What changed between two shapes of one contract version, member by member: a table, tool,
+ * observable, or event that was added, removed, or changed. Empty when the shapes match.
+ * Descriptions and tool policy are ignored, as in {@link validateImmutability}.
+ *
+ * @param existing - The frozen shape.
+ * @param incoming - The shape to compare with it.
+ * @returns One line per changed member, such as `tool add-item changed`.
+ */
+export declare function contractShapeChanges(existing: Pick<IContractDefinition, "tables" | "tools" | "observables" | "events">, incoming: Pick<IContractDefinition, "tables" | "tools" | "observables" | "events">): string[];
 /**
  * Validate that a frozen (stable) contract definition has not been modified.
  * If the existing definition has no `devTag` it is frozen; the incoming
- * definition must be structurally identical and also stable.
+ * definition must have the same shape and also be stable.
  * Dev contracts (`devTag: "dev"`) may change freely but cannot be registered
  * once a stable version exists for that contract+version.
+ *
+ * Descriptions may change on a frozen version (to point callers at a newer one, say), and so
+ * may a tool's policy (`remoteAccessLevel`, `requiresWorkflowRun`); member, field, and key order
+ * don't matter. IR keys added later (`fields`, `enumValues`, and an
+ * observable's `value`) are compared only when both definitions have them.
  */
 export declare function validateImmutability(existing: IContractDefinition, incoming: IContractDefinition): IValidationResult;
 /**