@camstack/types 1.2.417 → 1.2.418

package/dist/index.js

@@ -1,7 +1,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_sleep = require("./sleep-gtskVoMw.js");
+const require_sleep = require("./sleep-7Gw3GJ4n.js");
 const require_event_category = require("./event-category-DXZ3f9Q5.js");
-const require_composition = require("./composition-DsmkwP9-.js");
+const require_composition = require("./composition-OJKOJJD-.js");
 const require_node_color = require("./node-color.js");
 const require_err_msg = require("./err-msg-BhVbr0NX.js");
 const require_enums = require("./enums.js");
@@ -12624,7 +12624,10 @@ var CompositionProblemCodeSchema = zod.z.enum([
 	"target-missing",
 	"target-unreadable",
 	"not-replaceable",
-	"native-capability-replace"
+	"native-capability-replace",
+	"mixed-quantity",
+	"helper-mismatch",
+	"member-constraint"
 ]);
 /** One refusal, named (D391). `path` points into the composition, e.g. `features[0].fields.celsius`. */
 var CompositionProblemSchema = zod.z.object({
@@ -12648,7 +12651,8 @@ var CompositionUnavailableModeSchema = zod.z.enum([
 	"null",
 	"offline",
 	"unknown",
-	"release"
+	"release",
+	"omit"
 ]);
 /**
 * `derived` reads a source · `clock` reads only `now`, recomputed when a sibling
@@ -13019,6 +13023,24 @@ function inferExpressionKinds(input) {
 * planner (`composition-items.ts`). Internal to the composition module — NOT
 * in the barrel: these are planner internals, not a published contract.
 */
+function aggregateKinds(source) {
+	if (source.publish !== "value") return {
+		ok: true,
+		kinds: new Set(["number"])
+	};
+	if (source.reducer === "any" || source.reducer === "all") return {
+		ok: true,
+		kinds: new Set(["boolean"])
+	};
+	if (source.empty === "null") return {
+		ok: true,
+		kinds: new Set(["number", "null"])
+	};
+	return {
+		ok: true,
+		kinds: new Set(["number"])
+	};
+}
 function readKinds(read, lookupCap) {
 	const def = lookupCap(read.cap);
 	const schema = def?.runtimeState ?? def?.status?.schema;
@@ -13046,6 +13068,7 @@ function sourceKinds(source, lookupCap) {
 		code: "reserved-variant",
 		message: "code fields arrive in slice 4"
 	};
+	if (source.kind === "aggregate") return aggregateKinds(source);
 	const bindingKinds = /* @__PURE__ */ new Map();
 	for (const [name, binding] of Object.entries(source.bindings)) {
 		if (binding.kind === "literal") {
@@ -13242,6 +13265,388 @@ function planItems(def, feature, featureIndex, lookupCap, mode = "new") {
 	};
 }
 //#endregion
+//#region src/composition/helpers/catalog.ts
+/**
+* One catalog row per base reading a group helper can build (D944 §3).
+* Data, not a form default written into the block.
+*/
+var NOW = {
+	fieldPath: "lastFetchedAt",
+	expr: "now"
+};
+var CHANGED = {
+	fieldPath: "lastChangedAt",
+	expr: "now"
+};
+function numeric(input) {
+	return {
+		...input,
+		family: "numeric",
+		deviceType: require_err_msg.DeviceType.Sensor,
+		memberDeviceType: require_err_msg.DeviceType.Sensor,
+		baseUnit: require_sleep.baseUnitOf(input.quantity),
+		aggregates: require_composition.NUMERIC_AGGREGATES,
+		accept: [{
+			cap: input.outputCap,
+			fieldPath: input.outputField
+		}]
+	};
+}
+function binary(input) {
+	return {
+		...input,
+		family: "binary",
+		deviceType: require_err_msg.DeviceType.Sensor,
+		memberDeviceType: require_err_msg.DeviceType.Sensor,
+		quantity: "none",
+		baseUnit: void 0,
+		aggregates: require_composition.BINARY_AGGREGATES,
+		empty: "offline"
+	};
+}
+var GROUP_TEMPLATES = [
+	numeric({
+		id: "temperature",
+		summary: "Mean, median, min, max or sum of temperatures. Offline and unknown members are left out, never read as 0 °C.",
+		role: require_err_msg.DeviceRole.TemperatureSensor,
+		outputCap: "temperature-sensor",
+		outputField: "celsius",
+		quantity: "temperature",
+		defaultAggregate: "mean",
+		empty: "null",
+		companions: [NOW]
+	}),
+	numeric({
+		id: "humidity",
+		summary: "Humidity in percent. Offline and unknown members are left out, never read as 0 %.",
+		role: require_err_msg.DeviceRole.HumiditySensor,
+		outputCap: "humidity-sensor",
+		outputField: "percent",
+		quantity: "humidity",
+		defaultAggregate: "mean",
+		empty: "null",
+		companions: [NOW]
+	}),
+	numeric({
+		id: "pressure",
+		summary: "Pressure in hectopascals. Offline and unknown members are left out, never read as 0 hPa.",
+		role: require_err_msg.DeviceRole.PressureSensor,
+		outputCap: "pressure-sensor",
+		outputField: "hpa",
+		quantity: "pressure",
+		defaultAggregate: "mean",
+		empty: "null",
+		companions: [NOW]
+	}),
+	numeric({
+		id: "illuminance",
+		summary: "Illuminance in lux. Offline and unknown members are left out, never read as 0 lx.",
+		role: require_err_msg.DeviceRole.AmbientLightSensor,
+		outputCap: "ambient-light-sensor",
+		outputField: "lux",
+		quantity: "illuminance",
+		defaultAggregate: "mean",
+		empty: "null",
+		companions: [NOW]
+	}),
+	numeric({
+		id: "power",
+		summary: "Power in watts, summed by default. Nobody reporting omits the key rather than writing 0 W.",
+		role: require_err_msg.DeviceRole.PowerSensor,
+		outputCap: "power-meter",
+		outputField: "watts",
+		quantity: "power",
+		defaultAggregate: "sum",
+		empty: "omit",
+		companions: [NOW]
+	}),
+	numeric({
+		id: "energy",
+		summary: "Energy in kilowatt-hours, summed by default. Nobody reporting omits the key rather than writing 0 kWh.",
+		role: require_err_msg.DeviceRole.EnergySensor,
+		outputCap: "power-meter",
+		outputField: "kwhTotal",
+		quantity: "energy",
+		defaultAggregate: "sum",
+		empty: "omit",
+		companions: [NOW]
+	}),
+	numeric({
+		id: "battery",
+		summary: "Battery charge in percent. Offline and unknown members are left out, never read as 0 %.",
+		role: require_err_msg.DeviceRole.BatterySensor,
+		outputCap: "battery",
+		outputField: "percentage",
+		quantity: "percentage",
+		defaultAggregate: "mean",
+		empty: "null",
+		companions: [
+			{
+				fieldPath: "charging",
+				expr: "\"unknown\""
+			},
+			{
+				fieldPath: "sleeping",
+				expr: "false"
+			},
+			{
+				fieldPath: "lastUpdated",
+				expr: "now"
+			}
+		]
+	}),
+	numeric({
+		id: "numeric",
+		summary: "A numeric reading in the members’ shared quantity. Mixed quantities are refused. Nobody reporting publishes null, not 0.",
+		role: require_err_msg.DeviceRole.NumericSensor,
+		outputCap: "numeric-sensor",
+		outputField: "value",
+		quantity: "device",
+		defaultAggregate: "mean",
+		empty: "null",
+		companions: [NOW]
+	}),
+	binary({
+		id: "motion",
+		summary: "Any or all motion. Offline and unknown members are left out, never read as off. Nobody reporting takes the device offline.",
+		role: require_err_msg.DeviceRole.MotionSensor,
+		outputCap: "motion",
+		outputField: "detected",
+		defaultAggregate: "any",
+		accept: [{
+			cap: "motion",
+			fieldPath: "detected"
+		}],
+		companions: [{
+			fieldPath: "lastDetectedAt",
+			expr: "null"
+		}, {
+			fieldPath: "autoClearAfterMs",
+			expr: "null"
+		}]
+	}),
+	binary({
+		id: "contact",
+		summary: "Any or all open contacts. Offline and unknown members are left out, never read as closed.",
+		role: require_err_msg.DeviceRole.ContactSensor,
+		outputCap: "contact",
+		outputField: "entryOpen",
+		defaultAggregate: "any",
+		accept: [{
+			cap: "contact",
+			fieldPath: "entryOpen"
+		}],
+		companions: [CHANGED]
+	}),
+	binary({
+		id: "leak",
+		summary: "Any or all leak detections. Offline and unknown members are left out, never read as dry.",
+		role: require_err_msg.DeviceRole.LeakSensor,
+		outputCap: "flood",
+		outputField: "flooded",
+		defaultAggregate: "any",
+		accept: [{
+			cap: "flood",
+			fieldPath: "flooded"
+		}],
+		companions: [CHANGED]
+	}),
+	binary({
+		id: "smoke",
+		summary: "Any or all smoke detections. Offline and unknown members are left out, never read as clear.",
+		role: require_err_msg.DeviceRole.SmokeSensor,
+		outputCap: "smoke",
+		outputField: "detected",
+		defaultAggregate: "any",
+		accept: [{
+			cap: "smoke",
+			fieldPath: "detected"
+		}],
+		companions: [CHANGED]
+	}),
+	binary({
+		id: "occupancy",
+		summary: "Any or all of motion or binary sensors, published as a binary. Presence zones are not aggregated. Nobody reporting is offline, not off.",
+		role: require_err_msg.DeviceRole.BinarySensor,
+		outputCap: "binary",
+		outputField: "on",
+		defaultAggregate: "any",
+		accept: [{
+			cap: "motion",
+			fieldPath: "detected"
+		}, {
+			cap: "binary",
+			fieldPath: "on"
+		}],
+		companions: [CHANGED]
+	}),
+	binary({
+		id: "binary",
+		summary: "Any or all generic binary sensors. Offline and unknown members are left out, never read as off.",
+		role: require_err_msg.DeviceRole.BinarySensor,
+		outputCap: "binary",
+		outputField: "on",
+		defaultAggregate: "any",
+		accept: [{
+			cap: "binary",
+			fieldPath: "on"
+		}],
+		companions: [CHANGED]
+	})
+];
+var BY_ID = new Map(GROUP_TEMPLATES.map((template) => [template.id, template]));
+function groupTemplate(id) {
+	return BY_ID.get(id) ?? null;
+}
+//#endregion
+//#region src/composition/helpers/compile.ts
+function sameSource(a, b) {
+	return a.addonId === b.addonId && a.stableId === b.stableId;
+}
+function sameMember(a, b) {
+	return sameSource(a.source, b.source) && a.cap === b.cap && a.fieldPath === b.fieldPath;
+}
+function accepted(template, member) {
+	return template.accept.some((field) => field.cap === member.cap && field.fieldPath === member.fieldPath);
+}
+function memberProblems(template, spec) {
+	return spec.members.flatMap((member, index) => {
+		const at = `helper.members[${index}]`;
+		const problems = [];
+		if (!accepted(template, member)) {
+			const allowed = template.accept.map((field) => `${field.cap}.${field.fieldPath}`).join(" or ");
+			problems.push(problem("member-constraint", at, `a ${template.id} group reads ${allowed}; this member is ${member.cap}.${member.fieldPath}`));
+		}
+		if (spec.members.slice(0, index).some((other) => sameMember(other, member))) problems.push(problem("member-constraint", at, "this member is already in the group"));
+		return problems;
+	});
+}
+function aggregateSource(template, spec, reads, publish) {
+	return {
+		kind: "aggregate",
+		reducer: spec.aggregate,
+		reads: [...reads],
+		publish,
+		empty: template.empty
+	};
+}
+function expressionSource(expr) {
+	return {
+		kind: "expression",
+		expr,
+		bindings: {}
+	};
+}
+function draftOf$1(template, spec) {
+	const reads = spec.members.map((member) => ({
+		source: member.source,
+		cap: member.cap,
+		fieldPath: member.fieldPath
+	}));
+	const companions = Object.fromEntries(template.companions.map((companion) => [companion.fieldPath, expressionSource(companion.expr)]));
+	return {
+		target: {
+			kind: "new",
+			type: template.deviceType,
+			role: template.role
+		},
+		helper: spec,
+		features: [{
+			kind: "fields",
+			cap: template.outputCap,
+			fields: {
+				[template.outputField]: aggregateSource(template, spec, reads, "value"),
+				...companions
+			}
+		}, {
+			kind: "fields",
+			cap: "group-status",
+			fields: {
+				included: aggregateSource(template, spec, reads, "included"),
+				excluded: aggregateSource(template, spec, reads, "excluded"),
+				total: aggregateSource(template, spec, reads, "total")
+			}
+		}]
+	};
+}
+function parseDraft(draft) {
+	const parsed = require_composition.CompositionSchema.safeParse(draft);
+	if (parsed.success) return {
+		ok: true,
+		composition: parsed.data
+	};
+	return {
+		ok: false,
+		problems: [problem("helper-mismatch", "helper", `the template did not compile: ${parsed.error.issues.map((issue) => issue.message).join("; ")}`)]
+	};
+}
+/** Compile a group template to a new-device composition. Refusals are named. */
+function compileHelper(spec) {
+	const template = groupTemplate(spec.templateId);
+	if (template === null) return {
+		ok: false,
+		problems: [problem("member-constraint", "helper.templateId", `unknown template \`${spec.templateId}\``)]
+	};
+	if (!template.aggregates.includes(spec.aggregate)) {
+		const allowed = template.aggregates.join(", ");
+		return {
+			ok: false,
+			problems: [problem("kind-mismatch", "helper.aggregate", `a ${template.id} group aggregates by ${allowed}, not \`${spec.aggregate}\``)]
+		};
+	}
+	const members = memberProblems(template, spec);
+	if (members.length > 0) return {
+		ok: false,
+		problems: members
+	};
+	return parseDraft(draftOf$1(template, spec));
+}
+/** The built body, ignoring `helper`, so a save can demand one writer. */
+function sameHelperBody(stored, compiled) {
+	return JSON.stringify(stored.target) === JSON.stringify(compiled.target) && JSON.stringify(stored.features) === JSON.stringify(compiled.features);
+}
+function templateDeviceType(spec) {
+	return groupTemplate(spec.templateId)?.memberDeviceType ?? null;
+}
+//#endregion
+//#region src/composition/helpers/save.ts
+function quantityProblems(spec, facts) {
+	const template = groupTemplate(spec.templateId);
+	if (template === null || template.family !== "numeric") return [];
+	const known = spec.members.flatMap((member, index) => {
+		const quantity = facts.get(require_composition.compositionSourceKey(member.source))?.quantity;
+		return quantity === void 0 ? [] : [{
+			index,
+			quantity
+		}];
+	});
+	if (template.quantity !== "device") return known.flatMap((member) => member.quantity === template.quantity ? [] : [problem("mixed-quantity", `helper.members[${member.index}]`, `a ${template.id} group is ${template.quantity}${template.baseUnit === void 0 ? "" : ` (${template.baseUnit})`}; this member is ${member.quantity}`)]);
+	const distinct = [...new Set(known.map((member) => member.quantity))];
+	if (distinct.length <= 1) return [];
+	return [problem("mixed-quantity", "helper.members", `a numeric group requires one quantity; members report ${distinct.join(" and ")}`)];
+}
+function deviceTypeProblems(spec, facts) {
+	const template = groupTemplate(spec.templateId);
+	if (template === null) return [];
+	return spec.members.flatMap((member, index) => {
+		const deviceType = facts.get(require_composition.compositionSourceKey(member.source))?.deviceType;
+		if (deviceType === void 0 || deviceType === template.memberDeviceType) return [];
+		return [problem("member-constraint", `helper.members[${index}]`, `a ${template.id} group takes ${template.memberDeviceType} devices; this member is a ${deviceType}`)];
+	});
+}
+/**
+* Problems that refuse a save. No `helper` key means a free composition: this
+* returns nothing, and expression semantics stay as they are.
+*/
+function helperSaveProblems(composition, facts) {
+	const spec = composition.helper;
+	if (spec === void 0) return [];
+	const compiled = compileHelper(spec);
+	if (!compiled.ok) return compiled.problems;
+	if (!sameHelperBody(composition, compiled.composition)) return [problem("helper-mismatch", "helper", "the stored features are not this template — the helper spec is the only writer")];
+	return [...quantityProblems(spec, facts), ...deviceTypeProblems(spec, facts)];
+}
+//#endregion
 //#region src/composition/composition-graph.ts
 /**
 * The field graph across every composition, and the cycles in it (D659).
@@ -13472,6 +13877,7 @@ function planTopLevelField({ def, fields }, field, mode, lookupCap) {
 	const role = roleOf(source);
 	const unavailable = unavailableFor(tf, role, mode, def.name, fieldAt);
 	if (!unavailable.ok) return refused(unavailable.problem);
+	const omitEmpty = source.kind === "aggregate" && source.publish === "value" && source.empty === "omit";
 	const plan = {
 		cap: def.name,
 		path,
@@ -13479,7 +13885,7 @@ function planTopLevelField({ def, fields }, field, mode, lookupCap) {
 		kind: tf.kind,
 		nullable: tf.nullable,
 		required: tf.required,
-		unavailable: unavailable.unavailable,
+		unavailable: omitEmpty ? "omit" : unavailable.unavailable,
 		role,
 		source,
 		reads: [...require_composition.fieldReads(source)]
@@ -13744,10 +14150,15 @@ function validateComposition(composition, ctx) {
 		if (refusedFeatures.some((at) => item.path === at || item.path.startsWith(`${at}.`))) return false;
 		return refusedFeatures.length === 0 || item.path !== "features";
 	});
+	const facts = new Map([...ctx.sources].flatMap(([key, source]) => source.kind === "found" ? [[key, {
+		deviceType: source.deviceType,
+		quantity: source.quantity
+	}]] : []));
 	const problems = [
 		...plan.problems,
 		...sourceProblems(plan.fields, ctx, self),
-		...cycles
+		...cycles,
+		...helperSaveProblems(composition, facts)
 	];
 	return {
 		ok: problems.length === 0,
@@ -64307,6 +64718,53 @@ var gasCapability = {
 	volatileStateFields: ["lastChangedAt"]
 };
 //#endregion
+//#region src/capabilities/group-status.cap.ts
+/**
+* How many members of a helper group answered (D944). Counts are integers,
+* not measurements: zero included is a real count, never a stand-in reading.
+* The reading itself stays on the output capability. History is none — the
+* series that later statistics read is the output cap's own history block.
+*/
+var GroupStatusSchema = zod.z.object({
+	/** Members whose current value entered the aggregate. */
+	included: zod.z.number().int().nonnegative().meta(require_sleep.readingMeta("count", {
+		precision: 0,
+		label: "Reporting"
+	})),
+	/** Members left out: offline, unknown, or not a finite reading (D393). */
+	excluded: zod.z.number().int().nonnegative().meta(require_sleep.readingMeta("count", {
+		precision: 0,
+		label: "Excluded"
+	})),
+	/** `included` + `excluded`. */
+	total: zod.z.number().int().nonnegative().meta(require_sleep.readingMeta("count", {
+		precision: 0,
+		label: "Members"
+	}))
+});
+var groupStatusCapability = {
+	name: "group-status",
+	scope: "device",
+	deviceNative: true,
+	mode: "singleton",
+	deviceTypes: [require_err_msg.DeviceType.Sensor],
+	methods: {},
+	status: {
+		schema: GroupStatusSchema,
+		kind: "push"
+	},
+	runtimeState: GroupStatusSchema,
+	/**
+	* Runtime-state durability: **session** — recomputed from members on the
+	* next source event; a restored count would outlive the readings it named.
+	*
+	* See `RuntimeStateDurability`. Enforced by
+	* `scripts/check-runtime-state-durability.ts`.
+	*/
+	durability: "session",
+	history: "none"
+};
+//#endregion
 //#region src/capabilities/heating-valve.cap.ts
 var HeatingValveStatusSchema = zod.z.object({
 	/** Radiator valve opening 0 (closed) .. 100 (open). Null = not yet known. */
@@ -66402,12 +66860,18 @@ var motionCapability = {
 	methods: { 
 	/**
 	* Pull the current motion state synchronously. Convenience shortcut
-	* for consumers that don't need the full status object; equivalent
-	* to `getStatus()?.detected ?? false`. Will likely be folded into
-	* `getStatus` once the auto-injected status surface lands in every
-	* consumer.
+	* for consumers that don't need the full status object. A composed
+	* group answers from its slice (D944): unknown throws, it is not off.
 	*/
 isDetected: require_sleep.method(zod.z.object({ deviceId: zod.z.number() }), zod.z.boolean()) },
+	/**
+	* A composed motion group serves `isDetected` from `detected` (D944).
+	* Without this the cap stays uncomposable (`has-commands`).
+	*/
+	composedMethods: { isDetected: {
+		kind: "slice",
+		field: "detected"
+	} },
 	events: { 
 	/**
 	* Fires every time the runner transitions a camera between
@@ -77154,6 +77618,127 @@ function createDeviceExtensionProvider(options) {
 	};
 }
 //#endregion
+//#region src/composition/helpers/aggregate.ts
+function isBinaryReducer(reducer) {
+	return reducer === "any" || reducer === "all";
+}
+function includedValue(reducer, member) {
+	if (member.state !== "fresh") return null;
+	if (isBinaryReducer(reducer)) return typeof member.value === "boolean" ? member.value : null;
+	return typeof member.value === "number" && Number.isFinite(member.value) ? member.value : null;
+}
+function median$1(values) {
+	const sorted = [...values].toSorted((a, b) => a - b);
+	const mid = Math.floor(sorted.length / 2);
+	const right = sorted[mid];
+	const left = sorted[mid - 1];
+	if (right === void 0) throw new Error("median requires at least one finite number");
+	if (sorted.length % 2 === 1) return right;
+	if (left === void 0) throw new Error("median requires at least one finite number");
+	return (left + right) / 2;
+}
+function reduceNumbers(reducer, values) {
+	if (reducer === "min") return Math.min(...values);
+	if (reducer === "max") return Math.max(...values);
+	if (reducer === "sum") return values.reduce((sum, value) => sum + value, 0);
+	if (reducer === "median") return median$1(values);
+	return values.reduce((sum, value) => sum + value, 0) / values.length;
+}
+function reduceBooleans(reducer, values) {
+	return reducer === "all" ? values.every((value) => value) : values.some((value) => value);
+}
+function countsOf(included, total) {
+	return {
+		included,
+		excluded: total - included,
+		total
+	};
+}
+function fatalReason(members) {
+	const reasons = members.flatMap((member) => member.state === "unavailable" && member.fatal === true ? [member.reason ?? "source gone"] : []);
+	return reasons.length === 0 ? null : reasons.join("; ");
+}
+function emptyOutcome(empty, counts) {
+	if (empty === "null") return {
+		kind: "value",
+		value: null,
+		counts
+	};
+	return {
+		kind: "unavailable",
+		fatal: false,
+		reason: "no member included — unknown is not 0 or off",
+		counts
+	};
+}
+/** Pure. `members` is not mutated. An empty included set is null or unavailable, never 0 or false. */
+function evaluateAggregate(input) {
+	const included = input.members.flatMap((member) => {
+		const value = includedValue(input.reducer, member);
+		return value === null ? [] : [value];
+	});
+	const counts = countsOf(included.length, input.members.length);
+	const gone = fatalReason(input.members);
+	if (gone !== null) return {
+		kind: "unavailable",
+		fatal: true,
+		reason: gone,
+		counts
+	};
+	if (input.publish === "included") return {
+		kind: "value",
+		value: counts.included,
+		counts
+	};
+	if (input.publish === "excluded") return {
+		kind: "value",
+		value: counts.excluded,
+		counts
+	};
+	if (input.publish === "total") return {
+		kind: "value",
+		value: counts.total,
+		counts
+	};
+	if (included.length === 0) return emptyOutcome(input.empty, counts);
+	if (isBinaryReducer(input.reducer)) {
+		const flags = included.filter((value) => typeof value === "boolean");
+		return {
+			kind: "value",
+			value: reduceBooleans(input.reducer, flags),
+			counts
+		};
+	}
+	const numbers = included.filter((value) => typeof value === "number");
+	return {
+		kind: "value",
+		value: reduceNumbers(input.reducer, numbers),
+		counts
+	};
+}
+//#endregion
+//#region src/composition/helpers/source-pick.ts
+/** What the member step asks the selector for this template. */
+function sourcePickForTemplate(template) {
+	const valueKind = template.family === "numeric" ? "number" : "boolean";
+	return {
+		purpose: "member",
+		multiple: true,
+		max: 64,
+		deviceTypes: [template.memberDeviceType],
+		accept: template.accept.map((field) => ({
+			...field,
+			valueKind
+		})),
+		history: {
+			required: false,
+			minRetentionMs: null
+		},
+		mustBindCaps: [],
+		exclude: []
+	};
+}
+//#endregion
 //#region src/units/unit-table.ts
 /**
 * Frozen unit → spec table. `•` in the doc marks each dimension's canonical
@@ -77740,11 +78325,45 @@ function expressionOutcome(source, read, now, stateful) {
 		deadline: deadlines.length > 0 ? Math.min(...deadlines) : null
 	};
 }
+function aggregateRead(reading) {
+	if (reading.state === "unavailable") return {
+		state: "unavailable",
+		fatal: reading.fatal,
+		reason: reading.reason
+	};
+	return {
+		state: reading.state,
+		value: reading.value,
+		...reading.state === "stale" ? { reason: reading.reason } : {}
+	};
+}
+function aggregateField(source, read) {
+	const outcome = evaluateAggregate({
+		reducer: source.reducer,
+		members: source.reads.map((item) => aggregateRead(read(item))),
+		publish: source.publish,
+		empty: source.empty
+	});
+	if (outcome.kind === "value") return {
+		state: "fresh",
+		value: outcome.value,
+		reason: null,
+		deadline: null
+	};
+	return {
+		state: "unavailable",
+		value: null,
+		reason: outcome.reason,
+		fatal: outcome.fatal,
+		confirmed: true
+	};
+}
 function evaluateCompositionField(input) {
 	const { source } = input;
 	switch (source.kind) {
 		case "from": return fromReading(input.read(source), source);
 		case "expression": return expressionOutcome(source, input.read, input.now, input.stateful);
+		case "aggregate": return aggregateField(source, input.read);
 		case "code": return {
 			state: "unavailable",
 			value: null,
@@ -80600,6 +81219,7 @@ var DEVICE_LOCAL_STATE_CAPS = {
 	featureProbe: featureProbeCapability,
 	flood: floodCapability,
 	gas: gasCapability,
+	groupStatus: groupStatusCapability,
 	heatingValve: heatingValveCapability,
 	humidifier: humidifierCapability,
 	humiditySensor: humiditySensorCapability,
@@ -85925,6 +86545,13 @@ var METHOD_ACCESS_MAP = Object.freeze({
 		access: "view",
 		role: "viewer"
 	},
+	"groupStatus.getStatus": {
+		capName: "group-status",
+		capScope: "device",
+		addonId: null,
+		access: "view",
+		role: "viewer"
+	},
 	"heatingValve.getStatus": {
 		capName: "heating-valve",
 		capScope: "device",
@@ -92463,6 +93090,7 @@ var KNOWN_CAP_NAMES = [
 	"filesystem-browse",
 	"flood",
 	"gas",
+	"group-status",
 	"heating-valve",
 	"humidifier",
 	"humidity-sensor",
@@ -92611,6 +93239,7 @@ var DEVICE_CAP_NAMES = [
 	"feature-probe",
 	"flood",
 	"gas",
+	"group-status",
 	"heating-valve",
 	"humidifier",
 	"humidity-sensor",
@@ -96128,6 +96757,33 @@ var SENSOR_CAP_VOCABULARY = {
 			icon: "flame"
 		}]
 	},
+	"group-status": {
+		scope: "device",
+		noun: t("Group", "Gruppo"),
+		state: [
+			{
+				kind: "numeric",
+				field: "included",
+				quantity: t("the members reporting", "i membri che rispondono"),
+				label: t("Reporting", "Rispondono"),
+				icon: "users"
+			},
+			{
+				kind: "numeric",
+				field: "excluded",
+				quantity: t("the members left out", "i membri esclusi"),
+				label: t("Excluded", "Esclusi"),
+				icon: "users"
+			},
+			{
+				kind: "numeric",
+				field: "total",
+				quantity: t("the member count", "il numero di membri"),
+				label: t("Members", "Membri"),
+				icon: "sigma"
+			}
+		]
+	},
 	"humidity-sensor": {
 		scope: "device",
 		noun: t("Humidity", "Umidità"),
@@ -98265,6 +98921,7 @@ var CAP_NAMES_WITH_STATUS = [
 	"feature-probe",
 	"flood",
 	"gas",
+	"group-status",
 	"heating-valve",
 	"humidifier",
 	"humidity-sensor",
@@ -98387,6 +99044,7 @@ var CAPABILITY_NAMES = {
 	filesystemBrowse: "filesystem-browse",
 	flood: "flood",
 	gas: "gas",
+	groupStatus: "group-status",
 	heatingValve: "heating-valve",
 	humidifier: "humidifier",
 	humiditySensor: "humidity-sensor",
@@ -98793,6 +99451,10 @@ var CAPABILITY_ROUTER_KEYS = [
 		key: "gas",
 		name: "gas"
 	},
+	{
+		key: "groupStatus",
+		name: "group-status"
+	},
 	{
 		key: "heatingValve",
 		name: "heating-valve"
@@ -99306,6 +99968,7 @@ var ALL_CAPABILITY_DEFINITIONS = [
 	filesystemBrowseCapability,
 	floodCapability,
 	gasCapability,
+	groupStatusCapability,
 	heatingValveCapability,
 	humidifierCapability,
 	humiditySensorCapability,
@@ -100382,6 +101045,11 @@ var METHOD_DEVICE_SELECTORS = Object.freeze({
 		form: "single",
 		optional: false
 	}],
+	"groupStatus.getStatus": [{
+		name: "deviceId",
+		form: "single",
+		optional: false
+	}],
 	"heatingValve.getStatus": [{
 		name: "deviceId",
 		form: "single",
@@ -102393,7 +103061,7 @@ function getCapsByProviderKind(kind) {
 //#region src/generated/runtime-state-durability.ts
 /**
 * Per-cap runtime-state policy, projected from every `*.cap.ts` that declares
-* `runtimeState`. 72 caps: 38 `restored`, 34 `session`.
+* `runtimeState`. 73 caps: 38 `restored`, 35 `session`.
 *
 * A cap absent from this map has no runtime-state slice at all. A cap PRESENT
 * with `durability: 'session'` has one and has decided not to keep it.
@@ -102511,6 +103179,10 @@ var RUNTIME_STATE_POLICY = {
 		durability: "restored",
 		volatileFields: ["lastChangedAt"]
 	},
+	"group-status": {
+		durability: "session",
+		volatileFields: []
+	},
 	"heating-valve": {
 		durability: "session",
 		volatileFields: ["lastFetchedAt"]
@@ -102853,7 +103525,7 @@ var BucketAccumulator = class {
 //#region src/generated/history-catalog.ts
 /**
 * Cap history catalog, projected from every `*.cap.ts` `history` block.
-* 41 caps with series (75 series), 30 caps answered `'none'`.
+* 41 caps with series (75 series), 31 caps answered `'none'`.
 * Field keys are `runtimeState` paths (`a.b` into fixed objects only).
 */
 var HISTORY_CATALOG = {
@@ -103254,6 +103926,7 @@ var HISTORY_NONE_CAPS = [
 	"doorbell",
 	"event-emitter",
 	"feature-probe",
+	"group-status",
 	"image",
 	"image-settings",
 	"intercom",
@@ -114509,6 +115182,7 @@ exports.ADMIN_SCOPE = ADMIN_SCOPE;
 exports.AGENT_MDNS_QUERY_NAME = AGENT_MDNS_QUERY_NAME;
 exports.AGENT_MDNS_SERVICE_TYPE = AGENT_MDNS_SERVICE_TYPE;
 exports.AGENT_MDNS_TXT_KEYS = AGENT_MDNS_TXT_KEYS;
+exports.AGGREGATE_REDUCERS = require_composition.AGGREGATE_REDUCERS;
 exports.AGGREGATE_THROUGHPUT_BY_KIND = AGGREGATE_THROUGHPUT_BY_KIND;
 exports.ALEXA_EGRESS_PROFILE = ALEXA_EGRESS_PROFILE;
 exports.ALL_CAPABILITY_DEFINITIONS = ALL_CAPABILITY_DEFINITIONS;
@@ -114563,6 +115237,7 @@ exports.AdoptionOutcomeSchema = AdoptionOutcomeSchema;
 exports.AdoptionReleaseInputSchema = ReleaseInputSchema;
 exports.AdoptionStatusSchema = AdoptionStatusSchema;
 exports.AgentLoadSummarySchema = AgentLoadSummarySchema;
+exports.AggregateReducerSchema = require_composition.AggregateReducerSchema;
 exports.AirQualitySensorStatusSchema = AirQualitySensorStatusSchema;
 exports.AlarmArmModeSchema = AlarmArmModeSchema;
 exports.AlarmPanelStatusSchema = AlarmPanelStatusSchema;
@@ -114629,6 +115304,7 @@ exports.BASE_LIVE_EGRESS_PROFILE = BASE_LIVE_EGRESS_PROFILE;
 exports.BATTERY_DEVICE_PROFILE = BATTERY_DEVICE_PROFILE;
 exports.BATTERY_UNREACHABLE_AFTER_MS = BATTERY_UNREACHABLE_AFTER_MS;
 exports.BENCH_ROOT_STEP_ID = BENCH_ROOT_STEP_ID;
+exports.BINARY_AGGREGATES = require_composition.BINARY_AGGREGATES;
 exports.BIRTH_DECISION_DEFAULT_LIMIT = BIRTH_DECISION_DEFAULT_LIMIT;
 exports.BOOT_RECOVERY_BACKOFF_MS = require_sleep.BOOT_RECOVERY_BACKOFF_MS;
 exports.BUILTIN_RESULT_KINDS = BUILTIN_RESULT_KINDS;
@@ -114839,6 +115515,7 @@ exports.ComposerApplyResultSchema = ComposerApplyResultSchema;
 exports.ComposerBlockSchema = ComposerBlockSchema;
 exports.ComposerBlockVerdictSchema = ComposerBlockVerdictSchema;
 exports.ComposerUnreadableBlockSchema = ComposerUnreadableBlockSchema;
+exports.CompositionAggregateSourceSchema = require_composition.CompositionAggregateSourceSchema;
 exports.CompositionBindingSchema = require_composition.CompositionBindingSchema;
 exports.CompositionBlockInputSchema = CompositionBlockInputSchema;
 exports.CompositionBlockStateSchema = CompositionBlockStateSchema;
@@ -115215,12 +115892,17 @@ exports.FrameInputSchema = FrameInputSchema;
 exports.FrameLazyCountersSchema = FrameLazyCountersSchema;
 exports.FrameLazyMetricsSchema = FrameLazyMetricsSchema;
 exports.G711_SCALE_CORRECTION_DB = G711_SCALE_CORRECTION_DB;
+exports.GROUP_TEMPLATES = GROUP_TEMPLATES;
+exports.GROUP_TEMPLATE_IDS = require_composition.GROUP_TEMPLATE_IDS;
 exports.GasStatusSchema = GasStatusSchema;
 exports.GetLoggingSettingsInputSchema = GetLoggingSettingsInputSchema;
 exports.GetStreamWithCodecInputSchema = GetStreamWithCodecInputSchema;
 exports.GlobalMetricsSchema = GlobalMetricsSchema;
 exports.GridLayoutPatchSchema = GridLayoutPatchSchema;
 exports.GridLayoutViewSchema = GridLayoutViewSchema;
+exports.GroupHelperSpecSchema = require_composition.GroupHelperSpecSchema;
+exports.GroupStatusSchema = GroupStatusSchema;
+exports.GroupTemplateIdSchema = require_composition.GroupTemplateIdSchema;
 exports.HAP_AUDIO_BASE = HAP_AUDIO_BASE;
 exports.HAP_AUDIO_BITRATE_KBPS = HAP_AUDIO_BITRATE_KBPS;
 exports.HAP_AUDIO_VBV_KBITS = HAP_AUDIO_VBV_KBITS;
@@ -115244,6 +115926,8 @@ exports.HWACCEL_OPTIONS = HWACCEL_OPTIONS;
 exports.HardwareClassIdSchema = HardwareClassIdSchema;
 exports.HealthStatusSchema = HealthStatusSchema;
 exports.HeatingValveStatusSchema = HeatingValveStatusSchema;
+exports.HelperMemberSchema = require_composition.HelperMemberSchema;
+exports.HelperSpecSchema = require_composition.HelperSpecSchema;
 exports.HfModelResolutionSchema = HfModelResolutionSchema;
 exports.HistoryPointSchema = HistoryPointSchema;
 exports.HistoryResolutionEnum = HistoryResolutionEnum;
@@ -115418,6 +116102,7 @@ exports.MAX_EXPRESSION_BINDINGS = require_composition.MAX_EXPRESSION_BINDINGS;
 exports.MAX_EXPRESSION_CALL_ARGS = require_composition.MAX_EXPRESSION_CALL_ARGS;
 exports.MAX_EXPRESSION_EVAL_STEPS = require_composition.MAX_EXPRESSION_EVAL_STEPS;
 exports.MAX_EXPRESSION_SOURCE_LENGTH = require_composition.MAX_EXPRESSION_SOURCE_LENGTH;
+exports.MAX_HELPER_MEMBERS = require_composition.MAX_HELPER_MEMBERS;
 exports.MAX_KEYS = MAX_KEYS;
 exports.MAX_REASONS_PER_KEY = MAX_REASONS_PER_KEY;
 exports.MAX_REQUEUED_BUCKETS_PER_SERIES = MAX_REQUEUED_BUCKETS_PER_SERIES;
@@ -115609,6 +116294,7 @@ exports.NETWORK_LINK_UNKNOWN = NETWORK_LINK_UNKNOWN;
 exports.NODE_BENCHMARK_DEFAULTS = NODE_BENCHMARK_DEFAULTS;
 exports.NODE_COLOR_IDS = require_node_color.NODE_COLOR_IDS;
 exports.NO_MEASURED_CAPACITY = NO_MEASURED_CAPACITY;
+exports.NUMERIC_AGGREGATES = require_composition.NUMERIC_AGGREGATES;
 exports.NativeCropBboxSchema = NativeCropBboxSchema;
 exports.NativeCropRefSchema = NativeCropRefSchema;
 exports.NativeCropResultSchema = NativeCropResultSchema;
@@ -116663,6 +117349,7 @@ exports.commitWatchdogRestart = commitWatchdogRestart;
 exports.compareToTarget = compareToTarget;
 exports.compileExpression = require_composition.compileExpression;
 exports.compileExpressionSafe = require_composition.compileExpressionSafe;
+exports.compileHelper = compileHelper;
 exports.compileKeyedArrayOverride = compileKeyedArrayOverride;
 exports.compilePulseOverride = compilePulseOverride;
 exports.compileScalarOverride = compileScalarOverride;
@@ -116825,6 +117512,7 @@ exports.enumerateItemArrayFields = enumerateItemArrayFields;
 exports.enumerateSchemaFields = enumerateSchemaFields;
 exports.errMsg = require_err_msg.errMsg;
 exports.estimateNodeBenchmarkDurationMs = estimateNodeBenchmarkDurationMs;
+exports.evaluateAggregate = evaluateAggregate;
 exports.evaluateAst = require_composition.evaluateAst;
 exports.evaluateCompositionField = evaluateCompositionField;
 exports.evaluateCount = require_composition.evaluateCount;
@@ -116898,10 +117586,13 @@ exports.gifFilterComplex = gifFilterComplex;
 exports.gifFromMp4Args = gifFromMp4Args;
 exports.globalSecretScope = require_sleep.globalSecretScope;
 exports.grantRowsOf = grantRowsOf;
+exports.groupStatusCapability = groupStatusCapability;
+exports.groupTemplate = groupTemplate;
 exports.hasModelBoundOverrides = hasModelBoundOverrides;
 exports.hasMotionTrigger = hasMotionTrigger;
 exports.hasUrlScheme = hasUrlScheme;
 exports.heatingValveCapability = heatingValveCapability;
+exports.helperSaveProblems = helperSaveProblems;
 exports.hfModelUrl = require_sleep.hfModelUrl;
 exports.historyFieldsFor = historyFieldsFor;
 exports.historyItemFieldPath = require_sleep.historyItemFieldPath;
@@ -117329,6 +118020,7 @@ exports.runtimeDevices = runtimeDevices;
 exports.runtimeFieldUnit = runtimeFieldUnit;
 exports.runtimeStatePolicyFor = runtimeStatePolicyFor;
 exports.sameDoFamily = sameDoFamily;
+exports.sameHelperBody = sameHelperBody;
 exports.sameRead = sameRead;
 exports.sceneMonitorCapability = sceneMonitorCapability;
 exports.scheduleForSendTimes = scheduleForSendTimes;
@@ -117378,6 +118070,7 @@ exports.sliceChangedAt = require_composition.sliceChangedAt;
 exports.smokeCapability = smokeCapability;
 exports.smtpProviderCapability = smtpProviderCapability;
 exports.snapshotCapability = snapshotCapability;
+exports.sourcePickForTemplate = sourcePickForTemplate;
 exports.splitTranslationRef = splitTranslationRef;
 exports.squareAround = squareAround;
 exports.ssoBridgeCapability = ssoBridgeCapability;
@@ -117440,6 +118133,7 @@ exports.taskPhaseSchema = taskPhaseSchema;
 exports.taskTargetSchema = taskTargetSchema;
 exports.temperatureSensorCapability = temperatureSensorCapability;
 exports.templateCarriesSummary = templateCarriesSummary;
+exports.templateDeviceType = templateDeviceType;
 exports.templateVarDeliveryApplies = templateVarDeliveryApplies;
 exports.templateVarKindApplies = templateVarKindApplies;
 exports.templateVarSystemEventApplies = templateVarSystemEventApplies;