@camstack/system 1.2.143 → 1.2.145

package/dist/{manifest-python-deps-B_mCU6gz.js → manifest-python-deps-GjlyPjm0.js}

@@ -1,4 +1,5 @@
 const require_chunk = require("./chunk-Cek0wNdY.js");
+require("./dist-BVU5JADq.js");
 let node_crypto = require("node:crypto");
 node_crypto = require_chunk.__toESM(node_crypto);
 let _camstack_types_node = require("@camstack/types/node");
@@ -1653,6 +1654,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
@@ -1943,6 +2120,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;
@@ -2360,7 +2550,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;

package/dist/{retired-settings-keys-DnMYSIEr.mjs → retired-settings-keys-Dm1z4mO4.mjs}

@@ -1,4 +1,4 @@
-import { It as asJsonObject } from "./dist-CVuVKA-O.mjs";
+import { It as asJsonObject } from "./dist-CG7kwIZp.mjs";
 //#region src/builtins/sqlite-storage/retired-settings-keys.ts
 /**
 * Is THIS node the one whose settings store is the cluster's authority?

package/dist/{retired-settings-keys-Dvei9nhG.js → retired-settings-keys-_PLI9w0k.js}

@@ -1,4 +1,4 @@
-const require_dist = require("./dist-CQs1b7uh.js");
+const require_dist = require("./dist-BVU5JADq.js");
 //#region src/builtins/sqlite-storage/retired-settings-keys.ts
 /**
 * Is THIS node the one whose settings store is the cluster's authority?

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/system",
-  "version": "1.2.143",
+  "version": "1.2.145",
   "description": "Core addon for CamStack — builtins, pipeline, process management, auth, logging, events",
   "keywords": [
     "camstack",