@camstack/system 1.2.313 → 1.2.314

package/dist/{child-cap-dispatch-CHTiHbsv.mjs → child-cap-dispatch-AAltfBUH.mjs}

@@ -4631,31 +4631,6 @@ function buildNativeCapProxy(broker, addonId, capName, deviceId) {
 		};
 	} });
 }
-/**
-* Hub-side proxy for a device-scoped native cap whose owning runner is a
-* HUB-LOCAL forked child reachable over UDS. Mirrors {@link buildNativeCapProxy}
-* but dispatches via `LocalChildRegistry.callCapOnChild` (UDS) instead of
-* `broker.call` — the child no longer hosts a Moleculer service after the UDS
-* cutover, so a broker call fails "is not found". The `deviceId` is merged into
-* the method args (provider convention) and carried as the routing field.
-*/
-function buildUdsNativeCapProxy(registry, childId, capName, deviceId) {
-	return new Proxy({}, { get(_target, property) {
-		if (typeof property !== "string") return void 0;
-		return (input) => {
-			const mergedInput = typeof input === "object" && input !== null ? {
-				...input,
-				deviceId
-			} : { deviceId };
-			return registry.callCapOnChild(childId, {
-				capName,
-				method: property,
-				args: mergedInput,
-				deviceId
-			});
-		};
-	} });
-}
 function buildDeviceOpsProvider(device) {
 	const assertMatch = (incoming) => {
 		if (incoming !== device.id) throw new Error(`device-ops: deviceId mismatch — expected '${device.id}', got '${incoming}'`);
@@ -4841,6 +4816,61 @@ function createBrokerDeviceManagerApi(opts) {
 					generation: nativeCapReadinessGeneration,
 					sourceNodeId: nodeId
 				});
+			},
+			unregisterNativeCap(capName) {
+				const worker = opts.capabilityRegistry === void 0 && (opts.broker !== void 0 || opts.udsMode === true);
+				if (!opts.capabilityRegistry && !worker) throw new Error(`DeviceContext.unregisterNativeCap('${capName}') called on '${stableId}' but none of capabilityRegistry / broker / udsMode was provided.`);
+				const holder = opts.capabilityRegistry ? opts.capabilityRegistry.getNativeAddonId(capName, id) : workerNativeCapAddonIds.get(capName)?.get(id) ?? null;
+				const staleRetract = worker && holder === null;
+				if (holder !== addonId && !staleRetract) {
+					opts.logger.debug("unregisterNativeCap: the cap is not registered by this addon — no-op", {
+						tags: {
+							deviceId: id,
+							addonId
+						},
+						meta: { capName }
+					});
+					return;
+				}
+				if (staleRetract) opts.logger.info("unregisterNativeCap: retracting a binding this process never registered (a previous incarnation of the addon)", {
+					tags: {
+						deviceId: id,
+						addonId
+					},
+					meta: { capName }
+				});
+				else if (opts.capabilityRegistry) opts.capabilityRegistry.unregisterNativeProvider(capName, id);
+				else {
+					workerNativeCaps.get(capName)?.delete(id);
+					workerNativeCapAddonIds.get(capName)?.delete(id);
+					onWorkerNativeCapsChanged?.();
+				}
+				eventBus.emit({
+					id: randomUUID(),
+					timestamp: /* @__PURE__ */ new Date(),
+					source: {
+						type: "device",
+						id
+					},
+					category: EventCategory.DeviceBindingsChanged,
+					data: {
+						deviceId: id,
+						capName,
+						reason: "native-unregistered",
+						addonId,
+						nodeId
+					}
+				});
+				emitReadiness(eventBus, {
+					capName,
+					scope: {
+						type: "device",
+						deviceId: id
+					},
+					state: "down",
+					generation: nativeCapReadinessGeneration,
+					sourceNodeId: nodeId
+				});
 			}
 		};
 	};
@@ -7981,1536 +8011,1566 @@ function liftRoutingHints(args) {
 		...typeof deviceId === "number" && Number.isFinite(deviceId) ? { deviceId } : {}
 	};
 }
