@camstack/system 1.2.390 → 1.2.391

package/dist/kernel/transport/cap-child-index.d.ts

@@ -1,49 +1,49 @@
-import { ChildCapDescriptor } from './child-cap-protocol.js';
+import type { ChildCapDescriptor } from "./child-cap-protocol.js";
 /**
- * One connected child as the index reads it: its id and the cap manifest it
- * registered. A structural subset of `LocalChildRegistry`'s own child entry,
- * so the index can be built from `children.values()` directly and unit-tested
- * without a socket.
- */
+* One connected child as the index reads it: its id and the cap manifest it
+* registered. A structural subset of `LocalChildRegistry`'s own child entry,
+* so the index can be built from `children.values()` directly and unit-tested
+* without a socket.
+*/
 export interface CapIndexEntry {
-    readonly childId: string;
-    readonly caps: readonly ChildCapDescriptor[];
+	readonly childId: string;
+	readonly caps: readonly ChildCapDescriptor[];
 }
 /**
- * The two questions `resolveChildId` asks, answered in O(1).
- *
- * Deliberately NOT "resolve a child": the operator's `setActiveSingleton`
- * preference is read at CALL time from the capability registry and can change
- * without any child connecting or leaving, so the index must not be allowed to
- * hold an answer that depends on it. It holds only what the `children` map
- * says, which is the same thing that invalidates it.
- */
+* The two questions `resolveChildId` asks, answered in O(1).
+*
+* Deliberately NOT "resolve a child": the operator's `setActiveSingleton`
+* preference is read at CALL time from the capability registry and can change
+* without any child connecting or leaving, so the index must not be allowed to
+* hold an answer that depends on it. It holds only what the `children` map
+* says, which is the same thing that invalidates it.
+*/
 export interface CapChildIndex {
-    /** The FIRST child owning the exact `(capName, deviceId)` pair, or null. */
-    deviceOwner(capName: string, deviceId: number): string | null;
-    /**
-     * Every child owning a deviceId-LESS descriptor for `capName`, in children
-     * insertion order (so `[0]` is the first-registered), each named once.
-     */
-    singletonCandidates(capName: string): readonly string[];
+	/** The FIRST child owning the exact `(capName, deviceId)` pair, or null. */
+	deviceOwner(capName: string, deviceId: number): string | null;
+	/**
+	* Every child owning a deviceId-LESS descriptor for `capName`, in children
+	* insertion order (so `[0]` is the first-registered), each named once.
+	*/
+	singletonCandidates(capName: string): readonly string[];
 }
 /**
- * Build the `(cap, device?) → child` index from the connected children.
- *
- * A PURE function of what it is handed — it captures nothing, subscribes to
- * nothing and cannot be updated in place. That is the whole safety argument
- * (D3, D457): the only way to change what it says is to build a new one from
- * the `children` map, so an index can never name a child that map has already
- * dropped. An incremental index — add on register, remove on close — would be
- * a second registry that can disagree with the first, and a stale one routes
- * to a dead runner, which is strictly worse than a slow scan.
- *
- * Cost: O(children × descriptors), paid once per mutation of the children map
- * (a register, a re-register, a disconnect) rather than once per cap call.
- *
- * The two tiers stay separate, exactly as the scan had them: a device lookup
- * is never answered from a deviceId-less descriptor. `resolveChildId` owns
- * the fallback from tier 1 to tier 2, and folding it in here would make it
- * unreachable.
- */
+* Build the `(cap, device?) → child` index from the connected children.
+*
+* A PURE function of what it is handed — it captures nothing, subscribes to
+* nothing and cannot be updated in place. That is the whole safety argument
+* (D3, D457): the only way to change what it says is to build a new one from
+* the `children` map, so an index can never name a child that map has already
+* dropped. An incremental index — add on register, remove on close — would be
+* a second registry that can disagree with the first, and a stale one routes
+* to a dead runner, which is strictly worse than a slow scan.
+*
+* Cost: O(children × descriptors), paid once per mutation of the children map
+* (a register, a re-register, a disconnect) rather than once per cap call.
+*
+* The two tiers stay separate, exactly as the scan had them: a device lookup
+* is never answered from a deviceId-less descriptor. `resolveChildId` owns
+* the fallback from tier 1 to tier 2, and folding it in here would make it
+* unreachable.
+*/
 export declare function buildCapChildIndex(entries: Iterable<CapIndexEntry>): CapChildIndex;

