@camstack/system 1.2.485 → 1.2.487

package/dist/builtins/composer/composer.addon.js

@@ -3,22 +3,22 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 require("../../chunk-Cek0wNdY.js");
-const require_dist = require("../../dist-xCNJAQMh.js");
-const require_composition_sources = require("../../composition-sources-BSQneZV9.js");
-const require_retention = require("../../retention-DNDOPW7Z.js");
+const require_dist = require("../../dist-CrsVjBbk.js");
+const require_composition_sources = require("../../composition-sources-BulDAgW2.js");
+const require_retention = require("../../retention-DgA4qLBj.js");
 let zod = require("zod");
 //#region src/builtins/shared/device-state-changed.ts
 /** Structural narrowing helper for untrusted bus payloads. */
-function isRecord$2(value) {
+function isRecord$3(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function parseDeviceStateChanged(data) {
-	if (!isRecord$2(data)) return null;
+	if (!isRecord$3(data)) return null;
 	const deviceId = data["deviceId"];
 	const capName = data["capName"];
 	const slice = data["slice"];
 	if (typeof deviceId !== "number" || typeof capName !== "string") return null;
-	if (!isRecord$2(slice)) return null;
+	if (!isRecord$3(slice)) return null;
 	return {
 		deviceId,
 		capName,
@@ -26,15 +26,51 @@ function parseDeviceStateChanged(data) {
 	};
 }
 //#endregion
+//#region src/builtins/composer/actuator-invoke.ts
+/**
+* Turn one fan-out call into the member's existing cap method. A bad argument
+* fails that member only — the caller still attempts the rest.
+*/
+async function invokeActuatorCall(api, call) {
+	if (call.cap === "switch" && call.method === "setState") {
+		const on = call.args.on;
+		if (typeof on !== "boolean") throw new Error("switch.setState needs a boolean on");
+		await api.switchSetState(call.deviceId, on);
+		return;
+	}
+	if (call.cap === "brightness" && call.method === "setBrightness") {
+		const percentage = call.args.percentage;
+		if (typeof percentage !== "number" || !Number.isFinite(percentage)) throw new Error("brightness.setBrightness needs a finite percentage");
+		await api.setBrightness(call.deviceId, percentage);
+		return;
+	}
+	if (call.cap === "color" && call.method === "setColor") {
+		const color = require_dist.parseColorInput(call.args.color);
+		if (color === null) throw new Error("color.setColor needs a colour mode");
+		await api.setColor(call.deviceId, color);
+		return;
+	}
+	throw new Error(`no fan-out for ${call.cap}.${call.method}`);
+}
+//#endregion
+//#region src/builtins/composer/actuator-dispatch.ts
+var dispatcher = null;
+function setActuatorDispatcher(next) {
+	dispatcher = next;
+}
+function actuatorDispatcher() {
+	return dispatcher;
+}
+//#endregion
 //#region src/builtins/composer/composed-device.ts
 /**
 * A composed device: an ordinary `BaseDevice` whose caps are served by the
 * composer (D659). Every consumer (exporters, NC, UI, HomeKit) reads it
 * through its bindings, unchanged.
 *
-* It serves NO command method: slice 1 refuses any cap with one
-* (`has-commands`), and commands arrive with `forward` in slice 3. So each
-* composed cap is registered with an EMPTY native provider, and `getStatus`
+* A reading group serves no command. An actuator helper's `switch` (and, on
+* a light, `brightness` / `color` when every member binds them) fans the
+* call out through `actuatorDispatcher` (D944). `getStatus`
 * (R4) is the kernel's: `registerNativeCap` installs a default that reads the
 * device's runtime slice for any cap declaring both `status` and
 * `runtimeState` (`device-cap-proxy.ts`, "Default `getStatus`"), on the
@@ -50,13 +86,112 @@ function parseDeviceStateChanged(data) {
 * declaration is the authority for what this device is.
 */
 var COMPOSED_DEVICE_CONFIG_SCHEMA = zod.z.object({});
+function priorResults(slice) {
+	if (!isRecord$2(slice) || !Array.isArray(slice.results)) return [];
+	return slice.results.flatMap((row) => {
+		const parsed = require_dist.GroupCommandResultSchema.safeParse(row);
+		return parsed.success ? [parsed.data] : [];
+	});
+}
+function isRecord$2(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Unknown is a throw, never `false` (D393). */
+function sliceBoolean(slice, field) {
+	if (isRecord$2(slice)) {
+		const value = slice[field];
+		if (typeof value === "boolean") return value;
+	}
+	throw new Error(`composed ${field} is unknown — not a stand-in value`);
+}
 var ComposedDevice = class extends require_dist.BaseDevice {
-	features = [];
+	sharedFeatures = [];
+	extraCaps = /* @__PURE__ */ new Set();
+	get features() {
+		return this.sharedFeatures;
+	}
 	constructor(ctx, type, caps) {
 		super(ctx, COMPOSED_DEVICE_CONFIG_SCHEMA, { type });
-		for (const cap of caps) ctx.registerNativeCap(cap, {});
+		for (const cap of caps) {
+			if (cap.name === require_dist.motionCapability.name) {
+				const read = () => this.runtimeState.getCapState(require_dist.motionCapability.name);
+				ctx.registerNativeCap(require_dist.motionCapability, { isDetected: async () => sliceBoolean(read(), "detected") });
+				continue;
+			}
+			if (cap.name === require_dist.switchCapability.name) {
+				ctx.registerNativeCap(require_dist.switchCapability, { setState: async (input) => {
+					await this.dispatch("switch", "setState", { on: input.on });
+				} });
+				continue;
+			}
+			ctx.registerNativeCap(cap, {});
+		}
+		if (type === require_dist.DeviceType.Switch || type === require_dist.DeviceType.Light) ctx.registerNativeCap(require_dist.groupCommandsCapability, {});
 		this.markOnline(false);
 	}
+	/**
+	* Register or drop brightness and colour, and publish the shared colour
+	* modes. Switch stays: it is the active state, registered with the device.
+	*/
+	syncShared(caps, modes) {
+		this.ensureExtra(require_dist.brightnessCapability.name, caps.includes(require_dist.brightnessCapability.name), () => {
+			this.ctx.registerNativeCap(require_dist.brightnessCapability, { setBrightness: async (input) => {
+				await this.dispatch("brightness", "setBrightness", { percentage: input.percentage });
+			} });
+		});
+		this.ensureExtra(require_dist.colorCapability.name, caps.includes(require_dist.colorCapability.name), () => {
+			this.ctx.registerNativeCap(require_dist.colorCapability, { setColor: async (input) => {
+				await this.dispatch("color", "setColor", { color: input.color });
+			} });
+		});
+		this.sharedFeatures = [...modes];
+		this.refreshFeatures();
+	}
+	/** Keep each member's latest attempt. A later command replaces that member only. */
+	recordCommands(incoming) {
+		const prior = priorResults(this.runtimeState.getCapState(require_dist.groupCommandsCapability.name));
+		const byDevice = new Map(prior.map((row) => [row.deviceId, row]));
+		for (const row of incoming) byDevice.set(row.deviceId, row);
+		try {
+			this.runtimeState.setCapState(require_dist.groupCommandsCapability.name, { results: [...byDevice.values()] });
+		} catch (err) {
+			this.ctx.logger.error("actuator group could not store command results", {
+				tags: { deviceId: this.id },
+				meta: { error: require_dist.errMsg(err) }
+			});
+		}
+	}
+	ensureExtra(capName, want, register) {
+		const has = this.extraCaps.has(capName);
+		if (want && !has) {
+			register();
+			this.extraCaps = new Set([...this.extraCaps, capName]);
+			return;
+		}
+		if (!want && has) {
+			this.ctx.unregisterNativeCap?.(capName);
+			this.extraCaps = new Set([...this.extraCaps].filter((name) => name !== capName));
+		}
+	}
+	async dispatch(cap, method, args) {
+		const run = actuatorDispatcher();
+		if (run === null) {
+			this.ctx.logger.warn("actuator group command was not sent — fan-out is not attached", {
+				tags: { deviceId: this.id },
+				meta: {
+					cap,
+					method
+				}
+			});
+			throw new Error("actuator fan-out is not attached");
+		}
+		await run({
+			groupDeviceId: this.id,
+			cap,
+			method,
+			args
+		});
+	}
 	seed(capName, slice) {
 		try {
 			this.runtimeState.setCapState(capName, { ...slice });
@@ -226,6 +361,223 @@ var ClaimGate = class {
 	}
 };
 //#endregion
+//#region src/builtins/composer/actuator-groups.ts
+/**
+* Live actuator helpers (D944). State is the aggregate the composer already
+* runs. Commands are fanned out here: every member that binds the cap,
+* including one that is offline, and a failure on one does not cancel the rest.
+* A light's brightness and colour are registered only while every member binds
+* them, and recomputed when a member's bindings change.
+*/
+function isActuatorGroupDevice(device) {
+	return "syncShared" in device && "recordCommands" in device && "id" in device;
+}
+var ActuatorGroups = class {
+	deps;
+	groups = /* @__PURE__ */ new Map();
+	bound;
+	constructor(deps) {
+		this.deps = deps;
+		this.bound = (input) => this.command(input);
+		setActuatorDispatcher(this.bound);
+	}
+	shutdown() {
+		setActuatorDispatcher(null);
+	}
+	async sync(blocks) {
+		const next = /* @__PURE__ */ new Map();
+		for (const block of blocks) {
+			const remembered = await this.remember(block);
+			if (remembered !== null) next.set(block.id, remembered);
+		}
+		this.groups = next;
+	}
+	async onMemberBindings(deviceId) {
+		const hit = [...this.groups.values()].filter((group) => group.fanOut.some((member) => member.deviceId === deviceId));
+		if (hit.length === 0) return;
+		const next = new Map(this.groups);
+		for (const group of hit) {
+			const block = {
+				id: group.blockId,
+				helper: {
+					kind: "group",
+					templateId: group.templateId,
+					aggregate: "any",
+					active: "at-least-one",
+					members: group.members.map(copyMember)
+				}
+			};
+			const remembered = await this.remember(block);
+			if (remembered !== null) next.set(group.blockId, remembered);
+		}
+		this.groups = next;
+	}
+	async remember(block) {
+		const spec = block.helper;
+		if (spec === void 0) return null;
+		const template = require_dist.groupTemplate(spec.templateId);
+		if (template === null || template.family !== "actuator") return null;
+		if (template.id !== "switch" && template.id !== "light") return null;
+		const device = this.deps.deviceOf(block.id);
+		if (device === null) return null;
+		const viewed = await this.viewMembers(spec.members, device.id);
+		const shared = sharedOf(template.id, viewed);
+		const previous = this.groups.get(block.id)?.shared;
+		if (template.id === "light" && previous !== void 0) this.logCapChange(device.id, previous, shared, viewed);
+		const modes = template.id === "light" && shared.includes("color") ? require_dist.sharedColorModes(viewed.featureLists) : [];
+		device.syncShared(shared, modes);
+		return {
+			blockId: block.id,
+			templateId: template.id,
+			groupDeviceId: device.id,
+			members: spec.members.map(copyMember),
+			fanOut: viewed.fanOut,
+			shared
+		};
+	}
+	async viewMembers(members, groupDeviceId) {
+		const fanOut = [];
+		const capLists = [];
+		const featureLists = [];
+		let complete = true;
+		for (const member of members) {
+			const resolved = this.deps.resolve(member.source);
+			if (resolved.kind !== "found") {
+				complete = false;
+				this.deps.logger.warn("actuator group left a member out of shared commands — its device was not resolved", {
+					tags: { deviceId: groupDeviceId },
+					meta: { source: `${member.source.addonId}/${member.source.stableId}` }
+				});
+				continue;
+			}
+			const read = await this.deps.readMember(resolved.deviceId);
+			if (read.kind !== "ready") {
+				complete = false;
+				fanOut.push({
+					deviceId: resolved.deviceId,
+					caps: [],
+					online: true
+				});
+				this.deps.logger.warn("actuator group left a member out of shared commands — its capabilities could not be read", {
+					tags: { deviceId: resolved.deviceId },
+					meta: {
+						groupDeviceId,
+						error: read.error
+					}
+				});
+				continue;
+			}
+			capLists.push(read.caps);
+			featureLists.push(read.features);
+			fanOut.push({
+				deviceId: resolved.deviceId,
+				caps: read.caps,
+				online: true
+			});
+		}
+		return {
+			fanOut,
+			capLists: complete ? capLists : null,
+			featureLists
+		};
+	}
+	logCapChange(groupDeviceId, previous, shared, viewed) {
+		for (const cap of ["brightness", "color"]) {
+			const had = previous.includes(cap);
+			const has = shared.includes(cap);
+			if (had === has) continue;
+			if (has) {
+				this.deps.logger.info("light group gained a shared capability", {
+					tags: { deviceId: groupDeviceId },
+					meta: { cap }
+				});
+				continue;
+			}
+			this.deps.logger.warn("light group dropped a capability a member does not bind", {
+				tags: { deviceId: groupDeviceId },
+				meta: { cap }
+			});
+			for (const member of viewed.fanOut) {
+				if (member.caps.includes(cap)) continue;
+				this.deps.logger.warn("light group dropped a capability this member does not bind", {
+					tags: { deviceId: member.deviceId },
+					meta: {
+						groupDeviceId,
+						cap
+					}
+				});
+			}
+		}
+	}
+	async command(input) {
+		const group = [...this.groups.values()].find((item) => item.groupDeviceId === input.groupDeviceId);
+		if (group === void 0) {
+			this.deps.logger.warn("actuator command dropped — this device is not a live helper group", {
+				tags: { deviceId: input.groupDeviceId },
+				meta: {
+					cap: input.cap,
+					method: input.method
+				}
+			});
+			throw new Error("actuator group is not live");
+		}
+		if (!group.shared.includes(input.cap)) {
+			this.deps.logger.warn("actuator command dropped — the group does not share that capability", {
+				tags: { deviceId: input.groupDeviceId },
+				meta: {
+					cap: input.cap,
+					method: input.method
+				}
+			});
+			throw new Error(`group does not share ${input.cap}`);
+		}
+		const results = await require_dist.runFanOut(require_dist.fanOutTargets(group.fanOut, input.cap, input.method, input.args), (call) => this.deps.invoke(call));
+		const failed = results.flatMap((result) => result.ok ? [] : [result]);
+		for (const result of failed) this.deps.logger.warn("actuator group command failed on a member — the others were still attempted", {
+			tags: { deviceId: result.deviceId },
+			meta: {
+				groupDeviceId: input.groupDeviceId,
+				cap: input.cap,
+				method: input.method,
+				error: result.error
+			}
+		});
+		if (failed.length > 0) this.deps.logger.warn("actuator group command finished with member failures", {
+			tags: { deviceId: input.groupDeviceId },
+			meta: {
+				failed: failed.length,
+				attempted: results.length,
+				cap: input.cap
+			}
+		});
+		const at = this.deps.now();
+		this.deps.deviceOf(group.blockId)?.recordCommands(results.map((result) => ({
+			deviceId: result.deviceId,
+			cap: input.cap,
+			method: input.method,
+			ok: result.ok,
+			...result.ok ? {} : { error: result.error },
+			at
+		})));
+	}
+};
+function sharedOf(templateId, viewed) {
+	if (templateId === "switch") return ["switch"];
+	if (viewed.capLists === null) return ["switch"];
+	const shared = require_dist.sharedLightCaps(viewed.capLists);
+	return shared.includes("switch") ? shared : ["switch", ...shared];
+}
+function copyMember(member) {
+	return {
+		source: {
+			addonId: member.source.addonId,
+			stableId: member.source.stableId
+		},
+		cap: member.cap,
+		fieldPath: member.fieldPath
+	};
+}
+//#endregion
 //#region src/builtins/composer/composed-device-set.ts
 /**
 * The composed devices the composer DECLARED (D659): one row per `new`-target
@@ -1295,7 +1647,9 @@ function writable(record) {
 	switch (record.plan.unavailable) {
 		case "null": return null;
 		case "unknown": return "unknown";
-		default: return;
+		case "omit":
+		case "offline":
+		case "release": return;
 	}
 }
 function errorText(error) {
@@ -2018,7 +2372,16 @@ var CompositionRuntime = class {
 		this.seeded = new Set([...this.seeded, cap]);
 		this.markWritten(cap, entries);
 	}
+	/** An omitted optional reading must leave the slice, not keep the previous number (D944). */
+	clearsOmitted(cap) {
+		return this.recordsOf(cap).some((record) => record.plan.unavailable === "omit" && record.outcome?.state === "unavailable");
+	}
 	patchCap(cap, touched) {
+		if (this.clearsOmitted(cap)) {
+			const entries = this.entriesFor(cap, this.recordsOf(cap));
+			if (this.write(cap, "seed", entries)) this.markWritten(cap, entries);
+			return;
+		}
 		const entries = this.entriesFor(cap, this.recordsOf(cap).filter((r) => touched.has(fieldKey(r.plan)) && (!r.hasWritten || writable(r) !== r.written)));
 		if (entries.length === 0) return;
 		if (this.write(cap, "patch", entries)) this.markWritten(cap, entries);
@@ -3246,6 +3609,7 @@ var Composer = class {
 	claimGate;
 	targets;
 	grafts;
+	actuators;
 	/** The rows the composer owns, read ONCE before its first withdrawal decision. */
 	rowSeed;
 	/**
@@ -3277,6 +3641,7 @@ var Composer = class {
 			this.grafts.describing(deviceId);
 			return deps.describeTarget(deviceId);
 		});
+		this.actuators = this.attachActuators(deps);
 		this.waits = new ApplyWaits(deps.logger);
 		this.rowSeed = composedRowSeed({
 			logger: deps.logger,
@@ -3328,9 +3693,33 @@ var Composer = class {
 		this.targets.invalidate(data.deviceId);
 		this.grafts.onBindingsChanged(data);
 		this.dispatch(await this.deps.tracker.onBindingsChanged(data.deviceId, data.capName, data.reason));
+		await this.chained(() => this.actuators?.onMemberBindings(data.deviceId));
 	}
 	shutdown() {
 		for (const entry of this.live.values()) entry.runtime?.stop();
+		this.actuators?.shutdown();
+	}
+	attachActuators(deps) {
+		const read = deps.readActuatorMember;
+		const invoke = deps.invokeActuator;
+		if (read === void 0 || invoke === void 0) return null;
+		return new ActuatorGroups({
+			logger: deps.logger.child("actuators"),
+			now: deps.now,
+			resolve: (ref) => {
+				const found = deps.tracker.resolution(ref);
+				return found.kind === "found" ? {
+					kind: "found",
+					deviceId: found.deviceId
+				} : { kind: "other" };
+			},
+			readMember: read,
+			deviceOf: (blockId) => {
+				const device = this.composed.get(require_dist.composedDeviceStableId(blockId));
+				return device !== null && isActuatorGroupDevice(device) ? device : null;
+			},
+			invoke
+		});
 	}
 	/** Run `work` after every apply already queued, whether that settled or failed. */
 	chained(work) {
@@ -3364,6 +3753,10 @@ var Composer = class {
 		await Promise.all(rebuilt.stopped.map((runtime) => runtime.quiesce()));
 		const unreleasedClaims = await this.releaseConfirmed(releasing);
 		await this.syncSources(rebuilt);
+		await this.actuators?.sync(input.blocks.map((block) => ({
+			id: block.id,
+			helper: block.composition.helper
+		})));
 		await this.reconcileClaims();
 		return {
 			blocks: planned.map((p) => this.verdict(p.block.id)),
@@ -3746,8 +4139,21 @@ var NodeDeadlineTimer = class {
 function unanswered(def) {
 	return Object.entries(def.methods).filter(([name, m]) => m.systemOnly !== true && def.composedMethods?.[name] === void 0).map(([name]) => name);
 }
-function composedMethod(answer) {
+function isSliceRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** A slice field that is present. Unknown throws — it is not false or 0 (D393). */
+function sliceField(slice, field) {
+	const value = slice?.[field];
+	if (typeof value === "boolean" || typeof value === "number" || typeof value === "string") return value;
+	throw new Error(`composed ${field} is unknown — not a stand-in value`);
+}
+function composedMethod(answer, readSlice) {
 	if (answer.kind === "answer") return async () => answer.value;
+	if (answer.kind === "slice") {
+		const field = answer.field;
+		return async () => sliceField(await readSlice(), field);
+	}
 	return async () => {
 		throw new Error(answer.reason);
 	};
@@ -3865,7 +4271,11 @@ var GraftHost = class {
 		return ctx;
 	}
 	providerFor(deviceId, def) {
-		const answers = Object.entries(def.composedMethods ?? {}).map(([name, answer]) => [name, composedMethod(answer)]);
+		const readSlice = async () => {
+			const slice = await this.readMerged(deviceId, def.name);
+			return isSliceRecord(slice) ? slice : null;
+		};
+		const answers = Object.entries(def.composedMethods ?? {}).map(([name, answer]) => [name, composedMethod(answer, readSlice)]);
 		const withStatus = def.status === void 0 && def.runtimeState === void 0 ? [] : [["getStatus", async () => this.readMerged(deviceId, def.name)]];
 		return Object.fromEntries([...answers, ...withStatus]);
 	}
@@ -3942,7 +4352,7 @@ function entriesOf(request) {
 	}))];
 }
 function valueAtPath(slice, path) {
-	return path.split(".").reduce((node, segment) => isRecord$2(node) ? node[segment] : void 0, slice);
+	return path.split(".").reduce((node, segment) => isRecord$3(node) ? node[segment] : void 0, slice);
 }
 function onlineOf(slice) {
 	const online = slice["online"];
@@ -4609,12 +5019,12 @@ var DECLARED_INTEGRATION_NAME_UNUSED = "Blocks";
 var PULSE_HISTORY_MAX_POINTS = 5e3;
 /** The owner-only shadow payload is not in the typed catalog: narrowed at the boundary, like `device.state-changed`. */
 function parseNativeShadowChanged(data) {
-	if (!isRecord$2(data)) return null;
+	if (!isRecord$3(data)) return null;
 	const deviceId = data["deviceId"];
 	const capName = data["capName"];
 	const native = data["native"];
 	if (typeof deviceId !== "number" || typeof capName !== "string") return null;
-	if (!isRecord$2(native)) return null;
+	if (!isRecord$3(native)) return null;
 	return {
 		deviceId,
 		capName,
@@ -4778,7 +5188,43 @@ var ComposerAddon = class extends require_dist.BaseAddon {
 			describeTarget: readBoundCaps,
 			grafts,
 			now: () => Date.now(),
-			newTimer: () => new NodeDeadlineTimer(() => Date.now())
+			newTimer: () => new NodeDeadlineTimer(() => Date.now()),
+			readActuatorMember: async (deviceId) => {
+				try {
+					const bindings = await api.deviceManager.getBindings.query({ deviceId });
+					const found = await api.deviceManager.getDevice.query({ deviceId });
+					return {
+						kind: "ready",
+						caps: bindings.entries.map((entry) => entry.capName),
+						features: found === null ? [] : [...found.features]
+					};
+				} catch (err) {
+					return {
+						kind: "unreadable",
+						error: require_dist.errMsg(err)
+					};
+				}
+			},
+			invokeActuator: (call) => invokeActuatorCall({
+				switchSetState: async (deviceId, on) => {
+					await api.switch.setState.mutate({
+						deviceId,
+						on
+					});
+				},
+				setBrightness: async (deviceId, percentage) => {
+					await api.brightness.setBrightness.mutate({
+						deviceId,
+						percentage
+					});
+				},
+				setColor: async (deviceId, color) => {
+					await api.color.setColor.mutate({
+						deviceId,
+						color
+					});
+				}
+			}, call)
 		});
 		this.subscribe({ category: require_dist.EventCategory.DeviceStateChanged }, (event) => {
 			const data = parseDeviceStateChanged(event.data);