@camstack/system 1.2.390 → 1.2.392

package/dist/kernel/transport/parent-unowned-call.d.ts

@@ -1,244 +1,273 @@
-import { CapCallInput } from './child-cap-protocol.js';
-import { CapRouteResolver, HubLocalChildDispatcher } from './cap-route-resolver.js';
-import { HubNodeRegistry } from '../moleculer/node-registry.js';
-import { ClaimedStatusResolver } from '../status-overlay.js';
-import { ServiceBroker } from 'moleculer';
 /**
- * Minimal logger surface accepted by the unowned-call handler. Matches the
- * `LocalChildRegistryLogger` shape so a single logger object can be shared.
- */
+* parent-unowned-call.ts — the parent-side `onUnownedCall` fallback for the
+* `LocalChildRegistry` (F0 — slice-5 outbound completion).
+*
+* When a forked child issues `ctx.api.<cap>.<method>` for a cap that NO local
+* sibling owns, the call arrives at the parent's `LocalChildRegistry` as a
+* `cap-call-out` with no local provider. Before F0 the parent threw
+* `UDS_NO_ROUTE`, and the child's tRPC chain fell through to its own
+* `brokerTransportLink` (its per-addon broker). F1+F2 removes that broker, so
+* the PARENT must route the call instead and return the result over UDS.
+*
+* Routing strategy (resolver-first, broker-fallback):
+*   1. Resolver-first — `resolver.resolveCapRoute(capName, { deviceId })` +
+*      `resolver.dispatch(...)`. This covers every REGISTERED capability:
+*      hub-in-process caps, hub-local-UDS sibling caps, remote-moleculer caps,
+*      and agent-child-forward caps. No nodeId is supplied so the resolver does
+*      singleton/wherever-it-lives resolution.
+*   2. Broker-fallback — for what the resolver returns `no-provider` on. The
+*      hub's CORE services (`$core-caps` for `system`/`addons`/`capabilities`/
+*      `nodes`/…, `$stream-probe`, `settings-store`, …) are Moleculer services
+*      NOT registered as CapabilityRegistry providers, so the resolver can't
+*      see them — but the parent keeps its broker, so `brokerCallForCap`
+*      reaches them through cluster service discovery using the SAME action
+*      naming the child's `brokerTransportLink` used.
+*
+* The agent has no `CapRouteResolver` (it routes everything to the hub over its
+* own broker), so it passes `getResolver: () => null` and relies entirely on
+* the broker fallback — the agent's broker call reaches the hub mesh.
+*/
+import type { CapCallInput } from "./child-cap-protocol.js";
+import type { CapRouteResolver, HubLocalChildDispatcher } from "./cap-route-resolver.js";
+import type { HubNodeRegistry } from "../moleculer/node-registry.js";
+import type { ClaimedStatusResolver } from "../status-overlay.js";
+import type { ServiceBroker } from "moleculer";
+/**
+* Minimal logger surface accepted by the unowned-call handler. Matches the
+* `LocalChildRegistryLogger` shape so a single logger object can be shared.
+*/
 export interface ParentUnownedCallLogger {
-    debug?(msg: string, meta?: unknown): void;
-    warn?(msg: string, meta?: unknown): void;
+	debug?(msg: string, meta?: unknown): void;
+	warn?(msg: string, meta?: unknown): void;
 }
 export interface ParentUnownedCallDeps {
-    /**
-     * Returns the parent's `CapRouteResolver` at call time, or `null` when the
-     * parent has none (the agent) or it has not been constructed yet (the hub,
-     * before `onModuleInit` finishes — the resolver is built late, so this is a
-     * live getter, not a captured value).
-     */
-    readonly getResolver: () => CapRouteResolver | null;
-    /** The parent's Moleculer broker — reaches the cluster + the hub's `$`-infra services. */
-    readonly broker: ServiceBroker;
-    /**
-     * The hub's single capability authority. Used to find the node that OWNS a
-     * device-scoped native cap so the broker-fallback can be pinned to it instead
-     * of load-balancing the call (which can hit the wrong provider).
-     */
-    readonly nodeRegistry: HubNodeRegistry;
-    /**
-     * Hub-local UDS child dispatcher (`LocalChildRegistry`). Resolves
-     * device-scoped native caps OWNED by hub-local children (reolink/hikvision
-     * cameras run as forked hub-local UDS children — they register via the hub's
-     * `LocalChildRegistry`, NOT via `registerNode`, so the `nodeRegistry` lookup
-     * is empty for them) and dispatches the call to the owning child over UDS.
-     *
-     * A live GETTER (init-order safety): on the agent the local registry is built
-     * AFTER this handler, so the instance is captured lazily. Returns null when
-     * no local registry exists (failed to start) or when not yet constructed.
-     */
-    readonly getLocalDispatcher?: () => HubLocalChildDispatcher | null;
-    /**
-     * Optional predicate — returns `true` when `capName` is a DEVICE-NATIVE cap
-     * (`deviceNative: true` in its `CapabilityDefinition`): the provider IS the
-     * device and routes ONLY over UDS / the per-node native path, never as a plain
-     * Moleculer service. The kernel layer has no cap registry, so the wiring side
-     * (which does) injects this.
-     *
-     * It gates the registration-race recovery in the broker-fallback branch: when
-     * a device-scoped call's hub-local binding is not yet in the LocalChildRegistry
-     * (`resolveChildId === null`) and no remote owner is known, the handler applies
-     * a SHORT bounded retry, then — if still unresolved AND the cap is device-native
-     * — throws a precise "binding not yet registered" error instead of attempting
-     * the unpinned `brokerCallForCap`, which can NEVER reach a device-native cap and
-     * would surface the misleading doubled `${cap}.${cap}.${method}` Moleculer error.
-     *
-     * Omitted (or returning `false`) ⇒ legacy behaviour is preserved exactly: no
-     * retry, no precise error, straight to the existing broker fallback. This keeps
-     * deviceId-carrying SYSTEM-cap calls (e.g. `system.info({deviceId})`) fast.
-     */
-    readonly isDeviceNativeCap?: (capName: string) => boolean;
-    /**
-     * Optional predicate — returns `true` when `capName` declares
-     * `nodeIdMode: 'data'` in its `CapabilityDefinition` (`addon-settings`,
-     * `addons`, `nodes`, `pipeline-orchestrator`): an inline `nodeId` in the
-     * call args is DATA for the (hub-singleton) provider, which dispatches
-     * internally — NOT a routing hint. For such caps the handler must NOT lift
-     * `args.nodeId` into a routing pin: pinning routes the call to a node with
-     * no provider for the cap (e.g. a forked addon on an agent calling
-     * `addon-settings.getGlobalSettings({addonId, nodeId})` gets pinned to
-     * `nodeId` → dead broker fallback → ServiceNotFoundError). Suppressing the
-     * pin forwards the call unpinned → singleton resolution on the hub — exactly
-     * how `settings-store` (no `nodeId` arg) already behaves. `args` pass
-     * through UNTOUCHED: the provider still reads `nodeId` as data.
-     *
-     * The kernel layer has no cap registry, so the wiring side (which does)
-     * injects this. Omitted (or returning `false`) ⇒ legacy behaviour exactly:
-     * an inline `args.nodeId` keeps pinning (benchmark, platform-probe,
-     * pipeline-runner node-pinned execution is unaffected).
-     */
-    readonly isDataNodeIdCap?: (capName: string) => boolean;
-    /**
-     * Optional forward-to-hub dispatcher (the AGENT path). When present, a cap
-     * that no agent-LOCAL child owns is forwarded to the hub's `$hub-cap-fwd`
-     * service instead of attempted via raw Moleculer service discovery
-     * (`brokerCallForCap`). This is what makes an agent's forked addon reach a
-     * HUB-hosted cap (`stream-broker`, `settings-store`, …): hub-local addon
-     * runners register NO Moleculer service, so raw discovery for `${cap}.*`
-     * 30s-deadlines. The hub side answers `$hub-cap-fwd.forward` by running the
-     * call through ITS OWN `onUnownedCall` (resolver + broker-fallback), so the
-     * agent inherits the hub's full routing. The hub itself passes this undefined
-     * (it IS the hub) and keeps the `brokerCallForCap` path for its `$`-core
-     * services. See `hub-cap-forward.ts`.
-     */
-    readonly forwardToHub?: (input: CapCallInput) => Promise<unknown>;
-    /**
-     * Optional empty-collection fast-path. Returns `[]` (an empty aggregate) when
-     * `capName` is a `mode:'collection'` cap whose `method` is array-output AND
-     * ZERO providers are registered cluster-wide; `null`/`undefined` otherwise.
-     *
-     * Why: a collection cap with no providers IS the empty collection — but with
-     * nothing registered, the resolver returns `no-provider` and the call falls
-     * to the broker fallback, which polls Moleculer service discovery for a
-     * `${cap}.${method}` service that will NEVER appear until the discovery
-     * deadline (~30s) elapses. That 30s stall hit EVERY WebRTC cold start via the
-     * provider-less `turn-provider` (`getTurnServers`). Returning `[]` up front
-     * treats a provider-less collection as the empty collection it is — instant,
-     * no discovery. A collection WITH ≥1 provider returns `null` here and routes
-     * normally (the aggregate fans out across its providers as before). The
-     * kernel layer has no cap registry, so the wiring side (which has both the
-     * `CapabilityDefinition`s and the registry) injects this.
-     */
-    readonly resolveEmptyCollection?: (capName: string, method: string) => readonly unknown[] | null;
-    /**
-     * Optional collection FAN-OUT. Returns the union of `method` across every
-     * registered provider of a `mode:'collection'` cap, or `null` when the
-     * (cap, method) pair is not an aggregated collection array-method.
-     *
-     * Why: routing resolves ONE provider (`resolveChildId` picks the
-     * first-registered child, or the singleton preference — meaningless for a
-     * collection). The hub's tRPC cap-router instead fans array methods across
-     * every provider (`concatArrayMethod`). A forked addon calling the same cap
-     * through `ctx.api` therefore saw a DIFFERENT, smaller answer than the hub's
-     * own router — and for `notification-output`, whose three providers include
-     * two that hold no targets, it saw `[]`. The Notification Center read that
-     * empty catalog as "the target was deleted" and permanently dead-lettered
-     * every notification it ever produced (2026-07-30).
-     *
-     * Skipped when the call carries an explicit `nodeId` pin — a pin must route
-     * to its node, never be answered by a cluster-wide union. The kernel layer
-     * has no cap registry, so the wiring side injects this (same shape as
-     * {@link resolveEmptyCollection}, and it shares that path's aggregation code
-     * so the two answers cannot drift).
-     */
-    readonly callCollectionAggregate?: (capName: string, method: string, args: unknown) => Promise<readonly unknown[] | null>;
-    /**
-     * Optional `{ addonId }` PIN for a collection cap's SCALAR method — the twin
-     * of {@link callCollectionAggregate}, for the same reason.
-     *
-     * On a system-scoped collection cap `addonId` is not provider data: the
-     * codegen injects it as the `{nodeId?, addonId?}` selector on every method,
-     * and the hub's tRPC cap-router routes by it. This handler lifted only
-     * `nodeId` and `deviceId` out of a child's args, so a forked addon's pin was
-     * DISCARDED IN SILENCE and the call was answered by whichever provider
-     * registered first. `broker.getBrokerConfig({id:'ha_001', addonId:'provider-
-     * homeassistant'})` therefore returned Homematic's `null` — indistinguishable
-     * from "no such broker" — and the Home Assistant export could never open a
-     * link. Every write-up that "proved the pin works" had measured the hub's
-     * tRPC surface, never this path (2026-08-09).
-     *
-     * Returns a `{ value }` box so a legitimate `null` result is distinguishable
-     * from "not a pinned collection call, route normally", and THROWS when the
-     * pin names a non-provider — a pin that silently degrades to another
-     * provider's answer is worse than no pin. Array methods are never pinned
-     * here: their contract is the union above.
-     *
-     * The kernel layer has no cap registry, so the wiring side injects this and
-     * it shares the tRPC path's provider resolution — the two must not drift.
-     */
-    readonly callPinnedCollection?: (capName: string, method: string, args: unknown) => Promise<{
-        readonly value: unknown;
-    } | null>;
-    /**
-     * Optional predicate — returns `true` when `capName` is a HUB-CORE `$`-service
-     * cap (`system`, `addons`, `nodes`, `capabilities`, `stream-probe`, …): served
-     * by the hub's `$core-caps` / `$stream-probe` Moleculer services, NOT by any
-     * addon provider. These are the ONLY legitimate consumers of the unpinned
-     * `brokerCallForCap` fallback.
-     *
-     * It generalises the per-cap patches (`isDeviceNativeCap`,
-     * `resolveEmptyCollection`) into ONE rule: for any cap the resolver misses
-     * (`no-provider`) that is NOT a core `$`-service, the unpinned broker fallback
-     * is a STRUCTURALLY DEAD path — the cap's providers are broker-less forked
-     * children that expose no Moleculer service, so discovery 30s-deadlines into
-     * the misleading `${cap}.${cap}.${method}` error. Instead the handler retries
-     * the resolver briefly (the provider registers late in the post-restart boot
-     * window) and then throws a PRECISE "not yet registered" error. A NEW
-     * multi-node addon cap is covered automatically — no allowlist entry needed —
-     * because the discriminant is the already-maintained hub-core cap set, not a
-     * per-cap flag.
-     *
-     * The kernel layer has no cap registry, so the wiring side injects it.
-     * Omitted (or returning `false` for a core cap by mistake) ⇒ legacy behaviour
-     * exactly: the miss falls straight to the broker fallback with no retry.
-     */
-    readonly isCoreServiceCap?: (capName: string) => boolean;
-    /**
-     * Resolve the per-device NATIVE provider for `(capName, deviceId)` — the
-     * `native: true` route (see {@link CapCallInput.native}).
-     *
-     * Wired to this node's `CapabilityRegistry.getNativeProvider`, which is the
-     * SINGLE authority on the question: it already covers in-process natives,
-     * hub-local UDS vendor children (through the hub's `setNativeFallback`
-     * resolver) and remote agents. Nothing here re-derives that — a rule
-     * implemented twice is a rule that drifts, and this one previously drifted
-     * into a wrapper answering on behalf of the native it was supposed to call.
-     *
-     * Returns null when no addon publishes the cap for that device. The handler
-     * then FAILS the call rather than falling back to capName routing: falling
-     * back is how a wrapper ends up calling itself.
-     *
-     * Omitted ⇒ a `native: true` call is forwarded to the hub (agents) or
-     * rejected (no forwarder) — never silently downgraded to wrapper routing.
-     */
-    readonly resolveNative?: (capName: string, deviceId: number) => Record<string, (input: unknown) => Promise<unknown>> | null;
-    /**
-     * The hub's claim authority for a device-scoped `getStatus` (D663, ruling
-     * S3). Wired to `CapabilityRegistry.resolveClaimedStatus` — the SAME question
-     * the registry's own wrappers and the other two transport entries ask, through
-     * the one shared `answerClaimedGetStatus` (`claimed-get-status.ts`).
-     *
-     * Why here: every capName-based route below dispatches STRAIGHT to the owning
-     * runner (`hub-local-uds`, `remote-moleculer`), whose `getStatus` answers the
-     * NATIVE slice. This handler is the entry for a call no co-resident sibling
-     * owns (a remote agent's device, a hub-in-process cap, the agent's forward);
-     * the sibling short-circuit in `LocalChildRegistry` and the hub's
-     * `callCapabilityOnNode` are the other two, and each asks first. When the
-     * answer is `claimed` the merged slice IS the answer (`null` for a held claim,
-     * and for a device whose claims cannot be known) and the resolver is never
-     * consulted; a node pin does not bypass it — the hub is the one claim
-     * authority wherever the device runs. `unclaimed` routes exactly as before.
-     *
-     * Omitted (the agent has no claim authority; its handler forwards to the hub
-     * for hub-hosted caps, which answer through THIS hook on the hub) ⇒ legacy
-     * routing exactly. Known gap: an agent-resident child calling `getStatus` of
-     * an agent-resident device is answered by the agent's local dispatcher with
-     * no hub round-trip, so a claim is not honoured there (D663 open item).
-     */
-    readonly claimedStatus?: ClaimedStatusResolver;
-    /** Optional logger for the broker-fallback diagnostic line. */
-    readonly logger?: ParentUnownedCallLogger;
+	/**
+	* Returns the parent's `CapRouteResolver` at call time, or `null` when the
+	* parent has none (the agent) or it has not been constructed yet (the hub,
+	* before `onModuleInit` finishes — the resolver is built late, so this is a
+	* live getter, not a captured value).
+	*/
+	readonly getResolver: () => CapRouteResolver | null;
+	/** The parent's Moleculer broker — reaches the cluster + the hub's `$`-infra services. */
+	readonly broker: ServiceBroker;
+	/**
+	* The hub's single capability authority. Used to find the node that OWNS a
+	* device-scoped native cap so the broker-fallback can be pinned to it instead
+	* of load-balancing the call (which can hit the wrong provider).
+	*/
+	readonly nodeRegistry: HubNodeRegistry;
+	/**
+	* Hub-local UDS child dispatcher (`LocalChildRegistry`). Resolves
+	* device-scoped native caps OWNED by hub-local children (reolink/hikvision
+	* cameras run as forked hub-local UDS children — they register via the hub's
+	* `LocalChildRegistry`, NOT via `registerNode`, so the `nodeRegistry` lookup
+	* is empty for them) and dispatches the call to the owning child over UDS.
+	*
+	* A live GETTER (init-order safety): on the agent the local registry is built
+	* AFTER this handler, so the instance is captured lazily. Returns null when
+	* no local registry exists (failed to start) or when not yet constructed.
+	*/
+	readonly getLocalDispatcher?: () => HubLocalChildDispatcher | null;
+	/**
+	* Optional predicate — returns `true` when `capName` is a DEVICE-NATIVE cap
+	* (`deviceNative: true` in its `CapabilityDefinition`): the provider IS the
+	* device and routes ONLY over UDS / the per-node native path, never as a plain
+	* Moleculer service. The kernel layer has no cap registry, so the wiring side
+	* (which does) injects this.
+	*
+	* It gates the registration-race recovery in the broker-fallback branch: when
+	* a device-scoped call's hub-local binding is not yet in the LocalChildRegistry
+	* (`resolveChildId === null`) and no remote owner is known, the handler applies
+	* a SHORT bounded retry, then — if still unresolved AND the cap is device-native
+	* — throws a precise "binding not yet registered" error instead of attempting
+	* the unpinned `brokerCallForCap`, which can NEVER reach a device-native cap and
+	* would surface the misleading doubled `${cap}.${cap}.${method}` Moleculer error.
+	*
+	* Omitted (or returning `false`) ⇒ legacy behaviour is preserved exactly: no
+	* retry, no precise error, straight to the existing broker fallback. This keeps
+	* deviceId-carrying SYSTEM-cap calls (e.g. `system.info({deviceId})`) fast.
+	*/
+	readonly isDeviceNativeCap?: (capName: string) => boolean;
+	/**
+	* Optional predicate — returns `true` when `capName` declares
+	* `nodeIdMode: 'data'` in its `CapabilityDefinition` (`addon-settings`,
+	* `addons`, `nodes`, `pipeline-orchestrator`): an inline `nodeId` in the
+	* call args is DATA for the (hub-singleton) provider, which dispatches
+	* internally — NOT a routing hint. For such caps the handler must NOT lift
+	* `args.nodeId` into a routing pin: pinning routes the call to a node with
+	* no provider for the cap (e.g. a forked addon on an agent calling
+	* `addon-settings.getGlobalSettings({addonId, nodeId})` gets pinned to
+	* `nodeId` → dead broker fallback → ServiceNotFoundError). Suppressing the
+	* pin forwards the call unpinned → singleton resolution on the hub — exactly
+	* how `settings-store` (no `nodeId` arg) already behaves. `args` pass
+	* through UNTOUCHED: the provider still reads `nodeId` as data.
+	*
+	* The kernel layer has no cap registry, so the wiring side (which does)
+	* injects this. Omitted (or returning `false`) ⇒ legacy behaviour exactly:
+	* an inline `args.nodeId` keeps pinning (benchmark, platform-probe,
+	* pipeline-runner node-pinned execution is unaffected).
+	*/
+	readonly isDataNodeIdCap?: (capName: string) => boolean;
+	/**
+	* Optional forward-to-hub dispatcher (the AGENT path). When present, a cap
+	* that no agent-LOCAL child owns is forwarded to the hub's `$hub-cap-fwd`
+	* service instead of attempted via raw Moleculer service discovery
+	* (`brokerCallForCap`). This is what makes an agent's forked addon reach a
+	* HUB-hosted cap (`stream-broker`, `settings-store`, …): hub-local addon
+	* runners register NO Moleculer service, so raw discovery for `${cap}.*`
+	* 30s-deadlines. The hub side answers `$hub-cap-fwd.forward` by running the
+	* call through ITS OWN `onUnownedCall` (resolver + broker-fallback), so the
+	* agent inherits the hub's full routing. The hub itself passes this undefined
+	* (it IS the hub) and keeps the `brokerCallForCap` path for its `$`-core
+	* services. See `hub-cap-forward.ts`.
+	*/
+	readonly forwardToHub?: (input: CapCallInput) => Promise<unknown>;
+	/**
+	* Optional empty-collection fast-path. Returns `[]` (an empty aggregate) when
+	* `capName` is a `mode:'collection'` cap whose `method` is array-output AND
+	* ZERO providers are registered cluster-wide; `null`/`undefined` otherwise.
+	*
+	* Why: a collection cap with no providers IS the empty collection — but with
+	* nothing registered, the resolver returns `no-provider` and the call falls
+	* to the broker fallback, which polls Moleculer service discovery for a
+	* `${cap}.${method}` service that will NEVER appear until the discovery
+	* deadline (~30s) elapses. That 30s stall hit EVERY WebRTC cold start via the
+	* provider-less `turn-provider` (`getTurnServers`). Returning `[]` up front
+	* treats a provider-less collection as the empty collection it is — instant,
+	* no discovery. A collection WITH ≥1 provider returns `null` here and routes
+	* normally (the aggregate fans out across its providers as before). The
+	* kernel layer has no cap registry, so the wiring side (which has both the
+	* `CapabilityDefinition`s and the registry) injects this.
+	*/
+	readonly resolveEmptyCollection?: (capName: string, method: string) => readonly unknown[] | null;
+	/**
+	* Optional collection FAN-OUT. Returns the union of `method` across every
+	* registered provider of a `mode:'collection'` cap, or `null` when the
+	* (cap, method) pair is not an aggregated collection array-method.
+	*
+	* Why: routing resolves ONE provider (`resolveChildId` picks the
+	* first-registered child, or the singleton preference — meaningless for a
+	* collection). The hub's tRPC cap-router instead fans array methods across
+	* every provider (`concatArrayMethod`). A forked addon calling the same cap
+	* through `ctx.api` therefore saw a DIFFERENT, smaller answer than the hub's
+	* own router — and for `notification-output`, whose three providers include
+	* two that hold no targets, it saw `[]`. The Notification Center read that
+	* empty catalog as "the target was deleted" and permanently dead-lettered
+	* every notification it ever produced (2026-07-30).
+	*
+	* Skipped when the call carries an explicit `nodeId` pin — a pin must route
+	* to its node, never be answered by a cluster-wide union. The kernel layer
+	* has no cap registry, so the wiring side injects this (same shape as
+	* {@link resolveEmptyCollection}, and it shares that path's aggregation code
+	* so the two answers cannot drift).
+	*/
+	readonly callCollectionAggregate?: (capName: string, method: string, args: unknown) => Promise<readonly unknown[] | null>;
+	/**
+	* Optional `{ addonId }` PIN for a collection cap's SCALAR method — the twin
+	* of {@link callCollectionAggregate}, for the same reason.
+	*
+	* On a system-scoped collection cap `addonId` is not provider data: the
+	* codegen injects it as the `{nodeId?, addonId?}` selector on every method,
+	* and the hub's tRPC cap-router routes by it. This handler lifted only
+	* `nodeId` and `deviceId` out of a child's args, so a forked addon's pin was
+	* DISCARDED IN SILENCE and the call was answered by whichever provider
+	* registered first. `broker.getBrokerConfig({id:'ha_001', addonId:'provider-
+	* homeassistant'})` therefore returned Homematic's `null` — indistinguishable
+	* from "no such broker" — and the Home Assistant export could never open a
+	* link. Every write-up that "proved the pin works" had measured the hub's
+	* tRPC surface, never this path (2026-08-09).
+	*
+	* Returns a `{ value }` box so a legitimate `null` result is distinguishable
+	* from "not a pinned collection call, route normally", and THROWS when the
+	* pin names a non-provider — a pin that silently degrades to another
+	* provider's answer is worse than no pin. Array methods are never pinned
+	* here: their contract is the union above.
+	*
+	* The kernel layer has no cap registry, so the wiring side injects this and
+	* it shares the tRPC path's provider resolution — the two must not drift.
+	*/
+	readonly callPinnedCollection?: (capName: string, method: string, args: unknown) => Promise<{
+		readonly value: unknown;
+	} | null>;
+	/**
+	* Optional predicate — returns `true` when `capName` is a HUB-CORE `$`-service
+	* cap (`system`, `addons`, `nodes`, `capabilities`, `stream-probe`, …): served
+	* by the hub's `$core-caps` / `$stream-probe` Moleculer services, NOT by any
+	* addon provider. These are the ONLY legitimate consumers of the unpinned
+	* `brokerCallForCap` fallback.
+	*
+	* It generalises the per-cap patches (`isDeviceNativeCap`,
+	* `resolveEmptyCollection`) into ONE rule: for any cap the resolver misses
+	* (`no-provider`) that is NOT a core `$`-service, the unpinned broker fallback
+	* is a STRUCTURALLY DEAD path — the cap's providers are broker-less forked
+	* children that expose no Moleculer service, so discovery 30s-deadlines into
+	* the misleading `${cap}.${cap}.${method}` error. Instead the handler retries
+	* the resolver briefly (the provider registers late in the post-restart boot
+	* window) and then throws a PRECISE "not yet registered" error. A NEW
+	* multi-node addon cap is covered automatically — no allowlist entry needed —
+	* because the discriminant is the already-maintained hub-core cap set, not a
+	* per-cap flag.
+	*
+	* The kernel layer has no cap registry, so the wiring side injects it.
+	* Omitted (or returning `false` for a core cap by mistake) ⇒ legacy behaviour
+	* exactly: the miss falls straight to the broker fallback with no retry.
+	*/
+	readonly isCoreServiceCap?: (capName: string) => boolean;
+	/**
+	* Resolve the per-device NATIVE provider for `(capName, deviceId)` — the
+	* `native: true` route (see {@link CapCallInput.native}).
+	*
+	* Wired to this node's `CapabilityRegistry.getNativeProvider`, which is the
+	* SINGLE authority on the question: it already covers in-process natives,
+	* hub-local UDS vendor children (through the hub's `setNativeFallback`
+	* resolver) and remote agents. Nothing here re-derives that — a rule
+	* implemented twice is a rule that drifts, and this one previously drifted
+	* into a wrapper answering on behalf of the native it was supposed to call.
+	*
+	* Returns null when no addon publishes the cap for that device. The handler
+	* then FAILS the call rather than falling back to capName routing: falling
+	* back is how a wrapper ends up calling itself.
+	*
+	* Omitted ⇒ a `native: true` call is forwarded to the hub (agents) or
+	* rejected (no forwarder) — never silently downgraded to wrapper routing.
+	*/
+	readonly resolveNative?: (capName: string, deviceId: number) => Record<string, (input: unknown) => Promise<unknown>> | null;
+	/**
+	* The hub's claim authority for a device-scoped `getStatus` (D663, ruling
+	* S3). Wired to `CapabilityRegistry.resolveClaimedStatus` — the SAME question
+	* the registry's own wrappers and the other two transport entries ask, through
+	* the one shared `answerClaimedGetStatus` (`claimed-get-status.ts`).
+	*
+	* Why here: every capName-based route below dispatches STRAIGHT to the owning
+	* runner (`hub-local-uds`, `remote-moleculer`), whose `getStatus` answers the
+	* NATIVE slice. This handler is the entry for a call no co-resident sibling
+	* owns (a remote agent's device, a hub-in-process cap, the agent's forward);
+	* the sibling short-circuit in `LocalChildRegistry` and the hub's
+	* `callCapabilityOnNode` are the other two, and each asks first. When the
+	* answer is `claimed` the merged slice IS the answer (`null` for a held claim,
+	* and for a device whose claims cannot be known) and the resolver is never
+	* consulted; a node pin does not bypass it — the hub is the one claim
+	* authority wherever the device runs. `unclaimed` routes exactly as before.
+	*
+	* Omitted (the agent has no claim authority; its handler forwards to the hub
+	* for hub-hosted caps, which answer through THIS hook on the hub) ⇒ legacy
+	* routing exactly. Known gap: an agent-resident child calling `getStatus` of
+	* an agent-resident device is answered by the agent's local dispatcher with
+	* no hub round-trip, so a claim is not honoured there (D663 open item).
+	*/
+	readonly claimedStatus?: ClaimedStatusResolver;
+	/** Optional logger for the broker-fallback diagnostic line. */
+	readonly logger?: ParentUnownedCallLogger;
 }
 /**
- * Build the `onUnownedCall` handler the hub / agent passes into
- * `new LocalChildRegistry({ ..., onUnownedCall })`.
- *
- * The returned handler:
- *   - tries the resolver first (when present),
- *   - falls back to the broker for `no-provider` resolver misses (the
- *     `$`-infra / core services), and
- *   - surfaces a clear error when the call is genuinely unroutable (so the
- *     child's call rejects rather than hanging).
- */
+* Build the `onUnownedCall` handler the hub / agent passes into
+* `new LocalChildRegistry({ ..., onUnownedCall })`.
+*
+* The returned handler:
+*   - tries the resolver first (when present),
+*   - falls back to the broker for `no-provider` resolver misses (the
+*     `$`-infra / core services), and
+*   - surfaces a clear error when the call is genuinely unroutable (so the
+*     child's call rejects rather than hanging).
+*/
 export declare function createParentUnownedCallHandler(deps: ParentUnownedCallDeps): (input: CapCallInput) => Promise<unknown>;

package/dist/kernel/transport/peer-answered-error.d.ts

@@ -1,17 +1,17 @@
 /**
- * An error the FAR END of a channel answered with.
- *
- * The request was delivered, a handler ran, and it said no — typically a
- * provider refusing by throwing ("No home preset configured for this
- * camera"). That is an application answer, and it must reach the caller as
- * the provider's own sentence. A transport failure (channel closed, request
- * timed out, no child) is a plain `Error` and nobody answered it.
- *
- * `CapRouteResolver.dispatch` keys on this class: it used to wrap EVERY
- * non-routing throw as `CapRouteError{reason:'transport-failed'}`, so an
- * operator pressing PTZ Home was told the node was "not routable" when the
- * node had answered (2026-09-25, device 3836).
- */
+* An error the FAR END of a channel answered with.
+*
+* The request was delivered, a handler ran, and it said no — typically a
+* provider refusing by throwing ("No home preset configured for this
+* camera"). That is an application answer, and it must reach the caller as
+* the provider's own sentence. A transport failure (channel closed, request
+* timed out, no child) is a plain `Error` and nobody answered it.
+*
+* `CapRouteResolver.dispatch` keys on this class: it used to wrap EVERY
+* non-routing throw as `CapRouteError{reason:'transport-failed'}`, so an
+* operator pressing PTZ Home was told the node was "not routable" when the
+* node had answered (2026-09-25, device 3836).
+*/
 export declare class PeerAnsweredError extends Error {
-    constructor(message: string);
+	constructor(message: string);
 }