package/dist/kernel/transport/cap-route-resolver.d.ts

@@ -1,235 +1,260 @@
-import { ServiceDiscoveryBroker } from '../moleculer/resilient-cap-call.js';
-import { CapRoute, CapRouteOpts, HubLocalUdsRoute, InProcessProviderRef } from './cap-route.js';
-import { CapCallInput } from './child-cap-protocol.js';
 /**
- * Minimal surface of LocalChildRegistry that the resolver needs.
- * Keeping a narrow interface here prevents the resolver from depending on the
- * full LocalChildRegistry class and avoids `as unknown as` casts in tests.
- * The real `LocalChildRegistry` structurally satisfies this interface.
- */
+* CapRouteResolver — builds a live CapRouteSnapshot from injected deps and
+* dispatches a resolved CapRoute to the appropriate transport.
+*
+* Layer boundary: this file lives in `@camstack/kernel` and MUST NOT import
+* from `server/backend`. All server-side state is injected via narrow named
+* interfaces (NodeCapAuthority, InProcessProviderLookup, BrokerHandle).
+*
+* Wire conventions (kept here as the single source of truth):
+*
+*   remote-moleculer dispatch
+*     action  : `${addonId}.${capName}.${method}`
+*     params  : methodArgs (passed through)
+*     options : { nodeID: route.nodeId, timeout: 60_000 }
+*     note    : addonId is resolved by NodeCapAuthority.getAddonId(nodeId, cap)
+*
+*   agent-child-forward dispatch
+*     service : `$agent-cap-fwd`
+*     action  : `$agent-cap-fwd.forward`
+*     params  : { capName, method, args, childId, deviceId? }
+*     options : { nodeID: route.agentNodeId, timeout: 60_000 }
+*     note    : Task 6's agent-side service MUST register the Moleculer service
+*               `$agent-cap-fwd` with action `forward` that accepts this shape
+*               and fans the call over UDS to route.childId.
+*/
+import type { ServiceDiscoveryBroker } from "../moleculer/resilient-cap-call.js";
+import type { CapRoute, CapRouteOpts, HubLocalUdsRoute, InProcessProviderRef } from "./cap-route.js";
+import type { CapCallInput } from "./child-cap-protocol.js";
+/**
+* Minimal surface of LocalChildRegistry that the resolver needs.
+* Keeping a narrow interface here prevents the resolver from depending on the
+* full LocalChildRegistry class and avoids `as unknown as` casts in tests.
+* The real `LocalChildRegistry` structurally satisfies this interface.
+*/
 export interface HubLocalChildDispatcher {
-    /** Returns the childId that provides the cap, or null. */
-    resolveChildId(capName: string, deviceId?: number): string | null;
-    /** Forwards a cap call to a specific child by id. */
-    callCapOnChild(childId: string, input: CapCallInput): Promise<unknown>;
+	/** Returns the childId that provides the cap, or null. */
+	resolveChildId(capName: string, deviceId?: number): string | null;
+	/** Forwards a cap call to a specific child by id. */
+	callCapOnChild(childId: string, input: CapCallInput): Promise<unknown>;
 }
 /**
- * Minimal view of the cluster node registry needed to build a CapRouteSnapshot.
- * The concrete implementation (HubNodeRegistry) lives in server/backend and is
- * wired in by Task 4/5. Keeping this interface in kernel prevents a layering
- * inversion.
- */
+* Minimal view of the cluster node registry needed to build a CapRouteSnapshot.
+* The concrete implementation (HubNodeRegistry) lives in server/backend and is
+* wired in by Task 4/5. Keeping this interface in kernel prevents a layering
+* inversion.
+*/
 export interface NodeCapAuthority {
-    /** Returns true if the given node's latest manifest includes the given cap. */
-    nodeKnowsCap(nodeId: string, capName: string): boolean;
-    /** Returns true if the given nodeId is an agent (bare id, no '/' separator). */
-    nodeIsAgent(nodeId: string): boolean;
-    /** Returns true if the given node is currently connected/online. */
-    nodeOnline(nodeId: string): boolean;
-    /** Returns all nodeIds currently in the registry. */
-    listNodeIds(): readonly string[];
-    /**
-     * Returns the addonId for the provider that registered (nodeId, capName).
-     * Used to build the Moleculer action `${addonId}.${capName}.${method}`.
-     * Returns null when the node does not host the cap (should not happen if
-     * nodeKnowsCap is true, but guard defensively).
-     */
-    getAddonId(nodeId: string, capName: string): string | null;
-    /**
-     * Returns the childId (runner id) of the agent's UDS child that provides
-     * the given cap. Only meaningful when nodeIsAgent(nodeId) is true.
-     * Returns null when unknown.
-     */
-    getAgentChildId(agentNodeId: string, capName: string): string | null;
-    /**
-     * Returns true if the (nodeId, capName, deviceId?) tuple is a device-scoped
-     * NATIVE cap (vs. a system/manifest cap). When true, the remote-moleculer
-     * dispatcher uses `capActionName(addonId, cap, method, true)` which expands to
-     * `${addonId}.native-provider.${cap}.${method}` instead of the plain system-cap
-     * action `${addonId}.${cap}.${method}`.
-     * Implementations that do not track native caps should return false.
-     */
-    isNativeCap(nodeId: string, capName: string, deviceId?: number): boolean;
+	/** Returns true if the given node's latest manifest includes the given cap. */
+	nodeKnowsCap(nodeId: string, capName: string): boolean;
+	/** Returns true if the given nodeId is an agent (bare id, no '/' separator). */
+	nodeIsAgent(nodeId: string): boolean;
+	/** Returns true if the given node is currently connected/online. */
+	nodeOnline(nodeId: string): boolean;
+	/** Returns all nodeIds currently in the registry. */
+	listNodeIds(): readonly string[];
+	/**
+	* Returns the addonId for the provider that registered (nodeId, capName).
+	* Used to build the Moleculer action `${addonId}.${capName}.${method}`.
+	* Returns null when the node does not host the cap (should not happen if
+	* nodeKnowsCap is true, but guard defensively).
+	*/
+	getAddonId(nodeId: string, capName: string): string | null;
+	/**
+	* Returns the childId (runner id) of the agent's UDS child that provides
+	* the given cap. Only meaningful when nodeIsAgent(nodeId) is true.
+	* Returns null when unknown.
+	*/
+	getAgentChildId(agentNodeId: string, capName: string): string | null;
+	/**
+	* Returns true if the (nodeId, capName, deviceId?) tuple is a device-scoped
+	* NATIVE cap (vs. a system/manifest cap). When true, the remote-moleculer
+	* dispatcher uses `capActionName(addonId, cap, method, true)` which expands to
+	* `${addonId}.native-provider.${cap}.${method}` instead of the plain system-cap
+	* action `${addonId}.${cap}.${method}`.
+	* Implementations that do not track native caps should return false.
+	*/
+	isNativeCap(nodeId: string, capName: string, deviceId?: number): boolean;
 }
 /**
- * Injected lookup for providers that live in the hub host process.
- * Returns a ready-to-invoke InProcessProviderRef, or null if the cap is not
- * hosted in-process.
- */
+* Injected lookup for providers that live in the hub host process.
+* Returns a ready-to-invoke InProcessProviderRef, or null if the cap is not
+* hosted in-process.
+*/
 export type InProcessProviderLookup = (capName: string) => InProcessProviderRef | null;
 export interface CapRouteResolverDeps {
-    /** The hub's own Moleculer nodeId (e.g. `'hub'`). */
-    readonly hubNodeId: string;
-    /**
-     * Minimal Moleculer broker surface: `call` + `waitForServices`.
-     * Used for remote-moleculer and agent-child-forward dispatches.
-     */
-    readonly broker: ServiceDiscoveryBroker;
-    /**
-     * Local UDS child dispatcher — routes hub-local-uds dispatches.
-     * May be null when the UDS server failed to start.
-     */
-    readonly hubLocalRegistry: HubLocalChildDispatcher | null;
-    /**
-     * Authority over which nodes are online and which caps they know.
-     * Decouples the resolver from the concrete HubNodeRegistry class.
-     */
-    readonly nodeAuthority: NodeCapAuthority;
-    /**
-     * Lookup for hub-in-process providers.
-     * Decouples the resolver from CapabilityRegistry.
-     */
-    readonly inProcessProviders: InProcessProviderLookup;
-    /**
-     * Optional NODE-ACCURATE lookup for providers physically resident on the
-     * hub node — consulted ONLY when a call is EXPLICITLY pinned to the hub.
-     * `inProcessProviders` may resolve the cluster-elected ACTIVE singleton
-     * (a remote-proxy provider registered in the hub registry), which must not
-     * satisfy a `nodePin('hub')`. See `CapRouteSnapshot.hubResidentProvides`.
-     */
-    readonly hubResidentProviders?: InProcessProviderLookup;
-    /**
-     * Per-cap-method RPC timeout (ms). Lets a long-running cap method (e.g.
-     * `model-convert.convert`, minutes) override the default 60s remote/forward
-     * timeout that would otherwise kill it mid-run. Returns undefined to use the
-     * default. Resolved from the cap definition's `methods[method].timeoutMs`.
-     */
-    readonly capTimeoutMs?: (capName: string, method: string) => number | undefined;
+	/** The hub's own Moleculer nodeId (e.g. `'hub'`). */
+	readonly hubNodeId: string;
+	/**
+	* Minimal Moleculer broker surface: `call` + `waitForServices`.
+	* Used for remote-moleculer and agent-child-forward dispatches.
+	*/
+	readonly broker: ServiceDiscoveryBroker;
+	/**
+	* Local UDS child dispatcher — routes hub-local-uds dispatches.
+	* May be null when the UDS server failed to start.
+	*/
+	readonly hubLocalRegistry: HubLocalChildDispatcher | null;
+	/**
+	* Authority over which nodes are online and which caps they know.
+	* Decouples the resolver from the concrete HubNodeRegistry class.
+	*/
+	readonly nodeAuthority: NodeCapAuthority;
+	/**
+	* Lookup for hub-in-process providers.
+	* Decouples the resolver from CapabilityRegistry.
+	*/
+	readonly inProcessProviders: InProcessProviderLookup;
+	/**
+	* Optional NODE-ACCURATE lookup for providers physically resident on the
+	* hub node — consulted ONLY when a call is EXPLICITLY pinned to the hub.
+	* `inProcessProviders` may resolve the cluster-elected ACTIVE singleton
+	* (a remote-proxy provider registered in the hub registry), which must not
+	* satisfy a `nodePin('hub')`. See `CapRouteSnapshot.hubResidentProvides`.
+	*/
+	readonly hubResidentProviders?: InProcessProviderLookup;
+	/**
+	* Per-cap-method RPC timeout (ms). Lets a long-running cap method (e.g.
+	* `model-convert.convert`, minutes) override the default 60s remote/forward
+	* timeout that would otherwise kill it mid-run. Returns undefined to use the
+	* default. Resolved from the cap definition's `methods[method].timeoutMs`.
+	*/
+	readonly capTimeoutMs?: (capName: string, method: string) => number | undefined;
 }
 /**
- * Params envelope sent to the agent's `$agent-cap-fwd.forward` Moleculer action.
- *
- * Task 6 MUST register a Moleculer service named `$agent-cap-fwd` with an
- * action `forward` that receives this payload, resolves `childId` in its own
- * LocalChildRegistry, and dispatches over UDS to that child.
- */
+* Params envelope sent to the agent's `$agent-cap-fwd.forward` Moleculer action.
+*
+* Task 6 MUST register a Moleculer service named `$agent-cap-fwd` with an
+* action `forward` that receives this payload, resolves `childId` in its own
+* LocalChildRegistry, and dispatches over UDS to that child.
+*/
 export interface AgentCapForwardParams {
-    readonly capName: string;
-    readonly method: string;
-    readonly args: unknown;
-    /**
-     * Optional: the hub cannot resolve which forked child under the agent provides the cap.
-     * The agent resolves its own child locally (Task 6). Present when the hub authority
-     * happens to know it, absent (undefined) when not.
-     */
-    readonly childId?: string;
-    readonly deviceId?: number;
-    /**
-     * Out-of-band PROVIDER-selection hint — the twin of `CapCallMessage.addonId`
-     * (Task 7.5a). A GROUPED runner (`execution.group`) on an AGENT can host two
-     * co-located addons registering the SAME collection cap, exactly like the
-     * hub-local-uds case (`LocalChildRegistry.toCapCall`'s `addonId`, threaded by
-     * `buildCapCallFn`'s hub-local branch). Before this field existed, the hub had
-     * no channel to carry the selector across the hub→agent envelope — grouped-
-     * runner provider selection worked on the hub and silently fell back to
-     * "whichever provider is first" on an agent. Absent → the agent dispatch falls
-     * back to its sole provider for the cap (same fallback `child-cap-dispatch.ts`
-     * already has for a call that never carried the hint).
-     */
-    readonly addonId?: string;
+	readonly capName: string;
+	readonly method: string;
+	readonly args: unknown;
+	/**
+	* Optional: the hub cannot resolve which forked child under the agent provides the cap.
+	* The agent resolves its own child locally (Task 6). Present when the hub authority
+	* happens to know it, absent (undefined) when not.
+	*/
+	readonly childId?: string;
+	readonly deviceId?: number;
+	/**
+	* Out-of-band PROVIDER-selection hint — the twin of `CapCallMessage.addonId`
+	* (Task 7.5a). A GROUPED runner (`execution.group`) on an AGENT can host two
+	* co-located addons registering the SAME collection cap, exactly like the
+	* hub-local-uds case (`LocalChildRegistry.toCapCall`'s `addonId`, threaded by
+	* `buildCapCallFn`'s hub-local branch). Before this field existed, the hub had
+	* no channel to carry the selector across the hub→agent envelope — grouped-
+	* runner provider selection worked on the hub and silently fell back to
+	* "whichever provider is first" on an agent. Absent → the agent dispatch falls
+	* back to its sole provider for the cap (same fallback `child-cap-dispatch.ts`
+	* already has for a call that never carried the hint).
+	*/
+	readonly addonId?: string;
 }
 /** The Moleculer service name that Task 6's agent registers. */
 export declare const AGENT_CAP_FWD_SERVICE: "$agent-cap-fwd";
 /** The Moleculer action (service.action) for agent cap forwarding. */
