@peers-app/peers-sdk 0.23.4 → 0.23.5

package/dist/contracts/contract-provider-router.d.ts

@@ -26,6 +26,11 @@ export interface IContractProviderEndpointRequest {
     contractId: string;
     /** Target contract version. */
     version: number;
+    /**
+     * Provider selected by trusted host state. This value is never copied from
+     * an {@link IContractCall} or other guest payload.
+     */
+    providerPackageId?: string;
     /** Canonical data context returned by the authorization hook. */
     dataContextId?: string;
     /** Authorized caller context for this route. */
@@ -40,10 +45,20 @@ export interface IContractProviderEndpointRequest {
  * endpoint. The router caches the result until disposal.
  */
 export type ContractProviderEndpointResolver = (request: IContractProviderEndpointRequest) => IContractProviderEndpoint | Promise<IContractProviderEndpoint>;
+/**
+ * Resolves the provider package selected by trusted host state for one
+ * authorized route. The result participates in endpoint cache identity.
+ */
+export type ContractProviderPackageResolver = (request: IContractProviderEndpointRequest) => string | undefined | Promise<string | undefined>;
 /** Options for {@link createContractProviderRouter}. */
 export interface IContractProviderRouterOptions {
     /** Trusted host gate invoked before endpoint lookup or provider resolution. */
     authorizeCall: ContractCallAuthorizer;
+    /**
+     * Optional active-provider lookup. Supplying it makes endpoint caches
+     * provider-aware and automatically selects a new endpoint after a provider switch.
+     */
+    resolveProviderPackageId?: ContractProviderPackageResolver;
     /** Resolves an endpoint after authorization succeeds. */
     resolveEndpoint: ContractProviderEndpointResolver;
     /** Caller identity derived from the trusted underlying connection/session. */
@@ -51,6 +66,12 @@ export interface IContractProviderRouterOptions {
 }
 /** A connection-wide owner of contract request routing and endpoint lifecycle. */
 export interface IContractProviderRouter {
+    /**
+     * Dispose cached endpoints owned by a provider, for example after package
+     * replacement or uninstall. Existing subscription routes for those endpoints
+     * are dropped.
+     */
+    invalidateProvider(providerPackageId: string): void;
     /** Remove the request handler and dispose every resolved provider endpoint. */
     dispose(): void;
 }

package/dist/contracts/contract-provider-router.js

@@ -2,7 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createContractProviderRouter = createContractProviderRouter;
 const contract_transport_1 = require("./contract-transport");
-const routeKey = (contractId, version, dataContextId) => JSON.stringify([contractId, version, dataContextId ?? null]);
+const routeKey = (contractId, version, providerPackageId, dataContextId) => JSON.stringify([contractId, version, providerPackageId ?? null, dataContextId ?? null]);
 /**
  * Own the sole {@link CONTRACT_REQUEST_CHANNEL} handler for a shared connection.
  *
@@ -35,7 +35,7 @@ function createContractProviderRouter(transport, opts) {
         if (cached) {
             return cached.promise;
         }
-        const entry = {};
+        const entry = { providerPackageId: request.providerPackageId };
         entry.promise = Promise.resolve()
             .then(() => opts.resolveEndpoint(request))
             .then((endpoint) => {
@@ -102,14 +102,19 @@ function createContractProviderRouter(transport, opts) {
                 ...call,
                 dataContextId: authorization.dataContextId,
             };
-            const endpointKey = routeKey(call.contractId, call.version, authorization.dataContextId);
-            const endpoint = await getEndpoint(endpointKey, {
+            const endpointRequest = {
                 contractId: call.contractId,
                 version: call.version,
                 dataContextId: authorization.dataContextId,
                 context,
                 notify,
-            });
+            };
+            const providerPackageId = opts.resolveProviderPackageId
+                ? await opts.resolveProviderPackageId(endpointRequest)
+                : undefined;
+            endpointRequest.providerPackageId = providerPackageId;
+            const endpointKey = routeKey(call.contractId, call.version, providerPackageId, authorization.dataContextId);
+            const endpoint = await getEndpoint(endpointKey, endpointRequest);
             const result = await endpoint.handleCall(routedCall, context);
             if (isSubscribe && subscriptionId) {
                 const subscriptionRoute = {
@@ -141,6 +146,27 @@ function createContractProviderRouter(transport, opts) {
     };
     const offRequest = transport.on(contract_transport_1.CONTRACT_REQUEST_CHANNEL, handleAuthorizedCall);
     return {
+        invalidateProvider(providerPackageId) {
+            const invalidatedKeys = new Set();
+            for (const [key, entry] of endpointEntries) {
+                if (entry.providerPackageId !== providerPackageId) {
+                    continue;
+                }
+                invalidatedKeys.add(key);
+                endpointEntries.delete(key);
+                if (entry.endpoint) {
+                    entry.endpoint.dispose();
+                }
+                else {
+                    void entry.promise.then((endpoint) => endpoint.dispose()).catch(() => { });
+                }
+            }
+            for (const [subscriptionId, route] of subscriptionRoutes) {
+                if (invalidatedKeys.has(route.endpointKey)) {
+                    subscriptionRoutes.delete(subscriptionId);
+                }
+            }
+        },
         dispose() {
             if (disposed) {
                 return;

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

@@ -221,6 +221,9 @@ export interface IContractToolContext {
  * Every access is turned into an {@link IContractCall} sent on the transport's fixed
  * {@link CONTRACT_REQUEST_CHANNEL}; the resolved ack is the provider's return value.
  *
+ * Provider-only tables are omitted from {@link IContractConsumer.tables}; consumers must
+ * call a declared provider method instead of raw CRUD.
+ *
  * The consumer also subscribes to provider pushes: `events[name].subscribe(handler)` and
  * `tables[name].dataChanged.subscribe(handler)` both send a `"subscribe"` request and
  * demultiplex provider pushes arriving on {@link CONTRACT_NOTIFY_CHANNEL} by their

package/dist/contracts/contract-proxy.js

@@ -51,6 +51,9 @@ exports.CONTRACT_CALL_RPC = contract_transport_1.CONTRACT_REQUEST_CHANNEL;
  * Every access is turned into an {@link IContractCall} sent on the transport's fixed
  * {@link CONTRACT_REQUEST_CHANNEL}; the resolved ack is the provider's return value.
  *
+ * Provider-only tables are omitted from {@link IContractConsumer.tables}; consumers must
+ * call a declared provider method instead of raw CRUD.
+ *
  * The consumer also subscribes to provider pushes: `events[name].subscribe(handler)` and
  * `tables[name].dataChanged.subscribe(handler)` both send a `"subscribe"` request and
  * demultiplex provider pushes arriving on {@link CONTRACT_NOTIFY_CHANNEL} by their

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

@@ -14,12 +14,23 @@ export type ContractResolver = (ctx: {
 }) => IContractResolution | Promise<IContractResolution>;
 /** Input supplied to a trusted local host when a package tool resolves a pvar. */
 export interface ILocalContractVariableRequest {
+    /** Data context that owns the persistent variable. */
     dataContext: DataContext;
+    /** Persistent-variable name requested by the tool. */
     variableName: string;
+    /** Tool id making the request (for host policy / logging). */
     requestingToolId: string;
 }
 /** Host callback that resolves plaintext only inside a local provider process. */
 export type LocalContractVariableResolver = (request: ILocalContractVariableRequest) => Promise<string>;
+/** Options for a provider-scoped {@link registerContractResolver} registration. */
+export interface IContractResolverRegistrationOptions {
+    /**
+     * Provider package that owns this resolver. Omit for the legacy unscoped
+     * resolver used as a compatibility fallback.
+     */
+    providerPackageId?: string;
+}
 /** Connection-authenticated identity fields used to authorize remote contract calls. */
 export type ContractRemoteIdentity = Pick<IDeviceInfo, "deviceId" | "userId" | "publicKey" | "publicBoxKey">;
 /**
@@ -27,9 +38,16 @@ export type ContractRemoteIdentity = Pick<IDeviceInfo, "deviceId" | "userId" | "
  * Later registrations for the same contract+version replace earlier ones (matching the
  * registry's "latest provider wins for dev contracts" behavior).
  */
-export declare function registerContractResolver(contractId: string, version: number, resolver: ContractResolver): void;
-/** Look up the resolver for a contract version, if one is registered. */
-export declare function getContractResolver(contractId: string, version: number): ContractResolver | undefined;
+export declare function registerContractResolver(contractId: string, version: number, resolver: ContractResolver, opts?: IContractResolverRegistrationOptions): void;
+/**
+ * Look up a resolver for a contract version.
+ *
+ * When `providerPackageId` is supplied, an exact provider-scoped resolver wins
+ * and the legacy unscoped registration remains the compatibility fallback.
+ * An unscoped lookup may use a sole scoped resolver for callers that have not
+ * yet adopted provider selection; multiple scoped providers remain ambiguous.
+ */
+export declare function getContractResolver(contractId: string, version: number, providerPackageId?: string): ContractResolver | undefined;
 /**
  * Check whether a connection-authenticated remote identity has full contract authority.
  *

package/dist/contracts/contract-resolvers.js

@@ -15,17 +15,49 @@ const contract_provider_router_1 = require("./contract-provider-router");
 const contract_proxy_1 = require("./contract-proxy");
 const types_1 = require("./types");
 const resolvers = new Map();
+const resolverKey = (contractId, version, providerPackageId) => providerPackageId
+    ? `${(0, types_1.contractKey)(contractId, version)}#provider:${providerPackageId}`
+    : (0, types_1.contractKey)(contractId, version);
 /**
  * Register the resolver that provides the live implementation for a contract version.
  * Later registrations for the same contract+version replace earlier ones (matching the
  * registry's "latest provider wins for dev contracts" behavior).
  */
-function registerContractResolver(contractId, version, resolver) {
-    resolvers.set((0, types_1.contractKey)(contractId, version), resolver);
+function registerContractResolver(contractId, version, resolver, opts = {}) {
+    resolvers.set(resolverKey(contractId, version, opts.providerPackageId), resolver);
 }
-/** Look up the resolver for a contract version, if one is registered. */
-function getContractResolver(contractId, version) {
-    return resolvers.get((0, types_1.contractKey)(contractId, version));
+/**
+ * Look up a resolver for a contract version.
+ *
+ * When `providerPackageId` is supplied, an exact provider-scoped resolver wins
+ * and the legacy unscoped registration remains the compatibility fallback.
+ * An unscoped lookup may use a sole scoped resolver for callers that have not
+ * yet adopted provider selection; multiple scoped providers remain ambiguous.
+ */
+function getContractResolver(contractId, version, providerPackageId) {
+    const unscoped = resolvers.get(resolverKey(contractId, version));
+    if (providerPackageId) {
+        const scoped = resolvers.get(resolverKey(contractId, version, providerPackageId));
+        if (scoped) {
+            return scoped;
+        }
+        return unscoped;
+    }
+    if (unscoped) {
+        return unscoped;
+    }
+    const providerPrefix = `${(0, types_1.contractKey)(contractId, version)}#provider:`;
+    let onlyScopedResolver;
+    for (const [key, resolver] of resolvers) {
+        if (!key.startsWith(providerPrefix)) {
+            continue;
+        }
+        if (onlyScopedResolver) {
+            return undefined;
+        }
+        onlyScopedResolver = resolver;
+    }
+    return onlyScopedResolver;
 }
 /**
  * Check whether a connection-authenticated remote identity has full contract authority.
@@ -91,6 +123,41 @@ function getAuthorizedLocalDataContext(userContext, requestedId) {
     }
     return userContext.getDataContext(dataContextId);
 }
+function getActiveProviderPackageId(dataContext, contractId, version) {
+    return dataContext.packageLoader?.getActiveContractProviderPackageId?.(contractId, version);
+}
+async function resolveDataContextEndpoint(dataContext, request, resolveVariable) {
+    if (dataContext.packageLoader?.resolveContractEndpoint) {
+        return dataContext.packageLoader.resolveContractEndpoint(request, {
+            resolveVariable: resolveVariable
+                ? (variableName, requestingToolId) => resolveVariable({ dataContext, variableName, requestingToolId })
+                : undefined,
+        });
+    }
+    // Transitional fallback for hosts/tests that provide a partial DataContext.
+    const isolatedEndpoint = await dataContext.packageLoader?.resolveIsolatedEndpoint?.(request);
+    if (isolatedEndpoint) {
+        return isolatedEndpoint;
+    }
+    const resolver = getContractResolver(request.contractId, request.version, request.providerPackageId);
+    if (!resolver) {
+        throw new Error(`No contract provider registered for ${request.contractId} v${request.version}`);
+    }
+    const resolution = await resolver({ dataContext });
+    const localResolution = resolveVariable
+        ? {
+            ...resolution,
+            toolContext: {
+                dataContextId: dataContext.dataContextId,
+                getVariable: (variableName, requestingToolId) => resolveVariable({ dataContext, variableName, requestingToolId }),
+            },
+        }
+        : resolution;
+    return (0, contract_proxy_1.createContractProviderEndpoint)(localResolution, {
+        context: request.context,
+        notify: request.notify,
+    });
+}
 /**
  * Create a provider router for one authenticated UI-to-local-host session.
  *
@@ -127,24 +194,15 @@ function createLocalUserContextContractProviderRouter(transport, opts) {
                 context,
             };
         },
-        resolveEndpoint: async ({ contractId, version, dataContextId, context, notify }) => {
+        resolveProviderPackageId: async ({ contractId, version, dataContextId }) => {
             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 });
-            const localResolution = resolveVariable
-                ? {
-                    ...resolution,
-                    toolContext: {
-                        dataContextId: dataContext.dataContextId,
-                        getVariable: (variableName, requestingToolId) => resolveVariable({ dataContext, variableName, requestingToolId }),
-                    },
-                }
-                : resolution;
-            return (0, contract_proxy_1.createContractProviderEndpoint)(localResolution, { context, notify });
+            return getActiveProviderPackageId(dataContext, contractId, version);
+        },
+        resolveEndpoint: async (request) => {
+            const userContext = await getUserContext();
+            const dataContext = getAuthorizedLocalDataContext(userContext, request.dataContextId);
+            return resolveDataContextEndpoint(dataContext, request, resolveVariable);
         },
     });
 }
@@ -172,14 +230,13 @@ function createUserContextContractProviderRouter(transport, opts) {
     return (0, contract_provider_router_1.createContractProviderRouter)(transport, {
         context,
         authorizeCall: (call) => authorizeUserContextCall(call, userContext, remoteIdentity),
-        resolveEndpoint: async ({ contractId, version, dataContextId, notify }) => {
-            const resolver = getContractResolver(contractId, version);
-            if (!resolver) {
-                throw new Error(`No contract provider registered for ${contractId} v${version}`);
-            }
+        resolveProviderPackageId: ({ contractId, version, dataContextId }) => {
             const dataContext = userContext.getDataContext(dataContextId || userContext.userId);
-            const resolution = await resolver({ dataContext });
-            return (0, contract_proxy_1.createContractProviderEndpoint)(resolution, { notify });
+            return getActiveProviderPackageId(dataContext, contractId, version);
+        },
+        resolveEndpoint: (request) => {
+            const dataContext = userContext.getDataContext(request.dataContextId || userContext.userId);
+            return resolveDataContextEndpoint(dataContext, request);
         },
     });
 }
@@ -198,15 +255,31 @@ function createUserContextContractProviderRouter(transport, opts) {
 async function handleContractCall(call, opts) {
     const { userContext, remoteIdentity } = opts;
     const authorization = await authorizeUserContextCall(call, userContext, remoteIdentity);
-    const resolver = getContractResolver(call.contractId, call.version);
-    if (!resolver) {
-        throw new Error(`No contract provider registered for ${call.contractId} v${call.version}`);
-    }
     const routedCall = {
         ...call,
         dataContextId: authorization.dataContextId,
     };
     const dataContext = userContext.getDataContext(authorization.dataContextId || userContext.userId);
+    if (dataContext.packageLoader?.resolveContractEndpoint) {
+        const endpoint = await dataContext.packageLoader.resolveContractEndpoint({
+            contractId: call.contractId,
+            version: call.version,
+            providerPackageId: getActiveProviderPackageId(dataContext, call.contractId, call.version),
+            dataContextId: authorization.dataContextId,
+            context: authorization.context ?? {},
+            notify: async () => undefined,
+        });
+        try {
+            return await endpoint.handleCall(routedCall, authorization.context);
+        }
+        finally {
+            endpoint.dispose();
+        }
+    }
+    const resolver = getContractResolver(call.contractId, call.version);
+    if (!resolver) {
+        throw new Error(`No contract provider registered for ${call.contractId} v${call.version}`);
+    }
     const resolution = await resolver({ dataContext });
     const provider = (0, contract_proxy_1.createContractProvider)(resolution);
     return provider(routedCall, authorization.context);

package/dist/contracts/index.d.ts

@@ -1,15 +1,15 @@
 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 { type ContractCallAuthorizer, type ContractProviderEndpointResolver, type ContractProviderPackageResolver, 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 IContractConsumerBase, type IContractNotification, type IContractProviderEndpoint, type IContractProviderEndpointOptions, type IContractProviderSession, type IContractProviderSessionOptions, type IContractResolution, type IContractTableProxy, type IContractToolContext, type ITableProxy, sameUserContractPermissionCheck, } from "./contract-proxy";
-export { type ContractRemoteIdentity, type ContractResolver, createLocalUserContextContractProviderRouter, createUserContextContractProviderRouter, getContractResolver, handleContractCall, type ILocalContractVariableRequest, isSelfTrustedContractCaller, type LocalContractVariableResolver, registerContractResolver, } from "./contract-resolvers";
+export { type ContractRemoteIdentity, type ContractResolver, createLocalUserContextContractProviderRouter, createUserContextContractProviderRouter, getContractResolver, handleContractCall, type IContractResolverRegistrationOptions, type ILocalContractVariableRequest, isSelfTrustedContractCaller, type LocalContractVariableResolver, 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 { ContractRegistry, type IContractProviderRegistration } 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, type ILogsConsumer, LOGS_CONTRACT_VERSION, resolveLogsContract, } from "./system/logs-contract";
 export * from "./system/network-contracts";

package/dist/contracts/registry.d.ts

@@ -1,4 +1,14 @@
 import type { IAlsoImplementsDeclaration, IConsumedContract, IContractDefinition, IValidationResult } from "./types";
+/**
+ * One contract-provider registration in an atomic
+ * {@link ContractRegistry.registerBatch} operation.
+ */
+export interface IContractProviderRegistration {
+    /** Contract shape implemented by the provider package. */
+    definition: IContractDefinition;
+    /** Older contract shapes this implementation also satisfies. */
+    alsoImplements?: IAlsoImplementsDeclaration[];
+}
 /**
  * Per-group contract registry. Maps contract identities (contractId + version)
  * to their active provider.  In V1 this is in-memory only; persistence will
@@ -27,6 +37,41 @@ export declare class ContractRegistry {
      * @returns Validation result.  If invalid the provider is not registered.
      */
     register(providerPackageId: string, definition: IContractDefinition, alsoImplementsDecls?: IAlsoImplementsDeclaration[]): IValidationResult;
+    /**
+     * Atomically register every contract supplied by one provider package.
+     *
+     * Frozen-shape and `alsoImplements` checks run against a candidate registry
+     * containing the whole batch, so declarations may reference another
+     * contract in the same install. If any entry fails, no definition, provider,
+     * active-provider pointer, or reverse index is changed.
+     *
+     * @param providerPackageId - Trusted identity of the provider package.
+     * @param registrations - Contract definitions and compatibility declarations.
+     * @returns The combined validation result.
+     */
+    registerBatch(providerPackageId: string, registrations: readonly IContractProviderRegistration[]): IValidationResult;
+    /**
+     * Atomically replace the complete contract set for one provider package.
+     *
+     * Validation runs before the existing provider entries are touched. Active
+     * selections remain on this package for contract versions it still provides;
+     * removed versions fall back according to ordinary unregister semantics.
+     *
+     * @param providerPackageId - Trusted provider package identity.
+     * @param registrations - Complete replacement set.
+     * @returns Validation result; invalid replacements leave the registry unchanged.
+     */
+    replaceBatch(providerPackageId: string, registrations: readonly IContractProviderRegistration[]): IValidationResult;
+    /**
+     * Validate a complete provider registration batch without changing registry state.
+     *
+     * @param providerPackageId - Trusted provider package identity.
+     * @param registrations - Definitions and compatibility declarations to validate.
+     * @returns Combined validation result.
+     */
+    validateBatch(providerPackageId: string, registrations: readonly IContractProviderRegistration[]): IValidationResult;
+    private commitRegistrations;
+    private commitProvider;
     /**
      * Switch the active provider for a contract to a different registered package.
      * Returns false if the target package is not a registered provider for that contract.
@@ -44,6 +89,20 @@ export declare class ContractRegistry {
      * Includes inactive providers.
      */
     getRegisteredProviderIds(contractId: string, version: number): string[];
+    /**
+     * Resolve the concrete contract implementation selected for one provider.
+     *
+     * For a direct registration this matches the requested contract. For an
+     * `alsoImplements` alias it identifies the newer compatible implementation.
+     *
+     * @param contractId - Consumer-requested contract identity.
+     * @param version - Consumer-requested contract version.
+     * @param providerPackageId - Registry-selected provider package.
+     */
+    getProviderImplementation(contractId: string, version: number, providerPackageId: string): {
+        contractId: string;
+        version: number;
+    } | undefined;
     /**
      * Pick a provider for a consumed-contract declaration.
      *