@camstack/types 1.2.114 → 1.2.115

package/dist/index.js

@@ -1368,6 +1368,378 @@ function logLevelAtMost(level, threshold) {
 	return LOG_LEVEL_RANK[level] <= LOG_LEVEL_RANK[threshold];
 }
 //#endregion
+//#region src/logging/log-channel.ts
+/**
+* Per-component log CHANNELS — the gate a hot path consults, and the registry
+* an addon declares its channels in.
+*
+* ## Two axes, deliberately separated
+*
+* - **DECLARATION** — which channels exist. Only the addon knows:
+*   `stream-broker` knows webrtc/ICE/RTP, `provider-reolink` knows
+*   baichuan/handshake. A hand-wired central list rots at the first addition,
+*   and rots silently. So a channel is declared where it is consulted, and the
+*   `log-channels` capability enumerates the declarations.
+* - **VALUE** — at which level, for which scope, until when. That stays ONE
+*   thing: the logging settings document on the `system` cap. Two authorities
+*   over the values is the exact defect
+*   `docs/design/plans/2026-08-26-logging-per-componente.md` was written to
+*   remove; re-introducing it from the cure side would be grotesque.
+*
+* Nothing in this file reads a clock, an env var or a store. The registry is
+* a MIRROR: it is moved only by {@link LogChannelRegistry.apply}, called off
+* the hot path with a value somebody actually read, and by
+* {@link LogChannelRegistry.tick}, called on a timer. A store read that fails
+* never reaches here, so it can neither disarm an armed channel nor arm a
+* disarmed one (D49).
+*
+* ## The canonical call shape
+*
+* ```ts
+* if (CH_RTP.on && CH_RTP.wants(deviceId)) {
+*   CH_RTP.log(logger, 'rtp subscriber added', { tags: { deviceId }, meta: { ssrc } })
+* }
+* ```
+*
+* `on` is a plain boolean FIELD — never a getter — and it is the FIRST thing
+* read. Disarmed, a call site costs one load and one branch, and the `extras`
+* object literal is never constructed because it lives inside the branch. It
+* is the same shape already proven in production at `stream-broker.ts:1650`,
+* and the same discipline `LoggingGate.allowsDestination` uses for the
+* destination floor (measured at 1.93 ns/call when off).
+*
+* ## Why a channel emits at `info`
+*
+* `loki-logging.addon.ts` pins the destination default at `info` and
+* `loki-destination.ts` drops everything below it, so a line emitted at
+* `debug` never reaches Loki and the hub's in-memory ring only holds ~35
+* minutes. A diagnostic that cannot be read an hour later is worse than no
+* diagnostic, because it looks done. {@link LogChannelGate.log} therefore
+* emits at the channel's declared level, whose schema floor is `info`.
+*/
+/**
+* The level a channel writes at once armed.
+*
+* `debug` is absent ON PURPOSE and not by omission: below `info` the line does
+* not leave the process for Loki, and the whole point of arming a channel is
+* to read it later.
+*/
+var LogChannelLevelSchema = zod.z.enum([
+	"info",
+	"warn",
+	"error"
+]);
+/**
+* What an addon declares about one channel. No value, no state — a
+* declaration is inert.
+*/
+var LogChannelDescriptorSchema = zod.z.object({
+	/**
+	* Dotted `area.thing`, unique across the workspace. `area` is conventionally
+	* the addon's short name so an operator reading a channel list can tell who
+	* owns it without a second lookup.
+	*/
+	name: zod.z.string().min(3).regex(/^[a-z0-9-]+(\.[a-z0-9-]+)+$/, "a channel name is dotted lower-kebab, e.g. area.thing"),
+	/** One sentence: what the operator will SEE after arming it. */
+	description: zod.z.string().min(1),
+	/** The level its lines are emitted at. Never below `info`. */
+	defaultLevel: LogChannelLevelSchema,
+	/**
+	* Whether this channel can be narrowed to a camera.
+	*
+	* `true` is a PROMISE with two halves, and both must hold: the gate is
+	* consulted with the numeric device id, AND every line the channel admits
+	* carries `tags: { deviceId }` with that same numeric id. The second half is
+	* what makes `| json | deviceId="617"` work in Loki — `loki-payload.ts`
+	* keeps `deviceId` out of the stream labels for cardinality, so the tag in
+	* the body is the only way to filter.
+	*
+	* A channel whose lines carry the device only in `meta` (or not at all) is
+	* declared `false`. Declaring it `true` anyway would be a lie the UI repeats:
+	* the operator narrows to one camera, sees nothing, and concludes the code
+	* path was never taken.
+	*/
+	perDevice: zod.z.boolean()
+});
+/**
+* An armed window over one channel, as the document hands it to a mirror.
+*
+* A window is a DEADLINE, never a flag (ADR-0244): a channel somebody forgot
+* expires by itself, which is the one failure a boolean cannot avoid.
+*/
+var LogChannelWindowSchema = zod.z.object({
+	channel: zod.z.string().min(1),
+	/** Epoch ms the window closes at. */
+	armedUntilMs: zod.z.number(),
+	/** `null` = every camera. A non-empty list narrows to those numeric ids. */
+	deviceIds: zod.z.array(zod.z.number().int()).readonly().nullable()
+});
+/**
+* The gate a hot path holds.
+*
+* Obtain it ONCE — at module scope or in a constructor — and keep the
+* reference. Looking a channel up by name per line would put a Map lookup on
+* the path this class exists to keep free.
+*/
+var LogChannelGate = class {
+	descriptor;
+	/**
+	* HOT PATH GUARD. A plain data FIELD, and it must stay one.
+	*
+	* `log-channel.spec.ts` asserts the property descriptor has no getter and
+	* booby-traps the device set, so turning this into an accessor — or reading
+	* anything before it — fails the spec instead of taxing every line the
+	* process emits.
+	*/
+	on = false;
+	/** `null` while armed for every camera. Never read while `on` is false. */
+	devices = null;
+	level;
+	closesAtMs = 0;
+	constructor(descriptor) {
+		this.descriptor = descriptor;
+		this.level = descriptor.defaultLevel;
+	}
+	/** Epoch ms this channel disarms itself at. 0 when disarmed. */
+	get armedUntilMs() {
+		return this.on ? this.closesAtMs : 0;
+	}
+	/**
+	* Does this channel want a line about `deviceId`?
+	*
+	* Call it only behind `gate.on &&`. On its own it is still correct — the
+	* guard is repeated inside — but the point of the prefix is that a disarmed
+	* channel must not pay the call at all.
+	*/
+	wants(deviceId) {
+		if (!this.on) return false;
+		return this.devices === null || this.devices.has(deviceId);
+	}
+	/**
+	* Emit one line on this channel, at the channel's declared level.
+	*
+	* The channel name is added as `tags.logChannel` so LogQL can select the
+	* channel without matching on the message text, and whatever `tags` the
+	* caller passed — `deviceId` above all — is preserved.
+	*/
+	log(logger, message, extras) {
+		if (!this.on) return;
+		const tags = {
+			...extras.tags,
+			logChannel: this.descriptor.name
+		};
+		const line = {
+			...extras,
+			tags
+		};
+		if (this.level === "error") logger.error(message, line);
+		else if (this.level === "warn") logger.warn(message, line);
+		else logger.info(message, line);
+	}
+	/**
+	* Arm (or RE-arm, restarting) this channel. Off the hot path only.
+	*
+	* An empty `deviceIds` list is treated as "every camera" rather than "no
+	* camera": a window that matches nothing is indistinguishable from a
+	* disarmed one, and the operator who asked for it would wait for lines that
+	* can never come.
+	*/
+	arm(window) {
+		const ids = window.deviceIds;
+		this.devices = ids === null || ids.length === 0 ? null : new Set(ids);
+		this.closesAtMs = window.armedUntilMs;
+		this.on = true;
+	}
+	/** Disarm. Off the hot path only. */
+	disarm() {
+		this.on = false;
+		this.devices = null;
+		this.closesAtMs = 0;
+	}
+};
+/**
+* Every channel this PROCESS declares, and the mirror of what is armed on it.
+*
+* One per process. A forked runner has its own, and it is refreshed through
+* the `log-channels` capability by the hub that owns the document — the
+* registry never reaches for a value itself.
+*/
+var LogChannelRegistry = class {
+	gates = /* @__PURE__ */ new Map();
+	/**
+	* Declare a channel and get its gate.
+	*
+	* A duplicate name throws. Two declarations of one name is a programming
+	* error, not a merge: the operator would arm one and the other would stay
+	* dark, which is the dead-knob shape (D62) with an extra step.
+	*/
+	declare(descriptor) {
+		const parsed = LogChannelDescriptorSchema.parse(descriptor);
+		if (this.gates.get(parsed.name) !== void 0) throw new Error(`log channel "${parsed.name}" is already declared in this process — two declarations of one name is a programming error, not a merge`);
+		const gate = new LogChannelGate(parsed);
+		this.gates.set(parsed.name, gate);
+		return gate;
+	}
+	/** The declarations, sorted by name so a list is stable to read and diff. */
+	list() {
+		return [...this.gates.values()].map((gate) => gate.descriptor).sort((a, b) => a.name.localeCompare(b.name));
+	}
+	/** The gate for a declared channel, or `undefined`. */
+	gate(name) {
+		return this.gates.get(name);
+	}
+	/**
+	* Apply the FULL set of armed windows. Off the hot path.
+	*
+	* Full, not incremental, and that is the whole design: the document is the
+	* authority, so a channel the document does not name is disarmed here. An
+	* incremental apply would let a disarm get lost in transit and leave a
+	* channel running that nobody can see is running.
+	*
+	* A window already past its deadline is ignored rather than armed — a
+	* restore that re-armed an expired window would make a forgotten diagnostic
+	* immortal across restarts.
+	*
+	* Returns the names it could not place, so the caller can log them: a
+	* channel named in the document that this process does not declare is
+	* either a typo or an addon that has not booted yet, and both deserve a
+	* line rather than silence.
+	*/
+	apply(windows, nowMs) {
+		const wanted = /* @__PURE__ */ new Map();
+		const unknown = [];
+		for (const window of windows) {
+			if (window.armedUntilMs <= nowMs) continue;
+			if (!this.gates.has(window.channel)) {
+				unknown.push(window.channel);
+				continue;
+			}
+			wanted.set(window.channel, window);
+		}
+		for (const [name, gate] of this.gates) {
+			const window = wanted.get(name);
+			if (window === void 0) gate.disarm();
+			else gate.arm(window);
+		}
+		return unknown;
+	}
+	/**
+	* Disarm whatever has run out. Called on a timer, NEVER from a log path — a
+	* diagnostic that adds a `Date.now()` to the path it is measuring measures
+	* itself.
+	*
+	* Returns the names it closed, so the caller can write the one line that
+	* says a window ended and stops "it went quiet" from reading as "the branch
+	* was not taken".
+	*/
+	tick(nowMs) {
+		const closed = [];
+		for (const [name, gate] of this.gates) if (gate.on && gate.armedUntilMs <= nowMs) {
+			gate.disarm();
+			closed.push(name);
+		}
+		return closed;
+	}
+	/** The channels armed right now, as the document would describe them. */
+	armed() {
+		const out = [];
+		for (const [name, gate] of this.gates) if (gate.on) out.push({
+			channel: name,
+			armedUntilMs: gate.armedUntilMs,
+			deviceIds: null
+		});
+		return out;
+	}
+};
+//#endregion
+//#region src/logging/log-channel.singleton.ts
+/**
+* Process-wide holder for the {@link LogChannelRegistry}.
+*
+* Three call sites that never meet need the SAME instance: the hot paths that
+* declare a gate at module scope, the `log-channels` provider that enumerates
+* the declarations for the hub, and the same provider applying the windows the
+* document hands down. A registry built inside any one of them would be
+* refreshed and collected — the shape of a knob that never does anything.
+*
+* Same idiom as `logging-gate.singleton.ts` and
+* `http-request-census.singleton.ts`.
+*/
+var instance = null;
+/** The process-wide log channel registry. Created empty on first use. */
+function getLogChannelRegistry() {
+	instance ??= new LogChannelRegistry();
+	return instance;
+}
+/**
+* Declare a channel on the process-wide registry and get its gate.
+*
+* The one call an addon makes. Keep the returned gate in a module-scope
+* `const`: looking a channel up by name per line would put a Map lookup on
+* exactly the path this mechanism exists to keep free.
+*
+* `scripts/check-log-channel-gated.ts` reads these call sites. It pairs the
+* declared name with the binding it is assigned to and refuses to let a
+* channel ship that no `<binding>.on` anywhere consults — a declared channel
+* nobody reads is a knob the operator turns with nothing happening, forever,
+* and without a line. That is D62, and this repo has now shipped it three
+* times (`audioThresholdDbfs`, the HA entities with no source, the second
+* per-camera switch that wrote a store nobody read).
+*/
+function declareLogChannel(descriptor) {
+	return getLogChannelRegistry().declare(descriptor);
+}
+/** Test-only: drop the instance so a spec starts from an empty registry. */
+function __resetLogChannelRegistryForTests() {
+	instance = null;
+}
+//#endregion
+//#region src/logging/log-channel-provider.ts
+/**
+* How often expiry is noticed. Coarse on purpose: the cost of a channel
+* running a few seconds past its deadline is a few extra lines, and the cost
+* of a tight timer in every addon process is paid forever.
+*/
+var LOG_CHANNEL_TICK_MS = 5e3;
+/**
+* Build the `log-channels` provider for this process.
+*
+* `logger` is used ONLY off the hot path — for the arm/expiry lines — so a
+* channel that is never armed costs this module nothing but a timer.
+*/
+function createLogChannelsProvider(logger, options = {}) {
+	const registry = getLogChannelRegistry();
+	const now = options.now ?? Date.now;
+	const tickMs = options.tickMs ?? 5e3;
+	const timer = setInterval(() => {
+		const closed = registry.tick(now());
+		for (const name of closed) logger.info("log channel window closed", {
+			tags: { logChannel: name },
+			meta: { channel: name }
+		});
+	}, tickMs);
+	timer.unref?.();
+	return {
+		list: () => registry.list(),
+		apply: (input) => {
+			const unknown = registry.apply(input.windows, now());
+			const armed = registry.armed();
+			logger.info("log channels applied", { meta: {
+				armed: armed.map((window) => window.channel),
+				unknown,
+				declared: registry.list().length
+			} });
+			return {
+				armed: armed.length,
+				unknown
+			};
+		},
+		stop: () => {
+			clearInterval(timer);
+		}
+	};
+}
+//#endregion
 //#region src/interfaces/ops-log.ts
 /**
 * Ops-log — the durable, append-only operations audit shared by the
@@ -7312,6 +7684,35 @@ var MutationFilterSchema = zod.z.object({
 	whereBetween: zod.z.record(zod.z.string(), zod.z.tuple([zod.z.unknown(), zod.z.unknown()])).optional(),
 	whereNot: zod.z.record(zod.z.string(), zod.z.unknown()).optional()
 });
+/**
+* One scalar an {@link settingsStoreCapability.methods.aggregate} call asks for.
+*
+* `as` names the slot in the result, so the SAME column may be asked twice with
+* two operations (`MIN(startMs)` and `MAX(startMs)` in one round trip) — which
+* a `Record<column, op>` shape could not express.
+*/
+var AggregateFieldSchema = zod.z.object({
+	/** Result key. */
+	as: zod.z.string().min(1),
+	/** Column to aggregate. Must be a real column of a declared collection. */
+	field: zod.z.string().min(1),
+	op: zod.z.enum([
+		"sum",
+		"min",
+		"max"
+	])
+});
+/**
+* `COUNT(*)` plus one number per requested field.
+*
+* `null` means NO ROW MATCHED, never zero: a `SUM` over an empty set and a sum
+* that really is 0 are different facts, and an accounting caller that renders
+* "0 bytes, oldest = 0" for "nothing here" reports a lie about a disk.
+*/
+var AggregateResultSchema = zod.z.object({
+	count: zod.z.number().int(),
+	values: zod.z.record(zod.z.string(), zod.z.number().nullable())
+});
 /** A single stored record: `{ id, data }`. */
 var SettingsRecordSchema = zod.z.object({
 	id: zod.z.string(),
@@ -7479,6 +7880,32 @@ var settingsStoreCapability = {
 			collection: zod.z.string(),
 			filter: QueryFilterSchema.optional()
 		}), zod.z.number()),
