@camstack/system 1.2.308 → 1.2.309

package/dist/builtins/composer/composer.addon.mjs

@@ -0,0 +1,1677 @@
+import { $ as compositionSliceKey, K as buildCapabilityLookup, Ln as DeviceType, Q as composerCapability, Sn as toExpressionValue, Z as composedDeviceStableId, c as COMPOSER_ADDON_ID, et as compositionSourceKey, g as DeclaredDevices, i as BaseDevice, ir as EventCategory, jn as BaseAddon, kn as errMsg, t as ALL_CAPABILITY_DEFINITIONS, tn as planComposition, xt as evaluateCompositionField } from "../../dist-BEuQPDk_.mjs";
+import { n as parseDeviceStateChanged, t as isRecord } from "../../device-state-changed-DoBbkyEI.mjs";
+import { z } from "zod";
+//#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`
+* (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
+* registry path and the forked-runner (UDS) path alike. Every composable cap
+* qualifies: the validator refuses a cap with no `runtimeState`
+* (`validate-composition.ts`, `not-composable`). The default is correct only
+* because, for every composable cap, `status.schema` and `runtimeState` have
+* one shape — `composed-device.spec.ts` enumerates the real cap registry and
+* fails the day one breaks it (slice 3 lifting `has-commands` makes
+* `recording-signal` such a cap). `room-device.e2e.spec.ts` proves R4 through
+* the real registry. Its type comes from the declaration, not from
+* `deviceMeta`: a failed meta read builds a device as `generic`, and the
+* declaration is the authority for what this device is.
+*/
+var COMPOSED_DEVICE_CONFIG_SCHEMA = z.object({});
+var ComposedDevice = class extends BaseDevice {
+	features = [];
+	constructor(ctx, type, caps) {
+		super(ctx, COMPOSED_DEVICE_CONFIG_SCHEMA, { type });
+		for (const cap of caps) ctx.registerNativeCap(cap, {});
+		this.markOnline(false);
+	}
+	seed(capName, slice) {
+		try {
+			this.runtimeState.setCapState(capName, { ...slice });
+			return { ok: true };
+		} catch (err) {
+			return {
+				ok: false,
+				error: errMsg(err)
+			};
+		}
+	}
+	patch(capName, patch) {
+		try {
+			this.runtimeState.patchCapState(capName, { ...patch });
+			return { ok: true };
+		} catch (err) {
+			return {
+				ok: false,
+				error: errMsg(err)
+			};
+		}
+	}
+	setAvailable(available) {
+		this.markOnline(available);
+	}
+};
+function composedDeviceClass(type, caps) {
+	return class extends ComposedDevice {
+		constructor(ctx) {
+			super(ctx, type, caps);
+		}
+	};
+}
+/**
+* A composed device kept alive by the withdrawal gate for a persisted row whose
+* block this process has not planned (yet): no caps, offline. Its type is the
+* ROW's (`deviceMeta.type`) — only ever adopted from an existing row, where the
+* row is canonical — because there is no plan to take one from.
+*/
+var ComposedPlaceholderDevice = class extends ComposedDevice {
+	constructor(ctx) {
+		super(ctx, ctx.deviceMeta.type, []);
+	}
+};
+function isComposedDevice(device) {
+	return device instanceof ComposedDevice;
+}
+//#endregion
+//#region src/builtins/composer/composition-declarations.ts
+/**
+* Which composed devices exist (D659): one declaration per composition block,
+* owned by `composer` and hung off the shared Blocks integration.
+*
+* `DeclaredDevices` sweeps any row whose declaration is absent. A block missing
+* from ONE apply (a transient store read, a race) would delete the device, and
+* with it its id, exports and rules. The `WithdrawalGate` is D49 for that path:
+* a withdrawal needs a second consecutive apply to agree. The other half of the
+* rule — nothing is declared or withdrawn while the `core_blocks` store has not
+* loaded — is `Composer.apply`'s, which never reaches this gate then (R2).
+*/
+function declarationFor(input) {
+	return {
+		stableId: composedDeviceStableId(input.blockId),
+		name: input.name,
+		type: input.target.type,
+		DeviceClass: composedDeviceClass(input.target.type, input.caps),
+		...input.target.role === void 0 ? {} : { role: input.target.role }
+	};
+}
+/** What forces a rebuild of the live device: type, role, cap set. Never the name. */
+function shapeOf(input) {
+	return JSON.stringify([
+		input.target.type,
+		input.target.role ?? null,
+		input.caps.map((c) => c.name).toSorted()
+	]);
+}
+/**
+* The declaration that holds a persisted composed row whose block has no plan
+* in this apply. `name` and `type` are used only if the row has to be CREATED,
+* which `DeclaredDevices` does not do for a row it finds: it adopts it, and the
+* row's own name and type stay canonical (`ComposedPlaceholderDevice`).
+*/
+function placeholderDeclaration(stableId) {
+	return {
+		stableId,
+		name: stableId,
+		type: DeviceType.Generic,
+		DeviceClass: ComposedPlaceholderDevice
+	};
+}
+var WITHDRAWAL_CONFIRMATIONS = 2;
+var WithdrawalGate = class {
+	logger;
+	deviceIdOf;
+	known = /* @__PURE__ */ new Map();
+	misses = /* @__PURE__ */ new Map();
+	persistedIds = /* @__PURE__ */ new Map();
+	constructor(logger, deviceIdOf) {
+		this.logger = logger;
+		this.deviceIdOf = deviceIdOf;
+	}
+	/**
+	* The rows that exist before this process applied anything. Called once at
+	* boot, before the first `filter`: without it the mirror starts empty and a
+	* row missing from the first apply after a restart (a release, a block that
+	* no longer plans) is swept at once — one apply, not two. A seeded row
+	* missing from that apply counts as its FIRST miss and is held by
+	* `placeholderDeclaration`. A row the gate already knows keeps its entry and
+	* its miss count.
+	*/
+	seed(rows) {
+		const fresh = rows.filter((row) => !this.known.has(row.stableId));
+		this.known = new Map([...this.known, ...fresh.map((row) => [row.stableId, placeholderDeclaration(row.stableId)])]);
+		this.persistedIds = new Map([...this.persistedIds, ...rows.map((row) => [row.stableId, row.id])]);
+	}
+	filter(current) {
+		const present = new Map(current.map((d) => [d.stableId, d]));
+		const kept = [];
+		const misses = /* @__PURE__ */ new Map();
+		for (const [stableId, declaration] of this.known) {
+			if (present.has(stableId)) continue;
+			const count = (this.misses.get(stableId) ?? 0) + 1;
+			if (count < WITHDRAWAL_CONFIRMATIONS) {
+				this.logger.warn("a composition vanished from one apply — its device is kept until a second apply agrees", {
+					tags: this.tagsOf(stableId),
+					meta: {
+						stableId,
+						misses: count
+					}
+				});
+				kept.push(declaration);
+				misses.set(stableId, count);
+				continue;
+			}
+			this.logger.info("a composition is gone on two consecutive applies — its device is withdrawn", {
+				tags: this.tagsOf(stableId),
+				meta: { stableId }
+			});
+		}
+		this.known = new Map([...kept.map((d) => [d.stableId, d]), ...present]);
+		this.misses = misses;
+		return [...current, ...kept];
+	}
+	/**
+	* The live device's id, else the persisted row's. A declaration whose device
+	* was never built and never persisted has no numeric id to carry: the
+	* stableId in `meta` is then all there is.
+	*/
+	tagsOf(stableId) {
+		const deviceId = this.deviceIdOf(stableId) ?? this.persistedIds.get(stableId) ?? null;
+		return deviceId === null ? {} : { deviceId };
+	}
+};
+//#endregion
+//#region src/builtins/composer/composition-runtime.ts
+/**
+* One running composition: per-field state, writes to the composed device, and
+* one deadline timer (D659).
+*
+* - Only the fields a change affects are recomputed.
+* - A cap is SEEDED once (`setCapState`, every required field present), then
+*   PATCHED (`patchCapState` merges; the runtime-state twin of "`setAll`
+*   already merges").
+* - Unavailable is per field. A nullable field is written `null`; a
+*   non-nullable one is not written and the device goes offline (D393).
+* - A `clock` field (`now` only) is recomputed when a sibling of its cap
+*   changes value, so `binary.lastChangedAt` is the last transition. A
+*   `constant` is computed once.
+* - A windowed expression reports when it flips; ONE timer at the earliest
+*   such instant. It waits for no source (D3). Every evaluation is STORED, so
+*   a deadline that moved reaches the timer even when the value did not: an
+*   unstored deadline fires early, re-evaluates to "same", and re-arms
+*   `setTimeout(0)` until the real window closes — a poll (R1).
+* - A fatal (source gone) outcome is the block's failure, and it is sticky:
+*   the device stays offline until a new runtime, created on an operator edit
+*   or restart, clears it.
+* - A write the target REFUSES or THROWS on leaves the evaluated outcomes
+*   alone and marks its cap write-pending: the next pass that evaluates any
+*   field of that cap, and every deadline pass, re-writes the WHOLE current
+*   slice (a seed if it was never seeded). No retry timer — the next source
+*   event or deadline is the retry (D3). One log line per failure transition.
+* - Nothing escapes: a pass that throws is logged, and the timer is re-armed
+*   from the stored deadlines regardless.
+* - `stop()` is terminal: every entry point is a no-op afterwards.
+*/
+function errorText(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+function pendingReason(cap, pending) {
+	return pending.kind === "refused" ? `the \`${cap}\` capability refused the value: ${pending.error}` : `writing the \`${cap}\` capability threw: ${pending.error}`;
+}
+function fieldKey(plan) {
+	return `${plan.cap}.${plan.path}`;
+}
+function valueOf(outcome) {
+	return outcome === null || outcome.state === "unavailable" ? void 0 : outcome.value;
+}
+function reasonOf(outcome) {
+	if (outcome === null) return "not evaluated yet";
+	return outcome.reason;
+}
+/** State, value and reason — what a write or a log line is about. NEVER the deadline (R1). */
+function sameOutcome(a, b) {
+	return a !== null && a.state === b.state && valueOf(a) === valueOf(b) && reasonOf(a) === reasonOf(b);
+}
+/** A source is GONE: the outcome that must never be masked by a non-fatal one. */
+function isFatal(outcome) {
+	return outcome !== null && outcome.state === "unavailable" && outcome.fatal;
+}
+function writable(record) {
+	const outcome = record.outcome;
+	if (outcome === null) return void 0;
+	if (outcome.state !== "unavailable") return outcome.value;
+	return record.plan.unavailable === "null" ? null : void 0;
+}
+var CompositionRuntime = class {
+	deps;
+	records;
+	seeded = /* @__PURE__ */ new Set();
+	available = null;
+	failure = null;
+	disabledReason = null;
+	stopped = false;
+	/** The last `pass threw` logged (`during: message`); cleared by a pass that completes. */
+	lastPassError = null;
+	pending = /* @__PURE__ */ new Map();
+	heldBack = /* @__PURE__ */ new Set();
+	constructor(deps) {
+		this.deps = deps;
+		this.records = new Map(deps.fields.map((plan) => [fieldKey(plan), {
+			plan,
+			outcome: null,
+			written: void 0
+		}]));
+	}
+	start() {
+		if (this.disabledReason !== null) return;
+		this.guarded("start", true, () => this.pass([...this.records.keys()], "start"));
+	}
+	onSourcesChanged(sliceKeys) {
+		if (this.disabledReason !== null) return;
+		this.guarded("source", true, () => {
+			const affected = [...this.records.values()].filter((r) => r.plan.reads.some((read) => sliceKeys.has(compositionSliceKey(read.source, read.cap)))).map((r) => fieldKey(r.plan));
+			if (affected.length > 0) this.pass(affected, "source");
+		});
+	}
+	disable(reason) {
+		if (this.stopped) return;
+		this.disabledReason = reason;
+		this.deps.timer.disarm();
+		this.guarded("disable", false, () => {
+			const outcome = {
+				state: "unavailable",
+				value: null,
+				reason,
+				fatal: false
+			};
+			const touched = [...this.records.values()].filter((r) => !isFatal(r.outcome) && !sameOutcome(r.outcome, outcome));
+			for (const r of touched) this.logTransition(r, outcome);
+			this.records = new Map([...this.records].map(([k, r]) => [k, isFatal(r.outcome) ? r : {
+				...r,
+				outcome
+			}]));
+			this.writeCaps(new Set(touched.map((r) => fieldKey(r.plan))), /* @__PURE__ */ new Set());
+			this.updateAvailability();
+		});
+	}
+	/** Terminal: no write, no evaluation and no timer after this. */
+	stop() {
+		this.stopped = true;
+		this.deps.timer.disarm();
+	}
+	state() {
+		return {
+			failure: this.failure,
+			available: this.available === true,
+			fields: [...this.records.values()].map((r) => {
+				const pending = this.pending.get(r.plan.cap);
+				if (pending !== void 0 && !isFatal(r.outcome)) return {
+					cap: r.plan.cap,
+					path: r.plan.path,
+					state: "unavailable",
+					value: null,
+					reason: pendingReason(r.plan.cap, pending)
+				};
+				const value = valueOf(r.outcome);
+				const reason = reasonOf(r.outcome);
+				return {
+					cap: r.plan.cap,
+					path: r.plan.path,
+					state: r.outcome?.state ?? "unavailable",
+					value: value === void 0 ? null : value,
+					...reason === null ? {} : { reason }
+				};
+			})
+		};
+	}
+	/**
+	* Every entry point runs here: a no-op once stopped, nothing thrown escapes,
+	* and the one timer is re-armed from the stored deadlines whatever happened.
+	*/
+	guarded(during, rearm, body) {
+		if (this.stopped) return;
+		let threw = false;
+		try {
+			body();
+			this.lastPassError = null;
+		} catch (error) {
+			threw = true;
+			this.logPassError(during, errorText(error));
+		} finally {
+			if (rearm && !this.stopped && this.disabledReason === null) this.armDeadline(threw ? this.deps.now() : null);
+		}
+	}
+	/** Once per distinct failure, not once per pass: a reader that keeps throwing logs one line. */
+	logPassError(during, error) {
+		const key = `${during}: ${error}`;
+		if (key === this.lastPassError) return;
+		this.lastPassError = key;
+		this.deps.logger.error("composition pass threw — the runtime keeps running; the next source event or deadline re-runs it", {
+			tags: { deviceId: this.deps.target.id },
+			meta: {
+				blockId: this.deps.blockId,
+				during,
+				error
+			}
+		});
+	}
+	pass(keys, trigger) {
+		const initial = trigger === "start";
+		const now = this.deps.now();
+		const derived = this.evaluate(keys.filter((k) => this.records.get(k)?.plan.role === "derived"), now);
+		const followers = [...this.records.values()].filter((r) => r.plan.role === "clock" ? initial || derived.valueCaps.has(r.plan.cap) : r.plan.role === "constant" && initial).map((r) => fieldKey(r.plan));
+		const extra = this.evaluate(followers, now);
+		const evaluatedCaps = new Set([...keys, ...followers].flatMap((k) => {
+			const cap = this.records.get(k)?.plan.cap;
+			return cap === void 0 ? [] : [cap];
+		}));
+		const retry = new Set([...this.pending.keys()].filter((cap) => trigger === "deadline" || evaluatedCaps.has(cap)));
+		this.writeCaps(new Set([...derived.keys, ...extra.keys]), retry);
+		this.updateFailure();
+		this.updateAvailability();
+	}
+	evaluate(keys, now) {
+		const changed = /* @__PURE__ */ new Set();
+		const valueCaps = /* @__PURE__ */ new Set();
+		const next = new Map(this.records);
+		try {
+			for (const key of keys) {
+				const record = next.get(key);
+				if (record === void 0) continue;
+				const outcome = evaluateCompositionField({
+					source: record.plan.source,
+					read: this.deps.read,
+					now
+				});
+				next.set(key, {
+					...record,
+					outcome
+				});
+				if (sameOutcome(record.outcome, outcome)) continue;
+				if (record.outcome?.state !== outcome.state) this.logTransition(record, outcome);
+				if (valueOf(record.outcome) !== valueOf(outcome)) valueCaps.add(record.plan.cap);
+				changed.add(key);
+			}
+		} finally {
+			this.records = next;
+		}
+		return {
+			keys: changed,
+			valueCaps
+		};
+	}
+	recordsOf(cap) {
+		return [...this.records.values()].filter((r) => r.plan.cap === cap);
+	}
+	/** `retry`: write-pending caps this pass re-writes WHOLE, whether or not a value changed. */
+	writeCaps(touched, retry) {
+		const caps = new Set([...[...touched].flatMap((k) => {
+			const cap = this.records.get(k)?.plan.cap;
+			return cap === void 0 ? [] : [cap];
+		}), ...retry]);
+		for (const cap of caps) if (!this.seeded.has(cap)) this.seedCap(cap);
+		else if (this.pending.has(cap)) this.patchWholeCap(cap);
+		else this.patchCap(cap, touched);
+	}
+	seedCap(cap) {
+		const records = this.recordsOf(cap);
+		const missing = records.filter((r) => r.plan.required && writable(r) === void 0).map((r) => r.plan.path);
+		if (missing.length > 0) return this.holdBackSeed(cap, missing);
+		this.heldBack = new Set([...this.heldBack].filter((c) => c !== cap));
+		const entries = this.writableEntries(records);
+		if (!this.write(cap, "seed", entries)) return;
+		this.seeded = new Set([...this.seeded, cap]);
+		this.markWritten(cap, entries);
+	}
+	patchCap(cap, touched) {
+		const entries = this.writableEntries(this.recordsOf(cap).filter((r) => touched.has(fieldKey(r.plan)) && writable(r) !== r.written));
+		if (entries.length === 0) return;
+		if (this.write(cap, "patch", entries)) this.markWritten(cap, entries);
+	}
+	/** After a failed write nothing is known about what landed: send every current value. */
+	patchWholeCap(cap) {
+		const entries = this.writableEntries(this.recordsOf(cap));
+		if (entries.length === 0) return;
+		if (this.write(cap, "patch", entries)) this.markWritten(cap, entries);
+	}
+	writableEntries(records) {
+		return records.flatMap((r) => {
+			const v = writable(r);
+			return v === void 0 ? [] : [[r.plan.path, v]];
+		});
+	}
+	holdBackSeed(cap, missing) {
+		if (this.heldBack.has(cap)) return;
+		this.heldBack = new Set([...this.heldBack, cap]);
+		this.deps.logger.warn("composed capability not seeded yet — a required field has no value", {
+			tags: { deviceId: this.deps.target.id },
+			meta: {
+				blockId: this.deps.blockId,
+				cap,
+				missing
+			}
+		});
+	}
+	/** One write. A refusal or a throw marks the cap write-pending; true when it landed. */
+	write(cap, op, entries) {
+		const values = Object.fromEntries(entries);
+		let failed;
+		try {
+			const outcome = op === "seed" ? this.deps.target.seed(cap, values) : this.deps.target.patch(cap, values);
+			failed = outcome.ok ? null : {
+				kind: "refused",
+				error: outcome.error
+			};
+		} catch (error) {
+			failed = {
+				kind: "threw",
+				error: errorText(error)
+			};
+		}
+		if (failed === null) {
+			this.clearPending(cap);
+			return true;
+		}
+		this.markPending(cap, op, failed);
+		return false;
+	}
+	clearPending(cap) {
+		if (!this.pending.has(cap)) return;
+		this.pending = new Map([...this.pending].filter(([c]) => c !== cap));
+		this.deps.logger.info("composed capability written again after a failed write", {
+			tags: { deviceId: this.deps.target.id },
+			meta: {
+				blockId: this.deps.blockId,
+				cap
+			}
+		});
+	}
+	markPending(cap, op, failed) {
+		const wasPending = this.pending.has(cap);
+		this.pending = new Map([...this.pending, [cap, failed]]);
+		if (wasPending) return;
+		const message = failed.kind === "refused" ? "composed capability refused a write — its whole slice is re-written on the next pass that evaluates it" : "composed capability write threw — its whole slice is re-written on the next pass that evaluates it";
+		this.deps.logger.warn(message, {
+			tags: { deviceId: this.deps.target.id },
+			meta: {
+				blockId: this.deps.blockId,
+				cap,
+				op,
+				error: failed.error
+			}
+		});
+	}
+	markWritten(cap, entries) {
+		const written = new Map(entries);
+		this.records = new Map([...this.records].map(([k, r]) => r.plan.cap === cap && written.has(r.plan.path) ? [k, {
+			...r,
+			written: written.get(r.plan.path)
+		}] : [k, r]));
+	}
+	updateAvailability() {
+		const blocking = [...this.records.values()].filter((r) => r.plan.unavailable === "offline" && r.outcome?.state === "unavailable").map((r) => fieldKey(r.plan));
+		const unseeded = [...new Set(this.deps.fields.map((f) => f.cap))].filter((c) => !this.seeded.has(c));
+		const writePending = [...this.pending.keys()];
+		const available = this.disabledReason === null && this.failure === null && blocking.length === 0 && unseeded.length === 0 && writePending.length === 0;
+		if (available === this.available) return;
+		this.deps.target.setAvailable(available);
+		this.available = available;
+		const extras = {
+			tags: { deviceId: this.deps.target.id },
+			meta: {
+				blockId: this.deps.blockId,
+				blocking,
+				unseeded,
+				writePending,
+				failure: this.failure,
+				disabled: this.disabledReason
+			}
+		};
+		if (available) this.deps.logger.info("composed device available", extras);
+		else this.deps.logger.warn("composed device unavailable — a field has no value, a write is pending, or the block failed", extras);
+	}
+	updateFailure() {
+		if (this.failure !== null) return;
+		const fatal = [...this.records.values()].find((r) => r.outcome?.state === "unavailable" && r.outcome.fatal);
+		if (fatal === void 0 || fatal.outcome === null || fatal.outcome.state !== "unavailable") return;
+		this.failure = `source missing — ${fatal.outcome.reason}`;
+		this.deps.logger.error("composition failed: a source is gone — only the operator ends this (repair the source, edit or delete the block)", {
+			tags: { deviceId: this.deps.target.id },
+			meta: {
+				blockId: this.deps.blockId,
+				field: fieldKey(fatal.plan),
+				reason: fatal.outcome.reason
+			}
+		});
+	}
+	/** `after`: arm only deadlines later than this instant; null arms the earliest stored one. */
+	armDeadline(after) {
+		const deadlines = [...this.records.values()].flatMap((r) => r.outcome !== null && r.outcome.state !== "unavailable" && r.outcome.deadline !== null && (after === null || r.outcome.deadline > after) ? [r.outcome.deadline] : []);
+		if (deadlines.length === 0) {
+			this.deps.timer.disarm();
+			return;
+		}
+		this.deps.timer.arm(Math.min(...deadlines), () => this.onDeadline());
+	}
+	onDeadline() {
+		this.guarded("deadline", true, () => {
+			const now = this.deps.now();
+			const due = [...this.records.values()].filter((r) => r.outcome !== null && r.outcome.state !== "unavailable" && r.outcome.deadline !== null && r.outcome.deadline <= now).map((r) => fieldKey(r.plan));
+			if (due.length > 0) this.pass(due, "deadline");
+		});
+	}
+	logTransition(record, outcome) {
+		const from = record.outcome?.state ?? "pending";
+		if (from === "pending" && outcome.state === "fresh") return;
+		const extras = {
+			tags: { deviceId: this.deps.target.id },
+			meta: {
+				blockId: this.deps.blockId,
+				cap: record.plan.cap,
+				field: record.plan.path,
+				from,
+				to: outcome.state,
+				reason: reasonOf(outcome)
+			}
+		};
+		const message = `composed field ${fieldKey(record.plan)}: ${from} → ${outcome.state}`;
+		if (outcome.state === "fresh") this.deps.logger.info(message, extras);
+		else this.deps.logger.warn(message, extras);
+	}
+};
+//#endregion
+//#region src/builtins/composer/composer.ts
+/**
+* The composer: every declarative composition on this hub, in one runner
+* (D659).
+*
+* `apply` is called by `core-blocks`' supervisor on its existing converge with
+* the WHOLE set of composition blocks. It is idempotent: a block whose
+* `updatedAt`, device and plan are unchanged keeps its runtime; the declared set
+* is reconciled only when it changed. Every verdict names its reason.
+*
+* Nothing is declared or withdrawn until two things hold (D49): the
+* `core_blocks` store has loaded (R2), and the composer has read the rows it
+* already owns, so a restart is not the first miss of every block
+* (`WithdrawalGate.seed`). A block whose row exists but whose composition no
+* longer plans (a cap renamed by a release) keeps its device as an offline
+* placeholder with no capabilities, and reports `failed` naming why.
+*/
+var INTEGRATION_WAIT = "waiting for the shared Blocks integration to reconcile";
+var STORE_NOT_LOADED = "the core_blocks store has not loaded — nothing is declared or withdrawn until it does (D49)";
+var ROWS_UNREAD = "the composer's own device rows could not be read — nothing is declared or withdrawn until they are (D49)";
+var ROWS_EMPTY_UNCONFIRMED = "the composer's own device rows read empty once — a cold registry answers the same, so nothing is declared or withdrawn until the next apply's read agrees (D49)";
+/** The shape of a placeholder: no caps, so no plan to take a shape from. */
+var PLACEHOLDER_SHAPE = "placeholder";
+var Composer = class {
+	deps;
+	live = /* @__PURE__ */ new Map();
+	devices = /* @__PURE__ */ new Map();
+	/** StableIds whose row exists: the seeded persisted rows, then what every declare kept. */
+	rows = /* @__PURE__ */ new Set();
+	seeded = false;
+	/** The previous seed read answered `[]`: one more `[]` confirms it (D49). */
+	emptySeedSeen = false;
+	/** Consecutive applies refused because `core_blocks` had not loaded: warned once per run. */
+	storeWaitApplies = 0;
+	/** Consecutive applies refused because the Blocks integration had not reconciled: warned once per run. */
+	integrationWaitApplies = 0;
+	declaredFingerprint = null;
+	gate;
+	/** Applies never interleave: each one reads and replaces the whole live set. */
+	applyChain = Promise.resolve();
+	constructor(deps) {
+		this.deps = deps;
+		this.gate = new WithdrawalGate(deps.logger.child("withdrawal"), (stableId) => this.devices.get(stableId)?.id ?? null);
+	}
+	apply(input) {
+		const run = this.applyChain.then(() => this.applyNow(input), () => this.applyNow(input));
+		this.applyChain = run.then(() => void 0, () => void 0);
+		return run;
+	}
+	getStates(blockIds) {
+		return blockIds.flatMap((blockId) => {
+			const entry = this.live.get(blockId);
+			if (entry === void 0) return [];
+			const verdict = this.verdict(blockId);
+			return [{
+				blockId,
+				deviceId: entry.device?.id ?? null,
+				status: verdict.status,
+				...verdict.reason === void 0 ? {} : { reason: verdict.reason },
+				fields: entry.runtime?.state().fields.map((f) => ({ ...f })) ?? []
+			}];
+		});
+	}
+	/** Runs on the tracker's one chain (R3): resolves once the change reached every runtime. */
+	async onStateChanged(data) {
+		this.dispatch(await this.deps.tracker.onStateChanged(data.deviceId, data.capName, data.slice));
+	}
+	async onDeviceUnregistered(deviceId) {
+		this.dispatch(await this.deps.tracker.onDeviceUnregistered(deviceId));
+	}
+	async onBindingsChanged(data) {
+		this.dispatch(await this.deps.tracker.onBindingsChanged(data.deviceId, data.capName, data.reason));
+	}
+	shutdown() {
+		for (const entry of this.live.values()) entry.runtime?.stop();
+	}
+	async applyNow(input) {
+		const ids = [...input.blocks.map((b) => b.id), ...input.unreadableBlocks.map((u) => u.id)];
+		if (!input.storeLoaded) {
+			this.storeWaitApplies += 1;
+			if (this.storeWaitApplies === 1) this.deps.logger.warn("composer: the block store has not loaded — no device is declared, withdrawn or renamed", { meta: {
+				blocks: input.blocks.length,
+				live: this.live.size
+			} });
+			return this.waiting(ids, STORE_NOT_LOADED);
+		}
+		if (this.storeWaitApplies > 0) {
+			this.deps.logger.info("composer: the block store has loaded — applying again", { meta: { appliesRefused: this.storeWaitApplies } });
+			this.storeWaitApplies = 0;
+		}
+		if (input.integrationId === null) {
+			this.integrationWaitApplies += 1;
+			if (this.integrationWaitApplies === 1) this.deps.logger.warn("composer: the shared Blocks integration has not reconciled — no composed device can be declared", { meta: { blocks: input.blocks.length } });
+			return this.waiting(ids, INTEGRATION_WAIT);
+		}
+		if (this.integrationWaitApplies > 0) {
+			this.deps.logger.info("composer: the shared Blocks integration has reconciled — applying again", { meta: { appliesRefused: this.integrationWaitApplies } });
+			this.integrationWaitApplies = 0;
+		}
+		const unseeded = await this.ensureSeeded();
+		if (unseeded !== null) return this.waiting(ids, unseeded);
+		const planned = [...input.blocks.map((block) => this.plan(block)), ...input.unreadableBlocks.map((block) => this.planUnreadable(block))];
+		this.logPlanTransitions(planned);
+		const declarations = this.gate.filter(planned.flatMap((p) => p.declaration === null ? [] : [p.declaration]));
+		const rebuildErrors = await this.rebuildShapes(planned);
+		await this.reconcileDevices(input.integrationId, declarations, planned);
+		const rebuilt = await this.rebuildRuntimes(planned, declarations, new Set(input.restartBlockIds), rebuildErrors);
+		await this.syncSources(rebuilt);
+		return {
+			blocks: planned.map((p) => this.verdict(p.block.id)),
+			acted: true
+		};
+	}
+	waiting(blockIds, reason) {
+		return {
+			blocks: blockIds.map((blockId) => ({
+				blockId,
+				status: "starting",
+				reason
+			})),
+			acted: false
+		};
+	}
+	/**
+	* Seed the withdrawal gate with the rows that exist, ONCE, before its first
+	* `filter`; answers null once seeded, else why this apply must wait.
+	*
+	* An EMPTY answer is the destroying direction: a cold registry answers `[]`
+	* too, and `DeclaredDevices.reconcile` sweeps from its OWN later read — so a
+	* cold seed followed by a warm sweep would delete the row of a block that no
+	* longer plans, with no placeholder to hold it. `[]` is therefore trusted
+	* only when the next apply's read agrees (D49); that apply comes from the
+	* supervisor's existing converge, never a timer here (D3). A failed read
+	* changes nothing and breaks the agreement.
+	*/
+	async ensureSeeded() {
+		if (this.seeded) return null;
+		let rows;
+		try {
+			rows = await this.deps.readPersisted();
+		} catch (err) {
+			this.emptySeedSeen = false;
+			this.deps.logger.warn("composer: reading its own device rows failed — nothing is declared or withdrawn; retried on the next apply", { meta: { error: errMsg(err) } });
+			return ROWS_UNREAD;
+		}
+		if (rows.length === 0 && !this.emptySeedSeen) {
+			this.emptySeedSeen = true;
+			this.deps.logger.warn("composer: its own device rows read empty — waiting for the next apply to confirm before declaring or withdrawing anything");
+			return ROWS_EMPTY_UNCONFIRMED;
+		}
+		this.gate.seed(rows);
+		this.rows = new Set(rows.map((r) => r.stableId));
+		this.seeded = true;
+		this.deps.logger.info("composer: seeded the withdrawal gate from the persisted rows", { meta: {
+			rows: rows.length,
+			confirmedEmpty: rows.length === 0
+		} });
+		return null;
+	}
+	/**
+	* A row that exists but does not parse is held exactly like a composition
+	* that stopped planning: its device (if it has a row) stays as an offline
+	* placeholder, and the block fails naming the parse error. Absent, it would
+	* be withdrawn on the second apply that omitted it (D49).
+	*/
+	planUnreadable(block) {
+		const stableId = composedDeviceStableId(block.id);
+		const hasRow = this.rows.has(stableId);
+		return {
+			block: {
+				id: block.id,
+				name: block.name,
+				enabled: false,
+				updatedAt: 0
+			},
+			fields: [],
+			problems: [`the stored block does not parse — ${block.error}`],
+			declaration: hasRow ? placeholderDeclaration(stableId) : null,
+			shape: hasRow ? PLACEHOLDER_SHAPE : null,
+			spec: null
+		};
+	}
+	plan(block) {
+		const plan = planComposition(block.composition, this.deps.lookupCap);
+		const target = block.composition.target;
+		if (plan.problems.length > 0 || target.kind !== "new") {
+			const problems = plan.problems.length > 0 ? plan.problems.map((p) => `${p.path}: ${p.message}`) : [`target: a \`${target.kind}\` target is not composable in this release`];
+			const stableId = composedDeviceStableId(block.id);
+			const hasRow = this.rows.has(stableId);
+			return {
+				block,
+				fields: [],
+				problems,
+				declaration: hasRow ? placeholderDeclaration(stableId) : null,
+				shape: hasRow ? PLACEHOLDER_SHAPE : null,
+				spec: null
+			};
+		}
+		const caps = block.composition.features.flatMap((f) => {
+			const def = this.deps.lookupCap(f.cap);
+			return def === null ? [] : [def];
+		});
+		const declarationInput = {
+			blockId: block.id,
+			name: block.name,
+			target,
+			caps
+		};
+		return {
+			block,
+			fields: plan.fields,
+			problems: [],
+			declaration: declarationFor(declarationInput),
+			shape: shapeOf(declarationInput),
+			spec: {
+				type: target.type,
+				...target.role === void 0 ? {} : { role: target.role }
+			}
+		};
+	}
+	/** One line when a block starts or stops planning — never one per apply. */
+	logPlanTransitions(planned) {
+		for (const p of planned) {
+			const before = this.live.get(p.block.id)?.planned.problems.join("; ") ?? "";
+			const now = p.problems.join("; ");
+			if (before === now) continue;
+			const extras = {
+				tags: this.tagsOf(p.block.id),
+				meta: {
+					blockId: p.block.id,
+					problems: p.problems,
+					placeholder: p.declaration !== null
+				}
+			};
+			if (now === "") this.deps.logger.info("composition plans again", extras);
+			else this.deps.logger.warn(p.declaration === null ? "composition does not plan — no device is declared for it" : "composition no longer plans — its device is kept offline with no capabilities", extras);
+		}
+	}
+	/**
+	* A changed type/role/cap set (or a switch to or from a placeholder) needs a
+	* NEW device object: decommission, and let the reconcile adopt it with the
+	* new class. A failure keeps the old device and is retried next apply.
+	*/
+	async rebuildShapes(planned) {
+		const errors = /* @__PURE__ */ new Map();
+		for (const p of planned) {
+			const previous = this.live.get(p.block.id);
+			const device = previous?.device ?? null;
+			if (previous === void 0 || device === null || p.shape === null) continue;
+			if (previous.planned.shape === p.shape) continue;
+			try {
+				this.deps.logger.info("composition shape changed — rebuilding its device", {
+					tags: { deviceId: device.id },
+					meta: {
+						blockId: p.block.id,
+						from: previous.planned.shape,
+						to: p.shape
+					}
+				});
+				if (p.spec !== null) await this.deps.devices.applyDerivedSpec(device.id, p.spec);
+				await this.deps.devices.decommission(device.id);
+				const stableId = composedDeviceStableId(p.block.id);
+				this.devices = new Map([...this.devices].filter(([s]) => s !== stableId));
+				this.declaredFingerprint = null;
+			} catch (err) {
+				const error = errMsg(err);
+				errors.set(p.block.id, error);
+				this.deps.logger.warn("rebuilding a composed device failed — the old one is kept", {
+					tags: { deviceId: device.id },
+					meta: {
+						blockId: p.block.id,
+						error
+					}
+				});
+			}
+		}
+		return errors;
+	}
+	async reconcileDevices(integrationId, declarations, planned) {
+		const shapes = new Map(planned.flatMap((p) => p.declaration === null ? [] : [[p.declaration.stableId, p.shape]]));
+		const fingerprint = JSON.stringify(declarations.map((d) => [d.stableId, shapes.get(d.stableId) ?? null]).toSorted());
+		const allLive = declarations.every((d) => this.devices.has(d.stableId));
+		if (fingerprint === this.declaredFingerprint && allLive) return;
+		try {
+			const result = await this.deps.declare(integrationId, declarations);
+			this.devices = result.devices;
+			this.rows = new Set(declarations.map((d) => d.stableId).filter((s) => this.rows.has(s) || result.devices.has(s)));
+			this.declaredFingerprint = fingerprint;
+		} catch (err) {
+			this.deps.logger.warn("composer: the device declaration failed — keeping the devices already live", { meta: {
+				error: errMsg(err),
+				declarations: declarations.length
+			} });
+		}
+	}
+	async rebuildRuntimes(planned, declarations, restart, rebuildErrors) {
+		const reset = /* @__PURE__ */ new Set();
+		const fresh = /* @__PURE__ */ new Set();
+		const next = /* @__PURE__ */ new Map();
+		for (const p of planned) {
+			const previous = this.live.get(p.block.id);
+			const rebuildError = rebuildErrors.get(p.block.id) ?? null;
+			if (previous !== void 0 && rebuildError !== null) {
+				next.set(p.block.id, {
+					...previous,
+					rebuildError
+				});
+				continue;
+			}
+			const device = this.devices.get(composedDeviceStableId(p.block.id)) ?? null;
+			const appliedName = device === null ? null : p.block.name === null ? previous?.appliedName ?? device.name : await this.applyName(device, p.block.name, previous?.appliedName ?? null);
+			if (previous?.runtime != null && previous.device === device && previous.planned.block.updatedAt === p.block.updatedAt && previous.planned.block.enabled === p.block.enabled && !restart.has(p.block.id)) {
+				next.set(p.block.id, {
+					planned: p,
+					device,
+					runtime: previous.runtime,
+					appliedName,
+					rebuildError: null
+				});
+				continue;
+			}
+			previous?.runtime?.stop();
+			if (previous === void 0 || restart.has(p.block.id) || previous.planned.block.updatedAt !== p.block.updatedAt) for (const f of p.fields) for (const r of f.reads) reset.add(compositionSourceKey(r.source));
+			const runtime = device === null || p.fields.length === 0 ? null : this.newRuntime(p, device);
+			if (runtime !== null) fresh.add(runtime);
+			next.set(p.block.id, {
+				planned: p,
+				device,
+				runtime,
+				appliedName,
+				rebuildError: null
+			});
+		}
+		const held = new Set(declarations.map((d) => d.stableId));
+		for (const [blockId, entry] of this.live) {
+			if (next.has(blockId)) continue;
+			if (held.has(composedDeviceStableId(blockId))) next.set(blockId, entry);
+			else entry.runtime?.stop();
+		}
+		this.live = next;
+		return {
+			reset,
+			fresh
+		};
+	}
+	newRuntime(p, device) {
+		return new CompositionRuntime({
+			blockId: p.block.id,
+			fields: p.fields,
+			target: device,
+			read: (read) => this.deps.tracker.read(read),
+			now: this.deps.now,
+			timer: this.deps.newTimer(),
+			logger: this.deps.logger.child("runtime")
+		});
+	}
+	async applyName(device, name, applied) {
+		if ((applied ?? device.name) === name) return name;
+		try {
+			await this.deps.devices.setName(device.id, name);
+			this.deps.logger.info("composed device renamed after its block", {
+				tags: { deviceId: device.id },
+				meta: { name }
+			});
+			return name;
+		} catch (err) {
+			this.deps.logger.warn("composed device rename failed — retried on the next apply", {
+				tags: { deviceId: device.id },
+				meta: {
+					name,
+					error: errMsg(err)
+				}
+			});
+			return applied ?? device.name;
+		}
+	}
+	async syncSources(rebuilt) {
+		const requests = [...this.live.values()].filter((e) => e.runtime !== null && e.planned.block.enabled).flatMap((e) => e.planned.fields.flatMap((f) => f.reads.map((r) => ({
+			ref: r.source,
+			caps: [r.cap]
+		}))));
+		const changed = await this.syncTracker(requests, rebuilt.reset);
+		for (const entry of this.live.values()) {
+			const runtime = entry.runtime;
+			if (runtime === null) continue;
+			if (!entry.planned.block.enabled) runtime.disable("the block is disabled");
+			else if (rebuilt.fresh.has(runtime)) runtime.start();
+			else runtime.onSourcesChanged(changed);
+		}
+	}
+	/** A failed sync leaves the tracker as it was: the runtimes read what it holds. */
+	async syncTracker(requests, reset) {
+		try {
+			return await this.deps.tracker.sync(requests, reset);
+		} catch (err) {
+			this.deps.logger.warn("composer: syncing the tracked sources failed — retried on the next apply", { meta: {
+				error: errMsg(err),
+				sources: requests.length
+			} });
+			return /* @__PURE__ */ new Set();
+		}
+	}
+	dispatch(changed) {
+		if (changed.size === 0) return;
+		for (const entry of this.live.values()) if (entry.planned.block.enabled) entry.runtime?.onSourcesChanged(changed);
+	}
+	tagsOf(blockId) {
+		const deviceId = this.devices.get(composedDeviceStableId(blockId))?.id ?? null;
+		return deviceId === null ? {} : { deviceId };
+	}
+	verdict(blockId) {
+		const entry = this.live.get(blockId);
+		if (entry === void 0) return {
+			blockId,
+			status: "starting",
+			reason: "not applied yet"
+		};
+		if (entry.rebuildError !== null) return {
+			blockId,
+			status: "failed",
+			reason: `rebuilding the composed device for its new shape failed: ${entry.rebuildError}`
+		};
+		if (entry.planned.problems.length > 0) {
+			const kept = entry.planned.declaration === null ? "" : " — its device is kept offline with no capabilities";
+			return {
+				blockId,
+				status: "failed",
+				reason: `the composition does not validate: ${entry.planned.problems.join("; ")}${kept}`
+			};
+		}
+		if (!entry.planned.block.enabled) return {
+			blockId,
+			status: "stopped"
+		};
+		if (entry.device === null) return {
+			blockId,
+			status: "starting",
+			reason: "the composed device has not been constructed yet"
+		};
+		const failure = entry.runtime?.state().failure ?? null;
+		if (failure !== null) return {
+			blockId,
+			status: "failed",
+			reason: failure
+		};
+		return {
+			blockId,
+			status: "running"
+		};
+	}
+};
+//#endregion
+//#region src/builtins/composer/deadline-timer.ts
+/** Node's largest `setTimeout` delay; anything longer is clamped to 1 ms (`TimeoutOverflowWarning`). */
+var MAX_TIMER_DELAY_MS = 2147483647;
+/** One pending wake-up per composition, at its earliest expression deadline. Never a poll. */
+var NodeDeadlineTimer = class {
+	now;
+	handle = null;
+	constructor(now) {
+		this.now = now;
+	}
+	arm(at, fire) {
+		this.disarm();
+		this.schedule(at, fire);
+	}
+	/**
+	* A deadline further away than the largest delay is reached in legs: the
+	* clamped wake-up is NOT the deadline, so it re-arms the remainder instead of
+	* firing — firing early would re-arm the same deadline and, unclamped, Node
+	* turns it into a 1 ms spin (D3).
+	*/
+	schedule(at, fire) {
+		const remaining = Math.max(0, at - this.now());
+		const clamped = remaining > MAX_TIMER_DELAY_MS;
+		this.handle = setTimeout(() => {
+			this.handle = null;
+			if (clamped) this.schedule(at, fire);
+			else fire();
+		}, clamped ? MAX_TIMER_DELAY_MS : remaining);
+		this.handle.unref?.();
+	}
+	disarm() {
+		if (this.handle === null) return;
+		clearTimeout(this.handle);
+		this.handle = null;
+	}
+};
+//#endregion
+//#region src/builtins/composer/source-tracker.ts
+/**
+* What a composition's sources currently say, per source device and per cap
+* (D659).
+*
+* Fed by the events sources ALREADY emit (`device.state-changed`,
+* `device.unregistered`, `device.bindings-changed`). It never polls and arms no
+* timer. It reads the hub only to HYDRATE a source it has not resolved yet (on
+* `sync`, driven by the supervisor's existing converge), to CONFIRM a
+* destructive verdict, and to RECONCILE when the source device (re)registers.
+* A source once resolved is not re-read by `sync`: its values arrive by
+* `device.state-changed`. Events are telemetry and may be dropped (D8), so the
+* reconcile point is the one the source itself raises: a
+* `device.bindings-changed` for a cap it serves (`native-registered` on a
+* provider restart, a wrapper toggle) re-reads that cap — and `device-status`
+* re-reads `online` — and a source found under a NEW id after an unregister is
+* re-read at once. No timer, no poll (R7c).
+*
+*  - fresh: the last value, from a device that is online;
+*  - stale: the last value, while the device is offline or a re-read
+*    flickered. Nothing is destroyed (D49);
+*  - unavailable: no value — never a number that looks plausible (D393). A cap
+*    the provider unregistered is unavailable, NOT stale (spec §2), and so is a
+*    cap absent from the bindings of a device whose ROW exists: after a hub
+*    restart or a provider respawn the bindings are empty until the provider
+*    re-registers, and two back-to-back binding reads are one correlated read.
+*    `fatal` only when the source DEVICE is GONE and two index reads agreed.
+*    Fatal is sticky: only an operator reset ends it (no auto-repair, 2026-08-08).
+*
+* A re-read that answers "no report" never replaces a value already held: the
+* value is kept, marked stale with the reason (D49 — one empty read is not
+* proof). Only `native-unregistered` takes a value away (R7b).
+*
+* Every entry point runs on ONE promise chain (R3): `sync` builds its next map
+* across awaits, and an event that landed mid-way used to be overwritten when
+* that map was assigned. `read` is synchronous, from the last settled map.
+*
+* D224 (R7d): what is held here is the INPUT of a field the composition owns.
+* It is served to nobody else — no cap method, no getter for another addon
+* reads this map; the composed device's slice is the only output. A consumer
+* that wants a source's value asks the addon that owns that source.
+*/
+var DEVICE_STATUS_CAP = "device-status";
+function valueAtPath(slice, path) {
+	return path.split(".").reduce((node, segment) => isRecord(node) ? node[segment] : void 0, slice);
+}
+function onlineOf(slice) {
+	const online = slice["online"];
+	return typeof online === "boolean" ? online : null;
+}
+function findRow(read, stableId) {
+	if (read.kind === "unreadable") return {
+		kind: "unknown",
+		error: read.error
+	};
+	const row = read.rows.find((r) => r.stableId === stableId);
+	return row === void 0 ? { kind: "absent" } : {
+		kind: "found",
+		deviceId: row.id
+	};
+}
+var SourceTracker = class {
+	ports;
+	sources = /* @__PURE__ */ new Map();
+	/** The one chain every entry point joins (R3); the pattern is `BlockSupervisor.inFlight`. */
+	chain = Promise.resolve();
+	constructor(ports) {
+		this.ports = ports;
+	}
+	/**
+	* Track exactly `requests`. Hydrate what is new or unresolved; keep what is
+	* known. `reset` names source keys an OPERATOR action re-opens (a block edit
+	* or restart): only those lose a sticky `missing`.
+	*/
+	sync(requests, reset) {
+		return this.serialized(() => this.syncNow(requests, reset));
+	}
+	onStateChanged(deviceId, capName, slice) {
+		return this.serialized(async () => this.applyStateChanged(deviceId, capName, slice));
+	}
+	onDeviceUnregistered(deviceId) {
+		return this.serialized(() => this.confirmUnregistered(deviceId));
+	}
+	onBindingsChanged(deviceId, capName, reason) {
+		return this.serialized(() => this.applyBindingsChanged(deviceId, capName, reason));
+	}
+	/** Run `work` after everything already queued, whether that settled or failed; never let one failure stall the chain. */
+	serialized(work) {
+		const run = this.chain.then(work, work);
+		this.chain = run.then(() => void 0, () => void 0);
+		return run;
+	}
+	async syncNow(requests, reset) {
+		const merged = /* @__PURE__ */ new Map();
+		for (const request of requests) {
+			const k = compositionSourceKey(request.ref);
+			const prior = merged.get(k);
+			merged.set(k, {
+				ref: request.ref,
+				caps: [...new Set([...prior?.caps ?? [], ...request.caps])]
+			});
+		}
+		const lists = /* @__PURE__ */ new Map();
+		const next = /* @__PURE__ */ new Map();
+		const changed = /* @__PURE__ */ new Set();
+		for (const [k, request] of merged) {
+			const before = reset.has(k) ? void 0 : this.sources.get(k);
+			const after = await this.hydrate(request, before, lists);
+			next.set(k, after);
+			for (const cap of request.caps) if (before?.caps.get(cap) !== after.caps.get(cap) || before?.missingReason !== after.missingReason) changed.add(compositionSliceKey(request.ref, cap));
+		}
+		this.sources = next;
+		return changed;
+	}
+	read(read) {
+		const label = `${compositionSourceKey(read.source)} ${read.cap}.${read.fieldPath}`;
+		const tracked = this.sources.get(compositionSourceKey(read.source));
+		if (tracked === void 0) return {
+			state: "unavailable",
+			reason: `${label}: not tracked yet`,
+			fatal: false
+		};
+		if (tracked.missingReason !== null) return {
+			state: "unavailable",
+			reason: tracked.missingReason,
+			fatal: true
+		};
+		const cap = tracked.caps.get(read.cap);
+		if (cap === void 0) return {
+			state: "unavailable",
+			reason: `${label}: not tracked yet`,
+			fatal: false
+		};
+		if (cap.kind === "none" || cap.kind === "unbound") return {
+			state: "unavailable",
+			reason: `${label}: ${cap.reason}`,
+			fatal: false
+		};
+		const value = toExpressionValue(valueAtPath(cap.slice, read.fieldPath));
+		if (value === void 0) return {
+			state: "unavailable",
+			reason: `${label}: the field is absent or not a scalar`,
+			fatal: false
+		};
+		if (cap.staleReason !== null) return {
+			state: "stale",
+			value,
+			reason: cap.staleReason
+		};
+		if (tracked.online === false) return {
+			state: "stale",
+			value,
+			reason: "the source device is offline"
+		};
+		return {
+			state: "fresh",
+			value
+		};
+	}
+	applyStateChanged(deviceId, capName, slice) {
+		const changed = /* @__PURE__ */ new Set();
+		const next = new Map(this.sources);
+		for (const [k, source] of this.sources) {
+			if (source.deviceId !== deviceId || source.missingReason !== null) continue;
+			let updated = source;
+			if (capName === DEVICE_STATUS_CAP) {
+				const online = onlineOf(slice);
+				if (online !== source.online) {
+					updated = {
+						...updated,
+						online
+					};
+					for (const cap of source.caps.keys()) changed.add(compositionSliceKey(source.ref, cap));
+				}
+			}
+			const current = source.caps.get(capName);
+			if (current !== void 0) {
+				if (current.kind === "unbound") this.logHealed(deviceId, capName, "device.state-changed");
+				updated = {
+					...updated,
+					caps: new Map([...updated.caps, [capName, {
+						kind: "slice",
+						slice,
+						staleReason: null
+					}]])
+				};
+				changed.add(compositionSliceKey(source.ref, capName));
+			}
+			if (updated !== source) next.set(k, updated);
+		}
+		this.sources = next;
+		return changed;
+	}
+	async confirmUnregistered(deviceId) {
+		const changed = /* @__PURE__ */ new Set();
+		for (const [k, source] of this.sources) {
+			if (source.deviceId !== deviceId || source.missingReason !== null) continue;
+			const resolution = await this.resolveConfirmed(source.ref, void 0);
+			if (resolution.kind === "unknown") {
+				this.ports.logger.warn("composition source: could not confirm a removal — nothing changes", {
+					tags: { deviceId },
+					meta: {
+						source: k,
+						error: resolution.error
+					}
+				});
+				continue;
+			}
+			if (resolution.kind === "found" && resolution.deviceId === deviceId) continue;
+			const next = resolution.kind === "missing" ? {
+				...source,
+				deviceId: null,
+				missingReason: `source \`${k}\` (device ${deviceId}) was removed — two reads agreed`
+			} : await this.rereadUnderNewId(source, resolution.deviceId);
+			this.ports.logger.warn(resolution.kind === "missing" ? "composition source removed — its fields are unavailable until the operator acts" : "composition source re-registered under a new id — re-read under it", {
+				tags: { deviceId },
+				meta: {
+					source: k,
+					...resolution.kind === "found" ? { newDeviceId: resolution.deviceId } : {}
+				}
+			});
+			this.sources = new Map([...this.sources, [k, next]]);
+			for (const cap of source.caps.keys()) changed.add(compositionSliceKey(source.ref, cap));
+		}
+		return changed;
+	}
+	async applyBindingsChanged(deviceId, capName, reason) {
+		const changed = /* @__PURE__ */ new Set();
+		for (const [k, source] of this.sources) {
+			if (source.deviceId !== deviceId || source.missingReason !== null) continue;
+			const current = source.caps.get(capName);
+			let updated = source;
+			if (reason === "native-unregistered") {
+				if (current?.kind === "slice") {
+					const reading = {
+						kind: "none",
+						reason: `the provider unregistered \`${capName}\` — no value until it registers again`
+					};
+					updated = {
+						...updated,
+						caps: new Map([...updated.caps, [capName, reading]])
+					};
+				}
+			} else {
+				const reading = current !== void 0 ? await this.readCap(deviceId, capName, "bound", current) : null;
+				if (reading !== null) updated = {
+					...updated,
+					caps: new Map([...updated.caps, [capName, reading]])
+				};
+				if (current?.kind === "unbound" && reading !== null && reading.kind !== "unbound") this.logHealed(deviceId, capName, reason);
+				if (capName === DEVICE_STATUS_CAP) {
+					const online = reading === null ? await this.readOnline(deviceId) : reading.kind === "slice" ? onlineOf(reading.slice) : null;
+					if (online !== null && online !== source.online) {
+						updated = {
+							...updated,
+							online
+						};
+						for (const cap of source.caps.keys()) changed.add(compositionSliceKey(source.ref, cap));
+					}
+				}
+			}
+			if (updated === source) continue;
+			this.sources = new Map([...this.sources, [k, updated]]);
+			if (updated.caps !== source.caps) changed.add(compositionSliceKey(source.ref, capName));
+		}
+		return changed;
+	}
+	/** A source found under a NEW id is a re-registration: read it there now (R7c). */
+	async rereadUnderNewId(source, deviceId) {
+		const caps = /* @__PURE__ */ new Map();
+		for (const [cap, prior] of source.caps) caps.set(cap, await this.readCap(deviceId, cap, "bound", prior));
+		const online = await this.readOnline(deviceId) ?? source.online;
+		return {
+			...source,
+			deviceId,
+			online,
+			caps
+		};
+	}
+	async hydrate(request, before, lists) {
+		if (before !== void 0 && before.missingReason !== null) return before;
+		if (before !== void 0 && before.deviceId !== null) {
+			const added = request.caps.filter((cap) => !before.caps.has(cap));
+			if (added.length === 0 && request.caps.length === before.caps.size) return before;
+			const caps = await this.readCaps(before.deviceId, request.caps, before.caps, added);
+			return {
+				...before,
+				caps
+			};
+		}
+		const k = compositionSourceKey(request.ref);
+		const first = lists.get(request.ref.addonId) ?? await this.ports.listDevicesOf(request.ref.addonId);
+		lists.set(request.ref.addonId, first);
+		const resolution = await this.resolveConfirmed(request.ref, first);
+		if (resolution.kind === "missing") {
+			this.ports.logger.warn("composition source does not exist — two reads agreed", { meta: { source: k } });
+			return {
+				ref: request.ref,
+				deviceId: null,
+				missingReason: `source \`${k}\` does not exist — two reads agreed`,
+				online: null,
+				caps: /* @__PURE__ */ new Map()
+			};
+		}
+		if (resolution.kind === "unknown") {
+			this.ports.logger.warn("composition source: the device index could not be read — its fields are unavailable until the next apply", { meta: {
+				source: k,
+				error: resolution.error
+			} });
+			return {
+				ref: request.ref,
+				deviceId: null,
+				missingReason: null,
+				online: null,
+				caps: new Map(request.caps.map((cap) => [cap, {
+					kind: "none",
+					reason: `the source could not be resolved: ${resolution.error}`
+				}]))
+			};
+		}
+		const deviceId = resolution.deviceId;
+		const known = before?.caps ?? /* @__PURE__ */ new Map();
+		const toRead = request.caps.filter((cap) => known.get(cap)?.kind !== "slice");
+		const caps = await this.readCaps(deviceId, request.caps, known, toRead);
+		const online = before?.online ?? await this.readOnline(deviceId);
+		return {
+			ref: request.ref,
+			deviceId,
+			missingReason: null,
+			online,
+			caps
+		};
+	}
+	/** Read `toRead` (bindings first, then slices); every other requested cap keeps what `known` holds. */
+	async readCaps(deviceId, requested, known, toRead) {
+		const bound = toRead.length > 0 ? await this.readBindings(deviceId, toRead) : /* @__PURE__ */ new Map();
+		const caps = /* @__PURE__ */ new Map();
+		for (const cap of requested) {
+			const prior = known.get(cap);
+			caps.set(cap, prior !== void 0 && !toRead.includes(cap) ? prior : await this.readCap(deviceId, cap, bound.get(cap) ?? "unknown", prior));
+		}
+		return caps;
+	}
+	async resolveConfirmed(ref, first) {
+		const verdict = findRow(first ?? await this.ports.listDevicesOf(ref.addonId), ref.stableId);
+		if (verdict.kind !== "absent") return verdict;
+		const second = findRow(await this.ports.listDevicesOf(ref.addonId), ref.stableId);
+		if (second.kind === "found") {
+			this.ports.logger.warn("composition source: the device index disagreed with itself — keeping the source", {
+				tags: { deviceId: second.deviceId },
+				meta: { source: compositionSourceKey(ref) }
+			});
+			return second;
+		}
+		return second.kind === "absent" ? { kind: "missing" } : second;
+	}
+	/**
+	* One bindings read. A second one would not confirm anything: back to back
+	* they are one correlated read, and "unbound" no longer destroys work — it is
+	* a non-fatal `none` that `native-registered` heals.
+	*/
+	async readBindings(deviceId, caps) {
+		const read = await this.ports.readBoundCaps(deviceId);
+		return new Map(caps.map((c) => {
+			if (read.kind === "unreadable") return [c, "unknown"];
+			return [c, read.caps.has(c) ? "bound" : "unbound"];
+		}));
+	}
+	async readCap(deviceId, cap, binding, prior) {
+		if (binding === "unbound") {
+			const reason = `capability \`${cap}\` is not bound on device ${deviceId} — waiting for \`native-registered\``;
+			if (prior?.kind !== "unbound") this.ports.logger.warn("composition source: a requested capability is not bound — the field is unavailable until it registers", {
+				tags: { deviceId },
+				meta: {
+					cap,
+					reason
+				}
+			});
+			return {
+				kind: "unbound",
+				reason
+			};
+		}
+		const read = await this.ports.readSlice(deviceId, cap);
+		if (read.kind === "slice") return {
+			kind: "slice",
+			slice: read.slice,
+			staleReason: null
+		};
+		if (read.kind === "none") return prior?.kind === "slice" ? {
+			...prior,
+			staleReason: `a re-read found no \`${cap}\` report — the last value is kept`
+		} : {
+			kind: "none",
+			reason: `the source has not reported \`${cap}\` yet`
+		};
+		this.ports.logger.warn("composition source: a slice read failed — the last value is kept", {
+			tags: { deviceId },
+			meta: {
+				cap,
+				error: read.error
+			}
+		});
+		return prior?.kind === "slice" ? {
+			...prior,
+			staleReason: `re-read failed: ${read.error}`
+		} : {
+			kind: "none",
+			reason: `the slice could not be read: ${read.error}`
+		};
+	}
+	logHealed(deviceId, cap, via) {
+		this.ports.logger.info("composition source: an unbound capability is served again", {
+			tags: { deviceId },
+			meta: {
+				cap,
+				via
+			}
+		});
+	}
+	async readOnline(deviceId) {
+		const read = await this.ports.readSlice(deviceId, DEVICE_STATUS_CAP);
+		if (read.kind === "unreadable") this.ports.logger.warn("composition source: `device-status` could not be read — online unknown", {
+			tags: { deviceId },
+			meta: { error: read.error }
+		});
+		return read.kind === "slice" ? onlineOf(read.slice) : null;
+	}
+};
+//#endregion
+//#region src/builtins/composer/composer.addon.ts
+/**
+* The `composer` builtin (D659): runs every declarative composition in ONE
+* isolated runner (`execution.isolate` + `group: composer`). It is
+* frame-free and low-crash, and its group is a group of ONE — no device
+* provider or data plane shares it, so a crash respawns nothing else (D29,
+* enforced by `scripts/check-runner-group-isolation.ts`). `CrashSupervisor`
+* bounds it like every forked runner (D6). Hub-only: declarations are cluster
+* state.
+*/
+/** Ignored by `DeclaredDevices` whenever `integrationId` is supplied, which is always here. */
+var DECLARED_INTEGRATION_NAME_UNUSED = "Blocks";
+var ComposerAddon = class extends BaseAddon {
+	composer = null;
+	constructor() {
+		super({});
+	}
+	async onInitialize() {
+		const api = this.ctx.api;
+		const logger = this.ctx.logger;
+		const tracker = new SourceTracker({
+			logger: logger.child("sources"),
+			listDevicesOf: async (addonId) => {
+				try {
+					return {
+						kind: "rows",
+						rows: (await api.deviceManager.listAll.query({
+							addonId,
+							projection: "slim"
+						})).map((r) => ({
+							id: r.id,
+							stableId: r.stableId
+						}))
+					};
+				} catch (err) {
+					return {
+						kind: "unreadable",
+						error: errMsg(err)
+					};
+				}
+			},
+			readSlice: async (deviceId, capName) => {
+				try {
+					const slice = await api.deviceState.getCapSlice.query({
+						deviceId,
+						capName
+					});
+					return slice === null || slice === void 0 ? { kind: "none" } : {
+						kind: "slice",
+						slice
+					};
+				} catch (err) {
+					return {
+						kind: "unreadable",
+						error: errMsg(err)
+					};
+				}
+			},
+			readBoundCaps: async (deviceId) => {
+				try {
+					const bindings = await api.deviceManager.getBindings.query({ deviceId });
+					return {
+						kind: "caps",
+						caps: new Set(bindings.entries.map((e) => e.capName))
+					};
+				} catch (err) {
+					return {
+						kind: "unreadable",
+						error: errMsg(err)
+					};
+				}
+			}
+		});
+		const listOwnDevices = async () => api.deviceManager.listAll.query({ addonId: COMPOSER_ADDON_ID });
+		const declared = new DeclaredDevices({
+			logger: logger.child("declaration"),
+			addonId: COMPOSER_ADDON_ID,
+			devices: this.ctx.kernel.devices,
+			localNodeId: this.ctx.kernel.localNodeId,
+			getIntegration: async () => {
+				throw new Error("composer: devices hang off the Blocks integration; it never reads its own");
+			},
+			createIntegration: async () => {
+				throw new Error("composer: devices hang off the Blocks integration; it never mints one");
+			},
+			updateIntegration: async () => {
+				throw new Error("composer: devices hang off the Blocks integration; it never updates one");
+			},
+			listOwnDevices
+		});
+		const devices = this.ctx.kernel.devices;
+		this.composer = new Composer({
+			logger: logger.child("composer"),
+			tracker,
+			lookupCap: buildCapabilityLookup(ALL_CAPABILITY_DEFINITIONS),
+			readPersisted: async () => (await listOwnDevices()).map((r) => ({
+				id: r.id,
+				stableId: r.stableId
+			})),
+			declare: async (integrationId, declarations) => {
+				const result = await declared.reconcile({
+					integrationName: DECLARED_INTEGRATION_NAME_UNUSED,
+					integrationId,
+					devices: declarations
+				});
+				const handles = /* @__PURE__ */ new Map();
+				for (const outcome of result.devices) if (isComposedDevice(outcome.device)) handles.set(outcome.stableId, outcome.device);
+				else logger.error("a declared composition is not a ComposedDevice — its caps cannot be written", {
+					tags: { deviceId: outcome.deviceId },
+					meta: { stableId: outcome.stableId }
+				});
+				return { devices: handles };
+			},
+			devices: {
+				setName: (deviceId, name) => devices.setName(deviceId, name),
+				decommission: (deviceId) => devices.decommission(deviceId),
+				applyDerivedSpec: (deviceId, derived) => devices.applyDerivedSpec(deviceId, derived)
+			},
+			now: () => Date.now(),
+			newTimer: () => new NodeDeadlineTimer(() => Date.now())
+		});
+		this.subscribe({ category: EventCategory.DeviceStateChanged }, (event) => {
+			const data = parseDeviceStateChanged(event.data);
+			if (data !== null) this.composer?.onStateChanged(data).catch((err) => {
+				this.logEventFailure("device.state-changed", data.deviceId, err);
+			});
+		});
+		this.subscribe({ category: EventCategory.DeviceUnregistered }, (event) => {
+			this.composer?.onDeviceUnregistered(event.data.deviceId).catch((err) => {
+				this.logEventFailure("device.unregistered", event.data.deviceId, err);
+			});
+		});
+		this.subscribe({ category: EventCategory.DeviceBindingsChanged }, (event) => {
+			this.composer?.onBindingsChanged(event.data).catch((err) => {
+				this.logEventFailure("device.bindings-changed", event.data.deviceId, err);
+			});
+		});
+		logger.info("composer ready — waiting for core-blocks to apply the compositions");
+		return [{
+			capability: composerCapability,
+			provider: this.buildProvider()
+		}];
+	}
+	async onShutdown() {
+		this.composer?.shutdown();
+		this.composer = null;
+	}
+	/** An event handler never rejects unhandled: in a forked runner that is a crash strike (D6). */
+	logEventFailure(category, deviceId, err) {
+		this.ctx.logger.warn("composer: handling a device event failed — the next event or apply re-reads", {
+			tags: { deviceId },
+			meta: {
+				category,
+				error: errMsg(err)
+			}
+		});
+	}
+	buildProvider() {
+		return {
+			applyBlocks: async (input) => this.requireComposer().apply(input),
+			getStates: async ({ blockIds }) => ({ states: [...this.requireComposer().getStates(blockIds)] })
+		};
+	}
+	requireComposer() {
+		if (this.composer === null) throw new Error("composer: not initialized");
+		return this.composer;
+	}
+};
+//#endregion
+export { ComposerAddon, ComposerAddon as default };