@camstack/system 1.2.144 → 1.2.146

package/dist/kernel/moleculer/process-service.d.ts

@@ -16,10 +16,20 @@ interface RunnerAddonSpec {
  * one-off burst becomes the runner's permanent RSS.
  *
  * Measured on the live hub, 2026-08-17: the `recorder` runner reaches **2122 MB RSS** and stays
- * there after the deferred archive walk (99,809 segments in 84s), while the `RecordingIndex` it
- * actually retains is arithmetically ~21 MB (a `SegmentRow` is 5 numbers + 3 strings ≈ 207 B). The
- * same addon on two agent nodes carrying the same code and a smaller archive sits at **58 MB**.
- * The ~2 GB is walk garbage held as high-water in a heap that had no reason to collect it.
+ * there. The same addon on two agent nodes carrying the same code and a smaller archive sits at
+ * **58 MB**.
+ *
+ * ⚠ This paragraph used to attribute that ~2 GB to "walk garbage" from the deferred archive walk,
+ * and to argue from a ~21 MB `RecordingIndex`. Both were wrong, and the error cost a session on
+ * 2026-08-27. The deferred walk had NO CALLER and never ran (it has since been deleted). And the
+ * index is not 21 MB: a 2026-08-27 profile of the live recorder read `heapUsed = 1606 MB` against
+ * `external = 8 MB`, with an `smaps` census putting 1510 MB in V8's 256 KB page ranges against
+ * 54 MB of native heap — LIVE JavaScript retainers, not high-water garbage. The retained set is
+ * ~7.1 M `SegmentRow`s plus their path strings and Map entries (13 cameras x 2 profiles x 8 640
+ * segments/day x ~30 days), reseeded at boot by `SegmentHourLedger.hydrateIndex`.
+ *
+ * The lesson for anyone sizing this flag: a heap number needs a RETAINER, and "garbage the GC has
+ * no reason to collect" is the explanation to reach for last, not first.
  *
  * ## Why 1024
  *
@@ -36,8 +46,7 @@ interface RunnerAddonSpec {
  *
  * A runner whose working set genuinely does not fit declares its own number in its manifest
  * (`execution.maxOldSpaceMb`) — the number belongs next to the addon that knows its working set.
- * `recorder` (3072 MB; peak 2341 MB heapTotal during the deferred archive walk) is the one
- * shipped addon that does. `stream-broker` does NOT, despite 1585 MB peak RSS: ~1 GB of that is
+ * `recorder` (3072 MB; peak 2341 MB heapTotal) is the one shipped addon that does. `stream-broker` does NOT, despite 1585 MB peak RSS: ~1 GB of that is
  * `arrayBuffers` (47 RTP rings), which this flag does not bound and never will — its actual old
  * space peaks at 224 MB. Size the declaration from `heapTotal` in the `[mem]` heartbeat, never
  * from RSS.

package/dist/{manifest-python-deps-BuhBXCg0.mjs → manifest-python-deps-CVeckyXx.mjs}

@@ -1,3 +1,4 @@
+import "./dist-CG7kwIZp.mjs";
 import * as crypto$1 from "node:crypto";
 import { randomBytes, randomUUID } from "node:crypto";
 import { ensureBinary, ensureFfmpeg, ensurePython, installPythonPackages, installPythonRequirements } from "@camstack/types/node";
@@ -261,6 +262,22 @@ var consoleSink = {
 * The subtrahend is heapUSED, not heapTotal, deliberately: the pages V8
 * committed at a sawtooth peak and no longer needs are counted inside heapTotal,
 * and they are precisely what this number exists to see.
+*
+* ## What this number can and CANNOT be asked
+*
+* It answers exactly one question: *are there pages a `last-resort` GC could
+* hand back?* For that it is correct, and {@link shouldReclaim} is the only
+* gate that should ever be built on it.
+*
+* It can never answer *is this process too big?*, because `external` is
+* subtracted by construction. A process whose growth is entirely `external` —
+* Buffers, `arrayBuffers`, what a native addon mallocs — moves `rss` and the
+* subtrahend by the same amount, so this number is **algebraically constant
+* while the process triples**. That is not a threshold set too high; the
+* quantity cannot represent the event.
+*
+* It cost 11.4GB and a ~154 second stall of the whole container to establish
+* that. See {@link RssBudgetOptions} for the number that does answer it.
 */
 function strandedMb(s) {
 	return s.rssMb - s.heapUsedMb - s.externalMb;
@@ -269,6 +286,67 @@ function strandedMb(s) {
 function shouldReclaim(s, triggerMb = HEAP_RECLAIM_TRIGGER_MB) {
 	return strandedMb(s) > triggerMb;
 }
+/** Share of RSS, as a whole percent. Never divides by zero. */
+function share(partMb, rssMb) {
+	return rssMb > 0 ? Math.round(partMb / rssMb * 100) : 0;
+}
+/**
+* Split a sample into the three shapes and name the dominant one.
+*
+* `nativeResidue` is clamped at 0: `process.memoryUsage()` reads its fields at
+* slightly different instants, so `heapUsed + external` can transiently exceed
+* `rss` and a negative residue would misclassify the sample.
+*/
+function describeRss(s, budgetMb) {
+	const nativeResidueMb = Math.max(0, strandedMb(s));
+	const shape = s.heapUsedMb >= s.externalMb && s.heapUsedMb >= nativeResidueMb ? "v8-heap" : s.externalMb >= nativeResidueMb ? "external" : "native-residue";
+	return {
+		rssMb: s.rssMb,
+		budgetMb,
+		overMb: Math.max(0, s.rssMb - budgetMb),
+		heapUsedMb: s.heapUsedMb,
+		externalMb: s.externalMb,
+		nativeResidueMb,
+		arrayBuffersMb: s.arrayBuffersMb,
+		shape
+	};
+}
+/** What the operator can actually DO about each shape. */
+var SHAPE_ADVICE = {
+	"v8-heap": "live JS retainers — bounded by --max-old-space-size; the fix is the retained set",
+	external: "Buffers / native external — NO V8 flag bounds this, and the old-space ceiling never will",
+	"native-residue": "freed native memory the allocator has not returned — MALLOC_ARENA_MAX/VIPS_CONCURRENCY are already applied, so this lever is spent"
+};
+/**
+* Release the alarm below this share of the budget.
+*
+* Hysteresis, not a second budget: every process here sawtooths (the reclaim
+* pass alone moves hub-main by ~1.6GB), so a single threshold would print a
+* pair of lines on every cycle. 0.9 of the budget is a real retreat.
+*/
+var RSS_BUDGET_RELEASE_RATIO = .9;
+/**
+* Floor on how often a crossing may be ANNOUNCED again.
+*
+* Hysteresis alone bounds flapping around the edge; it does not bound a process
+* that genuinely swings across the budget every reclaim cycle
+* ({@link HEAP_RECLAIM_MIN_INTERVAL_MS} is 2 minutes, so that is up to 30 pairs
+* of lines an hour, forever). A process that oscillates across its budget is ONE
+* story, and the operator needs it told once per quarter-hour, not thirty times.
+*
+* This is the discipline the rest of this module already follows and the one the
+* log needed: on 2026-08-27 two real alarms were buried under 83,198 Hikvision
+* heartbeat lines in 12h. A watchdog that shouts is a watchdog that gets muted.
+*/
+var RSS_BUDGET_REANNOUNCE_MIN_MS = 9e5;
+/**
+* The alarm state machine, pure so the thresholds are testable without
+* allocating five gigabytes to reach them.
+*/
+function nextRssBudgetState(current, rssMb, budgetMb, releaseRatio = RSS_BUDGET_RELEASE_RATIO) {
+	if (current === "over") return rssMb < budgetMb * releaseRatio ? "within" : "over";
+	return rssMb > budgetMb ? "over" : "within";
+}
 function isGcFunction(value) {
 	return typeof value === "function";
 }
@@ -296,8 +374,19 @@ function createV8Reclaimer() {
 		return;
 	}
 }
-function format(label, s, loop) {
-	const line = `[mem] ${label} rss=${s.rssMb}MB heapUsed=${s.heapUsedMb}MB heapTotal=${s.heapTotalMb}MB heapLimit=${s.heapLimitMb}MB used=${Math.round(s.usedRatio * 100)}% external=${s.externalMb}MB arrayBuffers=${s.arrayBuffersMb}MB`;
+/**
+* The line that says HOW the process grew, not merely that it did.
+*
+* `heapUsed`, `external` and the native residue each carry their share of RSS,
+* because the shares are what separate the three fixes — and on the process this
+* module failed to catch, the shares were 9% / 74% / 16%, which names the answer
+* on sight.
+*/
+function formatOverBudget(label, b, source) {
+	return `[mem] ${label} OVER RSS BUDGET rss=${b.rssMb}MB budget=${b.budgetMb}MB over=+${b.overMb}MB shape=${b.shape} heapUsed=${b.heapUsedMb}MB(${share(b.heapUsedMb, b.rssMb)}%) external=${b.externalMb}MB(${share(b.externalMb, b.rssMb)}%) nativeResidue=${b.nativeResidueMb}MB(${share(b.nativeResidueMb, b.rssMb)}%) arrayBuffers=${b.arrayBuffersMb}MB budgetFrom="${source}" — ${SHAPE_ADVICE[b.shape]}`;
+}
+function format(label, s, loop, budgetMb) {
+	const line = `[mem] ${label} rss=${s.rssMb}MB heapUsed=${s.heapUsedMb}MB heapTotal=${s.heapTotalMb}MB heapLimit=${s.heapLimitMb}MB used=${Math.round(s.usedRatio * 100)}% external=${s.externalMb}MB arrayBuffers=${s.arrayBuffersMb}MB` + (budgetMb === void 0 ? "" : ` rssBudget=${budgetMb}MB`);
 	if (loop === void 0) return line;
 	return `${line} loopP50=${loop.p50Ms}ms loopP99=${loop.p99Ms}ms loopMax=${loop.maxMs}ms`;
 }
@@ -307,7 +396,7 @@ function format(label, s, loop) {
 * `unref`ed so it can never hold the process open, and every read is wrapped:
 * a diagnostic that can crash the process it watches is worse than none.
 */
-function startHeapWatch(label = "hub-main", sink = consoleSink, intervalMs = HEAP_WATCH_INTERVAL_MS, reclaimOptions, loopDelay = createLoopDelayMeter(), execArgv = process.execArgv, announceCeilingOrigin = true) {
+function startHeapWatch(label = "hub-main", sink = consoleSink, intervalMs = HEAP_WATCH_INTERVAL_MS, reclaimOptions, loopDelay = createLoopDelayMeter(), execArgv = process.execArgv, announceCeilingOrigin = true, rssBudget) {
 	const readMemory = reclaimOptions?.readMemory ?? (() => process.memoryUsage());
 	const now = reclaimOptions?.now ?? (() => Date.now());
 	const triggerMb = reclaimOptions?.triggerMb ?? 1024;
@@ -351,6 +440,39 @@ function startHeapWatch(label = "hub-main", sink = consoleSink, intervalMs = HEA
 	};
 	let mode = "steady";
 	let lastLoggedAt = Number.NEGATIVE_INFINITY;
+	const budgetMb = rssBudget?.budgetMb !== void 0 && rssBudget.budgetMb > 0 ? rssBudget.budgetMb : void 0;
+	const budgetSource = rssBudget?.source ?? "unspecified";
+	const releaseRatio = rssBudget?.releaseRatio ?? .9;
+	const reannounceMinMs = rssBudget?.reannounceMinMs ?? 9e5;
+	let budgetState = "within";
+	let lastBudgetWarnAt = Number.NEGATIVE_INFINITY;
+	/** Only pair a "back within" with an over-budget line that was actually said. */
+	let overBudgetAnnounced = false;
+	/**
+	* One line per STATE CHANGE, never one per sample.
+	*
+	* The probe runs every {@link HEAP_WATCH_FAST_INTERVAL_MS}; warning on every
+	* sample above the budget would put 30 lines a minute in the hub's shared log
+	* for a process that is legitimately, steadily large. That is precisely the
+	* failure mode that buried two real alarms under 83,198 heartbeat lines on
+	* 2026-08-27, so the crossing is the event and the level is not.
+	*/
+	const checkRssBudget = (sample, at) => {
+		if (budgetMb === void 0) return;
+		const previous = budgetState;
+		budgetState = nextRssBudgetState(previous, sample.rssMb, budgetMb, releaseRatio);
+		if (budgetState === previous) return;
+		if (budgetState === "over") {
+			if (at - lastBudgetWarnAt < reannounceMinMs) return;
+			lastBudgetWarnAt = at;
+			overBudgetAnnounced = true;
+			sink.warn(formatOverBudget(label, describeRss(sample, budgetMb), budgetSource));
+			return;
+		}
+		if (!overBudgetAnnounced) return;
+		overBudgetAnnounced = false;
+		sink.info(`[mem] ${label} back within its RSS budget — rss=${sample.rssMb}MB budget=${budgetMb}MB`);
+	};
 	/**
 	* PROBING and LOGGING are separate cadences, and that separation is the whole
 	* point.
@@ -376,18 +498,20 @@ function startHeapWatch(label = "hub-main", sink = consoleSink, intervalMs = HEA
 			const due = at - lastLoggedAt >= intervalMs;
 			if (mode === "escalated" || due) {
 				lastLoggedAt = at;
-				const line = format(label, sample, loopDelay?.read());
+				const line = format(label, sample, loopDelay?.read(), budgetMb);
 				if (sample.nearLimit) sink.warn(`${line} — APPROACHING HEAP LIMIT`);
 				else if (mode === "escalated") sink.warn(`${line} — heap elevated, sampling every ${probeIntervalMs}ms`);
 				else sink.info(line);
 			}
 			if (previous === "escalated" && mode === "steady") sink.info(`[mem] ${label} heap back to routine — logging every ${intervalMs}ms`);
+			checkRssBudget(sample, at);
 			maybeReclaim(sample);
 		} catch {}
 	};
 	const timer = setInterval(tick, probeIntervalMs);
 	timer.unref?.();
 	tick();
+	if (rssBudget !== void 0 && budgetMb === void 0) sink.info(`[mem] ${label} is NOT WATCHED against an RSS budget — no budget declared (${budgetSource}). rss growth outside the V8 heap raises nothing here: --max-old-space-size bounds old space only, and stranded subtracts external by construction. Declare execution.rssBudgetMb once this process has a measured working set.`);
 	if (announceCeilingOrigin && heapCeilingOrigin(execArgv) === "v8-default") sink.info(`[mem] ${label} heap ceiling is V8's DEFAULT (${read().heapLimitMb}MB) — no --max-old-space-size on argv. Nothing here CHOSE that number; it is derived from host RAM and moves with it.`);
 	let stopped = false;
 	return () => {
@@ -413,6 +537,71 @@ function startHeapWatch(label = "hub-main", sink = consoleSink, intervalMs = HEA
 */
 var RUNNER_HEAP_WATCH_INTERVAL_MS = 3e5;
 /**
+* Parse a budget carried across a process boundary as an env string.
+*
+* Anything that is not a positive finite integer is `undefined` — i.e. the
+* process is UNWATCHED and says so. A malformed budget must never round to a
+* silent default: that is the failure this whole mechanism exists to remove.
+*/
+function parseRssBudgetMb(raw) {
+	if (raw === void 0) return void 0;
+	const parsed = Number(raw);
+	if (!Number.isFinite(parsed) || parsed <= 0) return void 0;
+	return Math.floor(parsed);
+}
+/** Env var carrying a runner's declared RSS budget from parent to child. */
+var RUNNER_RSS_BUDGET_ENV = "CAMSTACK_RUNNER_RSS_BUDGET_MB";
+/** Operator override for hub-main's budget, applied without a release. */
+var HUB_RSS_BUDGET_ENV = "CAMSTACK_HUB_RSS_BUDGET_MB";
+/**
+* hub-main's declared RSS budget, in MB.
+*
+* ## Why the number lives HERE and not in the image
+*
+* hub-main has no manifest to declare it in, and the obvious alternative — the
+* entrypoint that already knew about `CAMSTACK_HUB_HEAP_MB` — is the least
+* deployable surface in this system. The Dockerfile says so itself: the image
+* never contains this repo's backend, so a value written there reaches a running
+* hub only on an image rebuild. `main.ts` is what `applyServerUpdate` replaces,
+* which is exactly why the heartbeat was started from there in the first place.
+* A budget that cannot ship is not a budget.
+*
+* ## Why 4096
+*
+* hub-main's entitlement is its old-space ceiling plus its measured native
+* floor. The floor is 438MB, established live across five consecutive
+* `gc(last-resort)` passes that landed within 4MB of each other
+* (4559/4561/4560/4562/4563MB) — sqlite pages, libvips, sharp, thread stacks and
+* node's own text. Against the 3072MB ceiling in force on 2026-08-27 that is
+* ~3.5GB of legitimate footprint, and 4096 leaves it ~600MB of slack.
+*
+* **This WILL fire on the hub as measured on 2026-08-27, and that is the point.**
+* That process sat at 4.87GiB with `external` at 360MB: ~2.8GB of it was native
+* memory already freed and never returned, spread across 13 anonymous mappings
+* >=64MB, with only 1295MB in V8 pages. `MALLOC_ARENA_MAX=2` and
+* `VIPS_CONCURRENCY=1` were already applied — verified from `/proc/<pid>/environ`
+* — so that lever is spent and the residue stands. The alarm reporting a
+* genuinely over-budget process is the mechanism working; a number picked to sit
+* just above today's RSS would be a rubber stamp.
+*
+* An operator who decides that residue is the cost of doing business moves it in
+* one place with {@link HUB_RSS_BUDGET_ENV}, and the decision is on the record
+* instead of being absorbed by a threshold nobody set.
+*/
+var HUB_MAIN_RSS_BUDGET_MB = 4096;
+/** hub-main's budget: the declared number, or the operator's override. */
+function hubMainRssBudget(env = process.env) {
+	const override = env[HUB_RSS_BUDGET_ENV];
+	if (override !== void 0) return {
+		budgetMb: parseRssBudgetMb(override),
+		source: HUB_RSS_BUDGET_ENV
+	};
+	return {
+		budgetMb: HUB_MAIN_RSS_BUDGET_MB,
+		source: "HUB_MAIN_RSS_BUDGET_MB (kernel/heap-watch)"
+	};
+}
+/**
 * Start the heap watch + stranded-page reclaimer for ONE addon runner, iff it
 * is a heavy one. Returns the stop function, or undefined when nothing started.
 *
@@ -446,13 +635,17 @@ var RUNNER_HEAP_WATCH_INTERVAL_MS = 3e5;
 function startRunnerHeapWatch(options) {
 	if (options.heapProfile !== "heavy") return void 0;
 	const intervalMs = options.intervalMs ?? 3e5;
-	if (options.reclaimSwitch === "off") return startHeapWatch(options.label, options.sink, intervalMs, void 0, void 0, void 0, false);
+	const rssBudget = {
+		budgetMb: parseRssBudgetMb(options.rssBudgetMb),
+		source: `manifest execution.rssBudgetMb (via ${RUNNER_RSS_BUDGET_ENV})`
+	};
+	if (options.reclaimSwitch === "off") return startHeapWatch(options.label, options.sink, intervalMs, void 0, void 0, void 0, false, rssBudget);
 	let reclaimOptions = options.reclaimOptions;
 	if (reclaimOptions === void 0) {
 		const reclaimer = createV8Reclaimer();
 		reclaimOptions = reclaimer === void 0 ? void 0 : { reclaim: reclaimer };
 	}
-	return startHeapWatch(options.label, options.sink, intervalMs, reclaimOptions, void 0, void 0, true);
+	return startHeapWatch(options.label, options.sink, intervalMs, reclaimOptions, void 0, void 0, true, rssBudget);
 }
 //#endregion
 //#region src/kernel/moleculer/addon-data-plane-facility.ts
@@ -1649,6 +1842,182 @@ async function readModifyWrite(input) {
 	return true;
 }
 //#endregion
+//#region src/kernel/moleculer/children-batch-loader.ts
+/**
+* "Who are my children?" asked by a thousand devices, answered in a handful of
+* calls.
+*
+* ## The number
+*
+* Every `BaseDevice` inherits a `getAccessoryChildren()` that returns `[]`, so
+* the accessory reconcile in `device-cap-proxy.ts` runs its orphan-prune step
+* for EVERY registered device — including the leaf accessories that can never
+* own one. Each pass asked `device-manager.getChildren` for its own id.
+* Measured on the live hub 2026-08-27, 120-second boot window, 1 017 devices:
+* **1 024 calls returning 919 rows in total**. A thousand round-trips, and a
+* thousand indexed scans behind them, to move less than one row each.
+*
+* ## Why a loader and not a caller that loops
+*
+* There is no loop to unroll. Reconcile is per-device by construction: it runs
+* inside `register()`, and again whenever a late feature-probe writes the
+* slice. The repetition is a THOUSAND INDEPENDENT CALLERS, not one caller
+* asking a thousand times — so the collapse has to happen between them.
+*
+* ## Why the batch is self-clocking, with no window to tune
+*
+* At most ONE batch call is in flight. Anything that arrives while it is in
+* flight lands in the next batch, dispatched the moment the current one
+* settles. That makes the batch size adapt to the arrival rate on its own:
+*
+*  - Idle: the first caller flushes on the next macrotask. No added wait, and
+*    no timer to pick a value for and be wrong about.
+*  - Boot: `BaseDeviceProvider.onRestoreDevices` issues every top-level
+*    `create()` at once and `runBounded(specs, 12)` spawns accessory children
+*    twelve wide, so reconciles arrive in bursts — measured as 2 372 device
+*    log lines in one 5-second bucket at boot+16s, against 62 at boot+142s.
+*    Every arrival inside one round-trip collapses into the next call.
+*  - Worst case: arrivals slower than a round-trip give batches of one, which
+*    is exactly today's cost. The loader can never be worse than what it
+*    replaces.
+*
+* A fixed debounce window would have to be guessed against that distribution,
+* and would tax the idle case to pay for the busy one.
+*
+* ## Degrading, rather than breaking, against an older hub
+*
+* `getChildrenBatch` is a NEW method: a hub that predates it rejects the call
+* (it does not silently strip the input and answer a different question, which
+* is what adding a `parentDeviceIds` FIELD to `getChildren` would have done).
+* Every waiter in a failed batch is then answered by the per-parent
+* `getChildren` it would have used anyway, so the reconcile is never denied
+* its answer. A rejection that names the method as unknown latches the
+* fallback permanently — re-probing a method the hub will never have, once per
+* batch for a whole boot, is the storm this exists to remove.
+*/
+/**
+* Narrow an untyped cap answer to the fields the reconcile reads.
+*
+* `callDeviceManager` is an untyped boundary, and the answer may come from a
+* hub of a different vintage. A row that does not carry an id, a stableId and
+* a name is not a child this code can prune ON, so it is dropped rather than
+* cast into shape — the prune step DELETES, and a half-parsed row is the input
+* that would make it delete the wrong thing.
+*/
+function parseChildRows(value) {
+	if (!Array.isArray(value)) return null;
+	const rows = [];
+	for (const entry of value) {
+		if (typeof entry !== "object" || entry === null) return null;
+		const id = Reflect.get(entry, "id");
+		const stableId = Reflect.get(entry, "stableId");
+		const name = Reflect.get(entry, "name");
+		const linkDeviceId = Reflect.get(entry, "linkDeviceId");
+		if (typeof id !== "number" || typeof stableId !== "string" || typeof name !== "string") return null;
+		rows.push({
+			id,
+			stableId,
+			name,
+			...typeof linkDeviceId === "number" || linkDeviceId === null ? { linkDeviceId } : {}
+		});
+	}
+	return rows;
+}
+/**
+* Narrow a `getChildrenBatch` answer: a record keyed by parent id as a string.
+*
+* An EMPTY record is a valid answer — "none of these parents has children" —
+* and so is what a hub that answers the call but knows none of the parents
+* would send. Both mean "nothing to prune", which is the safe direction. Only
+* a shape that is not a record at all is `null`, and the loader treats that as
+* a failed batch and re-asks per parent.
+*/
+function parseChildrenByParent(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
+	const out = /* @__PURE__ */ new Map();
+	for (const [key, entry] of Object.entries(value)) {
+		const parentDeviceId = Number(key);
+		if (!Number.isInteger(parentDeviceId)) return null;
+		const rows = parseChildRows(entry);
+		if (rows === null) return null;
+		out.set(parentDeviceId, rows);
+	}
+	return out;
+}
+/**
+* True when an error says the hub has no such procedure — the version-skew
+* case, and the only one worth latching on. Anything else (a timeout, a busy
+* broker) is transient and must not disable batching for the process lifetime.
+*/
+function looksLikeUnknownMethod(err) {
+	const lowered = (err instanceof Error ? err.message : String(err)).toLowerCase();
+	return lowered.includes("not_found") || lowered.includes("no procedure") || lowered.includes("unknown method") || lowered.includes("no such method") || lowered.includes("not available");
+}
+function createChildrenBatchLoader(opts) {
+	const maxBatch = Math.max(1, opts.maxBatch ?? 256);
+	let pending = [];
+	let flushScheduled = false;
+	let flushing = false;
+	let batchUnsupported = false;
+	const answerOneByOne = async (waiters) => {
+		await Promise.all(waiters.map(async (waiter) => {
+			try {
+				waiter.resolve(await opts.fetchOne(waiter.parentDeviceId));
+			} catch (err) {
+				waiter.reject(err);
+			}
+		}));
+	};
+	const runBatch = async (waiters) => {
+		const parentDeviceIds = [...new Set(waiters.map((w) => w.parentDeviceId))];
+		try {
+			const byParent = await opts.fetchBatch(parentDeviceIds);
+			for (const waiter of waiters) waiter.resolve(byParent.get(waiter.parentDeviceId) ?? []);
+		} catch (err) {
+			const unknown = looksLikeUnknownMethod(err);
+			if (unknown) batchUnsupported = true;
+			opts.logger.warn(unknown ? "device-manager.getChildrenBatch is not available on this hub — falling back to per-parent getChildren for the process lifetime" : "device-manager.getChildrenBatch failed — answering this batch per parent", { meta: {
+				parents: parentDeviceIds.length,
+				error: err instanceof Error ? err.message : String(err)
+			} });
+			await answerOneByOne(waiters);
+		}
+	};
+	const flush = async () => {
+		flushing = true;
+		try {
+			while (pending.length > 0) {
+				const batch = pending.slice(0, maxBatch);
+				pending = pending.slice(maxBatch);
+				if (batchUnsupported) await answerOneByOne(batch);
+				else await runBatch(batch);
+			}
+		} finally {
+			flushing = false;
+		}
+	};
+	const scheduleFlush = () => {
+		if (flushScheduled || flushing) return;
+		flushScheduled = true;
+		setTimeout(() => {
+			flushScheduled = false;
+			flush().catch((err) => {
+				opts.logger.warn("children batch flush threw", { meta: { error: err instanceof Error ? err.message : String(err) } });
+			});
+		}, 0);
+	};
+	return { load(parentDeviceId) {
+		return new Promise((resolve, reject) => {
+			pending.push({
+				parentDeviceId,
+				resolve,
+				reject
+			});
+			scheduleFlush();
+		});
+	} };
+}
+//#endregion
 //#region src/kernel/moleculer/device-cap-proxy.ts
 /**
 * Max number of accessory children spawned concurrently during a single
@@ -1939,6 +2308,19 @@ function createBrokerDeviceManagerApi(opts) {
 		api
 	});
 	let selfApi;
+	const childrenLoader = createChildrenBatchLoader({
+		logger: opts.logger,
+		fetchBatch: async (parentDeviceIds) => {
+			const parsed = parseChildrenByParent(await callDeviceManager(api, "getChildrenBatch", { parentDeviceIds }));
+			if (parsed === null) throw new Error("getChildrenBatch returned a shape this kernel cannot read");
+			return parsed;
+		},
+		fetchOne: async (parentDeviceId) => {
+			const parsed = parseChildRows(await callDeviceManager(api, "getChildren", { parentDeviceId }));
+			if (parsed === null) throw new Error("getChildren returned a shape this kernel cannot read");
+			return parsed;
+		}
+	});
 	const deviceRebuildFactories = /* @__PURE__ */ new Map();
 	const buildContext = (stableId, id, parentDeviceId = null, initialRuntimeState = {}, persistedConfig = {}, deviceMeta = null) => {
 		let runtimeStateRef = null;
@@ -2356,7 +2738,7 @@ function createBrokerDeviceManagerApi(opts) {
 					return;
 				}
 				try {
-					const currentChildren = await callDeviceManager(api, "getChildren", { parentDeviceId: device.id });
+					const currentChildren = await childrenLoader.load(device.id);
 					for (const child of currentChildren) {
 						if (child.linkDeviceId !== device.id) continue;
 						if (expected.has(child.stableId)) continue;
@@ -8200,4 +8582,4 @@ async function installManifestPythonDeps(declaration, addonDir, deps, logger) {
 	await deps.installPythonRequirements(reqAbs);
 }
 //#endregion
-export { buildUdsNativeCapProxy as $, createParentUnownedCallHandler as A, createV8Reclaimer as At, AGENT_CAP_FWD_SERVICE as B, brokerTransportLink as C, createAddonDataPlaneFacility as Ct, HUB_CAP_FWD_ACTION as D, HEAP_WATCH_WARN_RATIO as Dt, localProviderLink as E, HEAP_WATCH_INTERVAL_MS as Et, createUdsLoggerWithControl as F, createLocalTransport as G, CapRouteError as H, LocalChildClient as I, SocketChannel as J, UdsLocalTransportClient as K, LocalChildRegistry as L, createUdsEventBus as M, startHeapWatch as Mt, udsChildLogToWorkerEntry as N, startRunnerHeapWatch as Nt, HUB_CAP_FWD_SERVICE as O, RUNNER_HEAP_WATCH_INTERVAL_MS as Ot, createUdsLogger as P, strandedMb as Pt, buildNativeCapProxy as Q, UDS_NO_ROUTE_PREFIX as R, brokerCallForCap as S, runNpm as St, ipcParentLink as T, HEAP_RECLAIM_TRIGGER_MB as Tt, classifyCapRoute as U, CapRouteResolver as V, callWithServiceDiscovery as W, FrameDecoder as X, localEndpointPath as Y, encodeFrame as Z, createKernelHwAccel as _, CapabilityUnavailableError as _t, getWorkerDeviceRegistry as a, createAddonService as at, __resetCapUsageRegistryForTests as b, resolveAddonClass as bt, setHubConnected as c, capActionName as ct, getBrokerEventBus as d, capServiceName as dt, createBrokerDeviceManagerApi as et, getMoleculerEventStats as f, parseCapAction as ft, AddonDepsManager as g, CapabilityHandle as gt, subscribePassthrough as h, DeviceRegistry as ht, createUdsAddonContext as i, setWorkerNativeCapsChangeListener as it, createUdsEventBridge as j, shouldReclaim as jt, createHubCapForwardService as k, buildHeapSample as kt, EVENT_TOPIC_PREFIX as l, capActionSuffix as lt, setNodeEventInterest as m, serializeTypedArrays as mt, adaptBrokerToCluster as n, getWorkerNativeCapSnapshot as nt, getOrInitReadinessRegistry as o, validateProviderRegistrations as ot, registerEventBusService as p, deserializeTypedArrays as pt, UdsLocalTransportServer as q, createAddonContext as r, mountNativeCapService as rt, getOrInitReadinessRegistryForClient as s, NATIVE_PROVIDER_SERVICE_INFIX as st, installManifestPythonDeps as t, getWorkerNativeCapProvider as tt, clusterEventTopic as u, capBareAction as ut, resolveHwAccel as v, copyBundledNativeModules as vt, buildLinkChain as w, HEAP_RECLAIM_MIN_INTERVAL_MS as wt, getCapUsageRegistry as x, resolveNpmInvocation as xt, CapUsageRegistry as y, installManifestNativeDeps as yt, AGENT_CAP_FWD_ACTION as z };
+export { buildUdsNativeCapProxy as $, createParentUnownedCallHandler as A, RSS_BUDGET_REANNOUNCE_MIN_MS as At, AGENT_CAP_FWD_SERVICE as B, shouldReclaim as Bt, brokerTransportLink as C, createAddonDataPlaneFacility as Ct, HUB_CAP_FWD_ACTION as D, HEAP_WATCH_WARN_RATIO as Dt, localProviderLink as E, HEAP_WATCH_INTERVAL_MS as Et, createUdsLoggerWithControl as F, createV8Reclaimer as Ft, createLocalTransport as G, CapRouteError as H, startRunnerHeapWatch as Ht, LocalChildClient as I, describeRss as It, SocketChannel as J, UdsLocalTransportClient as K, LocalChildRegistry as L, hubMainRssBudget as Lt, createUdsEventBus as M, RUNNER_HEAP_WATCH_INTERVAL_MS as Mt, udsChildLogToWorkerEntry as N, RUNNER_RSS_BUDGET_ENV as Nt, HUB_CAP_FWD_SERVICE as O, HUB_MAIN_RSS_BUDGET_MB as Ot, createUdsLogger as P, buildHeapSample as Pt, buildNativeCapProxy as Q, UDS_NO_ROUTE_PREFIX as R, nextRssBudgetState as Rt, brokerCallForCap as S, runNpm as St, ipcParentLink as T, HEAP_RECLAIM_TRIGGER_MB as Tt, classifyCapRoute as U, strandedMb as Ut, CapRouteResolver as V, startHeapWatch as Vt, callWithServiceDiscovery as W, FrameDecoder as X, localEndpointPath as Y, encodeFrame as Z, createKernelHwAccel as _, CapabilityUnavailableError as _t, getWorkerDeviceRegistry as a, createAddonService as at, __resetCapUsageRegistryForTests as b, resolveAddonClass as bt, setHubConnected as c, capActionName as ct, getBrokerEventBus as d, capServiceName as dt, createBrokerDeviceManagerApi as et, getMoleculerEventStats as f, parseCapAction as ft, AddonDepsManager as g, CapabilityHandle as gt, subscribePassthrough as h, DeviceRegistry as ht, createUdsAddonContext as i, setWorkerNativeCapsChangeListener as it, createUdsEventBridge as j, RSS_BUDGET_RELEASE_RATIO as jt, createHubCapForwardService as k, HUB_RSS_BUDGET_ENV as kt, EVENT_TOPIC_PREFIX as l, capActionSuffix as lt, setNodeEventInterest as m, serializeTypedArrays as mt, adaptBrokerToCluster as n, getWorkerNativeCapSnapshot as nt, getOrInitReadinessRegistry as o, validateProviderRegistrations as ot, registerEventBusService as p, deserializeTypedArrays as pt, UdsLocalTransportServer as q, createAddonContext as r, mountNativeCapService as rt, getOrInitReadinessRegistryForClient as s, NATIVE_PROVIDER_SERVICE_INFIX as st, installManifestPythonDeps as t, getWorkerNativeCapProvider as tt, clusterEventTopic as u, capBareAction as ut, resolveHwAccel as v, copyBundledNativeModules as vt, buildLinkChain as w, HEAP_RECLAIM_MIN_INTERVAL_MS as wt, getCapUsageRegistry as x, resolveNpmInvocation as xt, CapUsageRegistry as y, installManifestNativeDeps as yt, AGENT_CAP_FWD_ACTION as z, parseRssBudgetMb as zt };