+		/**
+		* `COUNT(*)` and one `SUM` / `MIN` / `MAX` per requested field, in ONE
+		* statement, over the rows `filter` selects.
+		*
+		* Exists because "how much is there" was being answered by materialising
+		* "what is there". The recorder's storage-pressure sweep asked its in-RAM
+		* footage index for bytes/count/oldest/newest across a set of storage
+		* locations twice a minute, and the only way to answer that from a map is
+		* to visit every row — 7.1 M of them on the live hub, ~15 M row visits a
+		* minute on the main thread, which is also why the whole archive had to
+		* stay resident to be visited. The question is a sum; nothing needs to be
+		* materialised to answer it.
+		*
+		* **The engine REFUSES a field it cannot serve**, exactly as
+		* `query.columns` does and unlike a PREDICATE, which is skipped when
+		* unresolvable. A dropped predicate over-matches and the caller sees extra
+		* rows; a dropped aggregate returns a NUMBER that is wrong and looks
+		* exactly like a real one. That asymmetry is what this repo has already
+		* paid for once in `count`.
+		*/
+		aggregate: require_sleep.method(zod.z.object({
+			namespace: zod.z.string().optional(),
+			collection: zod.z.string(),
+			fields: zod.z.array(AggregateFieldSchema).readonly(),
+			filter: QueryFilterSchema.optional()
+		}), AggregateResultSchema),
 		/** Grouped counts per ((field-origin)/bucketSize) bucket, filtered. */
 		histogram: require_sleep.method(zod.z.object({
 			namespace: zod.z.string().optional(),
@@ -7687,6 +8114,15 @@ var dataStoreProviderCapability = {
 			collection: zod.z.string(),
 			filter: QueryFilterSchema.optional()
 		}), zod.z.number(), { auth: "admin" }),
+		/** `COUNT(*)` plus one SUM/MIN/MAX per field, in one statement. Mirror of
+		*  `settings-store.aggregate` — see it for why an unresolvable field is
+		*  refused rather than dropped. */
+		aggregate: require_sleep.method(zod.z.object({
+			namespace: zod.z.string().optional(),
+			collection: zod.z.string(),
+			fields: zod.z.array(AggregateFieldSchema).readonly(),
+			filter: QueryFilterSchema.optional()
+		}), AggregateResultSchema, { auth: "admin" }),
 		/** Grouped counts per ((field-origin)/bucketSize) bucket, filtered. */
 		histogram: require_sleep.method(zod.z.object({
 			namespace: zod.z.string().optional(),
@@ -8663,6 +9099,28 @@ var deviceProviderCapability = {
 * Forked workers register devices back to the hub via `ctx.devices`
 * (DeviceManagerApi → ctx.api.deviceManager.registerDevice), same as today.
 */
+/**
+* Most parents one `getChildrenBatch` may name.
+*
+* Every parent in the set becomes one bound `?` in the `parentDeviceId IN (…)`
+* the store compiles ({@link DeviceRowStore.listByParentMany} →
+* `filter-compiler.ts`), so the set size IS the SQL variable count. Two bounds
+* meet here and 256 clears both:
+*
+*  - `SQLITE_MAX_VARIABLE_NUMBER` is 32 766 on SQLite ≥ 3.32 but **999** on
+*    anything older, and better-sqlite3 links whatever amalgamation it was
+*    built against on the host. A fleet-sized set (1 017 parents today) sits
+*    ON that older limit; 256 stays a factor of four below it, so the batch
+*    can never turn a boot into `too many SQL variables` on a host nobody
+*    checked the build of.
+*  - One call's answer is the children of those parents, and the answer
+*    crosses a process boundary. Capping the ask caps the message.
+*
+* A caller with more parents sends ⌈n/256⌉ calls — four for today's fleet,
+* against 1 024 today. The cap is on the SCHEMA, not only on the caller: an
+* over-eager caller is refused, not silently truncated to a wrong answer.
+*/
+var DEVICE_CHILDREN_BATCH_MAX = 256;
 /** One child-placement directive on a container's `childLayout`. Structurally
 *  identical to `ChildLayoutEntry` in `device-management.ts` — the cap wire
 *  shape for the same field. The child is identified by its re-sync-stable
@@ -9174,6 +9632,39 @@ var deviceManagerCapability = {
 		/** List children of a parent device (by parent numeric id). */
 		getChildren: require_sleep.method(zod.z.object({ parentDeviceId: zod.z.number() }), zod.z.array(DeviceInfoSchema)),
 		/**
+		* `getChildren` for a NAMED SET of parents, in one call.
+		*
+		* The accessory reconcile in `device-cap-proxy.ts` asks this question once
+		* per registered device — every `BaseDevice` inherits a
+		* `getAccessoryChildren()` that returns `[]`, so even a leaf accessory
+		* pays a round-trip to learn it has nothing to prune. Measured on the live
+		* hub 2026-08-27 over a 120-second boot window, fleet of 1 017 devices:
+		* `DeviceRowStore.list < DeviceRowStore.listByParent < getChildren` at
+		* **1 024 calls** returning **919 rows in total** — 1 024 RPCs and 1 024
+		* indexed scans to move less than one row each. `listByParentMany`
+		* collapses the scans; this collapses the RPCs.
+		*
+		* Keyed by parent id as a STRING — a JSON object cannot key by number
+		* (same reason as `getDeviceStatusAggregateBatch`). The per-parent value
+		* is exactly what `getChildren` returns for that parent.
+		*
+		* A parent with no children — or one the fleet does not know — is ABSENT
+		* from the record, never an invented empty row: the same contract as
+		* `DeviceRowStore.getMany`/`listByParentMany`. An EMPTY `parentDeviceIds`
+		* reads nothing at all rather than degrading to "every device".
+		*
+		* `parentDeviceIds` is capped at {@link DEVICE_CHILDREN_BATCH_MAX} — see
+		* that constant for why. A caller with more parents than that sends more
+		* than one call; it never sends one pathological one.
+		*
+		* Version skew: this is a NEW method, not a new field on `getChildren`, so
+		* a hub that predates it answers NOT_FOUND rather than silently stripping
+		* an unknown input key and answering a DIFFERENT question. The kernel-side
+		* loader degrades to per-parent `getChildren` on that error — see
+		* `children-batch-loader.ts`.
+		*/
+		getChildrenBatch: require_sleep.method(zod.z.object({ parentDeviceIds: zod.z.array(zod.z.number()).max(256) }), zod.z.record(zod.z.string(), zod.z.array(DeviceInfoSchema))),
+		/**
 		* Resolve the devices LINKED to a camera — the single policy authority
 		* both consumers call (viewer devices panel + pipeline-analytics event
 		* kinds/ingest). Device-tree children are ALWAYS included; mode 'auto'
@@ -10355,6 +10846,82 @@ var llmCapability = {
 	}
 };
 //#endregion
+//#region src/capabilities/log-channels.cap.ts
+/**
+* `log-channels` — the capability an addon DECLARES its diagnostic channels
+* through. It stores nothing.
+*
+* ## Why a capability at all, and why this shape
+*
+* Which channels exist is knowledge only the addon has: `stream-broker` knows
+* webrtc/ICE/RTP, `provider-reolink` knows baichuan/handshake. A central list
+* maintained by hand rots at the first addition and rots INVISIBLY — nothing
+* fails, an operator just never sees the channel somebody added. So the list
+* is assembled from declarations at runtime.
+*
+* The shape is copied from `log-destination.cap.ts`, which already does
+* exactly this job: `mode: 'collection'`, `internal: true`,
+* `mount: { kind: 'skip' }` — no tRPC route, no generated hooks — while
+* `addons.listCapabilityProviders` still enumerates it, and the hub's
+* `CapabilityRegistry` still holds an RPC proxy per provider so a forked
+* runner's declarations reach hub-main over the transport that already exists.
+* No new UDS message, no second registry.
+*
+* ## What it deliberately does NOT own
+*
+* The VALUES — which channel is armed, for which cameras, until when — live in
+* ONE place: the logging settings document on the `system` cap
+* (`getLoggingSettings` / `setLoggingSettings`). Two authorities over the same
+* value is the defect the plan behind this work exists to remove, and
+* `setRequestCensus` was retired (D245) rather than allowed to be a second
+* one. {@link logChannelsCapability} therefore has no getter for a level, no
+* setter for a window and no persistence of any kind.
+*
+* ## Why `apply` is here even so
+*
+* The gate lives in the addon's PROCESS; the document lives in hub-main. Some
+* seam has to carry the value from the authority to the mirror, and a channel
+* that cannot be reached is precisely the dead knob this whole slice exists to
+* make impossible (D62 — `audioThresholdDbfs`, the HA entities with no source).
+* `apply` is that seam and nothing more: it writes an in-memory mirror, it
+* persists nothing, it is never the source of a value, and it is called only
+* with a set the hub actually read (D49 — a read that fails does not call it
+* at all, so no channel is silently disarmed by a bad read).
+*/
+/** What `apply` reports back — enough to log, not enough to be a second state. */
+var LogChannelApplyResultSchema = zod.z.object({
+	/** How many declared channels are armed in this process after the call. */
+	armed: zod.z.number().int().min(0),
+	/**
+	* Names the document armed that this process does not declare. Reported
+	* rather than swallowed: a name here is either a typo or an addon that has
+	* not booted, and both deserve a line instead of silence.
+	*/
+	unknown: zod.z.array(zod.z.string()).readonly()
+});
+var logChannelsCapability = {
+	name: "log-channels",
+	scope: "system",
+	mode: "collection",
+	internal: true,
+	methods: {
+		/** The channels this addon declares. Inert: no value, no state. */
+		list: require_sleep.method(zod.z.void(), zod.z.array(LogChannelDescriptorSchema).readonly()),
+		/**
+		* Refresh this process's mirror from the document's FULL set of armed
+		* windows.
+		*
+		* Full and not incremental on purpose: the document is the authority, so a
+		* channel it does not name is disarmed here. An incremental apply would
+		* let a disarm get lost in transit and leave a channel running that
+		* nobody can see is running.
+		*/
+		apply: require_sleep.method(zod.z.object({ windows: zod.z.array(LogChannelWindowSchema).readonly() }), LogChannelApplyResultSchema, { kind: "mutation" })
+	},
+	/** In-process only — enumerated through `addons.listCapabilityProviders`. */
+	mount: { kind: "skip" }
+};
+//#endregion
 //#region src/capabilities/log-destination.cap.ts
 var LogLevelSchema = zod.z.enum([
 	"debug",
@@ -30610,10 +31177,11 @@ var DiagnosticIdSchema = zod.z.enum(["request-census"]);
 * The layers of the level hierarchy, general → specific. The most specific
 * layer that carries an explicit value wins.
 *
-* `component` is DECLARED and not yet resolvable: the per-component channels
-* are a later slice of the same plan, and a `levelSource` enum that has to
-* grow later would force every consumer of this document to change with it.
-* Nothing returns `component` today.
+* `component` became RESOLVABLE on 2026-08-27: a component is a declared log
+* CHANNEL (`stream-broker.webrtc`, `provider-reolink.baichuan`), named by
+* `scopeComponent`. It was declared-but-dark in the first slice precisely so
+* that turning it on would not force every consumer of this document to widen
+* a `levelSource` enum — which is what has now not happened.
 */
 var LoggingScopeKindSchema = zod.z.enum([
 	"cluster",
@@ -30640,6 +31208,14 @@ var LoggingLevelLayerSchema = zod.z.object({
 	scope: LoggingScopeKindSchema,
 	/** The node this layer speaks for; `null` on the cluster layer. */
 	nodeId: zod.z.string().nullable(),
+	/**
+	* The declared channel this layer speaks for; `null` on every layer but
+	* `component`. Never folded into `nodeId`: a component level is CLUSTER-WIDE
+	* by design — the convention this repo settled on is one orchestrator-wide
+	* setting, never per node (D52) — so a component layer that carried a node
+	* would invite a per-node copy of a value that has no per-node meaning.
+	*/
+	component: zod.z.string().nullable(),
 	/** Explicitly set here, or `null` when this layer inherits. */
 	level: LogLevelSchema$1.nullable()
 });
@@ -30681,6 +31257,49 @@ var DiagnosticWindowPatchSchema = zod.z.object({
 	reportEveryMs: zod.z.number().int().positive().optional()
 });
 /**
+* A channel ARMED, as the document reports it.
+*
+* `armMs` is not echoed back: what an operator needs to see is the deadline
+* and the time left, because a diagnostic left running is itself an incident
+* and "armed for 10 minutes" said an hour ago is not an answer.
+*/
+var LogChannelWindowStateSchema = zod.z.object({
+	channel: zod.z.string(),
+	armed: zod.z.boolean(),
+	/** Epoch ms the window closes at. 0 when disarmed. */
+	armedUntilMs: zod.z.number(),
+	/** Ms left before it expires on its own. 0 when disarmed. */
+	remainingMs: zod.z.number(),
+	/**
+	* The cameras it is narrowed to, or `null` for every camera.
+	*
+	* A channel declared `perDevice: false` can only ever report `null` here:
+	* its lines do not carry `tags: { deviceId }`, so narrowing them would
+	* produce a filter that silently matches nothing. The server REFUSES such a
+	* patch rather than quietly widening it — ignoring the request would teach
+	* the operator that per-camera filtering works on that channel when it does
+	* not.
+	*/
+	deviceIds: zod.z.array(zod.z.number().int()).readonly().nullable()
+});
+/**
+* `armMs: 0` DISARMS. Same grammar as {@link DiagnosticWindowPatchSchema}, and
+* for the same reason: a channel is a window with a deadline, never a switch.
+*/
+var LogChannelWindowPatchSchema = zod.z.object({
+	channel: zod.z.string().min(1),
+	armMs: zod.z.number().int().min(0),
+	/**
+	* Narrow to these numeric device ids. Absent or `null` = every camera.
+	*
+	* Numeric because the repo's own rule makes it possible: every log line
+	* about a device carries `tags: { deviceId }` with the numeric id. That rule
+	* was paid for with a 22% thumbnail gap and a 3-hour media blackout both
+	* diagnosed by hand, and this is the first thing that collects on it.
+	*/
+	deviceIds: zod.z.array(zod.z.number().int()).readonly().nullable().optional()
+});
+/**
 * A PATCH, and patches MERGE.
 *
 * A field absent from the patch is left exactly as it was — arming a
@@ -30699,7 +31318,14 @@ var LoggingSettingsPatchSchema = zod.z.object({
 	* Only the diagnostics NAMED here change. An armed window that is not listed
 	* keeps running — a patch is never a full replacement.
 	*/
-	diagnostics: zod.z.array(DiagnosticWindowPatchSchema).readonly().optional()
+	diagnostics: zod.z.array(DiagnosticWindowPatchSchema).readonly().optional(),
+	/**
+	* Only the channels NAMED here change. An armed channel that is not listed
+	* keeps running — same rule as `diagnostics`, because a patch that silently
+	* disarmed the channels it did not mention would make the Levels page and
+	* the Diagnostics page fight over the same value.
+	*/
+	channels: zod.z.array(LogChannelWindowPatchSchema).readonly().optional()
 });
 /**
 * Which LAYER of the hierarchy is addressed. Absent = the cluster layer.
@@ -30712,9 +31338,22 @@ var LoggingSettingsPatchSchema = zod.z.object({
 * authority over the whole hierarchy and answers for every layer, so the
 * layer selector needs a name the transport does not already own.
 */
-var GetLoggingSettingsInputSchema = zod.z.object({ scopeNodeId: zod.z.string().optional() });
+var GetLoggingSettingsInputSchema = zod.z.object({
+	scopeNodeId: zod.z.string().optional(),
+	/**
+	* The declared CHANNEL this document is addressed at, when the caller wants
+	* the `component` layer. Absent = the node/cluster hierarchy only.
+	*
+	* Naming it separately rather than overloading `scopeNodeId` keeps the two
+	* axes from collapsing: a component level is cluster-wide, a node level is
+	* not, and one selector for both would make "which of these two did I just
+	* set" unanswerable — the exact ambiguity `explicit` exists to remove.
+	*/
+	scopeComponent: zod.z.string().optional()
+});
 var SetLoggingSettingsInputSchema = zod.z.object({
 	scopeNodeId: zod.z.string().optional(),
+	scopeComponent: zod.z.string().optional(),
 	patch: LoggingSettingsPatchSchema
 });
 /**
@@ -30729,9 +31368,20 @@ var SetLoggingSettingsInputSchema = zod.z.object({
 var LoggingSettingsStateSchema = zod.z.object({
 	/** The layer this document was read at. `null` = the cluster layer. */
 	scopeNodeId: zod.z.string().nullable(),
+	/** The channel this document was read at. `null` = no component layer. */
+	scopeComponent: zod.z.string().nullable(),
 	effective: LoggingEffectiveSchema,
 	explicit: LoggingExplicitSchema,
 	activeWindows: zod.z.array(DiagnosticWindowSchema).readonly(),
+	/**
+	* Every channel the cluster's addons DECLARE, gathered from the
+	* `log-channels` providers. Not stored anywhere: assembled per read, so a
+	* channel added by a redeployed addon appears without anybody editing a
+	* list, and a channel whose addon is gone stops being offered.
+	*/
+	channels: zod.z.array(LogChannelDescriptorSchema).readonly(),
+	/** The channels ARMED right now, each with its deadline. */
+	activeChannels: zod.z.array(LogChannelWindowStateSchema).readonly(),
 	persisted: zod.z.boolean()
 });
 var systemCapability = {
@@ -35121,6 +35771,7 @@ var CAPABILITY_NAMES = {
 	llmRuntime: "llm-runtime",
 	localNetwork: "local-network",
 	lockControl: "lock-control",
+	logChannels: "log-channels",
 	logDestination: "log-destination",
 	loginMethod: "login-method",
 	mediaPlayer: "media-player",
@@ -35492,6 +36143,10 @@ var CAPABILITY_ROUTER_KEYS = [
 		key: "lockControl",
 		name: "lock-control"
 	},
+	{
+		key: "logChannels",
+		name: "log-channels"
+	},
 	{
 		key: "logDestination",
 		name: "log-destination"
@@ -35880,6 +36535,7 @@ var ALL_CAPABILITY_DEFINITIONS = [
 	llmRuntimeCapability,
 	localNetworkCapability,
 	lockControlCapability,
+	logChannelsCapability,
 	logDestinationCapability,
 	loginMethodCapability,
 	mediaPlayerCapability,
@@ -36848,6 +37504,12 @@ var METHOD_ACCESS_MAP = Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"dataStoreProvider.aggregate": {
+		capName: "data-store-provider",
+		capScope: "system",
+		addonId: null,
+		access: "view"
+	},
 	"dataStoreProvider.count": {
 		capName: "data-store-provider",
 		capScope: "system",
@@ -37262,6 +37924,12 @@ var METHOD_ACCESS_MAP = Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"deviceManager.getChildrenBatch": {
+		capName: "device-manager",
+		capScope: "system",
+		addonId: null,
+		access: "view"
+	},
 	"deviceManager.getConfigSchema": {
 		capName: "device-manager",
 		capScope: "system",
@@ -38312,6 +38980,18 @@ var METHOD_ACCESS_MAP = Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"logChannels.apply": {
+		capName: "log-channels",
+		capScope: "system",
+		addonId: null,
+		access: "create"
+	},
+	"logChannels.list": {
+		capName: "log-channels",
+		capScope: "system",
+		addonId: null,
+		access: "view"
+	},
 	"logDestination.query": {
 		capName: "log-destination",
 		capScope: "system",
@@ -40466,6 +41146,12 @@ var METHOD_ACCESS_MAP = Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"settingsStore.aggregate": {
+		capName: "settings-store",
+		capScope: "system",
+		addonId: null,
+		access: "view"
+	},
 	"settingsStore.count": {
 		capName: "settings-store",
 		capScope: "system",
@@ -41815,6 +42501,7 @@ var KNOWN_CAP_NAMES = [
 	"llm-runtime",
 	"local-network",
 	"lock-control",
+	"log-channels",
 	"log-destination",
 	"login-method",
 	"media-player",
@@ -41973,6 +42660,7 @@ var SYSTEM_CAP_NAMES = [
 	"llm",
 	"llm-runtime",
 	"local-network",
+	"log-channels",
 	"log-destination",
 	"login-method",
 	"mesh-network",
@@ -42302,6 +42990,11 @@ var METHOD_DEVICE_SELECTORS = Object.freeze({
 		form: "single",
 		optional: false
 	}],
+	"deviceManager.getChildrenBatch": [{
+		name: "parentDeviceIds",
+		form: "array",
+		optional: false
+	}],
 	"deviceManager.getConfigSchema": [{
 		name: "deviceId",
 		form: "single",
@@ -43778,6 +44471,7 @@ var SYSTEM_SCOPE_DEVICE_METHODS = [
 	"deviceManager.getBindings",
 	"deviceManager.getBindingsBatch",
 	"deviceManager.getChildren",
+	"deviceManager.getChildrenBatch",
 	"deviceManager.getConfigSchema",
 	"deviceManager.getDevice",
 	"deviceManager.getDeviceAggregate",
@@ -44515,6 +45209,7 @@ function createSystemProxy(api) {
 			listPersistedByAddon: (input) => dispatch("deviceManager", "listPersistedByAddon", "query", input),
 			listAll: (input) => dispatch("deviceManager", "listAll", "query", input),
 			getChildren: (input) => dispatch("deviceManager", "getChildren", "query", input),
+			getChildrenBatch: (input) => dispatch("deviceManager", "getChildrenBatch", "query", input),
 			getLinkedDevicesBatch: (input) => dispatch("deviceManager", "getLinkedDevicesBatch", "query", input),
 			removeByIntegration: (input) => dispatch("deviceManager", "removeByIntegration", "mutation", input),
 			getBindingsBatch: (input) => dispatch("deviceManager", "getBindingsBatch", "query", input),
@@ -44829,6 +45524,7 @@ function createSystemProxy(api) {
 			deleteWhere: (input) => dispatch("settingsStore", "deleteWhere", "mutation", input),
 			updateWhere: (input) => dispatch("settingsStore", "updateWhere", "mutation", input),
 			count: (input) => dispatch("settingsStore", "count", "query", input),
+			aggregate: (input) => dispatch("settingsStore", "aggregate", "query", input),
 			histogram: (input) => dispatch("settingsStore", "histogram", "query", input),
 			isEmpty: (input) => dispatch("settingsStore", "isEmpty", "query", input),
 			declareCollection: (input) => dispatch("settingsStore", "declareCollection", "mutation", input)
@@ -49128,6 +49824,7 @@ exports.DETECTION_MACRO_CLASSES = DETECTION_MACRO_CLASSES;
 exports.DETECTION_PIPELINE_CAP_NAME = DETECTION_PIPELINE_CAP_NAME;
 exports.DEVICE_BACKEND_TO_FORMAT = DEVICE_BACKEND_TO_FORMAT;
 exports.DEVICE_CAP_NAMES = DEVICE_CAP_NAMES;
+exports.DEVICE_CHILDREN_BATCH_MAX = DEVICE_CHILDREN_BATCH_MAX;
 exports.DEVICE_PROFILES = DEVICE_PROFILES;
 exports.DEVICE_SCOPED_CAPS = require_sleep.DEVICE_SCOPED_CAPS;
 exports.DEVICE_SETTINGS_CONTRIBUTION_METHODS = require_sleep.DEVICE_SETTINGS_CONTRIBUTION_METHODS;
@@ -49278,6 +49975,7 @@ exports.IntercomAbilitySchema = IntercomAbilitySchema;
 exports.IntercomStatusSchema = IntercomStatusSchema;
 exports.KNOWN_CAP_NAMES = KNOWN_CAP_NAMES;
 exports.KeyEventSchema = KeyEventSchema;
+exports.LOG_CHANNEL_TICK_MS = LOG_CHANNEL_TICK_MS;
 exports.LOG_LEVEL_RANK = LOG_LEVEL_RANK;
 exports.LabelAttributionSchema = LabelAttributionSchema;
 exports.LabelDefinitionSchema = LabelDefinitionSchema;
@@ -49313,6 +50011,14 @@ exports.LocateSegmentResultSchema = LocateSegmentResultSchema;
 exports.LocationStatSchema = LocationStatSchema;
 exports.LockControlStatusSchema = LockControlStatusSchema;
 exports.LockStateSchema = LockStateSchema;
+exports.LogChannelApplyResultSchema = LogChannelApplyResultSchema;
+exports.LogChannelDescriptorSchema = LogChannelDescriptorSchema;
+exports.LogChannelGate = LogChannelGate;
+exports.LogChannelLevelSchema = LogChannelLevelSchema;
+exports.LogChannelRegistry = LogChannelRegistry;
+exports.LogChannelWindowPatchSchema = LogChannelWindowPatchSchema;
+exports.LogChannelWindowSchema = LogChannelWindowSchema;
+exports.LogChannelWindowStateSchema = LogChannelWindowStateSchema;
 exports.LogEntrySchema = LogEntrySchema;
 exports.LogLevelSchema = LogLevelSchema;
 exports.LogStreamEntrySchema = LogStreamEntrySchema;
@@ -49863,6 +50569,7 @@ exports.ZoneRuleStageEnum = ZoneRuleStageEnum;
 exports.ZoneRulesArraySchema = ZoneRulesArraySchema;
 exports.ZoneSchema = ZoneSchema;
 exports.ZoneScopeBreakdownSchema = ZoneScopeBreakdownSchema;
+exports.__resetLogChannelRegistryForTests = __resetLogChannelRegistryForTests;
 exports.accessoriesCapability = accessoriesCapability;
 exports.accessoryStableId = accessoryStableId;
 exports.addonPagesCapability = addonPagesCapability;
@@ -49959,6 +50666,7 @@ exports.createEventBusSliceSource = require_sleep.createEventBusSliceSource;
 exports.createExpressionScope = createExpressionScope;
 exports.createHwAccelCache = createHwAccelCache;
 exports.createLazyTrpcSource = require_sleep.createLazyTrpcSource;
+exports.createLogChannelsProvider = createLogChannelsProvider;
 exports.createMirrorSource = require_sleep.createMirrorSource;
 exports.createRuntimeStateBridge = createRuntimeStateBridge;
 exports.createSliceHandle = require_sleep.createSliceHandle;
@@ -49968,6 +50676,7 @@ exports.customModelRegistryCapability = customModelRegistryCapability;
 exports.dataStoreProviderCapability = dataStoreProviderCapability;
 exports.dayNightCapability = dayNightCapability;
 exports.declarationOwnerNodeId = declarationOwnerNodeId;
+exports.declareLogChannel = declareLogChannel;
 exports.decodeVectorBase64 = decodeVectorBase64;
 exports.decoderCapability = decoderCapability;
 exports.defaultDeliveryForSection = defaultDeliveryForSection;
@@ -50030,6 +50739,7 @@ exports.generateAutomationBlock = generateAutomationBlock;
 exports.getAudioMacroClassIds = getAudioMacroClassIds;
 exports.getByPath = getByPath;
 exports.getCapsByProviderKind = getCapsByProviderKind;
+exports.getLogChannelRegistry = getLogChannelRegistry;
 exports.getTaxonomyEntry = getTaxonomyEntry;
 exports.hasMotionTrigger = hasMotionTrigger;
 exports.hfModelUrl = hfModelUrl;
@@ -50083,6 +50793,7 @@ exports.localNetworkCapability = localNetworkCapability;
 exports.locationSimilarity = locationSimilarity;
 exports.lockControlCapability = lockControlCapability;
 exports.logBannerArgs = require_canonical_hash.logBannerArgs;
+exports.logChannelsCapability = logChannelsCapability;
 exports.logDestinationCapability = logDestinationCapability;
 exports.logLevelAtMost = logLevelAtMost;
 exports.loginMethodCapability = loginMethodCapability;