@camstack/system 1.2.476 → 1.2.478

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

@@ -3,8 +3,9 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 require("../../chunk-Cek0wNdY.js");
-const require_dist = require("../../dist-CNU7cdFf.js");
-const require_composition_sources = require("../../composition-sources-BNOP9mFp.js");
+const require_dist = require("../../dist-iVUkxljP.js");
+const require_composition_sources = require("../../composition-sources-yfxjp3qV.js");
+const require_retention = require("../../retention-B3z_lBP1.js");
 let zod = require("zod");
 //#region src/builtins/shared/device-state-changed.ts
 /** Structural narrowing helper for untrusted bus payloads. */
@@ -1201,9 +1202,33 @@ function createFieldRecord(plan, byCap, lookupCap) {
 		hasWritten: false,
 		written: void 0,
 		expressionMemory: require_dist.createStatefulExpressionMemory(),
-		eventHighWater: typeof initial === "number" && Number.isFinite(initial) ? initial : null
+		eventHighWater: typeof initial === "number" && Number.isFinite(initial) ? initial : null,
+		pulseHold: false
 	};
 }
+/** Apply a pulse start seed (D938). `keep` leaves the slice seed in place. */
+function applyPulseSeed(record, seed) {
+	if (seed === void 0 || seed.kind === "keep") return record;
+	if (seed.kind === "hold") return {
+		...record,
+		initial: void 0,
+		eventHighWater: null,
+		pulseHold: true
+	};
+	const value = seed.value;
+	return {
+		...record,
+		initial: value,
+		eventHighWater: typeof value === "number" && Number.isFinite(value) ? value : null,
+		pulseHold: false
+	};
+}
+function fieldRecords(fields, byCap, lookupCap, pulseSeeds) {
+	return new Map(fields.map((plan) => {
+		const key = fieldKey(plan);
+		return [key, applyPulseSeed(createFieldRecord(plan, byCap, lookupCap), pulseSeeds?.get(key))];
+	}));
+}
 function currentOutput(record) {
 	return record.hasWritten ? record.written : record.initial;
 }