-function readFanoutMode() {
-	const raw = process.env.CAMSTACK_UDS_EVENT_FANOUT;
-	if (raw === "shadow" || raw === "broadcast") return raw;
-	return "filter";
+//#endregion
+//#region src/kernel/moleculer/resilient-cap-call.ts
+/** Moleculer error `type` values meaning "the service is not (yet) routable". */
+var DISCOVERY_ERROR_TYPES = new Set(["SERVICE_NOT_FOUND", "SERVICE_NOT_AVAILABLE"]);
+/** Default ceiling for the discovery wait — fail-fast past this. */
+var DEFAULT_DISCOVERY_TIMEOUT_MS$1 = 3e4;
+function isDiscoveryError(err) {
+	if (typeof err !== "object" || err === null) return false;
+	const type = err.type;
+	return typeof type === "string" && DISCOVERY_ERROR_TYPES.has(type);
 }
 /**
-* 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).
-*/
-var UDS_NO_ROUTE_PREFIX = "UDS_NO_ROUTE";
-/**
-* 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.
+* Call a Moleculer action; on a service-discovery error, wait for the
+* named service to be discovered and retry the call exactly once.
 */
-var LocalChildRegistry = class {
-	children = /* @__PURE__ */ new Map();
-	registeredHandler = () => {};
-	goneHandler = () => {};
-	/** Source of {@link RegisteredChild.incarnation}; one bump per accepted connection. */
-	nextIncarnation = 1;
-	eventHandler = null;
-	logHandler = null;
-	readinessHandler = null;
-	server;
-	onUnownedCall;
-	logger;
-	getActiveSingletonAddonId;
-	resolveChildIdForAddon;
-	/** This node's own Moleculer nodeId (see {@link LocalChildRegistryOptions.ownNodeId}). */
-	ownNodeId;
-	/** See {@link LocalChildRegistryOptions.isAggregatedCollectionMethod}. */
-	isAggregatedCollectionMethod;
-	isAddonPinnedCall;
-	/** See {@link ForwardCensus}. Mutable counters on the hot path, by design. */
-	forwardedRaw = 0;
-	forwardedDecoded = 0;
-	/**
-	* 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.
-	*/
-	actionCensus = createCapActionCensus();
-	/** See {@link LocalChildRegistryOptions.capTimeoutMs}. */
-	capTimeoutMs;
-	/** See {@link LocalChildRegistryOptions.capUsageObserver}. */
-	capUsageObserver;
-	/** Tracks capNames already logged as UDS-routed; one INFO line per capName per process. */
-	egressRoutedCaps = /* @__PURE__ */ new Set();
-	/** Active event fan-out mode, read once from `CAMSTACK_UDS_EVENT_FANOUT`. */
-	fanoutMode = readFanoutMode();
-	/** Per-child event fan-out counters (sent / suppressed). */
-	childEventStats = /* @__PURE__ */ new Map();
-	/** D467: per-category production census (cumulative). See {@link CategoryFanoutSample}. */
-	categoryStats = /* @__PURE__ */ new Map();
-	/** Broadcasts whose category did not fit in {@link CATEGORY_CENSUS_MAX}. */
-	categoryOverflow = 0;
-	/** One INFO line the first time the census cap trips, never per event. */
-	categoryOverflowLogged = false;
-	/** Last pattern-set string logged per child, to dedup the INFO line. */
-	loggedPatternSet = /* @__PURE__ */ new Map();
-	/**
-	* 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).
-	*/
-	capChildIndex = null;
-	/**
-	* 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, onUnownedCallArg) {
-		if (serverOrOptions && !("listen" in serverOrOptions)) {
-			const opts = serverOrOptions;
-			this.server = opts.server;
-			this.onUnownedCall = opts.onUnownedCall;
-			this.logger = opts.logger;
-			this.getActiveSingletonAddonId = opts.getActiveSingletonAddonId;
-			this.resolveChildIdForAddon = opts.resolveChildIdForAddon;
-			this.ownNodeId = opts.ownNodeId;
-			this.isAggregatedCollectionMethod = opts.isAggregatedCollectionMethod;
-			this.isAddonPinnedCall = opts.isAddonPinnedCall;
-			this.capTimeoutMs = opts.capTimeoutMs;
-			this.capUsageObserver = opts.capUsageObserver;
-		} else {
-			this.server = serverOrOptions;
-			this.onUnownedCall = onUnownedCallArg;
-		}
-	}
-	async start() {
-		this.logger?.info("UDS event fan-out mode", { mode: this.fanoutMode });
-		this.server.onConnection((channel) => this.onConnection(channel));
-		await this.server.listen();
-	}
-	/**
-	* Per-child event fan-out counters (`{ sent, suppressed }`) or `null` if the
-	* child has no recorded events yet. Exposed for the starvation-verification
-	* surface (shadow burn-in + operator debug).
-	*/
-	getChildEventStats(childId) {
-		const s = this.childEventStats.get(childId);
-		return s === void 0 ? null : {
-			sent: s.sent,
-			suppressed: s.suppressed
-		};
-	}
-	/**
-	* 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() {
-		const out = [];
-		for (const [category, s] of this.categoryStats) out.push({
-			category,
-			broadcasts: s.broadcasts,
-			wanted: s.wanted
-		});
-		return out.toSorted((a, b) => b.broadcasts - a.broadcasts || a.category.localeCompare(b.category));
-	}
-	/** Broadcasts the census could not attribute because it was full (cumulative). */
-	categoryCensusOverflow() {
-		return this.categoryOverflow;
-	}
-	/**
-	* 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) {
-		const entry = this.children.get(childId);
-		if (entry === void 0) return null;
-		return entry.channel.readTraffic?.() ?? null;
+async function callWithServiceDiscovery(broker, serviceName, action, params, opts, discoveryTimeoutMs = DEFAULT_DISCOVERY_TIMEOUT_MS$1) {
+	try {
+		return await broker.call(action, params, opts);
+	} catch (err) {
+		if (!isDiscoveryError(err)) throw err;
+		await broker.waitForServices([serviceName], discoveryTimeoutMs);
+		return await broker.call(action, params, opts);
 	}
+}
+//#endregion
+//#region src/kernel/transport/cap-route.ts
+function buildMessage(capName, method, detail) {
+	const call = method !== void 0 ? `${capName}.${method}` : capName;
+	const target = detail.nodeId !== void 0 ? ` to node ${detail.nodeId}` : "";
+	const rejectedStr = detail.rejected.map((r) => `${r.kind}=${r.why}`).join("; ");
+	const rejectedClause = rejectedStr.length > 0 ? ` (rejected: ${rejectedStr})` : "";
+	return `${call} not routable${target}: ${detail.reason}${rejectedClause}`;
+}
+var CapRouteError = class extends Error {
+	reason;
+	nodeId;
+	rejected;
 	/**
-	* 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.
+	* @param cause  Optional original error that triggered this routing failure.
+	*               Stored as `Error.cause` (TC39 standard option, Node 16.9+).
+	*               Dispatchers wrapping transport errors MUST pass the original.
 	*/
-	getChildQueuedBytes(childId) {
-		const entry = this.children.get(childId);
-		if (entry === void 0) return null;
-		return entry.channel.queuedBytes?.() ?? null;
+	constructor(capName, method, detail, cause) {
+		super(buildMessage(capName, method, detail), cause !== void 0 ? { cause } : void 0);
+		this.name = "CapRouteError";
+		this.reason = detail.reason;
+		this.nodeId = detail.nodeId;
+		this.rejected = detail.rejected;
 	}
-	/** Cumulative {@link ForwardCensus} of this parent's `cap-call-out` routing. */
-	readForwardCensus() {
-		return {
-			raw: this.forwardedRaw,
-			decoded: this.forwardedDecoded
-		};
-	}
-	/**
-	* 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() {
-		return this.actionCensus.read();
-	}
-	/**
-	* The regime the counters above were produced under, read once from
-	* `CAMSTACK_UDS_EVENT_FANOUT` at construction.
-	*
-	* A suppressed count means "nothing WAS dropped" under `filter` and "nothing
-	* WOULD have been dropped" under `shadow`. Those are different claims, and
-	* until this getter existed the mode was invisible at runtime — the counters
-	* were readable and the regime that produced them was not.
-	*/
-	get eventFanoutMode() {
-		return this.fanoutMode;
-	}
-	/**
-	* 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() {
-		let count = 0;
-		for (const entry of this.children.values()) if (entry.eventPatterns === null) count += 1;
-		return count;
-	}
-	/**
-	* Does `entry` want to receive an event in `category`? Honours the fan-out
-	* mode: `broadcast` → always; undeclared patterns (`null`) → always
-	* (fail-open); 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. `shadow` is handled by the caller (it
-	* counts the would-suppress but still sends).
-	*
-	* 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.
-	*/
-	childWantsEvent(entry, category) {
-		if (this.fanoutMode === "broadcast") return true;
-		return this.childSubscribesTo(entry, category);
-	}
-	/**
-	* The SUBSCRIPTION answer alone, with no fan-out-mode override.
-	*
-	* {@link childWantsEvent} answers "will this child be sent the event", which
-	* under `broadcast` is `true` for everything and therefore cannot say whether
-	* anyone actually asked. The D467 census needs the second question, so the
-	* two are separate functions and `broadcast` mode overrides only the first.
-	*/
-	childSubscribesTo(entry, category) {
-		if (entry.eventPatterns === null) return true;
-		return entry.eventPatterns.some((p) => matchesPattern(p, category));
-	}
-	/**
-	* 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() {
-		if (this.children.size === 0) return null;
-		const union = /* @__PURE__ */ new Set();
-		for (const entry of this.children.values()) {
-			if (entry.eventPatterns === null) return null;
-			for (const p of entry.eventPatterns) union.add(p);
+};
+/**
+* Classifies a (capName, opts) pair into a typed CapRoute dispatch descriptor.
+*
+* Precedence (explicit nodeId path):
+*   1. hub-in-process — hub node + hubInProcessProvides
+*   2. hub-local-uds  — hub node + hubLocalChildProvides
+*   3. node-offline   → CapRouteError{reason:'node-offline'}
+*   4. agent-child-forward — node is an agent AND nodeKnowsCap
+*   5. remote-moleculer — any other online non-agent node
+*
+* Singleton path (no nodeId):
+*   1. hub-in-process (hub provides in-process)
+*   2. hub-local-uds  (a hub-local UDS child provides it)
+*   3. remote-moleculer (any online, non-hub node that knows it)
+*   4. → CapRouteError{reason:'no-provider', rejected: all considered routes}
+*
+* PURE: no side effects, no async, no broker/registry imports.
+*/
+function classifyCapRoute(capName, opts, snapshot) {
+	const rejected = [];
+	if (opts.nodeId !== void 0) return classifyExplicitNode(capName, opts.nodeId, opts.deviceId, snapshot, rejected);
+	return classifySingleton(capName, opts.deviceId, snapshot, rejected);
+}
+function classifyExplicitNode(capName, nodeId, deviceId, snap, rejected) {
+	if (nodeId === snap.hubNodeId) {
+		const residentProvides = snap.hubResidentProvides;
+		const providesOnHub = residentProvides ?? snap.hubInProcessProvides;
+		const getRef = residentProvides !== void 0 ? snap.getHubResidentProviderRef : snap.getInProcessProviderRef;
+		if (providesOnHub(capName)) {
+			const ref = getRef?.(capName) ?? null;
+			if (ref !== null) return {
+				kind: "hub-in-process",
+				capName,
+				ref
+			};
+			rejected.push({
+				kind: "hub-in-process",
+				why: "provider ref not available in snapshot"
+			});
+			throw new CapRouteError(capName, void 0, {
+				reason: "no-provider",
+				nodeId,
+				rejected
+			});
 		}
-		return [...union];
-	}
-	statsFor(childId) {
-		let s = this.childEventStats.get(childId);
-		if (s === void 0) {
-			s = {
-				sent: 0,
-				suppressed: 0
+		if (snap.hubLocalChildProvides(capName, deviceId)) {
+			const childId = snap.getHubLocalChildId?.(capName, deviceId) ?? null;
+			if (childId !== null) return {
+				kind: "hub-local-uds",
+				capName,
+				childId
 			};
-			this.childEventStats.set(childId, s);
+			rejected.push({
+				kind: "hub-local-uds",
+				why: "child id not resolvable from snapshot"
+			});
+			throw new CapRouteError(capName, void 0, {
+				reason: "no-provider",
+				nodeId,
+				rejected
+			});
 		}
-		return s;
+		rejected.push({
+			kind: "hub-in-process",
+			why: "hub does not provide this cap in-process"
+		});
+		rejected.push({
+			kind: "hub-local-uds",
+			why: "no hub-local child provides this cap"
+		});
+		throw new CapRouteError(capName, void 0, {
+			reason: "no-provider",
+			nodeId,
+			rejected
+		});
 	}
-	/** Deduped INFO line whenever a child's declared pattern set changes. */
-	logPatternSet(childId, patterns) {
-		const key = patterns === null ? "<undeclared>" : JSON.stringify([...patterns].toSorted());
-		if (this.loggedPatternSet.get(childId) === key) return;
-		this.loggedPatternSet.set(childId, key);
-		this.logger?.info("child event patterns", {
-			childId,
-			patterns: patterns ?? null
+	if (!snap.nodeOnline(nodeId)) {
+		rejected.push({
+			kind: "remote-moleculer",
+			why: `node ${nodeId} is offline`
+		});
+		throw new CapRouteError(capName, void 0, {
+			reason: "node-offline",
+			nodeId,
+			rejected
 		});
 	}
-	/**
-	* 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, deviceId) {
-		const index = this.capIndex();
-		if (deviceId !== void 0) {
-			const deviceOwner = index.deviceOwner(capName, deviceId);
-			if (deviceOwner !== null) return deviceOwner;
-		}
-		const candidates = index.singletonCandidates(capName);
-		if (candidates.length === 0) return null;
-		if (candidates.length === 1) return candidates[0];
-		const preferredAddonId = this.getActiveSingletonAddonId?.(capName) ?? null;
-		if (preferredAddonId !== null) {
-			const preferredChildId = this.resolveChildIdForAddon?.(preferredAddonId) ?? preferredAddonId;
-			if (candidates.includes(preferredChildId)) return preferredChildId;
-		}
-		return candidates[0];
+	if (snap.nodeIsAgent(nodeId)) {
+		if (snap.nodeKnowsCap(nodeId, capName)) return {
+			kind: "agent-child-forward",
+			capName,
+			agentNodeId: nodeId,
+			childId: snap.getAgentChildId?.(nodeId, capName) ?? void 0
+		};
+		rejected.push({
+			kind: "agent-child-forward",
+			why: `agent ${nodeId} does not know cap ${capName}`
+		});
+		throw new CapRouteError(capName, void 0, {
+			reason: "no-provider",
+			nodeId,
+			rejected
+		});
 	}
-	/**
-	* 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.
-	*/
-	recordCapUsage(callerChildId, providerChildId, capName, methodName) {
-		const sink = this.capUsageObserver;
-		if (sink === void 0 || callerChildId === null) return;
-		try {
-			sink({
-				callerAddonId: callerChildId,
-				providerAddonId: providerChildId ?? "(unresolved: parent-routed)",
-				capName,
-				methodName,
-				atMs: Date.now()
-			});
-		} catch {}
+	return {
+		kind: "remote-moleculer",
+		capName,
+		nodeId
+	};
+}
+function classifySingleton(capName, deviceId, snap, rejected) {
+	if (snap.hubInProcessProvides(capName)) {
+		const ref = snap.getInProcessProviderRef?.(capName) ?? null;
+		if (ref !== null) return {
+			kind: "hub-in-process",
+			capName,
+			ref
+		};
+		rejected.push({
+			kind: "hub-in-process",
+			why: "provider ref not available in snapshot"
+		});
+	} else rejected.push({
+		kind: "hub-in-process",
+		why: "hub does not provide this cap in-process"
+	});
+	if (snap.hubLocalChildProvides(capName, deviceId)) {
+		const childId = snap.getHubLocalChildId?.(capName, deviceId) ?? null;
+		if (childId !== null) return {
+			kind: "hub-local-uds",
+			capName,
+			childId
+		};
+		rejected.push({
+			kind: "hub-local-uds",
+			why: "child id not resolvable from snapshot"
+		});
+	} else rejected.push({
+		kind: "hub-local-uds",
+		why: "no hub-local child provides this cap"
+	});
+	const knownNodes = snap.listKnownNodeIds?.() ?? [];
+	for (const nodeId of knownNodes) if (nodeId !== snap.hubNodeId && snap.nodeOnline(nodeId) && snap.nodeKnowsCap(nodeId, capName)) return {
+		kind: "remote-moleculer",
+		capName,
+		nodeId
+	};
+	rejected.push({
+		kind: "remote-moleculer",
+		why: "no online remote node knows this cap"
+	});
+	throw new CapRouteError(capName, void 0, {
+		reason: "no-provider",
+		rejected
+	});
+}
+//#endregion
+//#region src/kernel/transport/cap-route-resolver.ts
+/** The Moleculer service name that Task 6's agent registers. */
+var AGENT_CAP_FWD_SERVICE = "$agent-cap-fwd";
+/** The Moleculer action (service.action) for agent cap forwarding. */
+var AGENT_CAP_FWD_ACTION = `${AGENT_CAP_FWD_SERVICE}.forward`;
+/** Default timeout for remote Moleculer cap calls (ms). */
+var REMOTE_CALL_TIMEOUT_MS = 6e4;
+function extractDeviceId(args) {
+	if (args === null || typeof args !== "object") return void 0;
+	const raw = Reflect.get(args, "deviceId");
+	return typeof raw === "number" ? raw : void 0;
+}
+/**
+* Extract an inline `nodeId` string from a cap call's args — the per-call node
+* pin a forked addon expresses by carrying `nodeId` in the input (the SAME way
+* device-scoped caps carry `deviceId`, and the way the generated cap-router on
+* the hub already honours an inline pin). Mirrors {@link extractDeviceId}.
+*
+* This is the routing source for hub→remote-node EXECUTION pinning (e.g. the
+* benchmark addon running a synthetic/decoder workload ON a chosen agent). The
+* out-of-band `nodePin(op.context)` path does NOT survive the forked addon →
+* hub UDS link chain, so `onUnownedCall` reads the inline pin instead. Provider
+* methods that don't declare `nodeId` simply ignore the extra field (they
+* destructure the fields they need); methods that DO declare it (e.g.
+* `getEngineProvisioning({nodeId})`) still receive it unchanged.
+*/
+function extractNodeId(args) {
+	if (args === null || typeof args !== "object") return void 0;
+	const raw = Reflect.get(args, "nodeId");
+	return typeof raw === "string" && raw.length > 0 ? raw : void 0;
+}
+/**
+* Merge `callerAddonId` into `args` as an extra field — the SAME "provider
+* destructures what it needs and ignores the rest" convention
+* {@link extractNodeId} already relies on for the inline `nodeId` pin.
+* `undefined` (the overwhelmingly common case: no caller hint, or the census
+* consuming it is disarmed) returns `args` unchanged — no allocation. A
+* non-object `args` (or `null`/array) is returned unchanged too: there is
+* nowhere to attach an extra key without changing the payload's shape, and a
+* provider taking a bare value never reads `callerAddonId` off it anyway.
+*/
+function withCallerAddonId(args, callerAddonId) {
+	if (callerAddonId === void 0) return args;
+	if (args === null || typeof args !== "object" || Array.isArray(args)) return args;
+	return {
+		...args,
+		callerAddonId
+	};
+}
+var CapRouteResolver = class {
+	hubNodeId;
+	broker;
+	hubLocalRegistry;
+	nodeAuthority;
+	inProcessProviders;
+	hubResidentProviders;
+	capTimeoutMs;
+	snapshot;
+	constructor(deps) {
+		this.hubNodeId = deps.hubNodeId;
+		this.broker = deps.broker;
+		this.hubLocalRegistry = deps.hubLocalRegistry;
+		this.nodeAuthority = deps.nodeAuthority;
+		this.inProcessProviders = deps.inProcessProviders;
+		this.hubResidentProviders = deps.hubResidentProviders;
+		this.capTimeoutMs = deps.capTimeoutMs;
+		this.snapshot = this.buildSnapshot();
+	}
+	/** Per-call RPC timeout: the cap method's declared override, else the default. */
+	callTimeout(capName, method) {
+		return this.capTimeoutMs?.(capName, method) ?? REMOTE_CALL_TIMEOUT_MS;
+	}
+	resolveCapRoute(capName, opts) {
+		return classifyCapRoute(capName, opts, this.snapshot);
 	}
 	/**
-	* 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.
+	* Resolve the hub-local-uds route for a cap owned by a forked hub-local
+	* child, IGNORING any in-hub provider registered for the same cap name.
 	*
-	* 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.
+	* `resolveCapRoute` gives Priority 1 to `hub-in-process`: when an in-hub
+	* provider (e.g. a wrapper) is registered for the cap, the route always
+	* classifies as `hub-in-process` and the hub-local-uds NATIVE child is never
+	* reached. That is correct for the generic dispatch path (the wrapper is the
+	* active provider), but WRONG for the native-cap fallback
+	* (`setNativeFallback`), whose contract is to reach the NATIVE provider in
+	* the forked vendor child so a wrapper can delegate to it. A wrapper cap
+	* with a forked native (today: `snapshot`) otherwise resolves to the wrapper
+	* itself, the native is never invoked, and the wrapper silently falls
+	* through to its secondary strategy.
 	*
-	* 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.
+	* This method consults ONLY the hub-local-child authority
+	* (`hubLocalChildProvides` + `getHubLocalChildId`, both deviceId-aware), so
+	* it returns the native child route regardless of any in-process shadow.
+	* Returns null when no hub-local child owns `(capName, deviceId)` — the
+	* caller then falls through to its remote-resolution branch.
 	*/
-	capIndex() {
-		if (this.capChildIndex === null) this.capChildIndex = buildCapChildIndex(this.children.values());
-		return this.capChildIndex;
-	}
-	/** Drop the derived index. MUST follow every write to {@link children}. */
-	invalidateCapIndex() {
-		this.capChildIndex = null;
+	resolveHubLocalUdsRoute(capName, deviceId) {
+		if (!this.snapshot.hubLocalChildProvides(capName, deviceId)) return null;
+		const childId = this.snapshot.getHubLocalChildId?.(capName, deviceId) ?? null;
+		if (childId === null) return null;
+		return {
+			kind: "hub-local-uds",
+			capName,
+			childId
+		};
 	}
 	/**
-	* 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.
+	* @param addonId Optional out-of-band PROVIDER-selection hint (Task 7.5a):
+	*   the addonId of the provider the CALLER already resolved (e.g.
+	*   `buildCapCallFn`'s `deps.addonId` for a registered grouped-runner
+	*   provider). Only meaningful for `agent-child-forward` — a `remote-moleculer`
+	*   route already encodes the provider in its action name
+	*   (`${addonId}.${cap}.${method}`, via `NodeCapAuthority.getAddonId`), and a
+	*   `hub-local-uds` caller that already knows the addonId (`buildCapCallFn`)
+	*   talks to `LocalChildRegistry.callCapOnChild` directly rather than through
+	*   `dispatch`.
+	* @param callerAddonId Optional out-of-band CALLER-identity hint — the
+	*   addon that ORIGINATED the call, distinct from `addonId` above (which
+	*   names the resolved PROVIDER, not the caller). Set by
+	*   `onUnownedCall` from `CapCallInput.callerAddonId`
+	*   (`LocalChildRegistry` stamped it off the registered `childId`). Only
+	*   the `hub-in-process` branch consumes it — merged into `args` so a
+	*   diagnostic tool deep in that provider (e.g. device-manager's
+	*   fleet-read census) can read it without every provider method changing
+	*   signature, the same "extra field the provider destructures or
+	*   ignores" convention `nodeId` already uses on this path.
 	*/
+	async dispatch(route, method, args, addonId, callerAddonId) {
+		try {
+			return await this.dispatchInner(route, method, args, addonId, callerAddonId);
+		} catch (err) {
+			if (err instanceof CapRouteError) throw err;
+			if (route.kind === "hub-in-process" || err instanceof PeerAnsweredError) throw err;
+			const nodeId = this.routeNodeId(route);
+			const cause = err instanceof Error ? err : new Error(String(err));
+			throw new CapRouteError(route.capName, method, {
+				reason: "transport-failed",
+				nodeId,
+				rejected: [{
+					kind: route.kind,
+					why: cause.message
+				}]
+			}, cause);
+		}
+	}
 	/**
-	* 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).
+	* Inner dispatch: may throw CapRouteError (validation failures) or arbitrary
+	* transport errors. The outer `dispatch` wraps non-CapRouteErrors.
 	*/
-	isChildKnown(childId) {
-		return this.children.has(childId);
-	}
-	childProvides(childId, capName, deviceId) {
-		const entry = this.children.get(childId);
-		if (!entry) return false;
-		if (deviceId !== void 0 && entry.caps.some((cap) => cap.capName === capName && cap.deviceId === deviceId)) return true;
-		return entry.caps.some((cap) => cap.capName === capName && cap.deviceId === void 0);
-	}
-	/**
-	* 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.
-	*/
-	capRequestOpts(input) {
-		const declared = this.capTimeoutMs?.(input.capName, input.method);
-		return typeof declared === "number" ? { timeoutMs: declared } : void 0;
-	}
-	/** Forward a cap method call to a SPECIFIC child by id over UDS; rejects if that child is absent. */
-	async callCapOnChild(childId, input) {
-		const entry = this.children.get(childId);
-		if (!entry) throw new Error(`no local child "${childId}" for cap "${input.capName}"`);
-		return entry.channel.request(this.toCapCall(input), this.capRequestOpts(input));
-	}
-	/** Forward a cap method call to the owning child over UDS; rejects if none. */
-	async callCap(input) {
-		const childId = this.resolveChildId(input.capName, input.deviceId);
-		const entry = childId === null ? void 0 : this.children.get(childId);
-		if (!entry) {
-			const where = input.deviceId === void 0 ? "" : ` for device ${input.deviceId}`;
-			throw new Error(`no local child provides cap "${input.capName}"${where}`);
+	async dispatchInner(route, method, args, addonId, callerAddonId) {
+		switch (route.kind) {
+			case "hub-in-process": return route.ref.invoke(method, withCallerAddonId(args, callerAddonId));
+			case "hub-local-uds": {
+				const registry = this.hubLocalRegistry;
+				if (registry === null) throw new CapRouteError(route.capName, method, {
+					reason: "no-provider",
+					rejected: [{
+						kind: "hub-local-uds",
+						why: "UDS registry not available"
+					}]
+				});
+				const deviceId = extractDeviceId(args);
+				const input = {
+					capName: route.capName,
+					method,
+					args,
+					...deviceId !== void 0 ? { deviceId } : {}
+				};
+				return registry.callCapOnChild(route.childId, input);
+			}
+			case "remote-moleculer": {
+				const addonId = this.nodeAuthority.getAddonId(route.nodeId, route.capName);
+				if (addonId === null) throw new CapRouteError(route.capName, method, {
+					reason: "no-provider",
+					nodeId: route.nodeId,
+					rejected: [{
+						kind: "remote-moleculer",
+						why: `no addonId known for ${route.nodeId}/${route.capName}`
+					}]
+				});
+				const deviceId = extractDeviceId(args);
+				const isNative = this.nodeAuthority.isNativeCap(route.nodeId, route.capName, deviceId);
+				const action = capActionName(addonId, route.capName, method, isNative);
+				return callWithServiceDiscovery(this.broker, addonId, action, args, {
+					nodeID: route.nodeId,
+					timeout: this.callTimeout(route.capName, method)
+				});
+			}
+			case "agent-child-forward": {
+				const deviceId = extractDeviceId(args);
+				const params = {
+					capName: route.capName,
+					method,
+					args,
+					...route.childId !== void 0 ? { childId: route.childId } : {},
+					...deviceId !== void 0 ? { deviceId } : {},
+					...addonId !== void 0 ? { addonId } : {}
+				};
+				return callWithServiceDiscovery(this.broker, AGENT_CAP_FWD_SERVICE, AGENT_CAP_FWD_ACTION, params, {
+					nodeID: route.agentNodeId,
+					timeout: this.callTimeout(route.capName, method)
+				});
+			}
 		}
-		return entry.channel.request(this.toCapCall(input), this.capRequestOpts(input));
-	}
-	/**
-	* 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>`).
-	*/
-	async callAddonOnChild(childId, input) {
-		const entry = this.children.get(childId);
-		if (!entry) throw new Error(`no local child "${childId}" for addon-call (${input.target})`);
-		return entry.channel.request(this.toAddonCall(input));
-	}
-	/** Build the parent→child `addon-call` wire message from an addon-call input. */
-	toAddonCall(input) {
-		return {
-			kind: "addon-call",
-			addonId: input.addonId,
-			target: input.target,
-			...input.action !== void 0 ? { action: input.action } : {},
-			...input.method !== void 0 ? { method: input.method } : {},
-			...input.args !== void 0 ? { args: input.args } : {},
-			...input.caller !== void 0 ? { caller: input.caller } : {}
-		};
 	}
-	/** Build the parent→child `cap-call` wire message from a routing input. */
-	toCapCall(input) {
+	buildSnapshot() {
+		const hubLocalRegistry = this.hubLocalRegistry;
+		const nodeAuthority = this.nodeAuthority;
+		const inProcessProviders = this.inProcessProviders;
+		const hubResidentProviders = this.hubResidentProviders;
 		return {
-			kind: "cap-call",
-			capName: input.capName,
-			method: input.method,
-			args: input.args,
-			...input.deviceId !== void 0 ? { deviceId: input.deviceId } : {},
-			...input.addonId !== void 0 ? { addonId: input.addonId } : {}
+			hubNodeId: this.hubNodeId,
+			hubInProcessProvides: (cap) => inProcessProviders(cap) !== null,
+			...hubResidentProviders !== void 0 ? {
+				hubResidentProvides: (cap) => hubResidentProviders(cap) !== null,
+				getHubResidentProviderRef: (cap) => hubResidentProviders(cap)
+			} : {},
+			hubLocalChildProvides: (cap, deviceId) => hubLocalRegistry !== null && hubLocalRegistry.resolveChildId(cap, deviceId) !== null,
+			nodeKnowsCap: (nodeId, cap) => nodeAuthority.nodeKnowsCap(nodeId, cap),
+			nodeIsAgent: (nodeId) => nodeAuthority.nodeIsAgent(nodeId),
+			nodeOnline: (nodeId) => nodeAuthority.nodeOnline(nodeId),
+			listKnownNodeIds: () => nodeAuthority.listNodeIds(),
+			getInProcessProviderRef: (cap) => inProcessProviders(cap),
+			getHubLocalChildId: (cap, deviceId) => hubLocalRegistry !== null ? hubLocalRegistry.resolveChildId(cap, deviceId) : null,
+			getAgentChildId: (agentNodeId, cap) => nodeAuthority.getAgentChildId(agentNodeId, cap)
 		};
 	}
-	listChildren() {
-		return [...this.children.values()].map((e) => ({
-			childId: e.childId,
-			caps: e.caps,
-			incarnation: e.incarnation
-		}));
-	}
-	/** Register the (single) child-registered handler. Only one handler is active at a time. */
-	onChildRegistered(handler) {
-		this.registeredHandler = handler;
+	/** Extract a nodeId string from a route for error reporting, or undefined. */
+	routeNodeId(route) {
+		switch (route.kind) {
+			case "hub-in-process": return this.hubNodeId;
+			case "hub-local-uds": return `${this.hubNodeId}/${route.childId}`;
+			case "remote-moleculer": return route.nodeId;
+			case "agent-child-forward": return route.agentNodeId;
+		}
 	}
+};
+//#endregion
+//#region src/kernel/transport/claimed-get-status.ts
+var GET_STATUS_METHOD = "getStatus";
+/** The device a `getStatus` is about, or `undefined` when the call is not one. */
+function deviceOfGetStatus(call) {
+	if (call.method !== "getStatus") return void 0;
+	return call.deviceId ?? extractDeviceId(call.args);
+}
+async function answerClaimedGetStatus(resolve, call) {
+	if (resolve === void 0) return null;
+	const deviceId = deviceOfGetStatus(call);
+	if (deviceId === void 0) return null;
+	const answer = await resolve(call.capName, deviceId);
+	if (answer.kind === "unclaimed") return null;
+	return { slice: answer.kind === "claimed" ? answer.slice : null };
+}
+function readFanoutMode() {
+	const raw = process.env.CAMSTACK_UDS_EVENT_FANOUT;
+	if (raw === "shadow" || raw === "broadcast") return raw;
+	return "filter";
+}
+/**
+* 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).
+*/
+var UDS_NO_ROUTE_PREFIX = "UDS_NO_ROUTE";
+/**
+* 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.
+*/
+var LocalChildRegistry = class {
+	children = /* @__PURE__ */ new Map();
+	registeredHandler = () => {};
+	goneHandler = () => {};
+	/** Source of {@link RegisteredChild.incarnation}; one bump per accepted connection. */
+	nextIncarnation = 1;
+	eventHandler = null;
+	logHandler = null;
+	readinessHandler = null;
+	server;
+	onUnownedCall;
+	logger;
+	getActiveSingletonAddonId;
+	resolveChildIdForAddon;
+	/** This node's own Moleculer nodeId (see {@link LocalChildRegistryOptions.ownNodeId}). */
+	ownNodeId;
+	/** See {@link LocalChildRegistryOptions.isAggregatedCollectionMethod}. */
+	isAggregatedCollectionMethod;
+	isAddonPinnedCall;
+	/** See {@link ForwardCensus}. Mutable counters on the hot path, by design. */
+	forwardedRaw = 0;
+	forwardedDecoded = 0;
 	/**
-	* 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.
+	* 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.
 	*/
-	onChildGone(handler) {
-		this.goneHandler = handler;
-	}
+	actionCensus = createCapActionCensus();
+	/** See {@link LocalChildRegistryOptions.capTimeoutMs}. */
+	capTimeoutMs;
+	/** See {@link LocalChildRegistryOptions.claimedStatus}. */
+	claimedStatus;
+	/** See {@link LocalChildRegistryOptions.capUsageObserver}. */
+	capUsageObserver;
+	/** Tracks capNames already logged as UDS-routed; one INFO line per capName per process. */
+	egressRoutedCaps = /* @__PURE__ */ new Set();
+	/** Active event fan-out mode, read once from `CAMSTACK_UDS_EVENT_FANOUT`. */
+	fanoutMode = readFanoutMode();
+	/** Per-child event fan-out counters (sent / suppressed). */
+	childEventStats = /* @__PURE__ */ new Map();
+	/** D467: per-category production census (cumulative). See {@link CategoryFanoutSample}. */
+	categoryStats = /* @__PURE__ */ new Map();
+	/** Broadcasts whose category did not fit in {@link CATEGORY_CENSUS_MAX}. */
+	categoryOverflow = 0;
+	/** One INFO line the first time the census cap trips, never per event. */
+	categoryOverflowLogged = false;
+	/** Last pattern-set string logged per child, to dedup the INFO line. */
+	loggedPatternSet = /* @__PURE__ */ new Map();
 	/**
-	* 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).
+	* 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).
 	*/
-	onChildEvent(handler) {
-		this.eventHandler = handler;
-	}
+	capChildIndex = null;
 	/**
-	* Register the (single) child-log handler. Invoked when a child sends a log
-	* entry via `LocalChildClient.sendLog`. Only one handler is active.
+	* 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 })
 	*/
-	onChildLog(handler) {
-		this.logHandler = handler;
-	}
-	/**
-	* Register the handler that supplies the authoritative readiness snapshot
-	* when a child sends a `readiness-request`. Only one handler is active.
-	*/
-	onReadinessSnapshotRequest(handler) {
-		this.readinessHandler = handler;
+	constructor(serverOrOptions, onUnownedCallArg) {
+		if (serverOrOptions && !("listen" in serverOrOptions)) {
+			const opts = serverOrOptions;
+			this.server = opts.server;
+			this.onUnownedCall = opts.onUnownedCall;
+			this.logger = opts.logger;
+			this.getActiveSingletonAddonId = opts.getActiveSingletonAddonId;
+			this.resolveChildIdForAddon = opts.resolveChildIdForAddon;
+			this.ownNodeId = opts.ownNodeId;
+			this.isAggregatedCollectionMethod = opts.isAggregatedCollectionMethod;
+			this.isAddonPinnedCall = opts.isAddonPinnedCall;
+			this.capTimeoutMs = opts.capTimeoutMs;
+			this.claimedStatus = opts.claimedStatus;
+			this.capUsageObserver = opts.capUsageObserver;
+		} else {
+			this.server = serverOrOptions;
+			this.onUnownedCall = onUnownedCallArg;
+		}
+	}
+	async start() {
+		this.logger?.info("UDS event fan-out mode", { mode: this.fanoutMode });
+		this.server.onConnection((channel) => this.onConnection(channel));
+		await this.server.listen();
 	}
 	/**
-	* 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.
+	* Per-child event fan-out counters (`{ sent, suppressed }`) or `null` if the
+	* child has no recorded events yet. Exposed for the starvation-verification
+	* surface (shadow burn-in + operator debug).
 	*/
-	sendEventToChild(childId, event, sourceNodeId) {
-		const entry = this.children.get(childId);
-		if (entry === void 0) return;
-		const msg = {
-			kind: "event",
-			event,
-			sourceNodeId
+	getChildEventStats(childId) {
+		const s = this.childEventStats.get(childId);
+		return s === void 0 ? null : {
+			sent: s.sent,
+			suppressed: s.suppressed
 		};
-		entry.channel.emit(msg);
 	}
 	/**
-	* Push a parent→child event to every registered child, optionally skipping
-	* one (the originating child, to avoid echo). Fire-and-forget.
+	* 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.
 	*/
-	broadcastEventToChildren(event, sourceNodeId, exceptChildId) {
-		const msg = {
-			kind: "event",
-			event,
-			sourceNodeId
-		};
-		let subscribed = 0;
-		for (const entry of this.children.values()) {
-			if (entry.childId === exceptChildId) continue;
-			if (this.childSubscribesTo(entry, event.category)) subscribed += 1;
-			const wants = this.childWantsEvent(entry, event.category);
-			const stats = this.statsFor(entry.childId);
-			if (!wants) stats.suppressed++;
-			if (wants || this.fanoutMode === "shadow") {
-				stats.sent++;
-				entry.channel.emit(msg);
-			}
-		}
-		this.recordCategoryBroadcast(event.category, subscribed);
+	categoryFanout() {
+		const out = [];
+		for (const [category, s] of this.categoryStats) out.push({
+			category,
+			broadcasts: s.broadcasts,
+			wanted: s.wanted
+		});
+		return out.toSorted((a, b) => b.broadcasts - a.broadcasts || a.category.localeCompare(b.category));
+	}
+	/** Broadcasts the census could not attribute because it was full (cumulative). */
+	categoryCensusOverflow() {
+		return this.categoryOverflow;
 	}
 	/**
-	* Record one PRODUCED event against its category. Called once per broadcast,
-	* outside the per-child loop, because production is what the census measures.
+	* 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.
 	*/
-	recordCategoryBroadcast(category, subscribed) {
-		const existing = this.categoryStats.get(category);
-		if (existing !== void 0) {
-			existing.broadcasts += 1;
-			existing.wanted += subscribed;
-			return;
-		}
-		if (this.categoryStats.size >= 256) {
-			this.categoryOverflow += 1;
-			if (!this.categoryOverflowLogged) {
-				this.categoryOverflowLogged = true;
-				this.logger?.info("event category census full — further new categories are unattributed", {
-					max: 256,
-					firstDropped: category
-				});
-			}
-			return;
-		}
-		this.categoryStats.set(category, {
-			broadcasts: 1,
-			wanted: subscribed
-		});
+	getChildSocketTraffic(childId) {
+		const entry = this.children.get(childId);
+		if (entry === void 0) return null;
+		return entry.channel.readTraffic?.() ?? null;
 	}
 	/**
-	* 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.
+	* 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.
 	*/
-	setChildLogLevel(childId, level) {
+	getChildQueuedBytes(childId) {
 		const entry = this.children.get(childId);
-		if (entry === void 0) return false;
-		const msg = {
-			kind: "set-log-level",
-			level
+		if (entry === void 0) return null;
+		return entry.channel.queuedBytes?.() ?? null;
+	}
+	/** Cumulative {@link ForwardCensus} of this parent's `cap-call-out` routing. */
+	readForwardCensus() {
+		return {
+			raw: this.forwardedRaw,
+			decoded: this.forwardedDecoded
 		};
-		entry.channel.emit(msg);
-		return true;
 	}
-	async close() {
-		await this.server.close();
+	/**
+	* 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() {
+		return this.actionCensus.read();
 	}
-	onConnection(channel) {
-		let childId = null;
-		const incarnation = this.nextIncarnation++;
-		channel.observeActions?.({
-			label: capActionLabel,
-			record: (label, reqBytes, resBytes) => {
-				const peerId = childId ?? "(pre-register)";
-				if (label === null) this.actionCensus.recordUnlabelled(peerId, reqBytes + resBytes);
-				else this.actionCensus.record(peerId, label, reqBytes, resBytes);
-			}
-		});
-		channel.onEvent((body) => {
-			const msg = body;
-			if (msg.kind === "event") {
-				if (childId !== null) this.eventHandler?.(childId, msg.event);
-				return;
-			}
-			if (msg.kind === "log") {
-				if (childId !== null) this.logHandler?.(childId, msg);
-				return;
-			}
-			if (msg.kind === "event-sub") {
-				if (childId === null) return;
-				const entry = this.children.get(childId);
-				if (entry === void 0) return;
-				this.children.set(childId, {
-					...entry,
-					eventPatterns: msg.patterns
-				});
-				this.logPatternSet(childId, msg.patterns);
-				return;
-			}
-		});
-		channel.onRequest(async (body, payload) => {
-			const msg = body;
-			if (msg.kind === "register") {
-				if (childId !== null && childId !== msg.childId) throw new Error(`child attempted to change identity from "${childId}" to "${msg.childId}"`);
-				childId = msg.childId;
-				const eventPatterns = msg.eventPatterns ?? null;
-				const superseded = this.children.get(msg.childId);
-				if (superseded !== void 0 && superseded.channel !== channel) this.logger?.info("local child superseded by a new connection", {
-					childId: msg.childId,
-					supersededIncarnation: superseded.incarnation,
-					incarnation
-				});
-				this.children.set(msg.childId, {
-					childId: msg.childId,
-					channel,
-					caps: msg.caps,
-					eventPatterns,
-					incarnation,
-					rawForward: msg.rawForward === true
-				});
-				this.invalidateCapIndex();
-				this.logPatternSet(msg.childId, eventPatterns);
-				this.registeredHandler({
-					childId: msg.childId,
-					caps: msg.caps,
-					incarnation,
-					...msg.customActions !== void 0 ? { customActions: msg.customActions } : {}
-				});
-				return {
-					ok: true,
-					rawForward: true
-				};
-			}
-			if (msg.kind === "cap-call-out") {
-				const out = msg;
-				const hints = out.hints ?? liftRoutingHints(out.args);
-				const materialise = () => payload !== void 0 ? unpackPayload(payload) : out.args;
-				const buildInput = () => ({
-					capName: out.capName,
-					method: out.method,
-					args: materialise(),
-					...out.deviceId !== void 0 ? { deviceId: out.deviceId } : {},
-					...out.nodeId !== void 0 ? { nodeId: out.nodeId } : {},
-					...out.native === true ? { native: true } : {},
-					...childId !== null ? { callerAddonId: childId } : {}
-				});
-				const pinnedNodeId = out.nodeId ?? hints.nodeId;
-				const pinTargetsThisNode = pinnedNodeId !== void 0 && this.ownNodeId !== void 0 && pinnedNodeId === this.ownNodeId;
-				const aggregated = pinnedNodeId === void 0 && this.isAggregatedCollectionMethod?.(out.capName, out.method) === true;
-				const addonPinned = pinnedNodeId === void 0 && this.isAddonPinnedCall?.(out.capName, out.method, hints) === true;
-				const target = !(out.native === true) && !aggregated && !addonPinned && (pinnedNodeId === void 0 || pinTargetsThisNode) ? this.resolveChildId(out.capName, out.deviceId) : null;
-				this.recordCapUsage(childId, target, out.capName, out.method);
-				const actionPeer = childId ?? "(pre-register)";
-				const actionLabel = `${out.capName}.${out.method}`;
-				if (target !== null) {
-					if (!this.egressRoutedCaps.has(out.capName)) {
-						this.egressRoutedCaps.add(out.capName);
-						this.logger?.info("routed child egress over UDS", { capName: out.capName });
-					}
-					const entry = this.children.get(target);
-					if (payload !== void 0 && entry !== void 0 && entry.rawForward) {
-						this.forwardedRaw += 1;
-						this.actionCensus.recordForward(actionPeer, actionLabel, "raw");
-						const forward = {
-							kind: "cap-call",
-							capName: out.capName,
-							method: out.method,
-							args: void 0,
-							...out.deviceId !== void 0 ? { deviceId: out.deviceId } : {}
-						};
-						const declared = this.capTimeoutMs?.(out.capName, out.method);
-						return entry.channel.request(forward, {
-							...typeof declared === "number" ? { timeoutMs: declared } : {},
-							payload
-						});
-					}
-					this.forwardedDecoded += 1;
-					this.actionCensus.recordForward(actionPeer, actionLabel, "decoded");
-					const input = buildInput();
-					return entry !== void 0 ? this.callCapOnChild(target, input) : this.callCap(input);
-				}
-				this.forwardedDecoded += 1;
-				this.actionCensus.recordForward(actionPeer, actionLabel, "decoded");
-				if (this.onUnownedCall !== void 0) return this.onUnownedCall(buildInput());
-				throw new Error(`${UDS_NO_ROUTE_PREFIX}: cap-call-out has no local provider for "${out.capName}" and no fallback`);
-			}
-			if (msg.kind === "readiness-request") return {
-				kind: "readiness-snapshot",
-				records: this.readinessHandler?.() ?? []
-			};
-			throw new Error(`unknown child request kind: ${msg.kind}`);
-		});
-		channel.onClose(() => {
-			if (childId === null) return;
-			const entry = this.children.get(childId);
-			if (entry === void 0) return;
-			if (entry.channel !== channel) {
-				this.logger?.info("ignoring close of a superseded local child connection", {
-					childId,
-					incarnation,
-					liveIncarnation: entry.incarnation
-				});
-				return;
-			}
-			this.children.delete(childId);
-			this.invalidateCapIndex();
-			this.childEventStats.delete(childId);
-			this.actionCensus.forget(childId);
-			this.loggedPatternSet.delete(childId);
-			this.goneHandler(childId, incarnation);
-		});
-	}
-};
-//#endregion
-//#region src/kernel/transport/local-child-client.ts
-/** Did the parent's `register` answer say it accepts payload-borne args? */
-function ackAcceptsRawForward(ack) {
-	if (ack === null || typeof ack !== "object") return false;
-	return ack.rawForward === true;
-}
-/**
-* Child side of the local UDS transport. Connects to its parent (hub or
-* agent), registers its cap manifest, and serves parent→child cap calls by
-* delegating to `dispatch`. The provider implementation lives in the child;
-* only routing keys + call arguments cross the wire.
-*
-* Additional channels beyond cap-call:
-*   - `emitEvent`              fire-and-forget event toward the parent
-*   - `sendLog`                fire-and-forget log entry toward the parent
-*   - `requestReadinessSnapshot` request/response snapshot of readiness records
-*   - `onEvent`                register a handler for parent→child events
-*
-* Events and logs emitted before `start()` resolves are buffered and flushed
-* on connect (mirrors the `updateCaps`/`latestCaps` pattern).
-*/
-var LocalChildClient = class {
-	options;
-	client = null;
-	channel = null;
-	/**
-	* The cap set `start()` will register, kept current by `updateCaps`. Native
-	* device caps register on device-restore, which can race AHEAD of the UDS
-	* connect — buffering here lets a pre-start `updateCaps` survive (start sends
-	* the latest set) instead of being lost or throwing.
-	*/
-	latestCaps;
-	/**
-	* Per-owner (addonId) category-pattern subscription sets, and their union.
-	* The union is declared to the parent (in `RegisterMessage.eventPatterns`
-	* pre/at-connect, or via an `event-sub` emit post-connect) so the parent can
-	* subscription-filter its event fan-out. Per-owner keying keeps the union
-	* correct if multiple event buses ever share one client (group-runner case).
-	*/
-	patternsByOwner = /* @__PURE__ */ new Map();
-	latestEventPatterns = [];
-	/**
-	* Whether `updateEventPatterns` has ever been called. A client that never
-	* declared a subscription set (no event bus wired — e.g. a pure cap-call
-	* runner) omits `eventPatterns` from its register frame entirely, so the
-	* parent treats it as UNDECLARED and fails OPEN (broadcast-all). Once any
-	* owner declares (in production every addon context's framework
-	* subscriptions do), the register carries the real union — even if empty.
-	*/
-	hasDeclaredEventPatterns = false;
 	/**
-	* The custom-action catalogs of every hosted addon, once the runner's init
-	* loop has produced them (`updateCaps(caps, catalogs)` at post-init). `null`
-	* until then, and OMITTED from the register frame while null: the parent
-	* reads absence as "not described yet", and a pre-init register must never
-	* look like "this child declares no actions". Kept on the client so every
-	* later re-register (native-cap change, reconnect) re-carries it unchanged.
+	* The regime the counters above were produced under, read once from
+	* `CAMSTACK_UDS_EVENT_FANOUT` at construction.
+	*
+	* A suppressed count means "nothing WAS dropped" under `filter` and "nothing
+	* WOULD have been dropped" under `shadow`. Those are different claims, and
+	* until this getter existed the mode was invisible at runtime — the counters
+	* were readable and the regime that produced them was not.
 	*/
-	latestCustomActions = null;
-	/** Events and logs queued while the channel is not yet open. */
-	pendingEmits = [];
+	get eventFanoutMode() {
+		return this.fanoutMode;
+	}
 	/**
-	* Whether the parent acknowledged raw-forward at `register`. Until it has,
-	* `callOut` sends args inline exactly as every child always did — a legacy
-	* parent would decode a payload-borne call to `args: undefined` and run the
-	* provider on nothing, silently. Re-read on every re-register.
+	* 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.
 	*/
-	parentRawForward = false;
-	/** Handler for parent→child events. Registered via `onEvent`. */
-	eventHandler = null;
+	undeclaredChildCount() {
+		let count = 0;
+		for (const entry of this.children.values()) if (entry.eventPatterns === null) count += 1;
+		return count;
+	}
 	/**
-	* Handler for parent→child addon-level calls (`routes` / `custom`).
-	* Registered via `onAddonCall`. Resolves the loaded addon instance and
-	* invokes its `addon-routes.getRoutes()` or its custom-action handler.
-	* Replaces the per-addon Moleculer `getRoutes` / `custom.<action>` actions
-	* removed in F1/F2. Only one handler is active at a time.
+	* Does `entry` want to receive an event in `category`? Honours the fan-out
+	* mode: `broadcast` → always; undeclared patterns (`null`) → always
+	* (fail-open); 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. `shadow` is handled by the caller (it
+	* counts the would-suppress but still sends).
+	*
+	* 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.
 	*/
-	addonCallHandler = null;
+	childWantsEvent(entry, category) {
+		if (this.fanoutMode === "broadcast") return true;
+		return this.childSubscribesTo(entry, category);
+	}
 	/**
-	* Handler for `set-log-level` messages pushed by the parent.
-	* Registered via `onSetLogLevel`. The handler applies the new level to the
-	* child's local Moleculer logger (mirrors `$node-mgmt.setLogLevel`).
-	* E2: wired in `addon-runner.ts` to forward to the broker logger.
+	* The SUBSCRIPTION answer alone, with no fan-out-mode override.
+	*
+	* {@link childWantsEvent} answers "will this child be sent the event", which
+	* under `broadcast` is `true` for everything and therefore cannot say whether
+	* anyone actually asked. The D467 census needs the second question, so the
+	* two are separate functions and `broadcast` mode overrides only the first.
 	*/
-	setLogLevelHandler = null;
-	/** Callbacks registered via `onConnected`. Fired on every (re)connect. */
-	connectedHandlers = [];
-	constructor(options) {
-		this.options = options;
-		this.latestCaps = options.caps;
+	childSubscribesTo(entry, category) {
+		if (entry.eventPatterns === null) return true;
+		return entry.eventPatterns.some((p) => matchesPattern(p, category));
 	}
 	/**
-	* Declare an owner's live category-pattern subscription set. Stores it
-	* per-owner (keyed by `ownerId` = addonId), recomputes the union, and — only
-	* if the union changed — declares it to the parent:
-	*   - pre-connect: buffered only; `start()`'s register frame carries the set.
-	*   - post-connect: emitted as a fire-and-forget `event-sub` (full-set
-	*     replace).
-	* Idempotent on an unchanged union (no redundant `event-sub` frames).
+	* 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.
 	*/
-	updateEventPatterns(ownerId, patterns) {
-		this.hasDeclaredEventPatterns = true;
-		this.patternsByOwner.set(ownerId, patterns);
-		const union = this.computePatternUnion();
-		if (!this.patternsEqual(union, this.latestEventPatterns)) {
-			this.latestEventPatterns = union;
-			if (this.channel !== null) {
-				const msg = {
-					kind: "event-sub",
-					patterns: union
-				};
-				this.channel.emit(msg);
-			}
+	aggregateEventInterest() {
+		if (this.children.size === 0) return null;
+		const union = /* @__PURE__ */ new Set();
+		for (const entry of this.children.values()) {
+			if (entry.eventPatterns === null) return null;
+			for (const p of entry.eventPatterns) union.add(p);
 		}
+		return [...union];
 	}
-	/** Sorted, de-duplicated union across all owners' pattern sets. */
-	computePatternUnion() {
-		const all = /* @__PURE__ */ new Set();
-		for (const patterns of this.patternsByOwner.values()) for (const p of patterns) all.add(p);
-		return [...all].toSorted();
+	statsFor(childId) {
+		let s = this.childEventStats.get(childId);
+		if (s === void 0) {
+			s = {
+				sent: 0,
+				suppressed: 0
+			};
+			this.childEventStats.set(childId, s);
+		}
+		return s;
 	}
-	/** Order-insensitive equality — both inputs are already sorted unions here. */
-	patternsEqual(a, b) {
-		if (a.length !== b.length) return false;
-		for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;
-		return true;
+	/** Deduped INFO line whenever a child's declared pattern set changes. */
+	logPatternSet(childId, patterns) {
+		const key = patterns === null ? "<undeclared>" : JSON.stringify([...patterns].toSorted());
+		if (this.loggedPatternSet.get(childId) === key) return;
+		this.loggedPatternSet.set(childId, key);
+		this.logger?.info("child event patterns", {
+			childId,
+			patterns: patterns ?? null
+		});
 	}
 	/**
-	* Register a callback that fires each time the client successfully connects
-	* (or reconnects) to its parent. Multiple handlers may be registered; all
-	* are called in registration order. Used by readiness-context in UDS mode
-	* to trigger a snapshot hydrate on connect/reconnect.
+	* 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.
 	*/
-	onConnected(handler) {
-		this.connectedHandlers.push(handler);
+	resolveChildId(capName, deviceId) {
+		const index = this.capIndex();
+		if (deviceId !== void 0) {
+			const deviceOwner = index.deviceOwner(capName, deviceId);
+			if (deviceOwner !== null) return deviceOwner;
+		}
+		const candidates = index.singletonCandidates(capName);
+		if (candidates.length === 0) return null;
+		if (candidates.length === 1) return candidates[0];
+		const preferredAddonId = this.getActiveSingletonAddonId?.(capName) ?? null;
+		if (preferredAddonId !== null) {
+			const preferredChildId = this.resolveChildIdForAddon?.(preferredAddonId) ?? preferredAddonId;
+			if (candidates.includes(preferredChildId)) return preferredChildId;
+		}
+		return candidates[0];
 	}
 	/**
-	* Register a handler for events pushed from the parent to this child.
-	* Must be called before `start()` to avoid missing early events (though
-	* registration after start is also safe for events not yet delivered).
-	* Replaces any previously registered handler.
+	* 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.
 	*/
-	onEvent(handler) {
-		this.eventHandler = handler;
+	recordCapUsage(callerChildId, providerChildId, capName, methodName) {
+		const sink = this.capUsageObserver;
+		if (sink === void 0 || callerChildId === null) return;
+		try {
+			sink({
+				callerAddonId: callerChildId,
+				providerAddonId: providerChildId ?? "(unresolved: parent-routed)",
+				capName,
+				methodName,
+				atMs: Date.now()
+			});
+		} catch {}
 	}
 	/**
-	* Register the handler invoked when the parent sends an `addon-call` (the
-	* addon-level routes / custom-action plane). The addon-runner wires this to
-	* resolve the loaded addon by id and dispatch to its `getRoutes()` or its
-	* custom-action handler. Safe to register before or after `start()`;
-	* replaces any prior handler.
+	* 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.
 	*/
-	onAddonCall(handler) {
-		this.addonCallHandler = handler;
+	capIndex() {
+		if (this.capChildIndex === null) this.capChildIndex = buildCapChildIndex(this.children.values());
+		return this.capChildIndex;
+	}
+	/** Drop the derived index. MUST follow every write to {@link children}. */
+	invalidateCapIndex() {
+		this.capChildIndex = null;
 	}
 	/**
-	* E2: Register a handler invoked when the parent sends a `set-log-level`
-	* message to this child. The handler should forward the new level to the
-	* child's local Moleculer broker logger (mirrors `$node-mgmt.setLogLevel`).
-	* Safe to register before or after `start()`. Replaces any prior handler.
+	* 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.
 	*/
-	onSetLogLevel(handler) {
-		this.setLogLevelHandler = handler;
+	/**
+	* 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) {
+		return this.children.has(childId);
+	}
+	childProvides(childId, capName, deviceId) {
+		const entry = this.children.get(childId);
+		if (!entry) return false;
+		if (deviceId !== void 0 && entry.caps.some((cap) => cap.capName === capName && cap.deviceId === deviceId)) return true;
+		return entry.caps.some((cap) => cap.capName === capName && cap.deviceId === void 0);
 	}
 	/**
-	* True once `start()` has successfully connected and registered. Used by
-	* callers (event-bus/logger bridges) to know the channel is live.
+	* 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.
 	*/
-	get isConnected() {
-		return this.channel !== null;
+	capRequestOpts(input) {
+		const declared = this.capTimeoutMs?.(input.capName, input.method);
+		return typeof declared === "number" ? { timeoutMs: declared } : void 0;
 	}
-	async start() {
-		if (this.client !== null) throw new Error("LocalChildClient: already started — call close() first");
-		const client = createLocalTransport().createClient(this.options.nodeId);
-		const channel = await client.connect();
-		channel.onRequest(async (body, payload) => {
-			const msg = body;
-			if (msg.kind === "cap-call") {
-				const args = payload !== void 0 ? unpackPayload(payload) : msg.args;
-				const result = await this.options.dispatch({
-					capName: msg.capName,
-					method: msg.method,
-					args,
-					...msg.deviceId !== void 0 ? { deviceId: msg.deviceId } : {},
-					...msg.addonId !== void 0 ? { addonId: msg.addonId } : {}
-				});
-				if (payload !== void 0 && result !== void 0) return new PayloadReply(void 0, packPayload(result));
-				return result;
-			}
-			if (msg.kind === "addon-call") {
-				if (this.addonCallHandler === null) throw new Error(`LocalChildClient: addon-call for "${msg.addonId}" arrived but no onAddonCall handler is registered`);
-				return this.addonCallHandler({
-					addonId: msg.addonId,
-					target: msg.target,
-					...msg.action !== void 0 ? { action: msg.action } : {},
-					...msg.method !== void 0 ? { method: msg.method } : {},
-					...msg.args !== void 0 ? { args: msg.args } : {},
-					...msg.caller !== void 0 ? { caller: msg.caller } : {}
-				});
-			}
-			throw new Error(`unknown parent request kind: ${msg.kind}`);
-		});
-		channel.onEvent((body) => {
-			const msg = body;
-			if (msg.kind === "event") {
-				this.eventHandler?.(msg.event);
-				return;
-			}
-			if (msg.kind === "set-log-level") this.setLogLevelHandler?.(msg.level);
-		});
-		const register = this.registerFrame(this.latestCaps);
-		try {
-			this.parentRawForward = ackAcceptsRawForward(await channel.request(register));
-		} catch (err) {
-			await client.close();
-			throw err;
-		}
-		this.client = client;
-		this.channel = channel;
-		this.flushPending(channel);
-		for (const cb of this.connectedHandlers) cb();
+	/** Forward a cap method call to a SPECIFIC child by id over UDS; rejects if that child is absent. */
+	async callCapOnChild(childId, input) {
+		const entry = this.children.get(childId);
+		if (!entry) throw new Error(`no local child "${childId}" for cap "${input.capName}"`);
+		return entry.channel.request(this.toCapCall(input), this.capRequestOpts(input));
 	}
-	/** Flush buffered pre-start emits over the now-open channel. */
-	flushPending(channel) {
-		for (const item of this.pendingEmits) channel.emit(item.msg);
-		this.pendingEmits.length = 0;
+	/** Forward a cap method call to the owning child over UDS; rejects if none. */
+	async callCap(input) {
+		const childId = this.resolveChildId(input.capName, input.deviceId);
+		const entry = childId === null ? void 0 : this.children.get(childId);
+		if (!entry) {
+			const where = input.deviceId === void 0 ? "" : ` for device ${input.deviceId}`;
+			throw new Error(`no local child provides cap "${input.capName}"${where}`);
+		}
+		return entry.channel.request(this.toCapCall(input), this.capRequestOpts(input));
 	}
 	/**
-	* Re-send the cap manifest to the parent, atomically replacing the child's
-	* registered descriptor set. Call this after device-restore so newly
-	* registered native (device-scoped) caps become routable over UDS.
+	* Forward an ADDON-LEVEL call (routes / custom-action) to a SPECIFIC child
+	* by id over UDS; rejects if that child is absent.
 	*
-	* Safe to call before `start()`: the new set is buffered and `start()` sends
-	* it (device-restore can race ahead of the UDS connect). After `start()`,
-	* the set is sent immediately.
+	* 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>`).
 	*/
-	async updateCaps(caps, customActions) {
-		this.latestCaps = caps;
-		if (customActions !== void 0) this.latestCustomActions = customActions;
-		if (this.channel === null) return;
-		this.parentRawForward = ackAcceptsRawForward(await this.channel.request(this.registerFrame(caps)));
+	async callAddonOnChild(childId, input) {
+		const entry = this.children.get(childId);
+		if (!entry) throw new Error(`no local child "${childId}" for addon-call (${input.target})`);
+		return entry.channel.request(this.toAddonCall(input));
 	}
-	/**
-	* The register frame: caps, plus everything a re-register must atomically
-	* re-carry so no separate re-sync can be missed — the subscription union
-	* (omitted if nothing ever declared, which keeps the fail-open shape) and the
-	* custom-action catalogs (omitted until the init loop produced them).
-	*/
-	registerFrame(caps) {
+	/** Build the parent→child `addon-call` wire message from an addon-call input. */
+	toAddonCall(input) {
 		return {
-			kind: "register",
-			childId: this.options.childId,
-			caps,
-			...this.hasDeclaredEventPatterns ? { eventPatterns: this.latestEventPatterns } : {},
-			...this.latestCustomActions !== null ? { customActions: this.latestCustomActions } : {},
-			rawForward: true
+			kind: "addon-call",
+			addonId: input.addonId,
+			target: input.target,
+			...input.action !== void 0 ? { action: input.action } : {},
+			...input.method !== void 0 ? { method: input.method } : {},
+			...input.args !== void 0 ? { args: input.args } : {},
+			...input.caller !== void 0 ? { caller: input.caller } : {}
 		};
 	}
-	/**
-	* Fire-and-forget: send a system event to the parent for forwarding to the
-	* hub event bus. Safe to call before `start()` — events are buffered and
-	* flushed on connect.
-	*/
-	emitEvent(event) {
-		const msg = {
-			kind: "event",
-			event
+	/** Build the parent→child `cap-call` wire message from a routing input. */
+	toCapCall(input) {
+		return {
+			kind: "cap-call",
+			capName: input.capName,
+			method: input.method,
+			args: input.args,
+			...input.deviceId !== void 0 ? { deviceId: input.deviceId } : {},
+			...input.addonId !== void 0 ? { addonId: input.addonId } : {}
 		};
-		if (this.channel !== null) this.channel.emit(msg);
-		else this.pendingEmits.push({
-			kind: "event",
-			msg
-		});
+	}
+	listChildren() {
+		return [...this.children.values()].map((e) => ({
+			childId: e.childId,
+			caps: e.caps,
+			incarnation: e.incarnation
+		}));
+	}
+	/** Register the (single) child-registered handler. Only one handler is active at a time. */
+	onChildRegistered(handler) {
+		this.registeredHandler = handler;
 	}
 	/**
-	* Fire-and-forget: send a structured log entry to the parent. Safe to call
-	* before `start()` — log entries are buffered and flushed on connect.
+	* 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.
 	*/
-	sendLog(entry) {
-		const msg = {
-			kind: "log",
-			...entry
-		};
-		if (this.channel !== null) this.channel.emit(msg);
-		else this.pendingEmits.push({
-			kind: "log",
-			msg
-		});
+	onChildGone(handler) {
+		this.goneHandler = handler;
 	}
 	/**
-	* Request the current readiness snapshot from the parent. Returns the
-	* authoritative set of `IReadinessRegistryRecord` entries the hub holds.
-	* Requires `start()` to have been called; throws with a clear message if not.
+	* 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).
 	*/
-	async requestReadinessSnapshot() {
-		if (this.channel === null) throw new Error("LocalChildClient: requestReadinessSnapshot called before start()");
-		return (await this.channel.request({ kind: "readiness-request" })).records;
+	onChildEvent(handler) {
+		this.eventHandler = handler;
 	}
 	/**
-	* Ask the parent to execute a cap call this child does NOT own. The parent
-	* routes to the owning local sibling over UDS, or — if no sibling owns it —
-	* to its `onUnownedCall` fallback (the cluster CapabilityRegistry in
-	* production). Throws if called before `start()`.
+	* Register the (single) child-log handler. Invoked when a child sends a log
+	* entry via `LocalChildClient.sendLog`. Only one handler is active.
 	*/
-	async callOut(input) {
-		if (this.channel === null) throw new Error("LocalChildClient: callOut before start");
-		const routing = {
-			...input.deviceId !== void 0 ? { deviceId: input.deviceId } : {},
-			...input.nodeId !== void 0 ? { nodeId: input.nodeId } : {},
-			...input.native === true ? { native: true } : {}
-		};
-		if (this.parentRawForward && input.args !== void 0) {
-			const hints = liftRoutingHints(input.args);
-			const msg = {
-				kind: "cap-call-out",
-				capName: input.capName,
-				method: input.method,
-				...Object.keys(hints).length > 0 ? { hints } : {},
-				...routing
-			};
-			const reply = await this.channel.request(msg, { payload: packPayload(input.args) });
-			return reply instanceof PayloadReply ? unpackPayload(reply.payload) : reply;
-		}
+	onChildLog(handler) {
+		this.logHandler = handler;
+	}
+	/**
+	* Register the handler that supplies the authoritative readiness snapshot
+	* when a child sends a `readiness-request`. Only one handler is active.
+	*/
+	onReadinessSnapshotRequest(handler) {
+		this.readinessHandler = handler;
+	}
+	/**
+	* 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, event, sourceNodeId) {
+		const entry = this.children.get(childId);
+		if (entry === void 0) return;
 		const msg = {
-			kind: "cap-call-out",
-			capName: input.capName,
-			method: input.method,
-			args: input.args,
-			...routing
+			kind: "event",
+			event,
+			sourceNodeId
 		};
-		return this.channel.request(msg);
-	}
-	/** Disconnect from the parent. Safe to call before `start()` (no-op) and idempotent. */
-	async close() {
-		await this.client?.close();
-		this.client = null;
-		this.channel = null;
+		entry.channel.emit(msg);
 	}
-};
-//#endregion
-//#region src/kernel/transport/cap-route.ts
-function buildMessage(capName, method, detail) {
-	const call = method !== void 0 ? `${capName}.${method}` : capName;
-	const target = detail.nodeId !== void 0 ? ` to node ${detail.nodeId}` : "";
-	const rejectedStr = detail.rejected.map((r) => `${r.kind}=${r.why}`).join("; ");
-	const rejectedClause = rejectedStr.length > 0 ? ` (rejected: ${rejectedStr})` : "";
-	return `${call} not routable${target}: ${detail.reason}${rejectedClause}`;
-}
-var CapRouteError = class extends Error {
-	reason;
-	nodeId;
-	rejected;
 	/**
-	* @param cause  Optional original error that triggered this routing failure.
-	*               Stored as `Error.cause` (TC39 standard option, Node 16.9+).
-	*               Dispatchers wrapping transport errors MUST pass the original.
+	* Push a parent→child event to every registered child, optionally skipping
+	* one (the originating child, to avoid echo). Fire-and-forget.
 	*/
-	constructor(capName, method, detail, cause) {
-		super(buildMessage(capName, method, detail), cause !== void 0 ? { cause } : void 0);
-		this.name = "CapRouteError";
-		this.reason = detail.reason;
-		this.nodeId = detail.nodeId;
-		this.rejected = detail.rejected;
+	broadcastEventToChildren(event, sourceNodeId, exceptChildId) {
+		const msg = {
+			kind: "event",
+			event,
+			sourceNodeId
+		};
+		let subscribed = 0;
+		for (const entry of this.children.values()) {
+			if (entry.childId === exceptChildId) continue;
+			if (this.childSubscribesTo(entry, event.category)) subscribed += 1;
+			const wants = this.childWantsEvent(entry, event.category);
+			const stats = this.statsFor(entry.childId);
+			if (!wants) stats.suppressed++;
+			if (wants || this.fanoutMode === "shadow") {
+				stats.sent++;
+				entry.channel.emit(msg);
+			}
+		}
+		this.recordCategoryBroadcast(event.category, subscribed);
 	}
-};
-/**
-* Classifies a (capName, opts) pair into a typed CapRoute dispatch descriptor.
-*
-* Precedence (explicit nodeId path):
-*   1. hub-in-process — hub node + hubInProcessProvides
-*   2. hub-local-uds  — hub node + hubLocalChildProvides
-*   3. node-offline   → CapRouteError{reason:'node-offline'}
-*   4. agent-child-forward — node is an agent AND nodeKnowsCap
-*   5. remote-moleculer — any other online non-agent node
-*
-* Singleton path (no nodeId):
-*   1. hub-in-process (hub provides in-process)
-*   2. hub-local-uds  (a hub-local UDS child provides it)
-*   3. remote-moleculer (any online, non-hub node that knows it)
-*   4. → CapRouteError{reason:'no-provider', rejected: all considered routes}
-*
-* PURE: no side effects, no async, no broker/registry imports.
-*/
-function classifyCapRoute(capName, opts, snapshot) {
-	const rejected = [];
-	if (opts.nodeId !== void 0) return classifyExplicitNode(capName, opts.nodeId, opts.deviceId, snapshot, rejected);
-	return classifySingleton(capName, opts.deviceId, snapshot, rejected);
-}
-function classifyExplicitNode(capName, nodeId, deviceId, snap, rejected) {
-	if (nodeId === snap.hubNodeId) {
-		const residentProvides = snap.hubResidentProvides;
-		const providesOnHub = residentProvides ?? snap.hubInProcessProvides;
-		const getRef = residentProvides !== void 0 ? snap.getHubResidentProviderRef : snap.getInProcessProviderRef;
-		if (providesOnHub(capName)) {
-			const ref = getRef?.(capName) ?? null;
-			if (ref !== null) return {
-				kind: "hub-in-process",
-				capName,
-				ref
-			};
-			rejected.push({
-				kind: "hub-in-process",
-				why: "provider ref not available in snapshot"
-			});
-			throw new CapRouteError(capName, void 0, {
-				reason: "no-provider",
-				nodeId,
-				rejected
-			});
+	/**
+	* Record one PRODUCED event against its category. Called once per broadcast,
+	* outside the per-child loop, because production is what the census measures.
+	*/
+	recordCategoryBroadcast(category, subscribed) {
+		const existing = this.categoryStats.get(category);
+		if (existing !== void 0) {
+			existing.broadcasts += 1;
+			existing.wanted += subscribed;
+			return;
 		}
-		if (snap.hubLocalChildProvides(capName, deviceId)) {
-			const childId = snap.getHubLocalChildId?.(capName, deviceId) ?? null;
-			if (childId !== null) return {
-				kind: "hub-local-uds",
-				capName,
-				childId
-			};
-			rejected.push({
-				kind: "hub-local-uds",
-				why: "child id not resolvable from snapshot"
-			});
-			throw new CapRouteError(capName, void 0, {
-				reason: "no-provider",
-				nodeId,
-				rejected
-			});
+		if (this.categoryStats.size >= 256) {
+			this.categoryOverflow += 1;
+			if (!this.categoryOverflowLogged) {
+				this.categoryOverflowLogged = true;
+				this.logger?.info("event category census full — further new categories are unattributed", {
+					max: 256,
+					firstDropped: category
+				});
+			}
+			return;
 		}
-		rejected.push({
-			kind: "hub-in-process",
-			why: "hub does not provide this cap in-process"
-		});
-		rejected.push({
-			kind: "hub-local-uds",
-			why: "no hub-local child provides this cap"
-		});
-		throw new CapRouteError(capName, void 0, {
-			reason: "no-provider",
-			nodeId,
-			rejected
-		});
-	}
-	if (!snap.nodeOnline(nodeId)) {
-		rejected.push({
-			kind: "remote-moleculer",
-			why: `node ${nodeId} is offline`
-		});
-		throw new CapRouteError(capName, void 0, {
-			reason: "node-offline",
-			nodeId,
-			rejected
+		this.categoryStats.set(category, {
+			broadcasts: 1,
+			wanted: subscribed
 		});
 	}
-	if (snap.nodeIsAgent(nodeId)) {
-		if (snap.nodeKnowsCap(nodeId, capName)) return {
-			kind: "agent-child-forward",
-			capName,
-			agentNodeId: nodeId,
-			childId: snap.getAgentChildId?.(nodeId, capName) ?? void 0
+	/**
+	* 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, level) {
+		const entry = this.children.get(childId);
+		if (entry === void 0) return false;
+		const msg = {
+			kind: "set-log-level",
+			level
 		};
-		rejected.push({
-			kind: "agent-child-forward",
-			why: `agent ${nodeId} does not know cap ${capName}`
+		entry.channel.emit(msg);
+		return true;
+	}
+	async close() {
+		await this.server.close();
+	}
+	onConnection(channel) {
+		let childId = null;
+		const incarnation = this.nextIncarnation++;
+		channel.observeActions?.({
+			label: capActionLabel,
+			record: (label, reqBytes, resBytes) => {
+				const peerId = childId ?? "(pre-register)";
+				if (label === null) this.actionCensus.recordUnlabelled(peerId, reqBytes + resBytes);
+				else this.actionCensus.record(peerId, label, reqBytes, resBytes);
+			}
 		});
-		throw new CapRouteError(capName, void 0, {
-			reason: "no-provider",
-			nodeId,
-			rejected
+		channel.onEvent((body) => {
+			const msg = body;
+			if (msg.kind === "event") {
+				if (childId !== null) this.eventHandler?.(childId, msg.event);
+				return;
+			}
+			if (msg.kind === "log") {
+				if (childId !== null) this.logHandler?.(childId, msg);
+				return;
+			}
+			if (msg.kind === "event-sub") {
+				if (childId === null) return;
+				const entry = this.children.get(childId);
+				if (entry === void 0) return;
+				this.children.set(childId, {
+					...entry,
+					eventPatterns: msg.patterns
+				});
+				this.logPatternSet(childId, msg.patterns);
+				return;
+			}
 		});
-	}
-	return {
-		kind: "remote-moleculer",
-		capName,
-		nodeId
-	};
-}
-function classifySingleton(capName, deviceId, snap, rejected) {
-	if (snap.hubInProcessProvides(capName)) {
-		const ref = snap.getInProcessProviderRef?.(capName) ?? null;
-		if (ref !== null) return {
-			kind: "hub-in-process",
-			capName,
-			ref
-		};
-		rejected.push({
-			kind: "hub-in-process",
-			why: "provider ref not available in snapshot"
+		channel.onRequest(async (body, payload) => {
+			const msg = body;
+			if (msg.kind === "register") {
+				if (childId !== null && childId !== msg.childId) throw new Error(`child attempted to change identity from "${childId}" to "${msg.childId}"`);
+				childId = msg.childId;
+				const eventPatterns = msg.eventPatterns ?? null;
+				const superseded = this.children.get(msg.childId);
+				if (superseded !== void 0 && superseded.channel !== channel) this.logger?.info("local child superseded by a new connection", {
+					childId: msg.childId,
+					supersededIncarnation: superseded.incarnation,
+					incarnation
+				});
+				this.children.set(msg.childId, {
+					childId: msg.childId,
+					channel,
+					caps: msg.caps,
+					eventPatterns,
+					incarnation,
+					rawForward: msg.rawForward === true
+				});
+				this.invalidateCapIndex();
+				this.logPatternSet(msg.childId, eventPatterns);
+				this.registeredHandler({
+					childId: msg.childId,
+					caps: msg.caps,
+					incarnation,
+					...msg.customActions !== void 0 ? { customActions: msg.customActions } : {}
+				});
+				return {
+					ok: true,
+					rawForward: true
+				};
+			}
+			if (msg.kind === "cap-call-out") {
+				const out = msg;
+				const hints = out.hints ?? liftRoutingHints(out.args);
+				const materialise = () => payload !== void 0 ? unpackPayload(payload) : out.args;
+				const buildInput = () => ({
+					capName: out.capName,
+					method: out.method,
+					args: materialise(),
+					...out.deviceId !== void 0 ? { deviceId: out.deviceId } : {},
+					...out.nodeId !== void 0 ? { nodeId: out.nodeId } : {},
+					...out.native === true ? { native: true } : {},
+					...childId !== null ? { callerAddonId: childId } : {}
+				});
+				if (this.claimedStatus !== void 0 && out.method === "getStatus") {
+					const claimed = await answerClaimedGetStatus(this.claimedStatus, {
+						capName: out.capName,
+						method: out.method,
+						deviceId: out.deviceId ?? (payload === void 0 ? extractDeviceId(out.args) : void 0)
+					});
+					if (claimed !== null) {
+						this.recordCapUsage(childId, null, out.capName, out.method);
+						return claimed.slice;
+					}
+				}
+				const pinnedNodeId = out.nodeId ?? hints.nodeId;
+				const pinTargetsThisNode = pinnedNodeId !== void 0 && this.ownNodeId !== void 0 && pinnedNodeId === this.ownNodeId;
+				const aggregated = pinnedNodeId === void 0 && this.isAggregatedCollectionMethod?.(out.capName, out.method) === true;
+				const addonPinned = pinnedNodeId === void 0 && this.isAddonPinnedCall?.(out.capName, out.method, hints) === true;
+				const target = !(out.native === true) && !aggregated && !addonPinned && (pinnedNodeId === void 0 || pinTargetsThisNode) ? this.resolveChildId(out.capName, out.deviceId) : null;
+				this.recordCapUsage(childId, target, out.capName, out.method);
+				const actionPeer = childId ?? "(pre-register)";
+				const actionLabel = `${out.capName}.${out.method}`;
+				if (target !== null) {
+					if (!this.egressRoutedCaps.has(out.capName)) {
+						this.egressRoutedCaps.add(out.capName);
+						this.logger?.info("routed child egress over UDS", { capName: out.capName });
+					}
+					const entry = this.children.get(target);
+					if (payload !== void 0 && entry !== void 0 && entry.rawForward) {
+						this.forwardedRaw += 1;
+						this.actionCensus.recordForward(actionPeer, actionLabel, "raw");
+						const forward = {
+							kind: "cap-call",
+							capName: out.capName,
+							method: out.method,
+							args: void 0,
+							...out.deviceId !== void 0 ? { deviceId: out.deviceId } : {}
+						};
+						const declared = this.capTimeoutMs?.(out.capName, out.method);
+						return entry.channel.request(forward, {
+							...typeof declared === "number" ? { timeoutMs: declared } : {},
+							payload
+						});
+					}
+					this.forwardedDecoded += 1;
+					this.actionCensus.recordForward(actionPeer, actionLabel, "decoded");
+					const input = buildInput();
+					return entry !== void 0 ? this.callCapOnChild(target, input) : this.callCap(input);
+				}
+				this.forwardedDecoded += 1;
+				this.actionCensus.recordForward(actionPeer, actionLabel, "decoded");
+				if (this.onUnownedCall !== void 0) return this.onUnownedCall(buildInput());
+				throw new Error(`${UDS_NO_ROUTE_PREFIX}: cap-call-out has no local provider for "${out.capName}" and no fallback`);
+			}
+			if (msg.kind === "readiness-request") return {
+				kind: "readiness-snapshot",
+				records: this.readinessHandler?.() ?? []
+			};
+			throw new Error(`unknown child request kind: ${msg.kind}`);
 		});
-	} else rejected.push({
-		kind: "hub-in-process",
-		why: "hub does not provide this cap in-process"
-	});
-	if (snap.hubLocalChildProvides(capName, deviceId)) {
-		const childId = snap.getHubLocalChildId?.(capName, deviceId) ?? null;
-		if (childId !== null) return {
-			kind: "hub-local-uds",
-			capName,
-			childId
-		};
-		rejected.push({
-			kind: "hub-local-uds",
-			why: "child id not resolvable from snapshot"
+		channel.onClose(() => {
+			if (childId === null) return;
+			const entry = this.children.get(childId);
+			if (entry === void 0) return;
+			if (entry.channel !== channel) {
+				this.logger?.info("ignoring close of a superseded local child connection", {
+					childId,
+					incarnation,
+					liveIncarnation: entry.incarnation
+				});
+				return;
+			}
+			this.children.delete(childId);
+			this.invalidateCapIndex();
+			this.childEventStats.delete(childId);
+			this.actionCensus.forget(childId);
+			this.loggedPatternSet.delete(childId);
+			this.goneHandler(childId, incarnation);
 		});
-	} else rejected.push({
-		kind: "hub-local-uds",
-		why: "no hub-local child provides this cap"
-	});
-	const knownNodes = snap.listKnownNodeIds?.() ?? [];
-	for (const nodeId of knownNodes) if (nodeId !== snap.hubNodeId && snap.nodeOnline(nodeId) && snap.nodeKnowsCap(nodeId, capName)) return {
-		kind: "remote-moleculer",
-		capName,
-		nodeId
-	};
-	rejected.push({
-		kind: "remote-moleculer",
-		why: "no online remote node knows this cap"
-	});
-	throw new CapRouteError(capName, void 0, {
-		reason: "no-provider",
-		rejected
-	});
-}
+	}
+};
 //#endregion
-//#region src/kernel/moleculer/resilient-cap-call.ts
-/** Moleculer error `type` values meaning "the service is not (yet) routable". */
-var DISCOVERY_ERROR_TYPES = new Set(["SERVICE_NOT_FOUND", "SERVICE_NOT_AVAILABLE"]);
-/** Default ceiling for the discovery wait — fail-fast past this. */
-var DEFAULT_DISCOVERY_TIMEOUT_MS$1 = 3e4;
-function isDiscoveryError(err) {
-	if (typeof err !== "object" || err === null) return false;
-	const type = err.type;
-	return typeof type === "string" && DISCOVERY_ERROR_TYPES.has(type);
+//#region src/kernel/transport/local-child-client.ts
+/** Did the parent's `register` answer say it accepts payload-borne args? */
+function ackAcceptsRawForward(ack) {
+	if (ack === null || typeof ack !== "object") return false;
+	return ack.rawForward === true;
 }
 /**
-* Call a Moleculer action; on a service-discovery error, wait for the
-* named service to be discovered and retry the call exactly once.
-*/
-async function callWithServiceDiscovery(broker, serviceName, action, params, opts, discoveryTimeoutMs = DEFAULT_DISCOVERY_TIMEOUT_MS$1) {
-	try {
-		return await broker.call(action, params, opts);
-	} catch (err) {
-		if (!isDiscoveryError(err)) throw err;
-		await broker.waitForServices([serviceName], discoveryTimeoutMs);
-		return await broker.call(action, params, opts);
-	}
-}
-//#endregion
-//#region src/kernel/transport/cap-route-resolver.ts
-/** The Moleculer service name that Task 6's agent registers. */
-var AGENT_CAP_FWD_SERVICE = "$agent-cap-fwd";
-/** The Moleculer action (service.action) for agent cap forwarding. */
-var AGENT_CAP_FWD_ACTION = `${AGENT_CAP_FWD_SERVICE}.forward`;
-/** Default timeout for remote Moleculer cap calls (ms). */
-var REMOTE_CALL_TIMEOUT_MS = 6e4;
-function extractDeviceId(args) {
-	if (args === null || typeof args !== "object") return void 0;
-	const raw = Reflect.get(args, "deviceId");
-	return typeof raw === "number" ? raw : void 0;
-}
-/**
-* Extract an inline `nodeId` string from a cap call's args — the per-call node
-* pin a forked addon expresses by carrying `nodeId` in the input (the SAME way
-* device-scoped caps carry `deviceId`, and the way the generated cap-router on
-* the hub already honours an inline pin). Mirrors {@link extractDeviceId}.
+* Child side of the local UDS transport. Connects to its parent (hub or
+* agent), registers its cap manifest, and serves parent→child cap calls by
+* delegating to `dispatch`. The provider implementation lives in the child;
+* only routing keys + call arguments cross the wire.
 *
-* This is the routing source for hub→remote-node EXECUTION pinning (e.g. the
-* benchmark addon running a synthetic/decoder workload ON a chosen agent). The
-* out-of-band `nodePin(op.context)` path does NOT survive the forked addon →
-* hub UDS link chain, so `onUnownedCall` reads the inline pin instead. Provider
-* methods that don't declare `nodeId` simply ignore the extra field (they
-* destructure the fields they need); methods that DO declare it (e.g.
-* `getEngineProvisioning({nodeId})`) still receive it unchanged.
-*/
-function extractNodeId(args) {
-	if (args === null || typeof args !== "object") return void 0;
-	const raw = Reflect.get(args, "nodeId");
-	return typeof raw === "string" && raw.length > 0 ? raw : void 0;
-}
-/**
-* Merge `callerAddonId` into `args` as an extra field — the SAME "provider
-* destructures what it needs and ignores the rest" convention
-* {@link extractNodeId} already relies on for the inline `nodeId` pin.
-* `undefined` (the overwhelmingly common case: no caller hint, or the census
-* consuming it is disarmed) returns `args` unchanged — no allocation. A
-* non-object `args` (or `null`/array) is returned unchanged too: there is
-* nowhere to attach an extra key without changing the payload's shape, and a
-* provider taking a bare value never reads `callerAddonId` off it anyway.
+* Additional channels beyond cap-call:
+*   - `emitEvent`              fire-and-forget event toward the parent
+*   - `sendLog`                fire-and-forget log entry toward the parent
+*   - `requestReadinessSnapshot` request/response snapshot of readiness records
+*   - `onEvent`                register a handler for parent→child events
+*
+* Events and logs emitted before `start()` resolves are buffered and flushed
+* on connect (mirrors the `updateCaps`/`latestCaps` pattern).
 */
-function withCallerAddonId(args, callerAddonId) {
-	if (callerAddonId === void 0) return args;
-	if (args === null || typeof args !== "object" || Array.isArray(args)) return args;
-	return {
-		...args,
-		callerAddonId
-	};
-}
-var CapRouteResolver = class {
-	hubNodeId;
-	broker;
-	hubLocalRegistry;
-	nodeAuthority;
-	inProcessProviders;
-	hubResidentProviders;
-	capTimeoutMs;
-	snapshot;
-	constructor(deps) {
-		this.hubNodeId = deps.hubNodeId;
-		this.broker = deps.broker;
-		this.hubLocalRegistry = deps.hubLocalRegistry;
-		this.nodeAuthority = deps.nodeAuthority;
-		this.inProcessProviders = deps.inProcessProviders;
-		this.hubResidentProviders = deps.hubResidentProviders;
-		this.capTimeoutMs = deps.capTimeoutMs;
-		this.snapshot = this.buildSnapshot();
+var LocalChildClient = class {
+	options;
+	client = null;
+	channel = null;
+	/**
+	* The cap set `start()` will register, kept current by `updateCaps`. Native
+	* device caps register on device-restore, which can race AHEAD of the UDS
+	* connect — buffering here lets a pre-start `updateCaps` survive (start sends
+	* the latest set) instead of being lost or throwing.
+	*/
+	latestCaps;
+	/**
+	* Per-owner (addonId) category-pattern subscription sets, and their union.
+	* The union is declared to the parent (in `RegisterMessage.eventPatterns`
+	* pre/at-connect, or via an `event-sub` emit post-connect) so the parent can
+	* subscription-filter its event fan-out. Per-owner keying keeps the union
+	* correct if multiple event buses ever share one client (group-runner case).
+	*/
+	patternsByOwner = /* @__PURE__ */ new Map();
+	latestEventPatterns = [];
+	/**
+	* Whether `updateEventPatterns` has ever been called. A client that never
+	* declared a subscription set (no event bus wired — e.g. a pure cap-call
+	* runner) omits `eventPatterns` from its register frame entirely, so the
+	* parent treats it as UNDECLARED and fails OPEN (broadcast-all). Once any
+	* owner declares (in production every addon context's framework
+	* subscriptions do), the register carries the real union — even if empty.
+	*/
+	hasDeclaredEventPatterns = false;
+	/**
+	* The custom-action catalogs of every hosted addon, once the runner's init
+	* loop has produced them (`updateCaps(caps, catalogs)` at post-init). `null`
+	* until then, and OMITTED from the register frame while null: the parent
+	* reads absence as "not described yet", and a pre-init register must never
+	* look like "this child declares no actions". Kept on the client so every
+	* later re-register (native-cap change, reconnect) re-carries it unchanged.
+	*/
+	latestCustomActions = null;
+	/** Events and logs queued while the channel is not yet open. */
+	pendingEmits = [];
+	/**
+	* Whether the parent acknowledged raw-forward at `register`. Until it has,
+	* `callOut` sends args inline exactly as every child always did — a legacy
+	* parent would decode a payload-borne call to `args: undefined` and run the
+	* provider on nothing, silently. Re-read on every re-register.
+	*/
+	parentRawForward = false;
+	/** Handler for parent→child events. Registered via `onEvent`. */
+	eventHandler = null;
+	/**
+	* Handler for parent→child addon-level calls (`routes` / `custom`).
+	* Registered via `onAddonCall`. Resolves the loaded addon instance and
+	* invokes its `addon-routes.getRoutes()` or its custom-action handler.
+	* Replaces the per-addon Moleculer `getRoutes` / `custom.<action>` actions
+	* removed in F1/F2. Only one handler is active at a time.
+	*/
+	addonCallHandler = null;
+	/**
+	* Handler for `set-log-level` messages pushed by the parent.
+	* Registered via `onSetLogLevel`. The handler applies the new level to the
+	* child's local Moleculer logger (mirrors `$node-mgmt.setLogLevel`).
+	* E2: wired in `addon-runner.ts` to forward to the broker logger.
+	*/
+	setLogLevelHandler = null;
+	/** Callbacks registered via `onConnected`. Fired on every (re)connect. */
+	connectedHandlers = [];
+	constructor(options) {
+		this.options = options;
+		this.latestCaps = options.caps;
 	}
-	/** Per-call RPC timeout: the cap method's declared override, else the default. */
-	callTimeout(capName, method) {
-		return this.capTimeoutMs?.(capName, method) ?? REMOTE_CALL_TIMEOUT_MS;
+	/**
+	* Declare an owner's live category-pattern subscription set. Stores it
+	* per-owner (keyed by `ownerId` = addonId), recomputes the union, and — only
+	* if the union changed — declares it to the parent:
+	*   - pre-connect: buffered only; `start()`'s register frame carries the set.
+	*   - post-connect: emitted as a fire-and-forget `event-sub` (full-set
+	*     replace).
+	* Idempotent on an unchanged union (no redundant `event-sub` frames).
+	*/
+	updateEventPatterns(ownerId, patterns) {
+		this.hasDeclaredEventPatterns = true;
+		this.patternsByOwner.set(ownerId, patterns);
+		const union = this.computePatternUnion();
+		if (!this.patternsEqual(union, this.latestEventPatterns)) {
+			this.latestEventPatterns = union;
+			if (this.channel !== null) {
+				const msg = {
+					kind: "event-sub",
+					patterns: union
+				};
+				this.channel.emit(msg);
+			}
+		}
+	}
+	/** Sorted, de-duplicated union across all owners' pattern sets. */
+	computePatternUnion() {
+		const all = /* @__PURE__ */ new Set();
+		for (const patterns of this.patternsByOwner.values()) for (const p of patterns) all.add(p);
+		return [...all].toSorted();
+	}
+	/** Order-insensitive equality — both inputs are already sorted unions here. */
+	patternsEqual(a, b) {
+		if (a.length !== b.length) return false;
+		for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;
+		return true;
+	}
+	/**
+	* Register a callback that fires each time the client successfully connects
+	* (or reconnects) to its parent. Multiple handlers may be registered; all
+	* are called in registration order. Used by readiness-context in UDS mode
+	* to trigger a snapshot hydrate on connect/reconnect.
+	*/
+	onConnected(handler) {
+		this.connectedHandlers.push(handler);
+	}
+	/**
+	* Register a handler for events pushed from the parent to this child.
+	* Must be called before `start()` to avoid missing early events (though
+	* registration after start is also safe for events not yet delivered).
+	* Replaces any previously registered handler.
+	*/
+	onEvent(handler) {
+		this.eventHandler = handler;
+	}
+	/**
+	* Register the handler invoked when the parent sends an `addon-call` (the
+	* addon-level routes / custom-action plane). The addon-runner wires this to
+	* resolve the loaded addon by id and dispatch to its `getRoutes()` or its
+	* custom-action handler. Safe to register before or after `start()`;
+	* replaces any prior handler.
+	*/
+	onAddonCall(handler) {
+		this.addonCallHandler = handler;
+	}
+	/**
+	* E2: Register a handler invoked when the parent sends a `set-log-level`
+	* message to this child. The handler should forward the new level to the
+	* child's local Moleculer broker logger (mirrors `$node-mgmt.setLogLevel`).
+	* Safe to register before or after `start()`. Replaces any prior handler.
+	*/
+	onSetLogLevel(handler) {
+		this.setLogLevelHandler = handler;
+	}
+	/**
+	* True once `start()` has successfully connected and registered. Used by
+	* callers (event-bus/logger bridges) to know the channel is live.
+	*/
+	get isConnected() {
+		return this.channel !== null;
+	}
+	async start() {
+		if (this.client !== null) throw new Error("LocalChildClient: already started — call close() first");
+		const client = createLocalTransport().createClient(this.options.nodeId);
+		const channel = await client.connect();
+		channel.onRequest(async (body, payload) => {
+			const msg = body;
+			if (msg.kind === "cap-call") {
+				const args = payload !== void 0 ? unpackPayload(payload) : msg.args;
+				const result = await this.options.dispatch({
+					capName: msg.capName,
+					method: msg.method,
+					args,
+					...msg.deviceId !== void 0 ? { deviceId: msg.deviceId } : {},
+					...msg.addonId !== void 0 ? { addonId: msg.addonId } : {}
+				});
+				if (payload !== void 0 && result !== void 0) return new PayloadReply(void 0, packPayload(result));
+				return result;
+			}
+			if (msg.kind === "addon-call") {
+				if (this.addonCallHandler === null) throw new Error(`LocalChildClient: addon-call for "${msg.addonId}" arrived but no onAddonCall handler is registered`);
+				return this.addonCallHandler({
+					addonId: msg.addonId,
+					target: msg.target,
+					...msg.action !== void 0 ? { action: msg.action } : {},
+					...msg.method !== void 0 ? { method: msg.method } : {},
+					...msg.args !== void 0 ? { args: msg.args } : {},
+					...msg.caller !== void 0 ? { caller: msg.caller } : {}
+				});
+			}
+			throw new Error(`unknown parent request kind: ${msg.kind}`);
+		});
+		channel.onEvent((body) => {
+			const msg = body;
+			if (msg.kind === "event") {
+				this.eventHandler?.(msg.event);
+				return;
+			}
+			if (msg.kind === "set-log-level") this.setLogLevelHandler?.(msg.level);
+		});
+		const register = this.registerFrame(this.latestCaps);
+		try {
+			this.parentRawForward = ackAcceptsRawForward(await channel.request(register));
+		} catch (err) {
+			await client.close();
+			throw err;
+		}
+		this.client = client;
+		this.channel = channel;
+		this.flushPending(channel);
+		for (const cb of this.connectedHandlers) cb();
 	}
-	resolveCapRoute(capName, opts) {
-		return classifyCapRoute(capName, opts, this.snapshot);
+	/** Flush buffered pre-start emits over the now-open channel. */
+	flushPending(channel) {
+		for (const item of this.pendingEmits) channel.emit(item.msg);
+		this.pendingEmits.length = 0;
 	}
 	/**
-	* Resolve the hub-local-uds route for a cap owned by a forked hub-local
-	* child, IGNORING any in-hub provider registered for the same cap name.
-	*
-	* `resolveCapRoute` gives Priority 1 to `hub-in-process`: when an in-hub
-	* provider (e.g. a wrapper) is registered for the cap, the route always
-	* classifies as `hub-in-process` and the hub-local-uds NATIVE child is never
-	* reached. That is correct for the generic dispatch path (the wrapper is the
-	* active provider), but WRONG for the native-cap fallback
-	* (`setNativeFallback`), whose contract is to reach the NATIVE provider in
-	* the forked vendor child so a wrapper can delegate to it. A wrapper cap
-	* with a forked native (today: `snapshot`) otherwise resolves to the wrapper
-	* itself, the native is never invoked, and the wrapper silently falls
-	* through to its secondary strategy.
+	* Re-send the cap manifest to the parent, atomically replacing the child's
+	* registered descriptor set. Call this after device-restore so newly
+	* registered native (device-scoped) caps become routable over UDS.
 	*
-	* This method consults ONLY the hub-local-child authority
-	* (`hubLocalChildProvides` + `getHubLocalChildId`, both deviceId-aware), so
-	* it returns the native child route regardless of any in-process shadow.
-	* Returns null when no hub-local child owns `(capName, deviceId)` — the
-	* caller then falls through to its remote-resolution branch.
+	* Safe to call before `start()`: the new set is buffered and `start()` sends
+	* it (device-restore can race ahead of the UDS connect). After `start()`,
+	* the set is sent immediately.
 	*/
-	resolveHubLocalUdsRoute(capName, deviceId) {
-		if (!this.snapshot.hubLocalChildProvides(capName, deviceId)) return null;
-		const childId = this.snapshot.getHubLocalChildId?.(capName, deviceId) ?? null;
-		if (childId === null) return null;
+	async updateCaps(caps, customActions) {
+		this.latestCaps = caps;
+		if (customActions !== void 0) this.latestCustomActions = customActions;
+		if (this.channel === null) return;
+		this.parentRawForward = ackAcceptsRawForward(await this.channel.request(this.registerFrame(caps)));
+	}
+	/**
+	* The register frame: caps, plus everything a re-register must atomically
+	* re-carry so no separate re-sync can be missed — the subscription union
+	* (omitted if nothing ever declared, which keeps the fail-open shape) and the
+	* custom-action catalogs (omitted until the init loop produced them).
+	*/
+	registerFrame(caps) {
 		return {
-			kind: "hub-local-uds",
-			capName,
-			childId
+			kind: "register",
+			childId: this.options.childId,
+			caps,
+			...this.hasDeclaredEventPatterns ? { eventPatterns: this.latestEventPatterns } : {},
+			...this.latestCustomActions !== null ? { customActions: this.latestCustomActions } : {},
+			rawForward: true
 		};
 	}
 	/**
-	* @param addonId Optional out-of-band PROVIDER-selection hint (Task 7.5a):
-	*   the addonId of the provider the CALLER already resolved (e.g.
-	*   `buildCapCallFn`'s `deps.addonId` for a registered grouped-runner
-	*   provider). Only meaningful for `agent-child-forward` — a `remote-moleculer`
-	*   route already encodes the provider in its action name
-	*   (`${addonId}.${cap}.${method}`, via `NodeCapAuthority.getAddonId`), and a
-	*   `hub-local-uds` caller that already knows the addonId (`buildCapCallFn`)
-	*   talks to `LocalChildRegistry.callCapOnChild` directly rather than through
-	*   `dispatch`.
-	* @param callerAddonId Optional out-of-band CALLER-identity hint — the
-	*   addon that ORIGINATED the call, distinct from `addonId` above (which
-	*   names the resolved PROVIDER, not the caller). Set by
-	*   `onUnownedCall` from `CapCallInput.callerAddonId`
-	*   (`LocalChildRegistry` stamped it off the registered `childId`). Only
-	*   the `hub-in-process` branch consumes it — merged into `args` so a
-	*   diagnostic tool deep in that provider (e.g. device-manager's
-	*   fleet-read census) can read it without every provider method changing
-	*   signature, the same "extra field the provider destructures or
-	*   ignores" convention `nodeId` already uses on this path.
+	* Fire-and-forget: send a system event to the parent for forwarding to the
+	* hub event bus. Safe to call before `start()` — events are buffered and
+	* flushed on connect.
 	*/
-	async dispatch(route, method, args, addonId, callerAddonId) {
-		try {
-			return await this.dispatchInner(route, method, args, addonId, callerAddonId);
-		} catch (err) {
-			if (err instanceof CapRouteError) throw err;
-			if (route.kind === "hub-in-process" || err instanceof PeerAnsweredError) throw err;
-			const nodeId = this.routeNodeId(route);
-			const cause = err instanceof Error ? err : new Error(String(err));
-			throw new CapRouteError(route.capName, method, {
-				reason: "transport-failed",
-				nodeId,
-				rejected: [{
-					kind: route.kind,
-					why: cause.message
-				}]
-			}, cause);
-		}
+	emitEvent(event) {
+		const msg = {
+			kind: "event",
+			event
+		};
+		if (this.channel !== null) this.channel.emit(msg);
+		else this.pendingEmits.push({
+			kind: "event",
+			msg
+		});
 	}
 	/**
-	* Inner dispatch: may throw CapRouteError (validation failures) or arbitrary
-	* transport errors. The outer `dispatch` wraps non-CapRouteErrors.
+	* Fire-and-forget: send a structured log entry to the parent. Safe to call
+	* before `start()` — log entries are buffered and flushed on connect.
 	*/
-	async dispatchInner(route, method, args, addonId, callerAddonId) {
-		switch (route.kind) {
-			case "hub-in-process": return route.ref.invoke(method, withCallerAddonId(args, callerAddonId));
-			case "hub-local-uds": {
-				const registry = this.hubLocalRegistry;
-				if (registry === null) throw new CapRouteError(route.capName, method, {
-					reason: "no-provider",
-					rejected: [{
-						kind: "hub-local-uds",
-						why: "UDS registry not available"
-					}]
-				});
-				const deviceId = extractDeviceId(args);
-				const input = {
-					capName: route.capName,
-					method,
-					args,
-					...deviceId !== void 0 ? { deviceId } : {}
-				};
-				return registry.callCapOnChild(route.childId, input);
-			}
-			case "remote-moleculer": {
-				const addonId = this.nodeAuthority.getAddonId(route.nodeId, route.capName);
-				if (addonId === null) throw new CapRouteError(route.capName, method, {
-					reason: "no-provider",
-					nodeId: route.nodeId,
-					rejected: [{
-						kind: "remote-moleculer",
-						why: `no addonId known for ${route.nodeId}/${route.capName}`
-					}]
-				});
-				const deviceId = extractDeviceId(args);
-				const isNative = this.nodeAuthority.isNativeCap(route.nodeId, route.capName, deviceId);
-				const action = capActionName(addonId, route.capName, method, isNative);
-				return callWithServiceDiscovery(this.broker, addonId, action, args, {
-					nodeID: route.nodeId,
-					timeout: this.callTimeout(route.capName, method)
-				});
-			}
-			case "agent-child-forward": {
-				const deviceId = extractDeviceId(args);
-				const params = {
-					capName: route.capName,
-					method,
-					args,
-					...route.childId !== void 0 ? { childId: route.childId } : {},
-					...deviceId !== void 0 ? { deviceId } : {},
-					...addonId !== void 0 ? { addonId } : {}
-				};
-				return callWithServiceDiscovery(this.broker, AGENT_CAP_FWD_SERVICE, AGENT_CAP_FWD_ACTION, params, {
-					nodeID: route.agentNodeId,
-					timeout: this.callTimeout(route.capName, method)
-				});
-			}
-		}
-	}
-	buildSnapshot() {
-		const hubLocalRegistry = this.hubLocalRegistry;
-		const nodeAuthority = this.nodeAuthority;
-		const inProcessProviders = this.inProcessProviders;
-		const hubResidentProviders = this.hubResidentProviders;
-		return {
-			hubNodeId: this.hubNodeId,
-			hubInProcessProvides: (cap) => inProcessProviders(cap) !== null,
-			...hubResidentProviders !== void 0 ? {
-				hubResidentProvides: (cap) => hubResidentProviders(cap) !== null,
-				getHubResidentProviderRef: (cap) => hubResidentProviders(cap)
-			} : {},
-			hubLocalChildProvides: (cap, deviceId) => hubLocalRegistry !== null && hubLocalRegistry.resolveChildId(cap, deviceId) !== null,
-			nodeKnowsCap: (nodeId, cap) => nodeAuthority.nodeKnowsCap(nodeId, cap),
-			nodeIsAgent: (nodeId) => nodeAuthority.nodeIsAgent(nodeId),
-			nodeOnline: (nodeId) => nodeAuthority.nodeOnline(nodeId),
-			listKnownNodeIds: () => nodeAuthority.listNodeIds(),
-			getInProcessProviderRef: (cap) => inProcessProviders(cap),
-			getHubLocalChildId: (cap, deviceId) => hubLocalRegistry !== null ? hubLocalRegistry.resolveChildId(cap, deviceId) : null,
-			getAgentChildId: (agentNodeId, cap) => nodeAuthority.getAgentChildId(agentNodeId, cap)
+	sendLog(entry) {
+		const msg = {
+			kind: "log",
+			...entry
 		};
+		if (this.channel !== null) this.channel.emit(msg);
+		else this.pendingEmits.push({
+			kind: "log",
+			msg
+		});
 	}
-	/** Extract a nodeId string from a route for error reporting, or undefined. */
-	routeNodeId(route) {
-		switch (route.kind) {
-			case "hub-in-process": return this.hubNodeId;
-			case "hub-local-uds": return `${this.hubNodeId}/${route.childId}`;
-			case "remote-moleculer": return route.nodeId;
-			case "agent-child-forward": return route.agentNodeId;
+	/**
+	* Request the current readiness snapshot from the parent. Returns the
+	* authoritative set of `IReadinessRegistryRecord` entries the hub holds.
+	* Requires `start()` to have been called; throws with a clear message if not.
+	*/
+	async requestReadinessSnapshot() {
+		if (this.channel === null) throw new Error("LocalChildClient: requestReadinessSnapshot called before start()");
+		return (await this.channel.request({ kind: "readiness-request" })).records;
+	}
+	/**
+	* Ask the parent to execute a cap call this child does NOT own. The parent
+	* routes to the owning local sibling over UDS, or — if no sibling owns it —
+	* to its `onUnownedCall` fallback (the cluster CapabilityRegistry in
+	* production). Throws if called before `start()`.
+	*/
+	async callOut(input) {
+		if (this.channel === null) throw new Error("LocalChildClient: callOut before start");
+		const routing = {
+			...input.deviceId !== void 0 ? { deviceId: input.deviceId } : {},
+			...input.nodeId !== void 0 ? { nodeId: input.nodeId } : {},
+			...input.native === true ? { native: true } : {}
+		};
+		if (this.parentRawForward && input.args !== void 0) {
+			const hints = liftRoutingHints(input.args);
+			const msg = {
+				kind: "cap-call-out",
+				capName: input.capName,
+				method: input.method,
+				...Object.keys(hints).length > 0 ? { hints } : {},
+				...routing
+			};
+			const reply = await this.channel.request(msg, { payload: packPayload(input.args) });
+			return reply instanceof PayloadReply ? unpackPayload(reply.payload) : reply;
 		}
+		const msg = {
+			kind: "cap-call-out",
+			capName: input.capName,
+			method: input.method,
+			args: input.args,
+			...routing
+		};
+		return this.channel.request(msg);
+	}
+	/** Disconnect from the parent. Safe to call before `start()` (no-op) and idempotent. */
+	async close() {
+		await this.client?.close();
+		this.client = null;
+		this.channel = null;
 	}
 };
 //#endregion
@@ -9772,6 +9832,13 @@ function createParentUnownedCallHandler(deps) {
 			});
 			throw new Error(`no native provider for capability "${input.capName}" on device ${String(deviceId)}`);
 		}
+		const claimed = await answerClaimedGetStatus(deps.claimedStatus, {
+			capName: input.capName,
+			method: input.method,
+			...deviceId !== void 0 ? { deviceId } : {},
+			args: input.args
+		});
+		if (claimed !== null) return claimed.slice;
 		const nodeId = deps.isDataNodeIdCap?.(input.capName) === true ? void 0 : input.nodeId ?? extractNodeId(input.args);
 		const pinnedToOtherNode = nodeId !== void 0 && nodeId !== deps.broker.nodeID;
 		if (nodeId === void 0) {
@@ -12635,4 +12702,4 @@ function createChildCapDispatch(deps) {
 	};
 }
 //#endregion
-export { CapUsageRegistry as $, capActionLabel as $n, buildHeapSample as $t, resolveHwAccel as A, createOutboundQueueGate as An, CapabilityUnavailableError as At, udsChildLogToWorkerEntry as B, diffSocketPlane as Bn, HEAP_RECLAIM_MIN_INTERVAL_MS as Bt, getBrokerEventBus as C, formatHeapSpaces as Cn, capBareAction as Ct, subscribePassthrough as D, OUTBOUND_QUEUE_COOLDOWN_MS as Dn, serializeTypedArrays as Dt, setNodeEventInterest as E, selectReportedSpaces as En, deserializeTypedArrays as Et, ipcParentLink as F, EMPTY_SOCKET_PLANE_BASELINE as Fn, resolveNpmInvocation as Ft, CapRouteResolver as G, recordSocketFrame as Gn, HUB_MAIN_HEAP_WATCH_LABEL as Gt, createUdsLoggerWithControl as H, readSocketQueues as Hn, HEAP_RECLAIM_TRIGGER_MB as Ht, localProviderLink as I, SOCKET_PLANE_TOP_N as In, runNpm as It, classifyCapRoute as J, socketDirectionMessages as Jn, RSS_BUDGET_REANNOUNCE_MIN_MS as Jt, callWithServiceDiscovery as K, sampleSocketDirection as Kn, HUB_MAIN_RSS_BUDGET_MB as Kt, createParentUnownedCallHandler as L, SOCKET_QUEUE_TOP_N as Ln, createAddonPeerBytesFacility as Lt, brokerTransportLink as M, MESH_QUEUE_TOP_N as Mn, installManifestNativeDeps as Mt, buildLinkChain as N, createMeshQueueReader as Nn, resolveAddonClass as Nt, AddonDepsManager as O, OUTBOUND_QUEUE_SUSTAIN_MS as On, DeviceRegistry as Ot, deviceCapResolverLink as P, formatMeshQueue as Pn, buildNpmChildEnv as Pt, readMoleculerFanoutMode as Q, MAX_CAP_ACTIONS_PER_PEER as Qn, ZERO_LOOP_DELAY as Qt, createUdsEventBridge as R, createSocketPlaneMeter as Rn, hostNodeIdOf as Rt, clusterEventTopic as S, emitHeapDiagnosticReport as Sn, capActionSuffix as St, registerEventBusService as T, readHeapSpaces as Tn, parseCapAction as Tt, AGENT_CAP_FWD_ACTION as U, EMPTY_SOCKET_DIRECTION as Un, HEAP_WATCH_INTERVAL_MS as Ut, createUdsLogger as V, formatSocketPlane as Vn, HEAP_RECLAIM_STEADY_STATE_INTERVAL_MS as Vt, AGENT_CAP_FWD_SERVICE as W, createSocketDirectionCounters as Wn, HEAP_WATCH_WARN_RATIO as Wt, LocalChildRegistry as X, CAP_ACTION_UNLABELLED as Xn, RUNNER_HEAP_WATCH_INTERVAL_MS as Xt, LocalChildClient as Y, CAP_ACTION_OVERFLOW_LABEL as Yn, RSS_BUDGET_RELEASE_RATIO as Yt, UDS_NO_ROUTE_PREFIX as Z, EMPTY_CAP_ACTION_READING as Zn, RUNNER_RSS_BUDGET_ENV as Zt, getWorkerDeviceRegistry as _, createInspectorArrayBufferCensus as _n, setWorkerNativeCapsChangeListener as _t, reapProcessGroup as a, nextRssBudgetState as an, diffEventPlane as ar, UdsLocalTransportServer as at, setHubConnected as b, DECISIVE_HEAP_SPACES as bn, NATIVE_PROVIDER_SERVICE_INFIX as bt, runnerOwnsProcessGroup as c, shouldReclaim as cn, localEndpointPath as ct, summarizeMembers as d, strandedMb as dn, buildNativeCapProxy as dt, createDeferredHeapWatchSink as en, createCapActionCensus as er, PARENT_ROUTED_PROVIDER_ADDON_ID as et, installManifestSystemDeps as f, ARRAY_BUFFER_CENSUS_COOLDOWN_MS as fn, buildUdsNativeCapProxy as ft, createUdsAddonContext as g, createArrayBufferCensusGate as gn, mountNativeCapService as gt, createAddonContext as h, ARRAY_BUFFER_RELEASE_MIN_DROP_RATIO as hn, getWorkerNativeCapSnapshot as ht, killOwnRunnerGroupAfterParentLoss as i, hubMainRssBudget as in, createEventPlaneReader as ir, UdsLocalTransportClient as it, brokerCallForCap as j, formatOutboundQueueVerdict as jn, copyBundledNativeModules as jt, createKernelHwAccel as k, OUTBOUND_QUEUE_THRESHOLD_BYTES as kn, CapabilityHandle as kt, signalAllRunnerGroups as l, startHeapWatch as ln, FrameDecoder as lt, adaptBrokerToCluster as m, ARRAY_BUFFER_CENSUS_THRESHOLD_MB as mn, getWorkerNativeCapProvider as mt, createChildCapDispatch as n, createV8Reclaimer as nn, EVENT_PLANE_TOP_N as nr, getCapUsageRegistry as nt, registerRunnerGroup as o, parseRssBudgetMb as on, formatEventPlane as or, SocketChannel as ot, installManifestPythonDeps as p, ARRAY_BUFFER_CENSUS_SUSTAIN_MS as pn, createBrokerDeviceManagerApi as pt, CapRouteError as q, socketDirectionBytes as qn, HUB_RSS_BUDGET_ENV as qt, defaultProcessGroupOps as r, describeRss as rn, createEventPlaneMeter as rr, createLocalTransport as rt, releaseRunnerGroup as s, reclaimIntervalMs as sn, PeerAnsweredError as st, CAP_METHOD_NOT_IMPLEMENTED as t, createLoopDelayMeter as tn, diffCapActionCensus as tr, __resetCapUsageRegistryForTests as tt, startRunnerParentDeathWatchdog as u, startRunnerHeapWatch as un, encodeFrame as ut, getOrInitReadinessRegistry as v, formatArrayBufferCensus as vn, createAddonService as vt, getMoleculerEventStats as w, heapSpaceField as wn, capServiceName as wt, EVENT_TOPIC_PREFIX as x, HEAP_SPACE_REPORT_MIN_MB as xn, capActionName as xt, getOrInitReadinessRegistryForClient as y, isArrayBufferCensusReport as yn, validateProviderRegistrations as yt, createUdsEventBus as z, createSocketPlaneReader as zn, createAddonDataPlaneFacility as zt };
+export { classifyCapRoute as $, EMPTY_CAP_ACTION_READING as $n, RUNNER_RSS_BUDGET_ENV as $t, resolveHwAccel as A, OUTBOUND_QUEUE_SUSTAIN_MS as An, DeviceRegistry as At, udsChildLogToWorkerEntry as B, createSocketPlaneMeter as Bn, hostNodeIdOf as Bt, getBrokerEventBus as C, HEAP_SPACE_REPORT_MIN_MB as Cn, capActionName as Ct, subscribePassthrough as D, readHeapSpaces as Dn, parseCapAction as Dt, setNodeEventInterest as E, heapSpaceField as En, capServiceName as Et, ipcParentLink as F, createMeshQueueReader as Fn, resolveAddonClass as Ft, UDS_NO_ROUTE_PREFIX as G, EMPTY_SOCKET_DIRECTION as Gn, HEAP_WATCH_INTERVAL_MS as Gt, createUdsLoggerWithControl as H, diffSocketPlane as Hn, HEAP_RECLAIM_MIN_INTERVAL_MS as Ht, localProviderLink as I, formatMeshQueue as In, buildNpmChildEnv as It, deviceOfGetStatus as J, sampleSocketDirection as Jn, HUB_MAIN_RSS_BUDGET_MB as Jt, GET_STATUS_METHOD as K, createSocketDirectionCounters as Kn, HEAP_WATCH_WARN_RATIO as Kt, createParentUnownedCallHandler as L, EMPTY_SOCKET_PLANE_BASELINE as Ln, resolveNpmInvocation as Lt, brokerTransportLink as M, createOutboundQueueGate as Mn, CapabilityUnavailableError as Mt, buildLinkChain as N, formatOutboundQueueVerdict as Nn, copyBundledNativeModules as Nt, AddonDepsManager as O, selectReportedSpaces as On, deserializeTypedArrays as Ot, deviceCapResolverLink as P, MESH_QUEUE_TOP_N as Pn, installManifestNativeDeps as Pt, CapRouteError as Q, CAP_ACTION_UNLABELLED as Qn, RUNNER_HEAP_WATCH_INTERVAL_MS as Qt, createUdsEventBridge as R, SOCKET_PLANE_TOP_N as Rn, runNpm as Rt, clusterEventTopic as S, DECISIVE_HEAP_SPACES as Sn, NATIVE_PROVIDER_SERVICE_INFIX as St, registerEventBusService as T, formatHeapSpaces as Tn, capBareAction as Tt, LocalChildClient as U, formatSocketPlane as Un, HEAP_RECLAIM_STEADY_STATE_INTERVAL_MS as Ut, createUdsLogger as V, createSocketPlaneReader as Vn, createAddonDataPlaneFacility as Vt, LocalChildRegistry as W, readSocketQueues as Wn, HEAP_RECLAIM_TRIGGER_MB as Wt, AGENT_CAP_FWD_SERVICE as X, socketDirectionMessages as Xn, RSS_BUDGET_REANNOUNCE_MIN_MS as Xt, AGENT_CAP_FWD_ACTION as Y, socketDirectionBytes as Yn, HUB_RSS_BUDGET_ENV as Yt, CapRouteResolver as Z, CAP_ACTION_OVERFLOW_LABEL as Zn, RSS_BUDGET_RELEASE_RATIO as Zt, getWorkerDeviceRegistry as _, ARRAY_BUFFER_RELEASE_MIN_DROP_RATIO as _n, getWorkerNativeCapSnapshot as _t, reapProcessGroup as a, describeRss as an, createEventPlaneMeter as ar, getCapUsageRegistry as at, setHubConnected as b, formatArrayBufferCensus as bn, createAddonService as bt, runnerOwnsProcessGroup as c, parseRssBudgetMb as cn, formatEventPlane as cr, UdsLocalTransportServer as ct, summarizeMembers as d, startHeapWatch as dn, localEndpointPath as dt, ZERO_LOOP_DELAY as en, MAX_CAP_ACTIONS_PER_PEER as er, callWithServiceDiscovery as et, installManifestSystemDeps as f, startRunnerHeapWatch as fn, FrameDecoder as ft, createUdsAddonContext as g, ARRAY_BUFFER_CENSUS_THRESHOLD_MB as gn, getWorkerNativeCapProvider as gt, createAddonContext as h, ARRAY_BUFFER_CENSUS_SUSTAIN_MS as hn, createBrokerDeviceManagerApi as ht, killOwnRunnerGroupAfterParentLoss as i, createV8Reclaimer as in, EVENT_PLANE_TOP_N as ir, __resetCapUsageRegistryForTests as it, brokerCallForCap as j, OUTBOUND_QUEUE_THRESHOLD_BYTES as jn, CapabilityHandle as jt, createKernelHwAccel as k, OUTBOUND_QUEUE_COOLDOWN_MS as kn, serializeTypedArrays as kt, signalAllRunnerGroups as l, reclaimIntervalMs as ln, SocketChannel as lt, adaptBrokerToCluster as m, ARRAY_BUFFER_CENSUS_COOLDOWN_MS as mn, buildNativeCapProxy as mt, createChildCapDispatch as n, createDeferredHeapWatchSink as nn, createCapActionCensus as nr, CapUsageRegistry as nt, registerRunnerGroup as o, hubMainRssBudget as on, createEventPlaneReader as or, createLocalTransport as ot, installManifestPythonDeps as p, strandedMb as pn, encodeFrame as pt, answerClaimedGetStatus as q, recordSocketFrame as qn, HUB_MAIN_HEAP_WATCH_LABEL as qt, defaultProcessGroupOps as r, createLoopDelayMeter as rn, diffCapActionCensus as rr, PARENT_ROUTED_PROVIDER_ADDON_ID as rt, releaseRunnerGroup as s, nextRssBudgetState as sn, diffEventPlane as sr, UdsLocalTransportClient as st, CAP_METHOD_NOT_IMPLEMENTED as t, buildHeapSample as tn, capActionLabel as tr, readMoleculerFanoutMode as tt, startRunnerParentDeathWatchdog as u, shouldReclaim as un, PeerAnsweredError as ut, getOrInitReadinessRegistry as v, createArrayBufferCensusGate as vn, mountNativeCapService as vt, getMoleculerEventStats as w, emitHeapDiagnosticReport as wn, capActionSuffix as wt, EVENT_TOPIC_PREFIX as x, isArrayBufferCensusReport as xn, validateProviderRegistrations as xt, getOrInitReadinessRegistryForClient as y, createInspectorArrayBufferCensus as yn, setWorkerNativeCapsChangeListener as yt, createUdsEventBus as z, SOCKET_QUEUE_TOP_N as zn, createAddonPeerBytesFacility as zt };