-export declare const AGENT_CAP_FWD_ACTION: "$agent-cap-fwd.forward";
+export declare const AGENT_CAP_FWD_ACTION: string;
 export declare function extractDeviceId(args: unknown): number | undefined;
 /**
- * Extract an inline `nodeId` string from a cap call's args — the per-call node
- * pin a forked addon expresses by carrying `nodeId` in the input (the SAME way
- * device-scoped caps carry `deviceId`, and the way the generated cap-router on
- * the hub already honours an inline pin). Mirrors {@link extractDeviceId}.
- *
- * This is the routing source for hub→remote-node EXECUTION pinning (e.g. the
- * benchmark addon running a synthetic/decoder workload ON a chosen agent). The
- * out-of-band `nodePin(op.context)` path does NOT survive the forked addon →
- * hub UDS link chain, so `onUnownedCall` reads the inline pin instead. Provider
- * methods that don't declare `nodeId` simply ignore the extra field (they
- * destructure the fields they need); methods that DO declare it (e.g.
- * `getEngineProvisioning({nodeId})`) still receive it unchanged.
- */
+* Extract an inline `nodeId` string from a cap call's args — the per-call node
+* pin a forked addon expresses by carrying `nodeId` in the input (the SAME way
+* device-scoped caps carry `deviceId`, and the way the generated cap-router on
+* the hub already honours an inline pin). Mirrors {@link extractDeviceId}.
+*
+* This is the routing source for hub→remote-node EXECUTION pinning (e.g. the
+* benchmark addon running a synthetic/decoder workload ON a chosen agent). The
+* out-of-band `nodePin(op.context)` path does NOT survive the forked addon →
+* hub UDS link chain, so `onUnownedCall` reads the inline pin instead. Provider
+* methods that don't declare `nodeId` simply ignore the extra field (they
+* destructure the fields they need); methods that DO declare it (e.g.
+* `getEngineProvisioning({nodeId})`) still receive it unchanged.
+*/
 export declare function extractNodeId(args: unknown): string | undefined;
 /**
- * Stamp the CALLER identity into a cap call's args — the SAME "provider
- * destructures what it needs and ignores the rest" convention
- * {@link extractNodeId} already relies on for the inline `nodeId` pin.
- *
- * The stamp is the transport's, never the caller's (D787):
- *  - a stamp (`callerAddonId` known to the transport) OVERWRITES whatever the
- *    args carry under that key;
- *  - NO stamp STRIPS the key: a call that crossed a wire with no identity the
- *    transport can vouch for must not arrive carrying a claimed one. The
- *    keychain owner-checks on this field, and until 2026-10-08 an unstamped
- *    call let a child's own `callerAddonId` through untouched.
- *
- * A hub in-process caller never reaches this function (`localProviderLink`
- * calls the provider directly), which is the one place a stated identity is
- * trusted. A non-object `args` (or `null`/array) is returned unchanged: there
- * is nowhere to attach a key, and nowhere one could hide.
- */
+* Stamp the CALLER identity into a cap call's args — the SAME "provider
+* destructures what it needs and ignores the rest" convention
+* {@link extractNodeId} already relies on for the inline `nodeId` pin.
+*
+* The stamp is the transport's, never the caller's (D787):
+*  - a stamp (`callerAddonId` known to the transport) OVERWRITES whatever the
+*    args carry under that key;
+*  - NO stamp STRIPS the key: a call that crossed a wire with no identity the
+*    transport can vouch for must not arrive carrying a claimed one. The
+*    keychain owner-checks on this field, and until 2026-10-08 an unstamped
+*    call let a child's own `callerAddonId` through untouched.
+*
+* A hub in-process caller never reaches this function (`localProviderLink`
+* calls the provider directly), which is the one place a stated identity is
+* trusted. A non-object `args` (or `null`/array) is returned unchanged: there
+* is nowhere to attach a key, and nowhere one could hide.
+*/
 export declare function stampCallerAddonId(args: unknown, callerAddonId: string | undefined): unknown;
 export declare class CapRouteResolver {
-    private readonly hubNodeId;
-    private readonly broker;
-    private readonly hubLocalRegistry;
-    private readonly nodeAuthority;
-    private readonly inProcessProviders;
-    private readonly hubResidentProviders?;
-    private readonly capTimeoutMs?;
-    private readonly snapshot;
-    constructor(deps: CapRouteResolverDeps);
-    /** Per-call RPC timeout: the cap method's declared override, else the default. */
-    private callTimeout;
-    resolveCapRoute(capName: string, opts: CapRouteOpts): CapRoute;
-    /**
-     * Resolve the hub-local-uds route for a cap owned by a forked hub-local
-     * child, IGNORING any in-hub provider registered for the same cap name.
-     *
-     * `resolveCapRoute` gives Priority 1 to `hub-in-process`: when an in-hub
-     * provider (e.g. a wrapper) is registered for the cap, the route always
-     * classifies as `hub-in-process` and the hub-local-uds NATIVE child is never
-     * reached. That is correct for the generic dispatch path (the wrapper is the
-     * active provider), but WRONG for the native-cap fallback
-     * (`setNativeFallback`), whose contract is to reach the NATIVE provider in
-     * the forked vendor child so a wrapper can delegate to it. A wrapper cap
-     * with a forked native (today: `snapshot`) otherwise resolves to the wrapper
-     * itself, the native is never invoked, and the wrapper silently falls
-     * through to its secondary strategy.
-     *
-     * This method consults ONLY the hub-local-child authority
-     * (`hubLocalChildProvides` + `getHubLocalChildId`, both deviceId-aware), so
-     * it returns the native child route regardless of any in-process shadow.
-     * Returns null when no hub-local child owns `(capName, deviceId)` — the
-     * caller then falls through to its remote-resolution branch.
-     */
-    resolveHubLocalUdsRoute(capName: string, deviceId?: number): HubLocalUdsRoute | null;
-    /**
-     * @param addonId Optional out-of-band PROVIDER-selection hint (Task 7.5a):
-     *   the addonId of the provider the CALLER already resolved (e.g.
-     *   `buildCapCallFn`'s `deps.addonId` for a registered grouped-runner
-     *   provider). Only meaningful for `agent-child-forward` — a `remote-moleculer`
-     *   route already encodes the provider in its action name
-     *   (`${addonId}.${cap}.${method}`, via `NodeCapAuthority.getAddonId`), and a
-     *   `hub-local-uds` caller that already knows the addonId (`buildCapCallFn`)
-     *   talks to `LocalChildRegistry.callCapOnChild` directly rather than through
-     *   `dispatch`.
-     * @param callerAddonId Optional out-of-band CALLER-identity hint — the
-     *   addon that ORIGINATED the call, distinct from `addonId` above (which
-     *   names the resolved PROVIDER, not the caller). Set by
-     *   `onUnownedCall` from `CapCallInput.callerAddonId`
-     *   (`LocalChildRegistry` stamped it off the registered `childId`). Only
-     *   the `hub-in-process` branch consumes it — merged into `args` so a
-     *   diagnostic tool deep in that provider (e.g. device-manager's
-     *   fleet-read census) can read it without every provider method changing
-     *   signature, the same "extra field the provider destructures or
-     *   ignores" convention `nodeId` already uses on this path.
-     */
-    dispatch(route: CapRoute, method: string, args: unknown, addonId?: string, callerAddonId?: string): Promise<unknown>;
-    /**
-     * Inner dispatch: may throw CapRouteError (validation failures) or arbitrary
-     * transport errors. The outer `dispatch` wraps non-CapRouteErrors.
-     */
-    private dispatchInner;
-    private buildSnapshot;
-    /** Extract a nodeId string from a route for error reporting, or undefined. */
-    private routeNodeId;
+	private readonly hubNodeId;
+	private readonly broker;
+	private readonly hubLocalRegistry;
+	private readonly nodeAuthority;
+	private readonly inProcessProviders;
+	private readonly hubResidentProviders?;
+	private readonly capTimeoutMs?;
+	private readonly snapshot;
+	constructor(deps: CapRouteResolverDeps);
+	/** Per-call RPC timeout: the cap method's declared override, else the default. */
+	private callTimeout;
+	resolveCapRoute(capName: string, opts: CapRouteOpts): CapRoute;
+	/**
+	* Resolve the hub-local-uds route for a cap owned by a forked hub-local
+	* child, IGNORING any in-hub provider registered for the same cap name.
+	*
+	* `resolveCapRoute` gives Priority 1 to `hub-in-process`: when an in-hub
+	* provider (e.g. a wrapper) is registered for the cap, the route always
+	* classifies as `hub-in-process` and the hub-local-uds NATIVE child is never
+	* reached. That is correct for the generic dispatch path (the wrapper is the
+	* active provider), but WRONG for the native-cap fallback
+	* (`setNativeFallback`), whose contract is to reach the NATIVE provider in
+	* the forked vendor child so a wrapper can delegate to it. A wrapper cap
+	* with a forked native (today: `snapshot`) otherwise resolves to the wrapper
+	* itself, the native is never invoked, and the wrapper silently falls
+	* through to its secondary strategy.
+	*
+	* This method consults ONLY the hub-local-child authority
+	* (`hubLocalChildProvides` + `getHubLocalChildId`, both deviceId-aware), so
+	* it returns the native child route regardless of any in-process shadow.
+	* Returns null when no hub-local child owns `(capName, deviceId)` — the
+	* caller then falls through to its remote-resolution branch.
+	*/
+	resolveHubLocalUdsRoute(capName: string, deviceId?: number): HubLocalUdsRoute | null;
+	/**
+	* @param addonId Optional out-of-band PROVIDER-selection hint (Task 7.5a):
+	*   the addonId of the provider the CALLER already resolved (e.g.
+	*   `buildCapCallFn`'s `deps.addonId` for a registered grouped-runner
+	*   provider). Only meaningful for `agent-child-forward` — a `remote-moleculer`
+	*   route already encodes the provider in its action name
+	*   (`${addonId}.${cap}.${method}`, via `NodeCapAuthority.getAddonId`), and a
+	*   `hub-local-uds` caller that already knows the addonId (`buildCapCallFn`)
+	*   talks to `LocalChildRegistry.callCapOnChild` directly rather than through
+	*   `dispatch`.
+	* @param callerAddonId Optional out-of-band CALLER-identity hint — the
+	*   addon that ORIGINATED the call, distinct from `addonId` above (which
+	*   names the resolved PROVIDER, not the caller). Set by
+	*   `onUnownedCall` from `CapCallInput.callerAddonId`
+	*   (`LocalChildRegistry` stamped it off the registered `childId`). Only
+	*   the `hub-in-process` branch consumes it — merged into `args` so a
+	*   diagnostic tool deep in that provider (e.g. device-manager's
+	*   fleet-read census) can read it without every provider method changing
+	*   signature, the same "extra field the provider destructures or
+	*   ignores" convention `nodeId` already uses on this path.
+	*/
+	dispatch(route: CapRoute, method: string, args: unknown, addonId?: string, callerAddonId?: string): Promise<unknown>;
+	/**
+	* Inner dispatch: may throw CapRouteError (validation failures) or arbitrary
+	* transport errors. The outer `dispatch` wraps non-CapRouteErrors.
+	*/
+	private dispatchInner;
+	private buildSnapshot;
+	/** Extract a nodeId string from a route for error reporting, or undefined. */
+	private routeNodeId;
 }