@@ -1257,6 +1282,7 @@ function namedField(r) {
 function writable(record) {
 	const outcome = record.outcome;
 	if (outcome === null) return void 0;
+	if (record.pulseHold && !record.hasWritten && (outcome.state === "unavailable" || outcome.value === null)) return;
 	if (outcome.state !== "unavailable") return outcome.value;
 	switch (record.plan.unavailable) {
 		case "null": return null;
@@ -1694,7 +1720,7 @@ var CompositionRuntime = class {
 	constructor(deps) {
 		this.deps = deps;
 		this.startedAtMs = deps.now();
-		this.records = new Map(deps.fields.map((plan) => [fieldKey(plan), createFieldRecord(plan, deps.initialByCap, deps.lookupCap)]));
+		this.records = fieldRecords(deps.fields, deps.initialByCap, deps.lookupCap, deps.pulseSeeds);
 		deps.target.onAsyncFailure?.((cap, failure) => this.onTargetWriteFailed(cap, failure));
 		const eventContext = {
 			deviceId: deps.target.id,
@@ -2541,7 +2567,7 @@ function writerFor(deps, p, device, onClaimEvent) {
 		onClaim: (cap, event) => onClaimEvent(deviceId, cap, owner, event)
 	});
 }
-function newCompositionRuntime(deps, p, target, seed) {
+function newCompositionRuntime(deps, p, target, seed, pulseSeeds) {
 	const self = p.target.kind === "existing" ? selfReadCaps(p.fields, p.target.ref, p.target.features) : null;
 	const targetKey = p.target.kind === "existing" ? require_dist.compositionSourceKey(p.target.ref) : null;
 	const nativeCaps = new Set(self?.native ?? []);
@@ -2554,6 +2580,7 @@ function newCompositionRuntime(deps, p, target, seed) {
 		target,
 		lookupCap: deps.lookupCap,
 		...seed === void 0 ? {} : { initialByCap: seed.byCap },
+		...pulseSeeds === void 0 ? {} : { pulseSeeds },
 		read: (read) => deps.tracker.read(read, require_dist.compositionSourceKey(read.source) === targetKey && nativeCaps.has(read.cap) ? "native" : "effective"),
 		isOwnRead: (read) => require_dist.compositionSourceKey(read.source) === ownKey && !nativeCaps.has(read.cap),
 		now: deps.now,
@@ -2759,6 +2786,389 @@ function verdictOf(blockId, entry, unsynced, grafts = null) {
 	};
 }
 //#endregion
+//#region src/builtins/composer/pulse-seed.ts
+/** The last false→true in time order. A series that opens already on is not a transition. */
+function lastOffToOn(points, beforeOn) {
+	const ordered = [...points].toSorted((a, b) => a.t - b.t);
+	let previous = beforeOn;
+	let rise = null;
+	for (const point of ordered) {
+		if (previous === false && point.on && Number.isFinite(point.t)) rise = point.t;
+		previous = point.on;
+	}
+	return rise;
+}
+function finite(value) {
+	return value !== null && Number.isFinite(value) ? value : null;
+}
+/**
+* What the source proves. A failed read is `hold`, never `none`.
+* When the source records no history and it is off, `lastChangedAt` is the
+* end of the last ring: it bounds the ring from above (the press was at or
+* before that instant). It is used only when it is newer than the target's
+* native stamp — an older bound does not prove the native value.
+*/
+function proof(facts) {
+	if (facts.history.kind === "unread") return {
+		kind: "hold",
+		reason: "history-unread"
+	};
+	if (facts.history.kind === "series") {
+		const at = lastOffToOn(facts.history.points, facts.history.beforeOn);
+		return at === null ? { kind: "none" } : {
+			kind: "rise",
+			at,
+			via: "history"
+		};
+	}
+	if (facts.level.kind === "unread") return {
+		kind: "hold",
+		reason: "level-unread"
+	};
+	const changedAt = facts.level.kind === "off" ? finite(facts.level.changedAt) : null;
+	const newerThanNative = changedAt !== null && (facts.nativeStamp === null || changedAt > facts.nativeStamp);
+	if (changedAt !== null && newerThanNative) return {
+		kind: "rise",
+		at: changedAt,
+		via: "changed-at-bound"
+	};
+	return { kind: "none" };
+}
+function claimed(owned) {
+	return owned.kind === "stamp" || owned.kind === "never";
+}
+function decidePulseSeed(facts) {
+	const proved = proof(facts);
+	if (proved.kind === "hold") return claimed(facts.owned) ? { kind: "keep" } : proved;
+	if (proved.kind === "rise") {
+		if (facts.owned.kind === "stamp" && facts.owned.at >= proved.at) return { kind: "keep" };
+		const count = facts.owned.kind === "stamp" ? facts.owned.count : 0;
+		return {
+			kind: "stamp",
+			at: proved.at,
+			count,
+			via: proved.via
+		};
+	}
+	return claimed(facts.owned) ? { kind: "keep" } : {
+		kind: "none",
+		count: 0
+	};
+}
+/** One failed source blocks "no ring". A rise from another source still stands. */
+function mergePulseDecisions(decisions) {
+	if (decisions.length === 0) return {
+		kind: "none",
+		count: 0
+	};
+	const stamps = decisions.flatMap((decision) => decision.kind === "stamp" ? [decision] : []);
+	if (stamps.length > 0) return stamps.reduce((best, next) => next.at > best.at ? next : best);
+	const hold = decisions.find((decision) => decision.kind === "hold");
+	if (hold !== void 0) return hold;
+	if (decisions.some((decision) => decision.kind === "keep")) return { kind: "keep" };
+	return {
+		kind: "none",
+		count: 0
+	};
+}
+//#endregion
+//#region src/builtins/composer/pulse-seed-resolve.ts
+/**
+* Gather a pulse override's start seed (D938). The stored expression is not
+* changed. A failed read holds the field: no seed, and a claimed stamp is
+* not cleared (D49).
+*/
+var ROSE_CALL = String.raw`rose\(\s*([A-Za-z_][A-Za-z0-9_]*)\s*,\s*([A-Za-z_][A-Za-z0-9_]*)`;
+function historySeriesKey(cap, fieldPath) {
+	return require_retention.capSeriesKey(cap, fieldPath);
+}
+async function resolvePulseSeeds(input) {
+	try {
+		return await resolveNow(input);
+	} catch (err) {
+		input.logger.warn("pulse override seed held — gathering the source facts threw, so nothing is seeded and nothing is cleared", {
+			tags: { deviceId: input.deviceId },
+			meta: {
+				blockId: input.blockId,
+				error: require_dist.errMsg(err)
+			}
+		});
+		return /* @__PURE__ */ new Map();
+	}
+}
+async function resolveNow(input) {
+	const roses = input.fields.filter(isPulseTimestamp);
+	if (roses.length === 0) return /* @__PURE__ */ new Map();
+	const listing = await readClaims(input);
+	if (listing === null) return /* @__PURE__ */ new Map();
+	const seeds = /* @__PURE__ */ new Map();
+	for (const field of roses) {
+		const decision = await decideField(input, field, listing);
+		logDecision(input, field, decision);
+		for (const [key, seed] of seedsFor(input.fields, field, decision)) seeds.set(key, seed);
+	}
+	return seeds;
+}
+function isPulseTimestamp(field) {
+	return field.source.kind === "expression" && require_dist.expressionContainsBuiltinCall(field.source.expr, "rose");
+}
+async function readClaims(input) {
+	try {
+		const listing = await input.claims.listClaims({ ownerPrefix: input.blockId });
+		if (listing.state === "loaded") return listing;
+		input.logger.warn("pulse override seed held — the claims index has not loaded, so nothing is seeded and nothing is cleared", {
+			tags: { deviceId: input.deviceId },
+			meta: {
+				blockId: input.blockId,
+				reason: listing.reason
+			}
+		});
+		return null;
+	} catch (err) {
+		input.logger.warn("pulse override seed held — the claims index could not be read, so nothing is seeded and nothing is cleared", {
+			tags: { deviceId: input.deviceId },
+			meta: {
+				blockId: input.blockId,
+				error: require_dist.errMsg(err)
+			}
+		});
+		return null;
+	}
+}
+async function decideField(input, field, listing) {
+	if (listing.state !== "loaded") return {
+		kind: "hold",
+		reason: "claims-unread"
+	};
+	const claim = listing.claims.find((row) => row.owner === input.blockId && row.deviceId === input.deviceId && row.capName === field.cap);
+	const slice = input.targetSeed.byCap.get(field.cap) ?? null;
+	const counter = counterField(input.fields, field);
+	const owned = ownedOf(claim, slice, field.path, counter?.path ?? null);
+	const nativeStamp = stampOf(slice, field.path);
+	const pairs = rosePairs(field);
+	if (pairs.length === 0) return { kind: "keep" };
+	const decisions = [];
+	for (const pair of pairs) decisions.push(await decidePair(input, pair, owned, nativeStamp));
+	return mergePulseDecisions(decisions);
+}
+async function decidePair(input, pair, owned, nativeStamp) {
+	const resolution = await input.sources.resolve(pair.source, false);
+	if (resolution.kind === "missing") return { kind: "keep" };
+	if (resolution.kind !== "found") return decidePulseSeed({
+		owned,
+		nativeStamp,
+		history: { kind: "unread" },
+		level: { kind: "unread" }
+	});
+	return decidePulseSeed({
+		owned,
+		nativeStamp,
+		history: await historyOf(input, resolution.deviceId, pair),
+		level: await levelOf(input, resolution.deviceId, pair)
+	});
+}
+async function historyOf(input, deviceId, pair) {
+	if (!recordsField(input.lookupCap, pair.cap, pair.activeField)) return { kind: "absent" };
+	const now = input.now();
+	const fromMs = now - require_retention.DEFAULT_RETENTION.rawDays * require_retention.DAY_MS;
+	try {
+		const answer = await input.readPulseHistory(deviceId, pair.cap, pair.activeField, fromMs, now);
+		if (answer.kind === "unread") return { kind: "unread" };
+		return {
+			kind: "series",
+			beforeOn: answer.series.beforeOn,
+			points: answer.series.points
+		};
+	} catch (err) {
+		input.logger.warn("pulse override history read threw — treated as unread", {
+			tags: { deviceId: input.deviceId },
+			meta: {
+				blockId: input.blockId,
+				sourceDeviceId: deviceId,
+				cap: pair.cap,
+				field: pair.activeField,
+				error: require_dist.errMsg(err)
+			}
+		});
+		return { kind: "unread" };
+	}
+}
+async function levelOf(input, deviceId, pair) {
+	try {
+		return levelFromSlice(await input.readCap(deviceId, pair.cap), pair);
+	} catch (err) {
+		input.logger.warn("pulse override source slice could not be read — treated as unread", {
+			tags: { deviceId: input.deviceId },
+			meta: {
+				blockId: input.blockId,
+				sourceDeviceId: deviceId,
+				cap: pair.cap,
+				error: require_dist.errMsg(err)
+			}
+		});
+		return { kind: "unread" };
+	}
+}
+function levelFromSlice(slice, pair) {
+	if (slice === null) return {
+		kind: "off",
+		changedAt: null
+	};
+	const active = slice[pair.activeField];
+	if (typeof active !== "boolean") return { kind: "unread" };
+	const changed = slice[pair.changedAtField];
+	const changedAt = typeof changed === "number" && Number.isFinite(changed) ? changed : null;
+	return active ? {
+		kind: "on",
+		changedAt
+	} : {
+		kind: "off",
+		changedAt
+	};
+}
+function recordsField(lookup, cap, fieldPath) {
+	const history = lookup(cap)?.history;
+	if (history === void 0 || history === "none") return false;
+	return Object.hasOwn(history.fields, fieldPath);
+}
+function ownedOf(claim, slice, timestampPath, counterPath) {
+	if (claim === void 0 || slice === null || !claim.fields.includes(timestampPath)) return { kind: "none" };
+	const at = slice[timestampPath];
+	if (at === null) return { kind: "never" };
+	if (typeof at !== "number" || !Number.isFinite(at)) return { kind: "none" };
+	const rawCount = counterPath === null ? void 0 : slice[counterPath];
+	return {
+		kind: "stamp",
+		at,
+		count: typeof rawCount === "number" && Number.isFinite(rawCount) && rawCount >= 0 ? rawCount : 0
+	};
+}
+function stampOf(slice, path) {
+	const at = slice?.[path];
+	return typeof at === "number" && Number.isFinite(at) ? at : null;
+}
+function counterField(fields, timestamp) {
+	return fields.find((field) => {
+		if (field.cap !== timestamp.cap || field.path === timestamp.path) return false;
+		return field.source.kind === "expression" && field.source.expr === `count(${timestamp.path})`;
+	});
+}
+function rosePairs(field) {
+	if (field.source.kind !== "expression") return [];
+	const found = [];
+	for (const match of field.source.expr.matchAll(new RegExp(ROSE_CALL, "g"))) {
+		const pair = rosePair(field, match[1], match[2]);
+		if (pair !== null) found.push(pair);
+	}
+	return found;
+}
+function rosePair(field, activeName, changedName) {
+	if (field.source.kind !== "expression") return null;
+	if (activeName === void 0 || changedName === void 0) return null;
+	const active = field.source.bindings[activeName];
+	const changed = field.source.bindings[changedName];
+	if (active === void 0 || changed === void 0) return null;
+	if (active.kind !== "from" || changed.kind !== "from") return null;
+	if (active.cap !== changed.cap) return null;
+	if (active.source.addonId !== changed.source.addonId) return null;
+	if (active.source.stableId !== changed.source.stableId) return null;
+	return {
+		source: active.source,
+		cap: active.cap,
+		activeField: active.fieldPath,
+		changedAtField: changed.fieldPath
+	};
+}
+function seedsFor(fields, timestamp, decision) {
+	const seeds = /* @__PURE__ */ new Map();
+	if (decision.kind === "keep") return seeds;
+	const counter = counterField(fields, timestamp);
+	if (decision.kind === "hold") {
+		seeds.set(fieldKey(timestamp), { kind: "hold" });
+		if (counter !== void 0) seeds.set(fieldKey(counter), {
+			kind: "value",
+			value: 0
+		});
+		return seeds;
+	}
+	if (decision.kind === "none") {
+		seeds.set(fieldKey(timestamp), {
+			kind: "value",
+			value: null
+		});
+		if (counter !== void 0) seeds.set(fieldKey(counter), {
+			kind: "value",
+			value: 0
+		});
+		return seeds;
+	}
+	seeds.set(fieldKey(timestamp), {
+		kind: "value",
+		value: decision.at
+	});
+	if (counter !== void 0) seeds.set(fieldKey(counter), {
+		kind: "value",
+		value: decision.count
+	});
+	return seeds;
+}
+/** Raw boolean points of the device-level series (`scope` empty). 1 is on. */
+function pulseHistoryFromQuery(series) {
+	const row = series.find((item) => item.scope === "");
+	if (row === void 0) return {
+		beforeOn: null,
+		points: []
+	};
+	return {
+		beforeOn: levelBit(row.before?.value ?? null),
+		points: row.points.flatMap((point) => {
+			const on = levelBit(point.last);
+			return on === null ? [] : [{
+				t: point.t,
+				on
+			}];
+		})
+	};
+}
+function levelBit(value) {
+	if (value === 1) return true;
+	if (value === 0) return false;
+	return null;
+}
+function logDecision(input, field, decision) {
+	const meta = {
+		blockId: input.blockId,
+		cap: field.cap,
+		field: field.path
+	};
+	if (decision.kind === "stamp") {
+		input.logger.info("pulse override seeded lastPressedAt from its source", {
+			tags: { deviceId: input.deviceId },
+			meta: {
+				...meta,
+				at: decision.at,
+				via: decision.via,
+				count: decision.count
+			}
+		});
+		return;
+	}
+	if (decision.kind === "none") {
+		input.logger.info("pulse override seeded no ring — the source proved none, so the native stamp is not used", {
+			tags: { deviceId: input.deviceId },
+			meta
+		});
+		return;
+	}
+	if (decision.kind === "hold") input.logger.warn("pulse override seed held — a source read failed, so nothing is seeded and nothing is cleared", {
+		tags: { deviceId: input.deviceId },
+		meta: {
+			...meta,
+			reason: decision.reason
+		}
+	});
+}
+//#endregion
 //#region src/builtins/composer/composer.ts
 /**
 * The composer: every declarative composition on this hub, in one runner
@@ -2996,6 +3406,7 @@ var Composer = class {
 				continue;
 			}
 			let targetSeed;
+			let pulseSeeds;
 			if (p.target.kind === "existing" && p.target.deviceId !== null && p.target.waiting === null && p.target.gone === null && p.block.enabled && p.fields.length > 0) try {
 				targetSeed = await readExistingTargetSeeds(p.target.deviceId, p.fields.map((field) => field.cap), this.deps.readExistingTargetCap);
 				reportSeedlessRestoredCaps({
@@ -3006,6 +3417,20 @@ var Composer = class {
 					seed: targetSeed,
 					lookupCap: this.deps.lookupCap
 				});
+				const readHistory = this.deps.readPulseHistory;
+				if (readHistory !== void 0) pulseSeeds = await resolvePulseSeeds({
+					blockId: p.block.id,
+					deviceId: p.target.deviceId,
+					fields: p.fields,
+					targetSeed,
+					lookupCap: this.deps.lookupCap,
+					claims: this.deps.claims,
+					sources: this.deps.tracker,
+					readCap: this.deps.readExistingTargetCap,
+					readPulseHistory: readHistory,
+					now: this.deps.now,
+					logger: this.deps.logger
+				});
 			} catch (err) {
 				const reason = `the target device state could not be read before ownership (${require_dist.errMsg(err)}) — nothing is grafted or claimed until it is; retried on the next apply`;
 				this.deps.logger.warn(previous?.runtime === null || previous === void 0 ? "customization target state could not be read — ownership is held" : "customization edit target state could not be read — the previous runtime stays installed", {
@@ -3031,7 +3456,7 @@ var Composer = class {
 			const writer = writerFor(this.deps, p, device, (deviceId, cap, owner, event) => {
 				this.onClaimEvent(deviceId, cap, owner, event);
 			});
-			const runtime = writer === null || p.fields.length === 0 ? null : newCompositionRuntime(this.deps, p, writer, targetSeed);
+			const runtime = writer === null || p.fields.length === 0 ? null : newCompositionRuntime(this.deps, p, writer, targetSeed, pulseSeeds);
 			if (writer !== null && p.target.kind === "existing" && p.target.deviceId !== null) this.grafts.plan({
 				deviceId: p.target.deviceId,
 				ref: p.target.ref,
@@ -4164,6 +4589,8 @@ var SourceTracker = class {
 */
 /** Ignored by `DeclaredDevices` whenever `integrationId` is supplied, which is always here. */
 var DECLARED_INTEGRATION_NAME_UNUSED = "Blocks";
+/** The device-history query ceiling. A switch's raw tier is change-only, so this is the whole window. */
+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;
@@ -4312,6 +4739,26 @@ var ComposerAddon = class extends require_dist.BaseAddon {
 				deviceId,
 				capName
 			}) ?? null,
+			readPulseHistory: async (deviceId, cap, fieldPath, fromMs, toMs) => {
+				try {
+					return {
+						kind: "series",
+						series: pulseHistoryFromQuery((await api.deviceHistory.query.query({
+							deviceId,
+							key: historySeriesKey(cap, fieldPath),
+							from: fromMs,
+							to: toMs,
+							resolution: "raw",
+							maxPoints: PULSE_HISTORY_MAX_POINTS
+						})).series)
+					};
+				} catch (err) {
+					return {
+						kind: "unread",
+						error: require_dist.errMsg(err)
+					};
+				}
+			},
 			describeTarget: readBoundCaps,
 			grafts,
 			now: () => Date.now(),