@peers-app/peers-sdk 0.25.21 → 0.26.0

package/dist/contracts/__tests__/workflow-context.test.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+require("../../index");
+const contract_proxy_1 = require("../contract-proxy");
+test("only the directly invoked tool receives workflow capability", async () => {
+    const workflow = { dataContextId: "group" };
+    const nested = jest.fn();
+    const action = jest.fn((_args, context) => {
+        expect(context.workflow).toBeUndefined();
+        expect(context.callContext.workflow).toBeUndefined();
+        expect(context.incomingCallContext.workflow).toBeUndefined();
+    });
+    const resolution = {
+        contractId: "contract",
+        version: 1,
+        forwardCallContext: true,
+        actionAliases: { do: "action" },
+        actionTools: {
+            action: { tool: { name: "action", usageDescription: "", accessLevel: 0 }, toolFn: action },
+        },
+        tools: {
+            run: {
+                tool: { name: "run", usageDescription: "", accessLevel: 0 },
+                toolFn: async (_args, context) => {
+                    expect((0, contract_proxy_1.requireWorkflowRunContext)(context, "run")).toBe(workflow);
+                    expect(context.callContext.workflow).toBeUndefined();
+                    expect(context.incomingCallContext.workflow).toBeUndefined();
+                    await context.dispatchTool({ contractId: "other", version: 1, toolName: "target" }, {});
+                    await context.dispatchAction("do", {});
+                },
+            },
+        },
+    };
+    const tables = { tableContainer: { getTable: () => ({ get: async () => undefined }) } };
+    const dataContext = {
+        dataContextId: "group",
+        userContext: {
+            userId: "u",
+            loadingPromise: Promise.resolve(),
+            userDataContext: tables,
+            getDataContext: () => tables,
+        },
+    };
+    const provider = (0, contract_proxy_1.createContractProvider)(resolution, { dispatchTool: nested });
+    await provider({
+        contractId: "contract",
+        version: 1,
+        member: "tool",
+        operation: "run",
+        name: "run",
+        args: [{}],
+    }, { dataContext, callerUserId: "u", workflow });
+    expect(nested.mock.calls[0][2].workflow).toBeUndefined();
+    expect(action).toHaveBeenCalled();
+    expect(() => (0, contract_proxy_1.requireWorkflowRunContext)({ dataContextId: "other", workflow }, "run")).toThrow("same data context");
+});
+test("workflow policy is retained by shape extraction", () => {
+    const { extractToolShape } = require("../extract");
+    expect(extractToolShape({ tool: { name: "run", usageDescription: "" }, requiresWorkflowRun: true })
+        .requiresWorkflowRun).toBe(true);
+});

package/dist/contracts/builder.d.ts

@@ -1,7 +1,7 @@
 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 { IToolCatalogMetadata } from "./tool-catalog";
 import type { IAlsoImplementsDeclaration, IConsumedContractHandle, IConsumedContractOptions, IContractDefinition, IContractEvent, IContractObservable, IPackageDefinitionResult, IRemoteContractHandle } from "./types";
 /**
  * Scoped builder for a single contract within a package. Returned by
@@ -17,8 +17,7 @@ export declare class ContractBuilder {
     private _observables;
     private _events;
     private _alsoImplements;
-    /** Full runtime tool instances for this contract (used by the install flow). */
-    private _toolInstances;
+    private warnedAboutToolInstances;
     /** Full table definitions for this contract (used by the install flow). */
     private _tableDefinitions;
     constructor(contractId: string, version: number, name: string, description?: string | undefined);
