@camstack/system 1.2.389 → 1.2.391

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

@@ -1,168 +1,168 @@
 /**
- * Discriminated union describing HOW a capName call should be dispatched.
- * Every variant carries `capName` so a resolved route is a self-contained
- * dispatch descriptor.  `method` is a dispatch-time concern supplied separately
- * to the dispatcher — it does not belong on the route.
- *
- * This file is intentionally import-free — no broker/registry deps — so it can
- * be imported from both the hub and agent without pulling the full kernel graph.
- */
+* Discriminated union describing HOW a capName call should be dispatched.
+* Every variant carries `capName` so a resolved route is a self-contained
+* dispatch descriptor.  `method` is a dispatch-time concern supplied separately
+* to the dispatcher — it does not belong on the route.
+*
+* This file is intentionally import-free — no broker/registry deps — so it can
+* be imported from both the hub and agent without pulling the full kernel graph.
+*/
 export interface CapRouteBase {
-    readonly capName: string;
+	readonly capName: string;
 }
 /**
- * A typed thunk that invokes a method on a provider that lives in the current
- * process. Using an invoker thunk instead of a raw `object` avoids `as`-casts
- * at every dispatch site: the resolver builds the thunk once (knowing the
- * provider's concrete type), and every consumer calls `ref.invoke(method, args)`
- * without any type assertion.
- */
+* A typed thunk that invokes a method on a provider that lives in the current
+* process. Using an invoker thunk instead of a raw `object` avoids `as`-casts
+* at every dispatch site: the resolver builds the thunk once (knowing the
+* provider's concrete type), and every consumer calls `ref.invoke(method, args)`
+* without any type assertion.
+*/
 export type CapInvoker = (method: string, args: unknown) => Promise<unknown>;
 export interface InProcessProviderRef {
-    readonly invoke: CapInvoker;
+	readonly invoke: CapInvoker;
 }
 export interface HubInProcessRoute extends CapRouteBase {
-    readonly kind: 'hub-in-process';
-    readonly ref: InProcessProviderRef;
+	readonly kind: "hub-in-process";
+	readonly ref: InProcessProviderRef;
 }
 export interface HubLocalUdsRoute extends CapRouteBase {
-    readonly kind: 'hub-local-uds';
-    readonly childId: string;
+	readonly kind: "hub-local-uds";
+	readonly childId: string;
 }
 export interface RemoteMoleculerRoute extends CapRouteBase {
-    readonly kind: 'remote-moleculer';
-    readonly nodeId: string;
+	readonly kind: "remote-moleculer";
+	readonly nodeId: string;
 }
 export interface AgentChildForwardRoute extends CapRouteBase {
-    readonly kind: 'agent-child-forward';
-    readonly agentNodeId: string;
-    /** Optional: the hub cannot resolve which forked child under an agent provides the cap.
-     * The agent resolves its own child locally (Task 6). */
-    readonly childId?: string;
+	readonly kind: "agent-child-forward";
+	readonly agentNodeId: string;
+	/** Optional: the hub cannot resolve which forked child under an agent provides the cap.
+	* The agent resolves its own child locally (Task 6). */
+	readonly childId?: string;
 }
 export type CapRoute = HubInProcessRoute | HubLocalUdsRoute | RemoteMoleculerRoute | AgentChildForwardRoute;
-export type CapRouteReason = 'no-provider' | 'node-offline' | 'cap-unknown' | 'transport-failed';
+export type CapRouteReason = "no-provider" | "node-offline" | "cap-unknown" | "transport-failed";
 export interface RejectedRoute {
-    readonly kind: string;
-    readonly why: string;
+	readonly kind: string;
+	readonly why: string;
 }
 export interface CapRouteErrorDetail {
-    readonly reason: CapRouteReason;
-    readonly nodeId?: string;
-    readonly rejected: readonly RejectedRoute[];
+	readonly reason: CapRouteReason;
+	readonly nodeId?: string;
+	readonly rejected: readonly RejectedRoute[];
 }
 export declare class CapRouteError extends Error {
-    readonly reason: CapRouteReason;
-    readonly nodeId: string | undefined;
-    readonly rejected: readonly RejectedRoute[];
-    /**
-     * @param cause  Optional original error that triggered this routing failure.
-     *               Stored as `Error.cause` (TC39 standard option, Node 16.9+).
-     *               Dispatchers wrapping transport errors MUST pass the original.
-     */
-    constructor(capName: string, method: string | undefined, detail: CapRouteErrorDetail, cause?: Error);
+	readonly reason: CapRouteReason;
+	readonly nodeId: string | undefined;
+	readonly rejected: readonly RejectedRoute[];
+	/**
+	* @param cause  Optional original error that triggered this routing failure.
+	*               Stored as `Error.cause` (TC39 standard option, Node 16.9+).
+	*               Dispatchers wrapping transport errors MUST pass the original.
+	*/
+	constructor(capName: string, method: string | undefined, detail: CapRouteErrorDetail, cause?: Error);
 }
 /**
- * A read-only snapshot of the registry state needed to classify a route.
- * All fields are predicates or accessors — no live broker/registry deps.
- *
- * `getInProcessProviderRef` is OPTIONAL: the plan's table-driven test literal
- * omits it because none of the 4 plan cases hit the hub-in-process branch.
- * When present, the function calls it; when absent (or returns null), the
- * hub-in-process branch falls through to a `no-provider` CapRouteError instead
- * of using an unsafe cast.  This keeps the union type-safe without casts.
- *
- * `listKnownNodeIds` is OPTIONAL: used for singleton resolution (no nodeId
- * given) to find a remote node that knows the cap. When absent, remote
- * singleton resolution is skipped (no remote-moleculer route for singletons).
- *
- * `getHubLocalChildId` is OPTIONAL: resolves the runner childId of the
- * hub-local child that provides this cap. When absent or returns null, the
- * hub-local-uds branch falls through to a `no-provider` CapRouteError.
- *
- * `getAgentChildId` is OPTIONAL: resolves the runner childId of the agent's
- * child that provides this cap. When absent or returns null, the
- * agent-child-forward branch falls through to a `no-provider` CapRouteError.
- */
+* A read-only snapshot of the registry state needed to classify a route.
+* All fields are predicates or accessors — no live broker/registry deps.
+*
+* `getInProcessProviderRef` is OPTIONAL: the plan's table-driven test literal
+* omits it because none of the 4 plan cases hit the hub-in-process branch.
+* When present, the function calls it; when absent (or returns null), the
+* hub-in-process branch falls through to a `no-provider` CapRouteError instead
+* of using an unsafe cast.  This keeps the union type-safe without casts.
+*
+* `listKnownNodeIds` is OPTIONAL: used for singleton resolution (no nodeId
+* given) to find a remote node that knows the cap. When absent, remote
+* singleton resolution is skipped (no remote-moleculer route for singletons).
+*
+* `getHubLocalChildId` is OPTIONAL: resolves the runner childId of the
+* hub-local child that provides this cap. When absent or returns null, the
+* hub-local-uds branch falls through to a `no-provider` CapRouteError.
+*
+* `getAgentChildId` is OPTIONAL: resolves the runner childId of the agent's
+* child that provides this cap. When absent or returns null, the
+* agent-child-forward branch falls through to a `no-provider` CapRouteError.
+*/
 export interface CapRouteSnapshot {
-    /** The nodeId that represents the hub itself in the mesh. */
-    readonly hubNodeId: string;
-    /**
-     * Returns true if a hub-local UDS child process provides this cap.
-     * The optional `deviceId` is a routing hint for device-scoped native caps:
-     * a child that owns only a specific device's cap will match on (capName, deviceId)
-     * while a singleton provider (no deviceId on the descriptor) matches on capName alone.
-     */
-    readonly hubLocalChildProvides: (cap: string, deviceId?: number) => boolean;
-    /** Returns true if the hub host process provides this cap in-process. */
-    readonly hubInProcessProvides: (cap: string) => boolean;
-    /** Returns true if the given node knows (registers) the given cap. */
-    readonly nodeKnowsCap: (nodeId: string, cap: string) => boolean;
-    /** Returns true if the given nodeId is an agent node (not a hub-local child). */
-    readonly nodeIsAgent: (nodeId: string) => boolean;
-    /** Returns true if the given node is currently online/reachable. */
-    readonly nodeOnline: (nodeId: string) => boolean;
-    /**
-     * Optional: resolves a concrete InProcessProviderRef for an in-process cap.
-     * Required to actually produce a HubInProcessRoute.  When absent or returns
-     * null, classifyCapRoute throws no-provider rather than casting.
-     */
-    readonly getInProcessProviderRef?: (cap: string) => InProcessProviderRef | null;
-    /**
-     * Optional NODE-ACCURATE variant of `hubInProcessProvides`, consulted ONLY
-     * for an EXPLICIT hub pin (`opts.nodeId === hubNodeId`). Returns true only
-     * when a provider physically resident on the hub node exists.
-     *
-     * Rationale: `hubInProcessProvides` may be backed by the cluster-elected
-     * ACTIVE singleton — which can be a REMOTE-proxy provider registered in the
-     * hub registry. That is correct for UNPINNED dispatch (election adherence)
-     * but must NOT satisfy an explicit `nodePin('hub')`: dispatching the remote
-     * proxy as "hub-in-process" silently executes the call on another node
-     * (the shm frame-plane cross-node decoder-session storm). When absent,
-     * classifyExplicitNode falls back to `hubInProcessProvides` (legacy).
-     */
-    readonly hubResidentProvides?: (cap: string) => boolean;
-    /**
-     * Optional: resolves the InProcessProviderRef of a HUB-RESIDENT provider
-     * (paired with `hubResidentProvides` — same node-accuracy contract). Used
-     * instead of `getInProcessProviderRef` when `hubResidentProvides` is set.
-     */
-    readonly getHubResidentProviderRef?: (cap: string) => InProcessProviderRef | null;
-    /**
-     * Optional: enumerates all known remote nodeIds for singleton cap resolution
-     * (the case where no explicit nodeId is given by the caller).
-     */
-    readonly listKnownNodeIds?: () => readonly string[];
-    /**
-     * Optional: resolves the runner childId of the hub-local child that provides this cap.
-     * The optional `deviceId` is a routing hint for device-scoped native caps (same semantics
-     * as `hubLocalChildProvides`).
-     */
-    readonly getHubLocalChildId?: (cap: string, deviceId?: number) => string | null;
-    /** Optional: resolves the runner childId of the agent's child that provides this cap. */
-    readonly getAgentChildId?: (agentNodeId: string, cap: string) => string | null;
+	/** The nodeId that represents the hub itself in the mesh. */
+	readonly hubNodeId: string;
+	/**
+	* Returns true if a hub-local UDS child process provides this cap.
+	* The optional `deviceId` is a routing hint for device-scoped native caps:
+	* a child that owns only a specific device's cap will match on (capName, deviceId)
+	* while a singleton provider (no deviceId on the descriptor) matches on capName alone.
+	*/
+	readonly hubLocalChildProvides: (cap: string, deviceId?: number) => boolean;
+	/** Returns true if the hub host process provides this cap in-process. */
+	readonly hubInProcessProvides: (cap: string) => boolean;
+	/** Returns true if the given node knows (registers) the given cap. */
+	readonly nodeKnowsCap: (nodeId: string, cap: string) => boolean;
+	/** Returns true if the given nodeId is an agent node (not a hub-local child). */
+	readonly nodeIsAgent: (nodeId: string) => boolean;
+	/** Returns true if the given node is currently online/reachable. */
+	readonly nodeOnline: (nodeId: string) => boolean;
+	/**
+	* Optional: resolves a concrete InProcessProviderRef for an in-process cap.
+	* Required to actually produce a HubInProcessRoute.  When absent or returns
+	* null, classifyCapRoute throws no-provider rather than casting.
+	*/
+	readonly getInProcessProviderRef?: (cap: string) => InProcessProviderRef | null;
+	/**
+	* Optional NODE-ACCURATE variant of `hubInProcessProvides`, consulted ONLY
+	* for an EXPLICIT hub pin (`opts.nodeId === hubNodeId`). Returns true only
+	* when a provider physically resident on the hub node exists.
+	*
+	* Rationale: `hubInProcessProvides` may be backed by the cluster-elected
+	* ACTIVE singleton — which can be a REMOTE-proxy provider registered in the
+	* hub registry. That is correct for UNPINNED dispatch (election adherence)
+	* but must NOT satisfy an explicit `nodePin('hub')`: dispatching the remote
+	* proxy as "hub-in-process" silently executes the call on another node
+	* (the shm frame-plane cross-node decoder-session storm). When absent,
+	* classifyExplicitNode falls back to `hubInProcessProvides` (legacy).
+	*/
+	readonly hubResidentProvides?: (cap: string) => boolean;
+	/**
+	* Optional: resolves the InProcessProviderRef of a HUB-RESIDENT provider
+	* (paired with `hubResidentProvides` — same node-accuracy contract). Used
+	* instead of `getInProcessProviderRef` when `hubResidentProvides` is set.
+	*/
+	readonly getHubResidentProviderRef?: (cap: string) => InProcessProviderRef | null;
+	/**
+	* Optional: enumerates all known remote nodeIds for singleton cap resolution
+	* (the case where no explicit nodeId is given by the caller).
+	*/
+	readonly listKnownNodeIds?: () => readonly string[];
+	/**
+	* Optional: resolves the runner childId of the hub-local child that provides this cap.
+	* The optional `deviceId` is a routing hint for device-scoped native caps (same semantics
+	* as `hubLocalChildProvides`).
+	*/
+	readonly getHubLocalChildId?: (cap: string, deviceId?: number) => string | null;
+	/** Optional: resolves the runner childId of the agent's child that provides this cap. */
+	readonly getAgentChildId?: (agentNodeId: string, cap: string) => string | null;
 }
 export interface CapRouteOpts {
-    readonly nodeId?: string;
-    /** Numeric device id — a routing hint for device-scoped native caps. */
-    readonly deviceId?: number;
+	readonly nodeId?: string;
+	/** Numeric device id — a routing hint for device-scoped native caps. */
+	readonly deviceId?: number;
 }
 /**
- * Classifies a (capName, opts) pair into a typed CapRoute dispatch descriptor.
- *
- * Precedence (explicit nodeId path):
- *   1. hub-in-process — hub node + hubInProcessProvides
- *   2. hub-local-uds  — hub node + hubLocalChildProvides
- *   3. node-offline   → CapRouteError{reason:'node-offline'}
- *   4. agent-child-forward — node is an agent AND nodeKnowsCap
- *   5. remote-moleculer — any other online non-agent node
- *
- * Singleton path (no nodeId):
- *   1. hub-in-process (hub provides in-process)
- *   2. hub-local-uds  (a hub-local UDS child provides it)
- *   3. remote-moleculer (any online, non-hub node that knows it)
- *   4. → CapRouteError{reason:'no-provider', rejected: all considered routes}
- *
- * PURE: no side effects, no async, no broker/registry imports.
- */
+* Classifies a (capName, opts) pair into a typed CapRoute dispatch descriptor.
+*
+* Precedence (explicit nodeId path):
+*   1. hub-in-process — hub node + hubInProcessProvides
+*   2. hub-local-uds  — hub node + hubLocalChildProvides
+*   3. node-offline   → CapRouteError{reason:'node-offline'}
+*   4. agent-child-forward — node is an agent AND nodeKnowsCap
+*   5. remote-moleculer — any other online non-agent node
+*
+* Singleton path (no nodeId):
+*   1. hub-in-process (hub provides in-process)
+*   2. hub-local-uds  (a hub-local UDS child provides it)
+*   3. remote-moleculer (any online, non-hub node that knows it)
+*   4. → CapRouteError{reason:'no-provider', rejected: all considered routes}
+*
+* PURE: no side effects, no async, no broker/registry imports.
+*/
 export declare function classifyCapRoute(capName: string, opts: CapRouteOpts, snapshot: CapRouteSnapshot): CapRoute;

package/dist/kernel/transport/cap-routing-hints.d.ts

@@ -1,42 +1,42 @@
 /**
- * The routing facts a parent reads OUT OF a cap call's args.
- *
- * `LocalChildRegistry` routes a child's `cap-call-out` on things it used to
- * read straight out of `args`: an inline `nodeId` (the historical per-call
- * node pin — `extractNodeId`), an `addonId` selector on a global collection
- * cap (`addonPinOf`), and — since D595 — the `provider` pin of a DEVICE
- * collection with the `deviceId` it applies to (`devicePinOf`). Under
- * raw-forward the parent never decodes `args`, so the SENDER lifts these
- * fields into the envelope, and the parent routes on the lifted copy in both
- * modes — one code path, whichever way the args travelled.
- *
- * ## Why `provider` and `deviceId` had to join them
- *
- * A field this envelope does not carry is a field the routing DECISION cannot
- * see, and that decision runs BEFORE `onUnownedCall`. D594 taught
- * `onUnownedCall` to honour a `{ provider }` pin on `videoclips` and wired
- * `isAddonPinnedCall` to recognise it — but `isAddonPinnedCall` is handed
- * THESE hints, not the args, so the predicate saw `{}`, answered false, and
- * the call was short-circuited to a sibling before the handler it was written
- * for could run. Correct and unreachable: the exact failure `addonPinOf`'s
- * own docblock records for the first attempt at the `addonId` fix, reproduced
- * a month later on the same shape (2026-09-22).
- *
- * `deviceId` rides along because a device pin is meaningless without it —
- * `provider` alone cannot say WHICH device's sources to narrow, and a pin that
- * cannot be resolved is not a pin.
- *
- * Only top-level scalar fields are lifted, which is exactly what the readers
- * ever looked at. Nothing else about the args is visible to the parent under
- * raw-forward, and that is the point.
- */
+* The routing facts a parent reads OUT OF a cap call's args.
+*
+* `LocalChildRegistry` routes a child's `cap-call-out` on things it used to
+* read straight out of `args`: an inline `nodeId` (the historical per-call
+* node pin — `extractNodeId`), an `addonId` selector on a global collection
+* cap (`addonPinOf`), and — since D595 — the `provider` pin of a DEVICE
+* collection with the `deviceId` it applies to (`devicePinOf`). Under
+* raw-forward the parent never decodes `args`, so the SENDER lifts these
+* fields into the envelope, and the parent routes on the lifted copy in both
+* modes — one code path, whichever way the args travelled.
+*
+* ## Why `provider` and `deviceId` had to join them
+*
+* A field this envelope does not carry is a field the routing DECISION cannot
+* see, and that decision runs BEFORE `onUnownedCall`. D594 taught
+* `onUnownedCall` to honour a `{ provider }` pin on `videoclips` and wired
+* `isAddonPinnedCall` to recognise it — but `isAddonPinnedCall` is handed
+* THESE hints, not the args, so the predicate saw `{}`, answered false, and
+* the call was short-circuited to a sibling before the handler it was written
+* for could run. Correct and unreachable: the exact failure `addonPinOf`'s
+* own docblock records for the first attempt at the `addonId` fix, reproduced
+* a month later on the same shape (2026-09-22).
+*
+* `deviceId` rides along because a device pin is meaningless without it —
+* `provider` alone cannot say WHICH device's sources to narrow, and a pin that
+* cannot be resolved is not a pin.
+*
+* Only top-level scalar fields are lifted, which is exactly what the readers
+* ever looked at. Nothing else about the args is visible to the parent under
+* raw-forward, and that is the point.
+*/
 export interface CapRoutingHints {
-    readonly nodeId?: string;
-    readonly addonId?: string;
-    /** The `{ provider }` pin of a device-collection cap (D554, D594). */
-    readonly provider?: string;
-    /** The device that pin applies to. Lifted with it, never without it. */
-    readonly deviceId?: number;
+	readonly nodeId?: string;
+	readonly addonId?: string;
+	/** The `{ provider }` pin of a device-collection cap (D554, D594). */
+	readonly provider?: string;
+	/** The device that pin applies to. Lifted with it, never without it. */
+	readonly deviceId?: number;
 }
 /** Lift {@link CapRoutingHints} from a call's args. Never throws. */
 export declare function liftRoutingHints(args: unknown): CapRoutingHints;