@camstack/system 1.2.390 → 1.2.392

package/dist/kernel/transport/local-child-registry.d.ts

@@ -1,621 +1,621 @@
-import { IReadinessRegistryRecord, SystemEvent } from '@camstack/types';
-import { CapUsageCallRecord } from '../moleculer/cap-usage-registry.js';
-import { CapActionReading } from './cap-action-census.js';
-import { CapRoutingHints } from './cap-routing-hints.js';
-import { ClaimedStatusResolver } from '../status-overlay.js';
-import { AddonCallInput, CapCallInput, ChildLogMessage, RegisteredChild } from './child-cap-protocol.js';
-import { LocalTransportServer } from './local-transport.js';
-import { SocketTrafficSample } from './socket-traffic.js';
+import { type IReadinessRegistryRecord, type SystemEvent } from "@camstack/types";
+import type { CapUsageCallRecord } from "../moleculer/cap-usage-registry.js";
+import { type CapActionReading } from "./cap-action-census.js";
+import { type CapRoutingHints } from "./cap-routing-hints.js";
+import type { ClaimedStatusResolver } from "../status-overlay.js";
+import type { AddonCallInput, CapCallInput, ChildLogMessage, RegisteredChild } from "./child-cap-protocol.js";
+import type { LocalTransportServer } from "./local-transport.js";
+import type { SocketTrafficSample } from "./socket-traffic.js";
 /**
- * How many child `cap-call-out`s this parent forwarded WITHOUT reading their
- * args (`raw`) against how many it decoded (`decoded`: an inline-args frame,
- * a target that cannot take a payload, or a call that left the sibling path
- * for `onUnownedCall`). Cumulative; the heartbeat reports the window.
- *
- * It exists because raw-forward makes the parent blind to the bytes on
- * purpose, and the one thing it must not be blind to is how often that
- * happens. A plane that says "raw=0" under load is a plane where the
- * negotiation failed, and nothing else would show it.
- */
+* How many child `cap-call-out`s this parent forwarded WITHOUT reading their
+* args (`raw`) against how many it decoded (`decoded`: an inline-args frame,
+* a target that cannot take a payload, or a call that left the sibling path
+* for `onUnownedCall`). Cumulative; the heartbeat reports the window.
+*
+* It exists because raw-forward makes the parent blind to the bytes on
+* purpose, and the one thing it must not be blind to is how often that
+* happens. A plane that says "raw=0" under load is a plane where the
+* negotiation failed, and nothing else would show it.
+*/
 export interface ForwardCensus {
-    readonly raw: number;
-    readonly decoded: number;
+	readonly raw: number;
+	readonly decoded: number;
 }
 /**
- * Peer id the action census charges frames that arrived before `register`.
- *
- * One frame per connection, and it is named rather than dropped: a census is
- * only worth its coverage, and coverage you cannot see is coverage you cannot
- * check.
- */
+* Peer id the action census charges frames that arrived before `register`.
+*
+* One frame per connection, and it is named rather than dropped: a census is
+* only worth its coverage, and coverage you cannot see is coverage you cannot
+* check.
+*/
 export declare const PRE_REGISTER_PEER_ID = "(pre-register)";
 /** Per-child event fan-out counters (sent = delivered, suppressed = gated/would-gate). */
 export interface ChildEventStats {
-    sent: number;
-    suppressed: number;
+	sent: number;
+	suppressed: number;
 }
 /**
- * D467 — one PRODUCED category over the life of the process.
- *
- * `broadcasts` counts emits, not deliveries: one call to
- * {@link LocalChildRegistry.broadcastEventToChildren} is one broadcast no
- * matter how many children are connected. This is the number the per-child
- * `sent`/`suppressed` counters cannot give — those are (event × child) pairs,
- * so on a 39-child node they read ~38x the production rate and a reader who
- * sums them concludes the cluster emits an order of magnitude more than it does.
- *
- * `wanted` is the number of (event × child) pairs whose SUBSCRIPTION matched —
- * the gate answer, which is also the delivery answer. `wanted === 0` over a window means
- * the category was serialised and walked across every child and **nobody asked
- * for it**: pure waste, and the one finding worth acting on.
- */
+* D467 — one PRODUCED category over the life of the process.
+*
+* `broadcasts` counts emits, not deliveries: one call to
+* {@link LocalChildRegistry.broadcastEventToChildren} is one broadcast no
+* matter how many children are connected. This is the number the per-child
+* `sent`/`suppressed` counters cannot give — those are (event × child) pairs,
+* so on a 39-child node they read ~38x the production rate and a reader who
+* sums them concludes the cluster emits an order of magnitude more than it does.
+*
+* `wanted` is the number of (event × child) pairs whose SUBSCRIPTION matched —
+* the gate answer, which is also the delivery answer. `wanted === 0` over a window means
+* the category was serialised and walked across every child and **nobody asked
+* for it**: pure waste, and the one finding worth acting on.
+*/
 export interface CategoryFanoutSample {
-    readonly category: string;
-    readonly broadcasts: number;
-    readonly wanted: number;
+	readonly category: string;
+	readonly broadcasts: number;
+	readonly wanted: number;
 }
 /**
- * Cap on the census map. `EventCategory` is a closed enum of ~120 members, so
- * 256 holds every legitimate category twice over; the cap exists because a
- * hand-rolled topic (forbidden, but this is the meter that would SEE one) could
- * otherwise grow the map without bound in a long-lived process. Overflow is not
- * silent — {@link LocalChildRegistry.categoryCensusOverflow} counts it and the
- * heartbeat prints it.
- */
+* Cap on the census map. `EventCategory` is a closed enum of ~120 members, so
+* 256 holds every legitimate category twice over; the cap exists because a
+* hand-rolled topic (forbidden, but this is the meter that would SEE one) could
+* otherwise grow the map without bound in a long-lived process. Overflow is not
+* silent — {@link LocalChildRegistry.categoryCensusOverflow} counts it and the
+* heartbeat prints it.
+*/
 export declare const CATEGORY_CENSUS_MAX = 256;
 /**
- * Sentinel prefix used in the no-route error thrown when `cap-call-out` has no
- * local sibling and no `onUnownedCall` fallback. `ipcParentLink` detects this
- * prefix to distinguish routing failures (safe to retry via broker) from real
- * provider errors (must NOT retry to avoid double-executing side effects).
- */
+* Sentinel prefix used in the no-route error thrown when `cap-call-out` has no
+* local sibling and no `onUnownedCall` fallback. `ipcParentLink` detects this
+* prefix to distinguish routing failures (safe to retry via broker) from real
+* provider errors (must NOT retry to avoid double-executing side effects).
+*/
 export declare const UDS_NO_ROUTE_PREFIX = "UDS_NO_ROUTE";
 /**
- * Minimal logger interface accepted by `LocalChildRegistry`.
- * Kept narrow so the registry doesn't depend on any concrete logger class.
- */
+* Minimal logger interface accepted by `LocalChildRegistry`.
+* Kept narrow so the registry doesn't depend on any concrete logger class.
+*/
 export interface LocalChildRegistryLogger {
-    info(msg: string, meta?: unknown): void;
+	info(msg: string, meta?: unknown): void;
 }
 /**
- * Options accepted by `LocalChildRegistry`.
- * The `server` field is the UDS server to listen on.
- * The optional `onUnownedCall` is the parent-supplied fallback invoked when no
- * local child owns the requested cap (the hub / agent will wire this to the
- * cluster CapabilityRegistry).
- * The optional `logger` receives a single deduplicated INFO line the first time
- * each capName is routed child→sibling over UDS.
- */
+* Options accepted by `LocalChildRegistry`.
+* The `server` field is the UDS server to listen on.
+* The optional `onUnownedCall` is the parent-supplied fallback invoked when no
+* local child owns the requested cap (the hub / agent will wire this to the
+* cluster CapabilityRegistry).
+* The optional `logger` receives a single deduplicated INFO line the first time
+* each capName is routed child→sibling over UDS.
+*/
 /**
- * Where the registry says that a runner came up or went away — the parent's
- * kernel bus. A forked runner has no Moleculer broker (Phase F), so
- * `$node.connected` never fires for it and the Moleculer-side emitter
- * (`agent-registry.service.ts`) never sees one: this registry is the only place
- * that knows (fix round 1 of the 2026-10-02 motion-release-order work, C1).
- */
+* Where the registry says that a runner came up or went away — the parent's
+* kernel bus. A forked runner has no Moleculer broker (Phase F), so
+* `$node.connected` never fires for it and the Moleculer-side emitter
+* (`agent-registry.service.ts`) never sees one: this registry is the only place
+* that knows (fix round 1 of the 2026-10-02 motion-release-order work, C1).
+*/
 export interface ChildLifecycleEvents {
-    /** This parent's node id (`'hub'`, or the bare agent id): the `<node>` of `<node>/<childId>`. */
-    readonly parentNodeId: () => string;
-    /** The parent's kernel bus `emit`. Telemetry (D8): a consumer must survive a dropped event. */
-    readonly emit: (event: SystemEvent) => void;
-    /**
-     * After `WorkerOnline` is emitted and before the pre-init register is acked.
-     * Production omits this and the registry uses {@link afterWorkerOnlineAnnounce}.
-     * Tests inject a seam so dropping the await turns the lifecycle spec red.
-     */
-    readonly afterOnlineAnnounce?: () => Promise<void>;
+	/** This parent's node id (`'hub'`, or the bare agent id): the `<node>` of `<node>/<childId>`. */
+	readonly parentNodeId: () => string;
+	/** The parent's kernel bus `emit`. Telemetry (D8): a consumer must survive a dropped event. */
+	readonly emit: (event: SystemEvent) => void;
+	/**
+	* After `WorkerOnline` is emitted and before the pre-init register is acked.
+	* Production omits this and the registry uses {@link afterWorkerOnlineAnnounce}.
+	* Tests inject a seam so dropping the await turns the lifecycle spec red.
+	*/
+	readonly afterOnlineAnnounce?: () => Promise<void>;
 }
 /**
- * One event-loop turn after `WorkerOnline` before the child's register is acked.
- * Gives a UDS sibling that already holds the frame (the orchestrator provider
- * gate) a turn to close its cameras before the child loads addons.
- */
+* One event-loop turn after `WorkerOnline` before the child's register is acked.
+* Gives a UDS sibling that already holds the frame (the orchestrator provider
+* gate) a turn to close its cameras before the child loads addons.
+*/
 export declare function afterWorkerOnlineAnnounce(): Promise<void>;
 export interface LocalChildRegistryOptions {
-    readonly server: LocalTransportServer;
-    /**
-     * Emit `WorkerOnline { workerId: '<parent>/<childId>' }` at a new
-     * incarnation's FIRST register — the pre-init frame `LocalChildClient.start()`
-     * sends before any addon module is loaded, so before `initialize()` and any
-     * device restore; it is emitted, then one event-loop turn is yielded, before
-     * that frame is acked — so a UDS consumer (the motion-slice provider gate)
-     * already has the frame in its socket and one turn to close the gate before
-     * the child proceeds to load — and `WorkerOffline` when the LIVE connection
-     * closes (never for a superseded one). Omitted: nothing is emitted.
-     */
-    readonly lifecycleEvents?: ChildLifecycleEvents;
-    readonly onUnownedCall?: (input: CapCallInput) => Promise<unknown>;
-    readonly logger?: LocalChildRegistryLogger;
-    /**
-     * Resolver for the operator's active-singleton preference. When two or
-     * more local children register the SAME singleton capName (e.g. two
-     * addons both providing `webrtc-session`), the registry must consult
-     * `CapabilityRegistry` to pick the operator-selected provider instead of
-     * returning the first-registered child by insertion order. Returns the preferred
-     * addonId (== childId for solo-addon runners), or null when no
-     * preference is set or the cap is not a singleton.
-     */
-    readonly getActiveSingletonAddonId?: (capName: string) => string | null;
-    /**
-     * Resolve an addonId to its runner/child id — the addon's
-     * `execution.group` when it declares one, else the addon id itself
-     * (`resolveRunnerId`). Needed so the active-singleton preference (which
-     * is expressed as an addonId) can be matched against the registry's
-     * candidate CHILD ids: a grouped addon's child id is the group name, not
-     * its own id. Omitted → identity (addonId === childId), preserving the
-     * solo-runner behaviour for every ungrouped addon.
-     */
-    readonly resolveChildIdForAddon?: (addonId: string) => string;
-    /**
-     * This node's own Moleculer nodeId (`'hub'` on the hub, the bare agent id on
-     * an agent). Used ONLY to decide whether an explicit per-call `nodeId` pin
-     * bypasses the local-sibling short-circuit in the `cap-call-out` path:
-     *   - a pin naming THIS node is satisfied by a co-resident sibling (the pin's
-     *     target lives here), so it routes locally exactly like an unpinned call;
-     *   - a pin naming ANOTHER node bypasses the sibling and reaches
-     *     `onUnownedCall` (so it is never silently answered by a same-named
-     *     provider on the wrong node).
-     *
-     * Omitted (legacy / positional construction) ⇒ prior behaviour EXACTLY: any
-     * pin bypasses the local sibling — without this node's id the registry cannot
-     * distinguish a pin-to-self from a pin-to-another-node.
-     */
-    readonly ownNodeId?: string;
-    /**
-     * Does `(capName, method)` name a `mode:'collection'` array method whose
-     * contract is the UNION across every provider? Such a call must NOT be
-     * short-circuited to a local sibling: `resolveChildId` picks ONE provider
-     * (first-registered, or the singleton preference — meaningless here), so the
-     * caller would see a fraction of the catalog the hub's own tRPC router
-     * returns. It goes to `onUnownedCall`, which owns the aggregate over local
-     * siblings, in-process providers and remote nodes alike.
-     *
-     * `notification-output` has three provider siblings; the Notification Center
-     * landed on one holding no targets, read the empty list as "target deleted"
-     * and permanently dead-lettered every notification it ever produced
-     * (2026-07-30). Omitted ⇒ prior behaviour exactly (sibling short-circuit for
-     * everything). The kernel has no cap registry, so the wiring side injects it.
-     */
-    readonly isAggregatedCollectionMethod?: (capName: string, method: string) => boolean;
-    /**
-     * Does this call carry an explicit `{ addonId }` selector naming the provider
-     * it wants? Such a call must NOT be short-circuited to a local sibling
-     * either: `resolveChildId` picks the FIRST-registered child for the cap name,
-     * which is the one thing the caller took the trouble to say it did not want.
-     * It goes to `onUnownedCall`, which resolves the named provider.
-     *
-     * The third argument is the call's ROUTING HINTS (`{ nodeId?, addonId? }`,
-     * `cap-routing-hints.ts`) — the two top-level string fields the parent ever
-     * read out of the args — not the args themselves. Under raw-forward the
-     * parent does not decode the args at all; the sender lifts the hints, and
-     * for a legacy frame the parent lifts them itself. Both modes reach this
-     * predicate with the same shape.
-     *
-     * The array-method bypass above and this one are the same defect seen twice.
-     * `broker.getBrokerConfig({id:'ha_001', addonId:'provider-homeassistant'})`
-     * from the Home Assistant export was answered by `provider-homematic` — which
-     * returns `null` for a broker it does not own, indistinguishable from "no
-     * such broker" — so the export could never open a link. Fixing only
-     * `onUnownedCall` did nothing, because this decision is made first: measured
-     * on the live hub with a deliberately bogus addonId, which came back `null`
-     * instead of refused (2026-08-09, [D105]).
-     *
-     * Omitted ⇒ prior behaviour exactly. The kernel has no cap registry, so the
-     * wiring side injects it, sharing the predicate with the handler that then
-     * performs the routing — a rule implemented twice is a rule that drifts.
-     */
-    readonly isAddonPinnedCall?: (capName: string, method: string, hints: CapRoutingHints) => boolean;
-    /**
-     * The hub's claim authority for a device-scoped `getStatus` (D663, ruling
-     * S3) — fifth member of the "an explicit intent must win over a co-located
-     * provider" family. A `getStatus` about a device whose cap is CLAIMED is
-     * answered HERE, from the hub mirror's merged slice, before `resolveChildId`
-     * is consulted: the sibling short-circuit would dispatch it straight to the
-     * owning child, whose `getStatus` is the NATIVE slice — an HA-MQTT / HomeKit
-     * exporter or the notification center (hub-local forked children) asking
-     * `battery.getStatus({ deviceId })` of a device owned by the hub-local
-     * `provider-homeassistant` child read the native value while the UI showed
-     * the merged one. The parent's `onUnownedCall` had the same answer, on a path
-     * this call never took. Same shared function (`answerClaimedGetStatus`) as
-     * that handler and the hub's `callCapabilityOnNode`, so the three entries
-     * cannot drift; a device whose claims are not yet known has them resolved
-     * first and is never answered native.
-     *
-     * Omitted (the agent has no claim authority) ⇒ prior behaviour exactly. The
-     * kernel has no cap registry, so the wiring side injects it.
-     */
-    readonly claimedStatus?: ClaimedStatusResolver;
-    /**
-     * Per-cap-method bound for UDS cap calls, in ms — read from the cap
-     * definition's declared `timeoutMs`. The SAME resolver the remote plane uses
-     * (`CapRouteResolver.capTimeoutMs`), so the two planes agree by construction
-     * instead of by coincidence.
-     *
-     * Without this the channel default (60 s) would apply to everything, and a
-     * legitimately long method — `applyServerUpdate` declares 16 min because it
-     * awaits a full npm install — would be cut off mid-run. Omitted ⇒ the
-     * channel default for every cap call.
-     */
-    readonly capTimeoutMs?: (capName: string, method: string) => number | undefined;
-    /**
-     * Sink for observed cap calls — the ONE place a forked addon's outbound
-     * `ctx.api` traffic can be recorded in the process that also holds the reader.
-     *
-     * ── Why here, and not in the caller ───────────────────────────────────────
-     * `getCapUsageRegistry()` is a per-process module singleton and the reader
-     * (`nodes.getCapUsageGraph`) runs on hub-main. The only writer used to be
-     * `addon-context-factory.ts`'s `localProviderLink` observer, which runs in
-     * the FORKED RUNNER — so every observation it made was written to an object
-     * hub-main can never read, and it fired only for co-located providers anyway
-     * (`ipcParentLink`, which carries every cross-process call, takes no
-     * observer). `nodes.getCapUsageGraph` therefore returned `[]` in 0.21 s
-     * against a hub running 64 addons and 1019 devices.
-     *
-     * ── Why here, and not in `onUnownedCall` ──────────────────────────────────
-     * Because most inter-addon traffic never gets there. `resolveChildId`
-     * short-circuits a cap owned by a sibling runner straight to `callCap`, and
-     * on the hub every addon IS a sibling runner. Recording in `onUnownedCall`
-     * would have seen `ctx.settings.*` (hub-in-process `settings-store`) and
-     * missed every addon→addon call — a graph with a whole plane silently
-     * missing, which is the defect it was meant to end.
-     *
-     * This handler is strictly upstream of BOTH branches, and it is where
-     * `callerAddonId` is already stamped off the UDS connection the frame
-     * arrived on — a caller identity the child cannot spoof.
-     *
-     * ── What it still cannot see (say it, do not hide it) ─────────────────────
-     *  1. **hub-main → hub-main.** An in-process builtin's `ctx.api` is
-     *     `AddonRegistryService.getBrokerApi()` — ONE lazily-built tRPC client
-     *     shared by every addon, so there is no per-caller identity to record.
-     *     Giving it an observer needs a per-addon client first.
-     *  2. **A runner's co-located calls.** `localProviderLink` answers inside the
-     *     runner and the frame never reaches this socket. Only the `detection` /
-     *     `ml` execution groups have co-located providers at all (D9, D29).
-     *  3. **An agent's own runners.** Their parent is the agent process, whose
-     *     `LocalChildRegistry` writes to the agent's singleton. Aggregating that
-     *     needs a transport hop. `$hub-cap-fwd`'s envelope has carried the
-     *     agent-stamped `callerAddonId` since D787 (the keychain owner-checks
-     *     it), but the hub does not feed it to this observer — an
-     *     agent-originated call is still not recorded here.
-     *
-     * MUST NOT throw; the call site catches anyway (see the record site).
-     */
-    readonly capUsageObserver?: (obs: CapUsageCallRecord) => void;
+	readonly server: LocalTransportServer;
+	/**
+	* Emit `WorkerOnline { workerId: '<parent>/<childId>' }` at a new
+	* incarnation's FIRST register — the pre-init frame `LocalChildClient.start()`
+	* sends before any addon module is loaded, so before `initialize()` and any
+	* device restore; it is emitted, then one event-loop turn is yielded, before
+	* that frame is acked — so a UDS consumer (the motion-slice provider gate)
+	* already has the frame in its socket and one turn to close the gate before
+	* the child proceeds to load — and `WorkerOffline` when the LIVE connection
+	* closes (never for a superseded one). Omitted: nothing is emitted.
+	*/
+	readonly lifecycleEvents?: ChildLifecycleEvents;
+	readonly onUnownedCall?: (input: CapCallInput) => Promise<unknown>;
+	readonly logger?: LocalChildRegistryLogger;
+	/**
+	* Resolver for the operator's active-singleton preference. When two or
+	* more local children register the SAME singleton capName (e.g. two
+	* addons both providing `webrtc-session`), the registry must consult
+	* `CapabilityRegistry` to pick the operator-selected provider instead of
+	* returning the first-registered child by insertion order. Returns the preferred
+	* addonId (== childId for solo-addon runners), or null when no
+	* preference is set or the cap is not a singleton.
+	*/
+	readonly getActiveSingletonAddonId?: (capName: string) => string | null;
+	/**
+	* Resolve an addonId to its runner/child id — the addon's
+	* `execution.group` when it declares one, else the addon id itself
+	* (`resolveRunnerId`). Needed so the active-singleton preference (which
+	* is expressed as an addonId) can be matched against the registry's
+	* candidate CHILD ids: a grouped addon's child id is the group name, not
+	* its own id. Omitted → identity (addonId === childId), preserving the
+	* solo-runner behaviour for every ungrouped addon.
+	*/
+	readonly resolveChildIdForAddon?: (addonId: string) => string;
+	/**
+	* This node's own Moleculer nodeId (`'hub'` on the hub, the bare agent id on
+	* an agent). Used ONLY to decide whether an explicit per-call `nodeId` pin
+	* bypasses the local-sibling short-circuit in the `cap-call-out` path:
+	*   - a pin naming THIS node is satisfied by a co-resident sibling (the pin's
+	*     target lives here), so it routes locally exactly like an unpinned call;
+	*   - a pin naming ANOTHER node bypasses the sibling and reaches
+	*     `onUnownedCall` (so it is never silently answered by a same-named
+	*     provider on the wrong node).
+	*
+	* Omitted (legacy / positional construction) ⇒ prior behaviour EXACTLY: any
+	* pin bypasses the local sibling — without this node's id the registry cannot
+	* distinguish a pin-to-self from a pin-to-another-node.
+	*/
+	readonly ownNodeId?: string;
+	/**
+	* Does `(capName, method)` name a `mode:'collection'` array method whose
+	* contract is the UNION across every provider? Such a call must NOT be
+	* short-circuited to a local sibling: `resolveChildId` picks ONE provider
+	* (first-registered, or the singleton preference — meaningless here), so the
+	* caller would see a fraction of the catalog the hub's own tRPC router
+	* returns. It goes to `onUnownedCall`, which owns the aggregate over local
+	* siblings, in-process providers and remote nodes alike.
+	*
+	* `notification-output` has three provider siblings; the Notification Center
+	* landed on one holding no targets, read the empty list as "target deleted"
+	* and permanently dead-lettered every notification it ever produced
+	* (2026-07-30). Omitted ⇒ prior behaviour exactly (sibling short-circuit for
+	* everything). The kernel has no cap registry, so the wiring side injects it.
+	*/
+	readonly isAggregatedCollectionMethod?: (capName: string, method: string) => boolean;
+	/**
+	* Does this call carry an explicit `{ addonId }` selector naming the provider
+	* it wants? Such a call must NOT be short-circuited to a local sibling
+	* either: `resolveChildId` picks the FIRST-registered child for the cap name,
+	* which is the one thing the caller took the trouble to say it did not want.
+	* It goes to `onUnownedCall`, which resolves the named provider.
+	*
+	* The third argument is the call's ROUTING HINTS (`{ nodeId?, addonId? }`,
+	* `cap-routing-hints.ts`) — the two top-level string fields the parent ever
+	* read out of the args — not the args themselves. Under raw-forward the
+	* parent does not decode the args at all; the sender lifts the hints, and
+	* for a legacy frame the parent lifts them itself. Both modes reach this
+	* predicate with the same shape.
+	*
+	* The array-method bypass above and this one are the same defect seen twice.
+	* `broker.getBrokerConfig({id:'ha_001', addonId:'provider-homeassistant'})`
+	* from the Home Assistant export was answered by `provider-homematic` — which
+	* returns `null` for a broker it does not own, indistinguishable from "no
+	* such broker" — so the export could never open a link. Fixing only
+	* `onUnownedCall` did nothing, because this decision is made first: measured
+	* on the live hub with a deliberately bogus addonId, which came back `null`
+	* instead of refused (2026-08-09, [D105]).
+	*
+	* Omitted ⇒ prior behaviour exactly. The kernel has no cap registry, so the
+	* wiring side injects it, sharing the predicate with the handler that then
+	* performs the routing — a rule implemented twice is a rule that drifts.
+	*/
+	readonly isAddonPinnedCall?: (capName: string, method: string, hints: CapRoutingHints) => boolean;
+	/**
+	* The hub's claim authority for a device-scoped `getStatus` (D663, ruling
+	* S3) — fifth member of the "an explicit intent must win over a co-located
+	* provider" family. A `getStatus` about a device whose cap is CLAIMED is
+	* answered HERE, from the hub mirror's merged slice, before `resolveChildId`
+	* is consulted: the sibling short-circuit would dispatch it straight to the
+	* owning child, whose `getStatus` is the NATIVE slice — an HA-MQTT / HomeKit
+	* exporter or the notification center (hub-local forked children) asking
+	* `battery.getStatus({ deviceId })` of a device owned by the hub-local
+	* `provider-homeassistant` child read the native value while the UI showed
+	* the merged one. The parent's `onUnownedCall` had the same answer, on a path
+	* this call never took. Same shared function (`answerClaimedGetStatus`) as
+	* that handler and the hub's `callCapabilityOnNode`, so the three entries
+	* cannot drift; a device whose claims are not yet known has them resolved
+	* first and is never answered native.
+	*
+	* Omitted (the agent has no claim authority) ⇒ prior behaviour exactly. The
+	* kernel has no cap registry, so the wiring side injects it.
+	*/
+	readonly claimedStatus?: ClaimedStatusResolver;
+	/**
+	* Per-cap-method bound for UDS cap calls, in ms — read from the cap
+	* definition's declared `timeoutMs`. The SAME resolver the remote plane uses
+	* (`CapRouteResolver.capTimeoutMs`), so the two planes agree by construction
+	* instead of by coincidence.
+	*
+	* Without this the channel default (60 s) would apply to everything, and a
+	* legitimately long method — `applyServerUpdate` declares 16 min because it
+	* awaits a full npm install — would be cut off mid-run. Omitted ⇒ the
+	* channel default for every cap call.
+	*/
+	readonly capTimeoutMs?: (capName: string, method: string) => number | undefined;
+	/**
+	* Sink for observed cap calls — the ONE place a forked addon's outbound
+	* `ctx.api` traffic can be recorded in the process that also holds the reader.
+	*
+	* ── Why here, and not in the caller ───────────────────────────────────────
+	* `getCapUsageRegistry()` is a per-process module singleton and the reader
+	* (`nodes.getCapUsageGraph`) runs on hub-main. The only writer used to be
+	* `addon-context-factory.ts`'s `localProviderLink` observer, which runs in
+	* the FORKED RUNNER — so every observation it made was written to an object
+	* hub-main can never read, and it fired only for co-located providers anyway
+	* (`ipcParentLink`, which carries every cross-process call, takes no
+	* observer). `nodes.getCapUsageGraph` therefore returned `[]` in 0.21 s
+	* against a hub running 64 addons and 1019 devices.
+	*
+	* ── Why here, and not in `onUnownedCall` ──────────────────────────────────
+	* Because most inter-addon traffic never gets there. `resolveChildId`
+	* short-circuits a cap owned by a sibling runner straight to `callCap`, and
+	* on the hub every addon IS a sibling runner. Recording in `onUnownedCall`
+	* would have seen `ctx.settings.*` (hub-in-process `settings-store`) and
+	* missed every addon→addon call — a graph with a whole plane silently
+	* missing, which is the defect it was meant to end.
+	*
+	* This handler is strictly upstream of BOTH branches, and it is where
+	* `callerAddonId` is already stamped off the UDS connection the frame
+	* arrived on — a caller identity the child cannot spoof.
+	*
+	* ── What it still cannot see (say it, do not hide it) ─────────────────────
+	*  1. **hub-main → hub-main.** An in-process builtin's `ctx.api` is
+	*     `AddonRegistryService.getBrokerApi()` — ONE lazily-built tRPC client
+	*     shared by every addon, so there is no per-caller identity to record.
+	*     Giving it an observer needs a per-addon client first.
+	*  2. **A runner's co-located calls.** `localProviderLink` answers inside the
+	*     runner and the frame never reaches this socket. Only the `detection` /
+	*     `ml` execution groups have co-located providers at all (D9, D29).
+	*  3. **An agent's own runners.** Their parent is the agent process, whose
+	*     `LocalChildRegistry` writes to the agent's singleton. Aggregating that
+	*     needs a transport hop. `$hub-cap-fwd`'s envelope has carried the
+	*     agent-stamped `callerAddonId` since D787 (the keychain owner-checks
+	*     it), but the hub does not feed it to this observer — an
+	*     agent-originated call is still not recorded here.
+	*
+	* MUST NOT throw; the call site catches anyway (see the record site).
+	*/
+	readonly capUsageObserver?: (obs: CapUsageCallRecord) => void;
 }
 /**
- * Parent-side authority for local addon-runners reachable over a
- * `LocalTransportServer` (UDS). Children register their cap manifest on
- * connect; the registry routes `(capName, deviceId?)` cap calls to the
- * owning child over the channel and drops a child's caps on disconnect.
- */
+* Parent-side authority for local addon-runners reachable over a
+* `LocalTransportServer` (UDS). Children register their cap manifest on
+* connect; the registry routes `(capName, deviceId?)` cap calls to the
+* owning child over the channel and drops a child's caps on disconnect.
+*/
 export declare class LocalChildRegistry {
-    private readonly children;
-    private registeredHandler;
-    private goneHandler;
-    /** Source of {@link RegisteredChild.incarnation}; one bump per accepted connection. */
-    private nextIncarnation;
-    private eventHandler;
-    private logHandler;
-    private readinessHandler;
-    private readonly server;
-    private readonly onUnownedCall?;
-    private readonly logger?;
-    private readonly lifecycleEvents?;
-    /** Per childId: the incarnation `WorkerOnline` was last said for. */
-    private readonly announcedIncarnation;
-    private readonly getActiveSingletonAddonId?;
-    private readonly resolveChildIdForAddon?;
-    /** This node's own Moleculer nodeId (see {@link LocalChildRegistryOptions.ownNodeId}). */
-    private readonly ownNodeId?;
-    /** See {@link LocalChildRegistryOptions.isAggregatedCollectionMethod}. */
-    private readonly isAggregatedCollectionMethod?;
-    private readonly isAddonPinnedCall?;
-    /** See {@link ForwardCensus}. Mutable counters on the hot path, by design. */
-    private forwardedRaw;
-    private forwardedDecoded;
-    /**
-     * The per-ACTION byte census (D456). `ForwardCensus` above is the same
-     * question asked of the whole plane; this one asks it per `<cap>.<method>`,
-     * beside the bytes that method actually moved. Both are kept: `socketFwd=`
-     * says whether the negotiation is working at all, and a `raw=0` on ONE
-     * method with `raw>0` on its neighbours is a different fault.
-     */
-    private readonly actionCensus;
-    /** See {@link LocalChildRegistryOptions.capTimeoutMs}. */
-    private readonly capTimeoutMs?;
-    /** See {@link LocalChildRegistryOptions.claimedStatus}. */
-    private readonly claimedStatus?;
-    /** See {@link LocalChildRegistryOptions.capUsageObserver}. */
-    private readonly capUsageObserver?;
-    /** Tracks capNames already logged as UDS-routed; one INFO line per capName per process. */
-    private readonly egressRoutedCaps;
-    /** Per-child event fan-out counters (sent / suppressed). */
-    private readonly childEventStats;
-    /** D467: per-category production census (cumulative). See {@link CategoryFanoutSample}. */
-    private readonly categoryStats;
-    /** Broadcasts whose category did not fit in {@link CATEGORY_CENSUS_MAX}. */
-    private categoryOverflow;
-    /** One INFO line the first time the census cap trips, never per event. */
-    private categoryOverflowLogged;
-    /** Last pattern-set string logged per child, to dedup the INFO line. */
-    private readonly loggedPatternSet;
-    /**
-     * Derived `(cap, device?) → child` index over {@link children}, or `null`
-     * when it must be rebuilt. See {@link capIndex} for why it is a cache and
-     * never a registry (D3, D457).
-     */
-    private capChildIndex;
-    /**
-     * Accepts either a plain positional `server` argument (backward-compatible)
-     * or a full `LocalChildRegistryOptions` object.
-     *
-     * Positional overloads (existing call sites are unchanged):
-     *   new LocalChildRegistry(server)
-     *   new LocalChildRegistry(server, onUnownedCall)
-     *
-     * Options object (new call sites that pass a logger):
-     *   new LocalChildRegistry({ server, onUnownedCall, logger })
-     */
-    constructor(serverOrOptions: LocalTransportServer | LocalChildRegistryOptions, onUnownedCallArg?: (input: CapCallInput) => Promise<unknown>);
-    start(): Promise<void>;
-    /**
-     * Per-child event fan-out counters (`{ sent, suppressed }`) or `null` if the
-     * child has no recorded events yet. Exposed for the starvation-verification
-     * surface (operator debug).
-     */
-    getChildEventStats(childId: string): ChildEventStats | null;
-    /**
-     * D467: every category this node has broadcast, with its emit count and how
-     * many child subscriptions matched. Cumulative for the life of the process —
-     * the heartbeat differences it, the same discipline as the per-child
-     * counters. Largest `broadcasts` first.
-     */
-    categoryFanout(): readonly CategoryFanoutSample[];
-    /** Broadcasts the census could not attribute because it was full (cumulative). */
-    categoryCensusOverflow(): number;
-    /**
-     * This child's socket traffic — bytes and messages, both directions, split by
-     * frame kind — or `null` when the child is gone or its channel keeps no
-     * counters (an in-process or test transport).
-     *
-     * The event counters above cover ONE kind of frame and, once surfaced on
-     * 2026-08-29, accounted for 4% of hub-main's ~44 000 socket syscalls/s. This
-     * is the same question asked of every frame the channel moves, and it is the
-     * only per-peer attribution that exists: `/proc` reports one `rchar`/`wchar`
-     * pair for the whole process and has no per-socket breakdown.
-     */
-    getChildSocketTraffic(childId: string): SocketTrafficSample | null;
-    /**
-     * Bytes this process has written to a child that the child has not yet
-     * taken, live, or `null` when the channel keeps no such reading. Read on
-     * every heartbeat probe (D446) — a child that stops draining is the shape
-     * of an outbound-queue episode, and the number lives on the channel.
-     */
-    getChildQueuedBytes(childId: string): number | null;
-    /** Cumulative {@link ForwardCensus} of this parent's `cap-call-out` routing. */
-    readForwardCensus(): ForwardCensus;
-    /**
-     * Cumulative per-action byte census: peer → `<cap>.<method>` → bytes, calls
-     * and the raw/decoded split. A COPY (`cap-action-census.ts` explains why it
-     * must be one); the heartbeat subtracts the previous reading.
-     *
-     * This is the instrument D454 closed by asking for. `socketTopBytes=` names
-     * the peer that moves the bytes and `txkB=` says they are responses; neither
-     * can say WHICH method originates them, and after raw-forward the bytes that
-     * cross are no longer the proxy for what hub-main pays — 85.7 % of sibling
-     * calls cross unread. What costs is what hub-main LOOKS at, and that is the
-     * `decoded` half of an entry, next to the bytes it carried.
-     */
-    readActionCensus(): CapActionReading;
-    /**
-     * Connected children that never declared a subscription pattern set.
-     *
-     * Each one is a fail-open on BOTH planes: `childWantsEvent` returns true for
-     * an undeclared child ({@link ChildEntry.eventPatterns} `=== null`), and
-     * `aggregateEventInterest` returns `null` — accept everything — if ANY
-     * connected child is undeclared, which disables the node's inbound cross-node
-     * gate as well. **One legacy runner silently turns off the filtering for the
-     * whole node**, and nothing reported it, so a zero here is as load-bearing as
-     * a non-zero one.
-     */
-    undeclaredChildCount(): number;
-    /**
-     * Does `entry` want to receive an event in `category`? Undeclared patterns
-     * (`null`) → always (fail-open, counted by {@link undeclaredChildCount});
-     * else the child's declared set must match via `matchesPattern` — the SAME
-     * function the child's own `deliverShared` map-key gate uses, giving provable
-     * delivery parity. The parent always filters: the `CAMSTACK_UDS_EVENT_FANOUT`
-     * shadow/broadcast modes were removed on 2026-10-06.
-     *
-     * NOTE: this gate must NOT consult `RING_BUFFER_DENY_PATTERNS` /
-     * `isHighFrequencyCategory` — those are ring-buffer STORAGE policy; a child
-     * that explicitly subscribes to a ring-denied category must still RECEIVE it.
-     */
-    private childWantsEvent;
-    /**
-     * D2: this node's aggregate cross-node event interest — the UNION of every
-     * connected child's declared category patterns. Consumed by the parent's
-     * `$event-bus` inbound gate (via `setNodeEventInterest`) so the node only
-     * accepts cross-node (Moleculer) categories at least one local child wants.
-     *
-     * Returns `null` (fail-open — accept everything) when:
-     *   - NO child is currently connected (boot window before the first forked
-     *     child completes its UDS handshake, or every child has disconnected): a
-     *     node MUST NOT drop 100% of inbound cross-node events during that window,
-     *     and a child may connect imminently. This is distinct from the
-     *     declared-empty case below.
-     *   - ANY connected child is UNDECLARED (`eventPatterns === null`, a legacy
-     *     runner): a node cannot safely narrow its inbound set while a child's
-     *     real interest is unknown. Mirrors the per-child fail-open in
-     *     {@link childWantsEvent}, aggregated conservatively.
-     *
-     * Returns an EMPTY array only when ≥1 child is connected and EVERY connected
-     * child declared an explicit empty set — a genuine "wants nothing". Reads the
-     * live `children` map, so a child registering / disconnecting / sending
-     * `event-sub` is reflected on the next call with no extra bookkeeping.
-     */
-    aggregateEventInterest(): readonly string[] | null;
-    private statsFor;
-    /** Deduped INFO line whenever a child's declared pattern set changes. */
-    private logPatternSet;
-    /**
-     * Child id that can service a call to `capName` (optionally addressing
-     * `deviceId`), or null.
-     *
-     * `deviceId` is a routing HINT, not a hard filter. A singleton cap
-     * (`pipeline-runner`, `stream-broker`, …) addresses devices through its
-     * METHOD ARGUMENTS — `attachCamera({ deviceId })` is one provider serving
-     * many cameras — so its descriptor carries no `deviceId`. Resolving on
-     * `deviceId` alone would never match it and would force the call onto the
-     * broker fallback (which then hangs in service discovery). Hence:
-     *   1. exact device-scoped owner (native per-device caps where each child
-     *      owns a disjoint device subset) is preferred, then
-     *   2. a singleton owner (deviceId-less descriptor) is the fallback.
-     * A cap is globally singleton XOR device-scoped, so the two tiers never
-     * compete for the same capName.
-     */
-    resolveChildId(capName: string, deviceId?: number): string | null;
-    /**
-     * Publish one cap-usage observation, if a sink is wired.
-     *
-     * Cost discipline — this is on the hot path (D181: hub-main's event loop is
-     * the cluster's only queue): no sink means one undefined check; with a sink
-     * it is one object literal and one `Date.now()`, and the sink itself is O(1).
-     * Wrapped so a broken observer can never fail the call it observes — the
-     * registry swallows too, and BOTH matter: this catch also covers a sink that
-     * is not the registry.
-     */
-    private recordCapUsage;
-    /**
-     * The cap index over the CURRENT children, rebuilt on first use after any
-     * mutation of {@link children}.
-     *
-     * This replaced a linear walk of every child's cap manifest per
-     * `cap-call-out`, measured at **7.1 % of hub-main's busy main thread**
-     * across 39 children (D456). Why it did not exist before is the whole
-     * design: what it indexes moves — a runner is replaced on every update, a
-     * crash respawns one, a child re-registers with a replacement manifest after
-     * init — and an index that names a dead child routes work into a socket
-     * nobody is reading, which is strictly worse than a slow scan.
-     *
-     * So it is not maintained; it is DISCARDED. `buildCapChildIndex` is a pure
-     * function of `children.values()`, the only two writers of that map
-     * ({@link invalidateCapIndex}'s call sites) drop the index in the same
-     * statement, and nothing else can construct one. There is no add-on-register
-     * / remove-on-close path that could disagree with the map — i.e. no shadow
-     * registry (D3): the map remains the single authority and this holds no fact
-     * it does not.
-     *
-     * The operator's active-singleton preference is deliberately NOT indexed —
-     * it changes without any child connecting or leaving, so `resolveChildId`
-     * reads it live and the index only supplies the candidate list.
-     */
-    private capIndex;
-    /** Drop the derived index. MUST follow every write to {@link children}. */
-    private invalidateCapIndex;
-    /**
-     * Does the named child currently provide `(capName, deviceId?)`?
-     *
-     * Used by the hub proxy seam, which knows the EXACT addon (→ runner →
-     * childId) a provider belongs to. Unlike `resolveChildId` (which picks the
-     * first child owning `capName`), this targets one child — required for
-     * COLLECTION caps (`addon-widgets-source`, …) where many children register
-     * the same capName: routing by capName alone collapses every provider to
-     * the first child. Same deviceId-as-hint semantics as `resolveChildId`:
-     * a device-scoped descriptor matching `deviceId` OR a deviceId-less
-     * (singleton/collection) descriptor counts.
-     */
-    /**
-     * Is `childId` currently connected (has it completed its UDS handshake)?
-     * Coarser than {@link childProvides}: it answers "is the child reachable
-     * over UDS at all", regardless of which caps it has announced yet. Used by
-     * the route-mount fallback to decide between the handler-stripped
-     * `callAddonOnChild(target:'routes')` path (child reachable) and awaiting a
-     * cap proxy's `getRoutes()` (child not yet UDS-registered).
-     */
-    isChildKnown(childId: string): boolean;
-    childProvides(childId: string, capName: string, deviceId?: number): boolean;
-    /**
-     * Per-request options for a cap call: the cap method's declared `timeoutMs`
-     * when one exists, else `undefined` so the channel applies its default.
-     * Mirrors `CapRouteResolver.callTimeout` for the remote plane.
-     */
-    private capRequestOpts;
-    /** Forward a cap method call to a SPECIFIC child by id over UDS; rejects if that child is absent. */
-    callCapOnChild(childId: string, input: CapCallInput): Promise<unknown>;
-    /** Forward a cap method call to the owning child over UDS; rejects if none. */
-    callCap(input: CapCallInput): Promise<unknown>;
-    /**
-     * Forward an ADDON-LEVEL call (routes / custom-action) to a SPECIFIC child
-     * by id over UDS; rejects if that child is absent.
-     *
-     * The childId for a hub-local single-addon runner equals the addonId
-     * (`resolveRunnerId` returns the addonId when no `execution.group` is
-     * declared — no shipped addon declares one). Mirrors `callCapOnChild` for
-     * the cap plane; carries the two surfaces the removed per-addon Moleculer
-     * broker used to serve (`getRoutes` + `custom.<action>`).
-     */
-    callAddonOnChild(childId: string, input: AddonCallInput): Promise<unknown>;
-    /** Build the parent→child `addon-call` wire message from an addon-call input. */
-    private toAddonCall;
-    /** Build the parent→child `cap-call` wire message from a routing input. */
-    private toCapCall;
-    listChildren(): readonly RegisteredChild[];
-    /** Register the (single) child-registered handler. Only one handler is active at a time. */
-    onChildRegistered(handler: (child: RegisteredChild) => void): void;
-    /**
-     * Register the (single) child-gone handler. Only one handler is active at a
-     * time. The handler receives the {@link RegisteredChild.incarnation} of the
-     * connection that closed — carry it into whatever teardown it triggers, so a
-     * dead generation cannot tear down its successor's work.
-     */
-    onChildGone(handler: (childId: string, incarnation: number) => void): void;
-    /**
-     * Register the (single) child-event handler. Invoked when a child sends an
-     * event via `LocalChildClient.emitEvent`. Only one handler is active at a
-     * time; a new handler replaces the prior one. Pass `null` to clear the
-     * handler entirely (used by the UDS event bridge disposer on shutdown).
-     */
-    onChildEvent(handler: ((childId: string, event: SystemEvent) => void) | null): void;
-    /**
-     * Register the (single) child-log handler. Invoked when a child sends a log
-     * entry via `LocalChildClient.sendLog`. Only one handler is active.
-     */
-    onChildLog(handler: (childId: string, entry: ChildLogMessage) => void): void;
-    /**
-     * Register the handler that supplies the authoritative readiness snapshot
-     * when a child sends a `readiness-request`. Only one handler is active.
-     */
-    onReadinessSnapshotRequest(handler: () => readonly IReadinessRegistryRecord[]): void;
-    /**
-     * Push a parent→child event to a specific child. Fire-and-forget (uses the
-     * one-way `emit` path on the channel). No-op if the child is not connected.
-     */
-    sendEventToChild(childId: string, event: SystemEvent, sourceNodeId: string): void;
-    /**
-     * Push a parent→child event to every registered child, optionally skipping
-     * one (the originating child, to avoid echo). Fire-and-forget.
-     */
-    broadcastEventToChildren(event: SystemEvent, sourceNodeId: string, exceptChildId?: string): void;
-    /**
-     * Record one PRODUCED event against its category. Called once per broadcast,
-     * outside the per-child loop, because production is what the census measures.
-     */
-    private recordCategoryBroadcast;
-    /**
-     * E2: Send a `set-log-level` control message to a specific child.
-     * Returns `true` if the child is currently connected and the message was
-     * emitted; `false` if the child is not connected (no-op). The `false`
-     * return lets the caller (MoleculerService.setChildLogLevelByNodeId) fall
-     * back to the Moleculer `$node-mgmt.setLogLevel` action for the node.
-     * Mirrors the `$node-mgmt.setLogLevel` Moleculer action for UDS children.
-     */
-    setChildLogLevel(childId: string, level: string): boolean;
-    close(): Promise<void>;
-    /** `WorkerOnline`, once per incarnation: a re-register of the same connection says nothing. */
-    private announceOnline;
-    /** `WorkerOffline` for the LIVE connection's close (a superseded close never reaches here). */
-    private announceOffline;
-    private emitLifecycle;
-    private onConnection;
+	private readonly children;
+	private registeredHandler;
+	private goneHandler;
+	/** Source of {@link RegisteredChild.incarnation}; one bump per accepted connection. */
+	private nextIncarnation;
+	private eventHandler;
+	private logHandler;
+	private readinessHandler;
+	private readonly server;
+	private readonly onUnownedCall?;
+	private readonly logger?;
+	private readonly lifecycleEvents?;
+	/** Per childId: the incarnation `WorkerOnline` was last said for. */
+	private readonly announcedIncarnation;
+	private readonly getActiveSingletonAddonId?;
+	private readonly resolveChildIdForAddon?;
+	/** This node's own Moleculer nodeId (see {@link LocalChildRegistryOptions.ownNodeId}). */
+	private readonly ownNodeId?;
+	/** See {@link LocalChildRegistryOptions.isAggregatedCollectionMethod}. */
+	private readonly isAggregatedCollectionMethod?;
+	private readonly isAddonPinnedCall?;
+	/** See {@link ForwardCensus}. Mutable counters on the hot path, by design. */
+	private forwardedRaw;
+	private forwardedDecoded;
+	/**
+	* The per-ACTION byte census (D456). `ForwardCensus` above is the same
+	* question asked of the whole plane; this one asks it per `<cap>.<method>`,
+	* beside the bytes that method actually moved. Both are kept: `socketFwd=`
+	* says whether the negotiation is working at all, and a `raw=0` on ONE
+	* method with `raw>0` on its neighbours is a different fault.
+	*/
+	private readonly actionCensus;
+	/** See {@link LocalChildRegistryOptions.capTimeoutMs}. */
+	private readonly capTimeoutMs?;
+	/** See {@link LocalChildRegistryOptions.claimedStatus}. */
+	private readonly claimedStatus?;
+	/** See {@link LocalChildRegistryOptions.capUsageObserver}. */
+	private readonly capUsageObserver?;
+	/** Tracks capNames already logged as UDS-routed; one INFO line per capName per process. */
+	private readonly egressRoutedCaps;
+	/** Per-child event fan-out counters (sent / suppressed). */
+	private readonly childEventStats;
+	/** D467: per-category production census (cumulative). See {@link CategoryFanoutSample}. */
+	private readonly categoryStats;
+	/** Broadcasts whose category did not fit in {@link CATEGORY_CENSUS_MAX}. */
+	private categoryOverflow;
+	/** One INFO line the first time the census cap trips, never per event. */
+	private categoryOverflowLogged;
+	/** Last pattern-set string logged per child, to dedup the INFO line. */
+	private readonly loggedPatternSet;
+	/**
+	* Derived `(cap, device?) → child` index over {@link children}, or `null`
+	* when it must be rebuilt. See {@link capIndex} for why it is a cache and
+	* never a registry (D3, D457).
+	*/
+	private capChildIndex;
+	/**
+	* Accepts either a plain positional `server` argument (backward-compatible)
+	* or a full `LocalChildRegistryOptions` object.
+	*
+	* Positional overloads (existing call sites are unchanged):
+	*   new LocalChildRegistry(server)
+	*   new LocalChildRegistry(server, onUnownedCall)
+	*
+	* Options object (new call sites that pass a logger):
+	*   new LocalChildRegistry({ server, onUnownedCall, logger })
+	*/
+	constructor(serverOrOptions: LocalTransportServer | LocalChildRegistryOptions, onUnownedCallArg?: (input: CapCallInput) => Promise<unknown>);
+	start(): Promise<void>;
+	/**
+	* Per-child event fan-out counters (`{ sent, suppressed }`) or `null` if the
+	* child has no recorded events yet. Exposed for the starvation-verification
+	* surface (operator debug).
+	*/
+	getChildEventStats(childId: string): ChildEventStats | null;
+	/**
+	* D467: every category this node has broadcast, with its emit count and how
+	* many child subscriptions matched. Cumulative for the life of the process —
+	* the heartbeat differences it, the same discipline as the per-child
+	* counters. Largest `broadcasts` first.
+	*/
+	categoryFanout(): readonly CategoryFanoutSample[];
+	/** Broadcasts the census could not attribute because it was full (cumulative). */
+	categoryCensusOverflow(): number;
+	/**
+	* This child's socket traffic — bytes and messages, both directions, split by
+	* frame kind — or `null` when the child is gone or its channel keeps no
+	* counters (an in-process or test transport).
+	*
+	* The event counters above cover ONE kind of frame and, once surfaced on
+	* 2026-08-29, accounted for 4% of hub-main's ~44 000 socket syscalls/s. This
+	* is the same question asked of every frame the channel moves, and it is the
+	* only per-peer attribution that exists: `/proc` reports one `rchar`/`wchar`
+	* pair for the whole process and has no per-socket breakdown.
+	*/
+	getChildSocketTraffic(childId: string): SocketTrafficSample | null;
+	/**
+	* Bytes this process has written to a child that the child has not yet
+	* taken, live, or `null` when the channel keeps no such reading. Read on
+	* every heartbeat probe (D446) — a child that stops draining is the shape
+	* of an outbound-queue episode, and the number lives on the channel.
+	*/
+	getChildQueuedBytes(childId: string): number | null;
+	/** Cumulative {@link ForwardCensus} of this parent's `cap-call-out` routing. */
+	readForwardCensus(): ForwardCensus;
+	/**
+	* Cumulative per-action byte census: peer → `<cap>.<method>` → bytes, calls
+	* and the raw/decoded split. A COPY (`cap-action-census.ts` explains why it
+	* must be one); the heartbeat subtracts the previous reading.
+	*
+	* This is the instrument D454 closed by asking for. `socketTopBytes=` names
+	* the peer that moves the bytes and `txkB=` says they are responses; neither
+	* can say WHICH method originates them, and after raw-forward the bytes that
+	* cross are no longer the proxy for what hub-main pays — 85.7 % of sibling
+	* calls cross unread. What costs is what hub-main LOOKS at, and that is the
+	* `decoded` half of an entry, next to the bytes it carried.
+	*/
+	readActionCensus(): CapActionReading;
+	/**
+	* Connected children that never declared a subscription pattern set.
+	*
+	* Each one is a fail-open on BOTH planes: `childWantsEvent` returns true for
+	* an undeclared child ({@link ChildEntry.eventPatterns} `=== null`), and
+	* `aggregateEventInterest` returns `null` — accept everything — if ANY
+	* connected child is undeclared, which disables the node's inbound cross-node
+	* gate as well. **One legacy runner silently turns off the filtering for the
+	* whole node**, and nothing reported it, so a zero here is as load-bearing as
+	* a non-zero one.
+	*/
+	undeclaredChildCount(): number;
+	/**
+	* Does `entry` want to receive an event in `category`? Undeclared patterns
+	* (`null`) → always (fail-open, counted by {@link undeclaredChildCount});
+	* else the child's declared set must match via `matchesPattern` — the SAME
+	* function the child's own `deliverShared` map-key gate uses, giving provable
+	* delivery parity. The parent always filters: the `CAMSTACK_UDS_EVENT_FANOUT`
+	* shadow/broadcast modes were removed on 2026-10-06.
+	*
+	* NOTE: this gate must NOT consult `RING_BUFFER_DENY_PATTERNS` /
+	* `isHighFrequencyCategory` — those are ring-buffer STORAGE policy; a child
+	* that explicitly subscribes to a ring-denied category must still RECEIVE it.
+	*/
+	private childWantsEvent;
+	/**
+	* D2: this node's aggregate cross-node event interest — the UNION of every
+	* connected child's declared category patterns. Consumed by the parent's
+	* `$event-bus` inbound gate (via `setNodeEventInterest`) so the node only
+	* accepts cross-node (Moleculer) categories at least one local child wants.
+	*
+	* Returns `null` (fail-open — accept everything) when:
+	*   - NO child is currently connected (boot window before the first forked
+	*     child completes its UDS handshake, or every child has disconnected): a
+	*     node MUST NOT drop 100% of inbound cross-node events during that window,
+	*     and a child may connect imminently. This is distinct from the
+	*     declared-empty case below.
+	*   - ANY connected child is UNDECLARED (`eventPatterns === null`, a legacy
+	*     runner): a node cannot safely narrow its inbound set while a child's
+	*     real interest is unknown. Mirrors the per-child fail-open in
+	*     {@link childWantsEvent}, aggregated conservatively.
+	*
+	* Returns an EMPTY array only when ≥1 child is connected and EVERY connected
+	* child declared an explicit empty set — a genuine "wants nothing". Reads the
+	* live `children` map, so a child registering / disconnecting / sending
+	* `event-sub` is reflected on the next call with no extra bookkeeping.
+	*/
+	aggregateEventInterest(): readonly string[] | null;
+	private statsFor;
+	/** Deduped INFO line whenever a child's declared pattern set changes. */
+	private logPatternSet;
+	/**
+	* Child id that can service a call to `capName` (optionally addressing
+	* `deviceId`), or null.
+	*
+	* `deviceId` is a routing HINT, not a hard filter. A singleton cap
+	* (`pipeline-runner`, `stream-broker`, …) addresses devices through its
+	* METHOD ARGUMENTS — `attachCamera({ deviceId })` is one provider serving
+	* many cameras — so its descriptor carries no `deviceId`. Resolving on
+	* `deviceId` alone would never match it and would force the call onto the
+	* broker fallback (which then hangs in service discovery). Hence:
+	*   1. exact device-scoped owner (native per-device caps where each child
+	*      owns a disjoint device subset) is preferred, then
+	*   2. a singleton owner (deviceId-less descriptor) is the fallback.
+	* A cap is globally singleton XOR device-scoped, so the two tiers never
+	* compete for the same capName.
+	*/
+	resolveChildId(capName: string, deviceId?: number): string | null;
+	/**
+	* Publish one cap-usage observation, if a sink is wired.
+	*
+	* Cost discipline — this is on the hot path (D181: hub-main's event loop is
+	* the cluster's only queue): no sink means one undefined check; with a sink
+	* it is one object literal and one `Date.now()`, and the sink itself is O(1).
+	* Wrapped so a broken observer can never fail the call it observes — the
+	* registry swallows too, and BOTH matter: this catch also covers a sink that
+	* is not the registry.
+	*/
+	private recordCapUsage;
+	/**
+	* The cap index over the CURRENT children, rebuilt on first use after any
+	* mutation of {@link children}.
+	*
+	* This replaced a linear walk of every child's cap manifest per
+	* `cap-call-out`, measured at **7.1 % of hub-main's busy main thread**
+	* across 39 children (D456). Why it did not exist before is the whole
+	* design: what it indexes moves — a runner is replaced on every update, a
+	* crash respawns one, a child re-registers with a replacement manifest after
+	* init — and an index that names a dead child routes work into a socket
+	* nobody is reading, which is strictly worse than a slow scan.
+	*
+	* So it is not maintained; it is DISCARDED. `buildCapChildIndex` is a pure
+	* function of `children.values()`, the only two writers of that map
+	* ({@link invalidateCapIndex}'s call sites) drop the index in the same
+	* statement, and nothing else can construct one. There is no add-on-register
+	* / remove-on-close path that could disagree with the map — i.e. no shadow
+	* registry (D3): the map remains the single authority and this holds no fact
+	* it does not.
+	*
+	* The operator's active-singleton preference is deliberately NOT indexed —
+	* it changes without any child connecting or leaving, so `resolveChildId`
+	* reads it live and the index only supplies the candidate list.
+	*/
+	private capIndex;
+	/** Drop the derived index. MUST follow every write to {@link children}. */
+	private invalidateCapIndex;
+	/**
+	* Does the named child currently provide `(capName, deviceId?)`?
+	*
+	* Used by the hub proxy seam, which knows the EXACT addon (→ runner →
+	* childId) a provider belongs to. Unlike `resolveChildId` (which picks the
+	* first child owning `capName`), this targets one child — required for
+	* COLLECTION caps (`addon-widgets-source`, …) where many children register
+	* the same capName: routing by capName alone collapses every provider to
+	* the first child. Same deviceId-as-hint semantics as `resolveChildId`:
+	* a device-scoped descriptor matching `deviceId` OR a deviceId-less
+	* (singleton/collection) descriptor counts.
+	*/
+	/**
+	* Is `childId` currently connected (has it completed its UDS handshake)?
+	* Coarser than {@link childProvides}: it answers "is the child reachable
+	* over UDS at all", regardless of which caps it has announced yet. Used by
+	* the route-mount fallback to decide between the handler-stripped
+	* `callAddonOnChild(target:'routes')` path (child reachable) and awaiting a
+	* cap proxy's `getRoutes()` (child not yet UDS-registered).
+	*/
+	isChildKnown(childId: string): boolean;
+	childProvides(childId: string, capName: string, deviceId?: number): boolean;
+	/**
+	* Per-request options for a cap call: the cap method's declared `timeoutMs`
+	* when one exists, else `undefined` so the channel applies its default.
+	* Mirrors `CapRouteResolver.callTimeout` for the remote plane.
+	*/
+	private capRequestOpts;
+	/** Forward a cap method call to a SPECIFIC child by id over UDS; rejects if that child is absent. */
+	callCapOnChild(childId: string, input: CapCallInput): Promise<unknown>;
+	/** Forward a cap method call to the owning child over UDS; rejects if none. */
+	callCap(input: CapCallInput): Promise<unknown>;
+	/**
+	* Forward an ADDON-LEVEL call (routes / custom-action) to a SPECIFIC child
+	* by id over UDS; rejects if that child is absent.
+	*
+	* The childId for a hub-local single-addon runner equals the addonId
+	* (`resolveRunnerId` returns the addonId when no `execution.group` is
+	* declared — no shipped addon declares one). Mirrors `callCapOnChild` for
+	* the cap plane; carries the two surfaces the removed per-addon Moleculer
+	* broker used to serve (`getRoutes` + `custom.<action>`).
+	*/
+	callAddonOnChild(childId: string, input: AddonCallInput): Promise<unknown>;
+	/** Build the parent→child `addon-call` wire message from an addon-call input. */
+	private toAddonCall;
+	/** Build the parent→child `cap-call` wire message from a routing input. */
+	private toCapCall;
+	listChildren(): readonly RegisteredChild[];
+	/** Register the (single) child-registered handler. Only one handler is active at a time. */
+	onChildRegistered(handler: (child: RegisteredChild) => void): void;
+	/**
+	* Register the (single) child-gone handler. Only one handler is active at a
+	* time. The handler receives the {@link RegisteredChild.incarnation} of the
+	* connection that closed — carry it into whatever teardown it triggers, so a
+	* dead generation cannot tear down its successor's work.
+	*/
+	onChildGone(handler: (childId: string, incarnation: number) => void): void;
+	/**
+	* Register the (single) child-event handler. Invoked when a child sends an
+	* event via `LocalChildClient.emitEvent`. Only one handler is active at a
+	* time; a new handler replaces the prior one. Pass `null` to clear the
+	* handler entirely (used by the UDS event bridge disposer on shutdown).
+	*/
+	onChildEvent(handler: ((childId: string, event: SystemEvent) => void) | null): void;
+	/**
+	* Register the (single) child-log handler. Invoked when a child sends a log
+	* entry via `LocalChildClient.sendLog`. Only one handler is active.
+	*/
+	onChildLog(handler: (childId: string, entry: ChildLogMessage) => void): void;
+	/**
+	* Register the handler that supplies the authoritative readiness snapshot
+	* when a child sends a `readiness-request`. Only one handler is active.
+	*/
+	onReadinessSnapshotRequest(handler: () => readonly IReadinessRegistryRecord[]): void;
+	/**
+	* Push a parent→child event to a specific child. Fire-and-forget (uses the
+	* one-way `emit` path on the channel). No-op if the child is not connected.
+	*/
+	sendEventToChild(childId: string, event: SystemEvent, sourceNodeId: string): void;
+	/**
+	* Push a parent→child event to every registered child, optionally skipping
+	* one (the originating child, to avoid echo). Fire-and-forget.
+	*/
+	broadcastEventToChildren(event: SystemEvent, sourceNodeId: string, exceptChildId?: string): void;
+	/**
+	* Record one PRODUCED event against its category. Called once per broadcast,
+	* outside the per-child loop, because production is what the census measures.
+	*/
+	private recordCategoryBroadcast;
+	/**
+	* E2: Send a `set-log-level` control message to a specific child.
+	* Returns `true` if the child is currently connected and the message was
+	* emitted; `false` if the child is not connected (no-op). The `false`
+	* return lets the caller (MoleculerService.setChildLogLevelByNodeId) fall
+	* back to the Moleculer `$node-mgmt.setLogLevel` action for the node.
+	* Mirrors the `$node-mgmt.setLogLevel` Moleculer action for UDS children.
+	*/
+	setChildLogLevel(childId: string, level: string): boolean;
+	close(): Promise<void>;
+	/** `WorkerOnline`, once per incarnation: a re-register of the same connection says nothing. */
+	private announceOnline;
+	/** `WorkerOffline` for the LIVE connection's close (a superseded close never reaches here). */
+	private announceOffline;
+	private emitLifecycle;
+	private onConnection;
 }