@@ -35,9 +34,11 @@ export declare class ContractBuilder {
      */
     set events(events: IContractEvent[]);
     get events(): IContractEvent[];
-    /** Full tool instances with executable toolFn for runtime registration. */
-    set toolInstances(instances: IToolInstance[]);
-    get toolInstances(): IToolInstance[];
+    /**
+     * Discard executable assignments from bundles compiled against an older SDK.
+     * @deprecated Implement tools with registerContractResolver instead.
+     */
+    set toolInstances(_instances: never);
     /** Full table definitions for runtime table registration. */
     set tableDefinitions(defs: ITableDefinition[]);
     get tableDefinitions(): ITableDefinition[];
@@ -53,7 +54,7 @@ export declare class ContractBuilder {
     _build(): {
         definition: IContractDefinition;
         alsoImplements: IAlsoImplementsDeclaration[];
-        toolInstances: IToolInstance[];
+        toolMetadata: IToolCatalogMetadata[];
         tableDefinitions: ITableDefinition[];
     };
 }
@@ -108,7 +109,7 @@ export declare function rejectConsumedContractHandle(handle: IConsumedContractHa
  * Top-level builder passed to the `definePackage` callback.
  *
  * Packages may define **zero** contracts (e.g. UI-only apps with no persisted
- * tables). Tables, tool shapes, and executable `toolInstances` /
+ * tables). Tables, tool shapes, and runtime
  * `tableDefinitions` are only attached via {@link PackageBuilder.contract} —
  * there is no package-level API for them, so persistence always implies a
  * contract.

package/dist/contracts/builder.js

@@ -25,8 +25,7 @@ class ContractBuilder {
     _observables = [];
     _events = [];
     _alsoImplements = [];
-    /** Full runtime tool instances for this contract (used by the install flow). */
-    _toolInstances = [];
+    warnedAboutToolInstances = false;
     /** Full table definitions for this contract (used by the install flow). */
     _tableDefinitions = [];
     constructor(contractId, version, name, description) {
@@ -64,12 +63,15 @@ class ContractBuilder {
     get events() {
         return this._events;
     }
-    /** Full tool instances with executable toolFn for runtime registration. */
-    set toolInstances(instances) {
-        this._toolInstances = instances;
-    }
-    get toolInstances() {
-        return this._toolInstances;
+    /**
+     * Discard executable assignments from bundles compiled against an older SDK.
+     * @deprecated Implement tools with registerContractResolver instead.
+     */
+    set toolInstances(_instances) {
+        if (this.warnedAboutToolInstances)
+            return;
+        this.warnedAboutToolInstances = true;
+        console.warn(`Contract ${this.name} (${this.contractId}@${this.version}) assigned toolInstances, which no longer run; implement these tools with registerContractResolver (docs/Packages/contracts.md#migrating-from-toolinstances)`);
     }
     /** Full table definitions for runtime table registration. */
     set tableDefinitions(defs) {
@@ -103,7 +105,23 @@ class ContractBuilder {
                 events: [...this._events],
             },
             alsoImplements: [...this._alsoImplements],
-            toolInstances: [...this._toolInstances],
+            toolMetadata: this._tools.flatMap(({ tool }) => {
+                const { isAssistantRunner, configSchema, detailedDescription } = tool;
+                return isAssistantRunner !== undefined ||
+                    configSchema !== undefined ||
+                    detailedDescription !== undefined
+                    ? [
+                        {
+                            contractId: this.contractId,
+                            version: this.version,
+                            toolName: tool.name,
+                            isAssistantRunner,
+                            configSchema,
+                            detailedDescription,
+                        },
+                    ]
+                    : [];
+            }),
             tableDefinitions: [...this._tableDefinitions],
         };
     }
@@ -188,7 +206,7 @@ function rejectConsumedContractHandle(handle, reason) {
  * Top-level builder passed to the `definePackage` callback.
  *
  * Packages may define **zero** contracts (e.g. UI-only apps with no persisted
- * tables). Tables, tool shapes, and executable `toolInstances` /
+ * tables). Tables, tool shapes, and runtime
  * `tableDefinitions` are only attached via {@link PackageBuilder.contract} —
  * there is no package-level API for them, so persistence always implies a
  * contract.
@@ -312,19 +330,19 @@ class PackageBuilder {
         }
         const contracts = [];
         const alsoImplementsMap = new Map();
-        const allToolInstances = [];
+        const allToolMetadata = [];
         const allTableDefinitions = [];
         for (const cb of this._contracts) {
-            const { definition, alsoImplements, toolInstances, tableDefinitions } = cb._build();
+            const { definition, alsoImplements, toolMetadata, tableDefinitions } = cb._build();
             contracts.push(definition);
             if (alsoImplements.length > 0) {
                 alsoImplementsMap.set((0, types_1.contractKey)(cb.contractId, cb.version), alsoImplements);
             }
-            allToolInstances.push(...toolInstances);
+            allToolMetadata.push(...toolMetadata);
             allTableDefinitions.push(...tableDefinitions);
         }
-        if (contracts.length === 0 && (allToolInstances.length > 0 || allTableDefinitions.length > 0)) {
-            throw new Error("Tables and executable tools must be declared on a contract (use pkg.contract(...), then assign .tables, .tools, .toolInstances, or .tableDefinitions on that builder). UI-only packages omit contracts and do not register tables or tools.");
+        if (contracts.length === 0 && allTableDefinitions.length > 0) {
+            throw new Error("Tables must be declared on a contract (use pkg.contract(...), then assign .tables or .tableDefinitions on that builder). UI-only packages omit contracts and do not register tables.");
         }
         return {
             packageId: this._packageId,
@@ -335,7 +353,7 @@ class PackageBuilder {
             alsoImplements: alsoImplementsMap,
             assistants: [...this.assistants],
             appNavs: [...this.appNavs],
-            toolInstances: allToolInstances,
+            ...(allToolMetadata.length ? { toolMetadata: allToolMetadata } : {}),
             tableDefinitions: allTableDefinitions,
         };
     }

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

@@ -55,7 +55,7 @@ export interface IContractProviderEndpointRequest {
  * Resolves an endpoint for an authorized contract/version/data-context route.
  *
  * The callback may adapt local live objects or return a remote/sandbox-backed
- * endpoint. The router caches the result until disposal.
+ * endpoint. The router caches the result until invalidation, retirement or disposal.
  */
 export type ContractProviderEndpointResolver = (request: IContractProviderEndpointRequest) => IContractProviderEndpoint | Promise<IContractProviderEndpoint>;
 /**
@@ -95,6 +95,15 @@ export interface IContractProviderRouter {
     /** Remove the request handler and dispose every resolved provider endpoint. */
     dispose(): void;
 }
+/**
+ * Signals that this exact endpoint rejected a call before invoking provider code.
+ * Routers may refresh that endpoint and retry once. The endpoint identity prevents
+ * a retirement error from a downstream call from replaying its caller's effects.
+ */
+export declare class RetiredContractProviderEndpointError extends Error {
+    readonly endpoint: IContractProviderEndpoint;
+    constructor(endpoint: IContractProviderEndpoint);
+}
 /**
  * Own the sole {@link CONTRACT_REQUEST_CHANNEL} handler for a shared connection.
  *
@@ -106,6 +115,8 @@ export interface IContractProviderRouter {
  * idempotent and skip reauthorization while still reaching the endpoint that owns the live
  * source. Disposing the router removes its request handler and disposes all cached endpoints,
  * including endpoints whose asynchronous resolution finishes during teardown.
+ * A lifetime guard's retirement rejection refreshes the cached endpoint once,
+ * before any provider code has run. Errors from provider execution are not retried.
  *
  * @param transport  Duplex contract transport shared by all contracts on one connection.
  * @param opts       Trusted authorization, endpoint resolution, and caller context hooks.

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

@@ -1,7 +1,22 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.RetiredContractProviderEndpointError = void 0;
 exports.createContractProviderRouter = createContractProviderRouter;
 const contract_transport_1 = require("./contract-transport");
+/**
+ * Signals that this exact endpoint rejected a call before invoking provider code.
+ * Routers may refresh that endpoint and retry once. The endpoint identity prevents
+ * a retirement error from a downstream call from replaying its caller's effects.
+ */
+class RetiredContractProviderEndpointError extends Error {
+    endpoint;
+    constructor(endpoint) {
+        super("Host contract endpoint has been retired");
+        this.endpoint = endpoint;
+        this.name = "RetiredContractProviderEndpointError";
+    }
+}
+exports.RetiredContractProviderEndpointError = RetiredContractProviderEndpointError;
 const routeKey = (contractId, version, providerPackageId, dataContextId, targetDeviceId) => JSON.stringify([
     contractId,
     version,
@@ -29,6 +44,8 @@ function assertRemoteTargetCallSupported(call) {
  * idempotent and skip reauthorization while still reaching the endpoint that owns the live
  * source. Disposing the router removes its request handler and disposes all cached endpoints,
  * including endpoints whose asynchronous resolution finishes during teardown.
+ * A lifetime guard's retirement rejection refreshes the cached endpoint once,
+ * before any provider code has run. Errors from provider execution are not retried.
  *
  * @param transport  Duplex contract transport shared by all contracts on one connection.
  * @param opts       Trusted authorization, endpoint resolution, and caller context hooks.
@@ -146,8 +163,29 @@ function createContractProviderRouter(transport, opts) {
                 : undefined;
             endpointRequest.providerPackageId = providerPackageId;
             const endpointKey = routeKey(call.contractId, call.version, providerPackageId, authorization.dataContextId, targetDeviceId);
-            const endpoint = await getEndpoint(endpointKey, endpointRequest);
-            const result = await endpoint.handleCall(routedCall, context);
+            let endpoint = await getEndpoint(endpointKey, endpointRequest);
+            let result;
+            try {
+                result = await endpoint.handleCall(routedCall, context);
+            }
+            catch (error) {
+                if (disposed ||
+                    !(error instanceof RetiredContractProviderEndpointError) ||
+                    error.endpoint !== endpoint)
+                    throw error;
+                // Only retire the entry that rejected this call. Another concurrent call
+                // may already have refreshed the same route and attached subscriptions.
+                if (endpointEntries.get(endpointKey)?.endpoint === endpoint) {
+                    endpointEntries.delete(endpointKey);
+                    for (const [id, route] of subscriptionRoutes) {
+                        if (route.endpointKey === endpointKey)
+                            subscriptionRoutes.delete(id);
+                    }
+                    endpoint.dispose();
+                }
+                endpoint = await getEndpoint(endpointKey, endpointRequest);
+                result = await endpoint.handleCall(routedCall, context);
+            }
             if (isSubscribe && subscriptionId) {
                 const subscriptionRoute = {
                     endpointKey,

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

@@ -1,9 +1,10 @@
 import type { DataContext } from "../context/data-context";
 import type { Table } from "../data/orm/table";
-import type { IToolInstance } from "../data/tools";
+import type { ITool, IToolInstance } from "../data/tools";
 import type { Event, ISubscriptionResult } from "../events";
 import { type Observable } from "../observable";
 import type { IIsolatedCallPrincipal } from "../package-loader/isolated-runtime";
+import type { IWorkflowRunContext } from "../types/workflow-run-context";
 import { type IContractTransport } from "./contract-transport";
 import type { IContractDefinition, IRemoteContractConsumer } from "./types";
 /**
@@ -222,6 +223,8 @@ export interface IContractConsumer extends IContractConsumerBase {
  * contract calls unless a host explicitly opts in.
  */
 export interface IContractToolContext {
+    /** Direct host invocation only; never forwarded to nested, remote or isolated calls. */
+    workflow?: IWorkflowRunContext;
     /** Authorized data context in which the tool is executing. */
     dataContextId: string;
     /**
@@ -308,19 +311,26 @@ export declare function createRemoteContractConsumer(contract: IContractDefiniti
     dataContextId?: string;
 }): IRemoteContractConsumer<IContractConsumer>;
 /**
- * The live implementation a **provider** dispatches contract calls to. This is the
- * runtime-callable counterpart to {@link IResolvedContract} (which additionally tracks
- * the providing package); the proxy layer only needs the live members.
+ * Provider-local executable metadata. Existing IToolInstance values remain assignable;
+ * new implementations need no catalog ID, persisted row, or executable registration.
  */
+export interface IContractToolImplementation {
+    /** Provider metadata; the contract member name supplies identity, without a Tools row. */
+    tool: Pick<ITool, "name" | "usageDescription"> & Partial<Pick<ITool, "toolId" | "detailedDescription" | "inputSchema" | "outputSchema" | "accessLevel" | "authorityPropagation" | "remoteAccessLevel">>;
+    toolFn: IToolInstance["toolFn"];
+    inputSchema?: IToolInstance["inputSchema"];
+    outputSchema?: IToolInstance["outputSchema"];
+}
+/** Context-bound live members of a provider; executable ownership stays with the contract. */
 export interface IContractResolution {
     contractId: string;
     version: number;
     tables?: Record<string, Table<any>>;
-    tools?: Record<string, IToolInstance>;
+    tools?: Record<string, IContractToolImplementation>;
     /** Tool used for alias catalog admission; defaults to a tool requesting preservation. */
     actionDispatcher?: string;
     /** Private canonical tools; selectors never carry their own numeric permissions. */
-    actionTools?: Record<string, IToolInstance>;
+    actionTools?: Record<string, IContractToolImplementation>;
     /** Package-owned selector-to-tool mapping, validated by the host. */
     actionAliases?: Record<string, string>;
     /**
@@ -365,6 +375,8 @@ export interface IContractResolution {
 }
 /** Identity of the caller, supplied by the transport layer for permission checks. */
 export interface IContractCallContext {
+    /** In-process workflow capability; never serialized or propagated to nested calls. */
+    workflow?: IWorkflowRunContext;
     /** User id of the caller (e.g. the remote device's user), if known. */
     callerUserId?: string;
     /** User id of the local device executing the call. */
@@ -531,4 +543,6 @@ 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;
+/** Require the directly invoked host tool’s workflow in the authorized data context. */
+export declare function requireWorkflowRunContext(toolContext: IContractToolContext | undefined, toolName: string): IWorkflowRunContext;
 export {};

package/dist/contracts/contract-proxy.js

@@ -8,6 +8,7 @@ exports.authorizedContractActionNames = authorizedContractActionNames;
 exports.createContractProvider = createContractProvider;
 exports.createContractProviderEndpoint = createContractProviderEndpoint;
 exports.createContractProviderSession = createContractProviderSession;
+exports.requireWorkflowRunContext = requireWorkflowRunContext;
 const access_level_1 = require("../data/access-level");
 const group_permissions_1 = require("../data/group-permissions");
 const decorators_1 = require("../data/orm/decorators");
@@ -623,7 +624,8 @@ function createContractProvider(resolution, opts = {}) {
                 }
                 if (resolution.actionTools && !Object.keys(resolution.actionAliases ?? {}).length)
                     throw new Error("Action dispatcher requires registered checked actions");
-                const authority = await assertContractToolAccess(tool, call, context);
+                const { workflow, ...caller } = context;
+                const authority = await assertContractToolAccess(tool, call, caller);
                 if (resolution.toolContext ||
                     resolution.forwardCallContext ||
                     resolution.actionAliases ||
@@ -631,24 +633,24 @@ function createContractProvider(resolution, opts = {}) {
                     if (call.args.length > 1) {
                         throw new Error("Permission denied: tool runs accept a single argument when host context is forwarded");
                     }
-                    const base = resolution.toolContext ?? {
-                        dataContextId: context.dataContext?.dataContextId ?? "",
+                    const { workflow: _inheritedWorkflow, ...base } = resolution.toolContext ?? {
+                        dataContextId: caller.dataContext?.dataContextId ?? "",
                         getVariable: async () => {
                             throw new Error("Persistent variables are not available to this contract tool");
                         },
                     };
                     const dispatchTool = (frame) => async (target, args) => {
                         if (target.dataContextId &&
-                            target.dataContextId !== context.dataContext?.dataContextId)
+                            target.dataContextId !== caller.dataContext?.dataContextId)
                             throw new Error("Cross-context action dispatch is denied");
                         if (target.targetDeviceId)
                             throw new Error("Strict delegated calls cannot target another device until authority transport is supported");
-                        if (!context.dataContext || !frame.userId)
+                        if (!caller.dataContext || !frame.userId)
                             throw new Error("Missing trusted execution context");
                         if (!opts.dispatchTool)
                             throw new Error("Runtime tool dispatch is unavailable");
                         return opts.dispatchTool(target, args, {
-                            ...context,
+                            ...caller,
                             authority: (0, action_dispatch_1.narrowActionPrincipal)(frame, true),
                         });
                     };
@@ -659,16 +661,17 @@ function createContractProvider(resolution, opts = {}) {
                             throw new Error(`Unknown action selector: ${name}`);
                         const actionCall = { ...call, name: target, args: [args] };
                         const actionContext = {
-                            ...context,
+                            ...caller,
                             authority: { ...frame, strictActionScope: true },
                         };
                         const checked = await assertContractToolAccess(action, actionCall, actionContext);
                         return action.toolFn(args, {
                             ...capabilities,
-                            callerPackageId: context.callerPackageId,
+                            workflow: undefined,
+                            callerPackageId: caller.callerPackageId,
                             actorUserId: checked.userId,
                             authority: checked,
-                            callContext: { ...context, authority: checked },
+                            callContext: { ...caller, authority: checked },
                             incomingCallContext: actionContext,
                             dispatchAction: checkedActionDispatcher(checked, capabilities),
                             dispatchTool: dispatchTool(checked),
@@ -676,10 +679,11 @@ function createContractProvider(resolution, opts = {}) {
                     };
                     return tool.toolFn(call.args[0], {
                         ...base,
-                        callerPackageId: context.callerPackageId,
+                        workflow: caller.callerDeviceId || caller.callerPackageId ? undefined : workflow,
+                        callerPackageId: caller.callerPackageId,
                         actorUserId: authority.userId,
-                        callContext: { ...context, authority },
-                        incomingCallContext: context,
+                        callContext: { ...caller, authority },
+                        incomingCallContext: caller,
                         dispatchTool: dispatchTool(authority),
                         authority,
                         dispatchAction: resolution.actionAliases
@@ -982,3 +986,10 @@ function createContractProviderSession(resolution, transport, opts = {}) {
         },
     };
 }
+/** Require the directly invoked host tool’s workflow in the authorized data context. */
+function requireWorkflowRunContext(toolContext, toolName) {
+    const workflow = toolContext?.workflow;
+    if (!workflow || workflow.dataContextId !== toolContext?.dataContextId)
+        throw new Error(`Tool ${toolName} requires a workflow run in the same data context`);
+    return workflow;
+}

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

@@ -23,6 +23,18 @@ export interface ILocalContractVariableRequest {
 }
 /** Host callback that resolves plaintext only inside a local provider process. */
 export type LocalContractVariableResolver = (request: ILocalContractVariableRequest) => Promise<string>;
+/**
+ * Capture synchronous bundle registrations without publishing candidate code.
+ * The returned callback replaces this context's provider resolvers only when
+ * called in the loader's guarded activation turn. Throwing evaluation discards
+ * the batch; asynchronous installation never holds a process-wide capture open.
+ * Package resolvers always require an owning context and cannot change system
+ * signed-out routing or another package's implementation.
+ * @internal
+ */
+export declare function stagePackageContractResolvers(dataContext: DataContext, providerPackageId: string, evaluate: () => void): () => void;
+/** Retire one context's host resolver code without changing catalog history. @internal */
+export declare function unregisterPackageContractResolvers(dataContext: DataContext, providerPackageId: string): void;
 /** Options for a provider-scoped {@link registerContractResolver} registration. */
 export interface IContractResolverRegistrationOptions {
     /**
@@ -43,6 +55,8 @@ export type ContractRemoteIdentity = Pick<IDeviceInfo, "deviceId" | "userId" | "
  * 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).
+ * During PackageLoader bundle evaluation, registration is staged for activation
+ * in the owning context; direct runtime registrations remain process-wide.
  */
 export declare function registerContractResolver(contractId: string, version: number, resolver: ContractResolver, opts?: IContractResolverRegistrationOptions): void;
 /**
@@ -52,8 +66,10 @@ export declare function registerContractResolver(contractId: string, version: nu
  * 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.
+ * Supplying `dataContext` first checks host packages activated in that context.
+ * Their staged registrations never replace global system/compatibility resolvers.
  */
-export declare function getContractResolver(contractId: string, version: number, providerPackageId?: string): ContractResolver | undefined;
+export declare function getContractResolver(contractId: string, version: number, providerPackageId?: string, dataContext?: DataContext): ContractResolver | undefined;
 /**
  * Verify that a connection- or message-authenticated remote identity matches a valid
  * self-signed Users record in the provider's personal or shared-group data.
@@ -73,6 +89,8 @@ export declare function verifyRemoteContractIdentity(userContext: UserContext, r
  * {@link TrustLevel.Self}. Unsigned discovery stubs and key mismatches fail closed.
  */
 export declare function isSelfTrustedContractCaller(userContext: UserContext, remoteIdentity: ContractRemoteIdentity): Promise<boolean>;
+/** Whether a contract must remain on the local host, including Device Operations targets. */
+export declare function isLocalOnlyContractId(contractId: string): boolean;
 /**
  * Authorize one inbound contract call from **another device**.
  *
@@ -87,7 +105,7 @@ export declare function isSelfTrustedContractCaller(userContext: UserContext, re
  *    group the provider belongs to, must be a tool run, the contract definition registered
  *    for that group must mark the tool with {@link IContractTool.remoteAccessLevel}, and
  *    the caller's role in that group must meet it. Missing loader, definition, or level
- *    fails closed.
+ *    fails closed. Catalog readiness precedes reading the group's definitions.
  *
  * @param call Inbound call.
  * @param userContext Provider's user context.
@@ -102,7 +120,8 @@ export declare function authorizeRemoteContractCall(call: IContractCall, userCon
  * deferred until each call. This prevents renderer startup from racing provider
  * registration. Calls may target only the local user's personal context or a
  * currently known group context; arbitrary valid IDs are rejected before
- * `UserContext.getDataContext` can create a new context.
+ * `UserContext.getDataContext` can create a new context. Provider selection waits
+ * for catalog readiness, including explicit provider requests on a cold context.
  *
  * Contracts registered with `requiresUserContext: false` resolve before sign-in
  * when `peekUserContext` reports that no user is loaded. Every other call still