@camstack/types 1.2.268 → 1.2.269

package/dist/{composition-QlOB7QTG.js → composition-BAH3n-zq.js}

@@ -714,6 +714,197 @@ function replaceWithSortedKeys(_key, value) {
 	return value;
 }
 //#endregion
+//#region src/catalogs/sensor-active-state.ts
+/**
+* LA tabella "quale booleano di questo tipo di device conta come ALTO", e il
+* valutatore puro del suo FRONTE.
+*
+* Viveva dentro il builtin virtual-doorbell
+* (`@camstack/system` — `builtins/doorbell/trigger-engine.ts`) e i suoi
+* predicati erano privati al modulo. Il recorder ne ha bisogno per il trigger
+* `RecordingTriggers.sensorDeviceIds`: copiarla avrebbe creato la SECONDA
+* tabella, che diverge alla prima cap aggiunta e il cui sintomo — "il sensore
+* fa suonare il campanello ma non registra" — è esattamente D62. Quindi si
+* SPOSTA qui e il doorbell la ri-esporta.
+*
+* ⚠ NON è `DEVICE_STATE_READERS` (`catalogs/device-state-vocabulary.ts`), e le
+* due non vanno unificate: quella risponde a "qual è la PAROLA di stato per una
+* regola" (e include `presence`, `cover`, `alarm-panel`), questa a "qual è il
+* booleano il cui FRONTE conta". Vocabolari deliberatamente diversi.
+*/
+/**
+* Known binary / switch source caps → the boolean slice field whose
+* false→true rise counts as ACTIVE. Every entry is "fire on active".
+* Sensors whose "active" reading is not a plain boolean (presence's string
+* state, connectivity's connected flag) are deliberately excluded — a
+* reconnect is not a doorbell press, and it is not a recording either.
+*/
+var SOURCE_CAP_ACTIVE_FIELD = {
+	contact: "entryOpen",
+	binary: "on",
+	switch: "on",
+	motion: "detected",
+	flood: "flooded",
+	gas: "detected",
+	smoke: "detected",
+	"carbon-monoxide": "detected",
+	vibration: "detected",
+	tamper: "tampered"
+};
+/**
+* The same caps → the slice field carrying the ms-epoch timestamp of the
+* last transition. Every source cap MUST appear here (guarded by a spec):
+* without a transition timestamp the evaluator cannot tell a genuine rise
+* from a boot-time hydration when the FIRST slice it ever sees is already
+* active, and errs towards silence — swallowing the rise.
+*
+* These timestamps are UPSTREAM ones, not ingest ones: the Home Assistant
+* provider derives them from `state.last_changed`, so they survive our own
+* restarts and correctly read as "hours ago" for a state that has been
+* active for hours. `motion` names its rise timestamp `lastDetectedAt`.
+*/
+var SOURCE_CAP_CHANGED_AT_FIELD = {
+	contact: "lastChangedAt",
+	binary: "lastChangedAt",
+	switch: "lastChangedAt",
+	motion: "lastDetectedAt",
+	flood: "lastChangedAt",
+	gas: "lastChangedAt",
+	smoke: "lastChangedAt",
+	"carbon-monoxide": "lastChangedAt",
+	vibration: "lastChangedAt",
+	tamper: "lastChangedAt"
+};
+/** Cap names whose presence in a device's bindings qualify it as a source. */
+var SOURCE_CAPS = Object.keys(SOURCE_CAP_ACTIVE_FIELD);
+/**
+* Device `type` values (from `DeviceType`) that can host a binary/switch
+* source cap. Used by the camera's `device-multiselect` picker as the
+* CLIENT-SIDE filter, alongside `SOURCE_CAPS`.
+*
+* Why types and not caps alone: the shared picker filters
+* `deviceManager.listAll` rows client-side, and those rows carry only the
+* device's advertised `features` — NOT its registered cap list. On the live
+* cluster binary sensors and switches advertise EMPTY features (features
+* mirror only a handful of caps like `motion-trigger`), so a caps-only
+* filter matched against `features` would list nothing (the very bug this
+* replaced, which relied on the now-empty `getAllBindings`). Matching by
+* `type` is the reliable client-side signal; the union with `SOURCE_CAPS`
+* still captures any device that DOES advertise a source-cap feature.
+* `sensor` covers contact/motion/flood/gas/smoke/CO/vibration/tamper,
+* `switch` covers switches, `control` covers generic binary actuators.
+*/
+var SOURCE_DEVICE_TYPES = [
+	"sensor",
+	"switch",
+	"control"
+];
+/** True when a cap is a recognised binary/switch source. */
+function isSourceCap(capName) {
+	return Object.prototype.hasOwnProperty.call(SOURCE_CAP_ACTIVE_FIELD, capName);
+}
+/** Extract the "active" boolean a source cap's slice carries, or null when
+*  the cap is unknown or the field is missing / non-boolean. */
+function sliceActiveValue(capName, slice) {
+	const field = SOURCE_CAP_ACTIVE_FIELD[capName];
+	if (field === void 0) return null;
+	const raw = slice[field];
+	return typeof raw === "boolean" ? raw : null;
+}
+/** Ms-epoch transition timestamp a source cap's slice carries, or null when
+*  it is absent, non-numeric or the zero "never observed" sentinel. */
+function sliceChangedAt(capName, slice) {
+	const field = SOURCE_CAP_CHANGED_AT_FIELD[capName];
+	if (field === void 0) return null;
+	const raw = slice[field];
+	if (typeof raw !== "number" || !Number.isFinite(raw) || raw <= 0) return null;
+	return raw;
+}
+/**
+* How recent a source's own transition timestamp must be for a FIRST
+* sighting that is already active to count as a genuine rise rather than a
+* hydration of long-standing state.
+*/
+var DEFAULT_FIRST_SIGHTING_FRESHNESS_MS = 3e4;
+/**
+* The source-independent edge rule. The caller supplies an already extracted
+* boolean level and source timestamp; this function owns first-sighting
+* freshness and false-to-true detection.
+*/
+function evaluateSensorLevelEdge(input) {
+	const timestamp = input.changedAt;
+	const freshFloor = Math.max(input.startedAtMs, input.nowMs - input.firstSightingFreshnessMs);
+	const firstRise = input.priorLevel === void 0 && input.level && timestamp !== null && Number.isFinite(timestamp) && timestamp >= freshFloor;
+	const transitionRise = input.priorLevel === false && input.level && timestamp !== null && Number.isFinite(timestamp);
+	if ((firstRise || transitionRise) && timestamp !== null) return {
+		kind: "rise",
+		timestamp
+	};
+	return {
+		kind: "none",
+		nextPriorLevel: input.level
+	};
+}
+/**
+* IL fronte. Puro: nessun orologio proprio, nessuna memoria — il chiamante
+* porta `prior`, `nowMs` e il proprio `startedAtMs`.
+*
+* Il caso della PRIMA slice già attiva è trattato esplicitamente e vale come
+* fronte solo se il timestamp UPSTREAM della transizione è posteriore a
+* `startedAtMs` **e** entro `firstSightingFreshnessMs`. Entrambe le metà
+* servono: la sola freschezza scatterebbe su un'idratazione al boot di uno
+* stato flippato pochi secondi prima del riavvio, e il solo "dopo che abbiamo
+* iniziato" scatterebbe, su un processo di lunga vita, per una sorgente
+* adottata oggi il cui stato è cambiato ieri. Il caso ambiguo ERRA VERSO IL
+* SILENZIO e lo dichiara (`baseline-seeded-stale-active`).
+*/
+function evaluateSensorEdge(input) {
+	const value = sliceActiveValue(input.capName, input.slice);
+	if (value === null) return {
+		edge: "none",
+		value: null,
+		reason: isSourceCap(input.capName) ? "non-boolean-value" : "unknown-cap"
+	};
+	if (evaluateSensorLevelEdge({
+		level: value,
+		changedAt: sliceChangedAt(input.capName, input.slice),
+		priorLevel: input.prior,
+		startedAtMs: input.startedAtMs,
+		nowMs: input.nowMs,
+		firstSightingFreshnessMs: input.firstSightingFreshnessMs
+	}).kind === "rise") return {
+		edge: "rising",
+		value: true
+	};
+	if (input.prior === void 0) {
+		if (!value) return {
+			edge: "none",
+			value,
+			reason: "baseline-seeded-inactive"
+		};
+		return {
+			edge: "none",
+			value,
+			reason: "baseline-seeded-stale-active"
+		};
+	}
+	if (input.prior === value) return {
+		edge: "none",
+		value,
+		reason: "no-change"
+	};
+	if (!value) return {
+		edge: "none",
+		value,
+		reason: "falling-edge"
+	};
+	return {
+		edge: "none",
+		value,
+		reason: "missing-timestamp"
+	};
+}
+//#endregion
 //#region src/expression/errors.ts
 /**
 * Error types for the safe expression engine. Two distinct classes so callers
@@ -740,6 +931,9 @@ var ExpressionEvalError = class extends Error {
 };
 //#endregion
 //#region src/expression/builtins.ts
+function isStatefulBuiltin(name) {
+	return name === "rose" || name === "count";
+}
 function asFiniteNumber(value, name, index) {
 	if (typeof value !== "number" || !Number.isFinite(value)) throw new ExpressionEvalError(`${name}: argument ${index + 1} must be a finite number`);
 	return value;
@@ -775,6 +969,37 @@ function toNumberOrNull(value) {
 	const parsed = Number(trimmed);
 	return Number.isFinite(parsed) ? parsed : null;
 }
+var DEFAULT_ROSE_DEBOUNCE_MS = 2e3;
+function evaluateRose(level, changedAt, debounceMs, call, field, env) {
+	const active = asBoolean(level, "rose", 0);
+	const timestamp = typeof changedAt === "number" && Number.isFinite(changedAt) ? changedAt : null;
+	const debounce = debounceMs === void 0 ? DEFAULT_ROSE_DEBOUNCE_MS : asFiniteNumber(debounceMs, "rose", 2);
+	if (debounce < 0) throw new ExpressionEvalError("rose: debounce must be a non-negative finite number");
+	const verdict = evaluateSensorLevelEdge({
+		level: active,
+		changedAt: timestamp,
+		priorLevel: call.priorLevel,
+		startedAtMs: env.startedAtMs,
+		nowMs: env.nowMs,
+		firstSightingFreshnessMs: DEFAULT_FIRST_SIGHTING_FRESHNESS_MS
+	});
+	call.priorLevel = verdict.kind === "rise" ? true : verdict.nextPriorLevel;
+	if (verdict.kind === "none") return env.currentOutput;
+	if (field.acceptedEdgeAt !== null && verdict.timestamp - field.acceptedEdgeAt < debounce) return env.currentOutput;
+	field.acceptedEdgeAt = verdict.timestamp;
+	return verdict.timestamp;
+}
+function evaluateCount(input, call, currentOutput) {
+	const currentCount = typeof currentOutput === "number" && Number.isFinite(currentOutput) && currentOutput >= 0 ? currentOutput : 0;
+	if (typeof input !== "number" || !Number.isFinite(input)) return currentCount;
+	if (call.highWater === null) {
+		call.highWater = input;
+		return currentCount;
+	}
+	if (input <= call.highWater) return currentCount;
+	call.highWater = input;
+	return currentCount + 1;
+}
 var INF = Number.POSITIVE_INFINITY;
 var table = {
 	min: {
@@ -914,6 +1139,20 @@ var table = {
 			const present = args.flatMap((a, i) => a === null ? [] : [asFiniteNumber(a, "latest", i)]);
 			return present.length === 0 ? null : finiteResult(Math.max(...present), "latest");
 		}
+	},
+	rose: {
+		minArgs: 2,
+		maxArgs: 3,
+		apply: () => {
+			throw new ExpressionEvalError("rose: stateful evaluation context is required");
+		}
+	},
+	count: {
+		minArgs: 1,
+		maxArgs: 1,
+		apply: () => {
+			throw new ExpressionEvalError("count: stateful evaluation context is required");
+		}
 	}
 };
 /** Frozen, null-prototype builtin table. */
@@ -1397,22 +1636,28 @@ function step(ctx) {
 	ctx.steps += 1;
 	if (ctx.steps > ctx.maxSteps) throw new ExpressionEvalError("expression evaluation step budget exceeded");
 }
-function evalNode(node, ctx) {
+function childPath(path, child) {
+	return `${path}/${child}`;
+}
+function evalNode(node, ctx, path) {
 	step(ctx);
 	switch (node.kind) {
 		case "literal": return node.value;
 		case "identifier":
 			if (!(node.name in ctx.scope)) throw new ExpressionEvalError(`unknown identifier: ${node.name}`);
 			return ctx.scope[node.name];
-		case "unary": return evalUnary(node.op, evalNode(node.operand, ctx));
-		case "binary": return evalBinary(node.op, evalNode(node.left, ctx), evalNode(node.right, ctx));
+		case "unary": return evalUnary(node.op, evalNode(node.operand, ctx, childPath(path, "operand")));
+		case "binary": return evalBinary(node.op, evalNode(node.left, ctx, childPath(path, "left")), evalNode(node.right, ctx, childPath(path, "right")));
 		case "logical": {
-			const left = evalNode(node.left, ctx);
-			if (node.op === "&&") return truthy(left) ? evalNode(node.right, ctx) : left;
-			return truthy(left) ? left : evalNode(node.right, ctx);
+			const left = evalNode(node.left, ctx, childPath(path, "left"));
+			if (node.op === "&&") return truthy(left) ? evalNode(node.right, ctx, childPath(path, "right")) : left;
+			return truthy(left) ? left : evalNode(node.right, ctx, childPath(path, "right"));
+		}
+		case "conditional": return truthy(evalNode(node.test, ctx, childPath(path, "test"))) ? evalNode(node.consequent, ctx, childPath(path, "consequent")) : evalNode(node.alternate, ctx, childPath(path, "alternate"));
+		case "call": {
+			const args = node.args.map((arg, index) => evalNode(arg, ctx, childPath(path, `arg:${index}`)));
+			return invokeCall(node.callee, args, path, ctx);
 		}
-		case "conditional": return truthy(evalNode(node.test, ctx)) ? evalNode(node.consequent, ctx) : evalNode(node.alternate, ctx);
-		case "call": return evalCall(node.callee, node.args.map((a) => evalNode(a, ctx)), ctx.hooks);
 	}
 }
 function evalUnary(op, operand) {
@@ -1443,11 +1688,19 @@ function evalBinary(op, left, right) {
 			throw new ExpressionEvalError(`"${op}" requires two numbers or two strings`);
 	}
 }
-function evalCall(callee, args, hooks) {
+function invokeCall(callee, args, path, ctx) {
 	if (!Object.prototype.hasOwnProperty.call(EXPRESSION_BUILTINS, callee)) throw new ExpressionEvalError(`unknown function: ${callee}`);
 	const builtin = EXPRESSION_BUILTINS[callee];
 	if (args.length < builtin.minArgs || args.length > builtin.maxArgs) throw new ExpressionEvalError(`${callee}: wrong number of arguments (${args.length})`);
-	return builtin.apply(args, hooks);
+	if (isStatefulBuiltin(callee)) {
+		if (ctx.invokeStateful === void 0) throw new ExpressionEvalError(`${callee}: stateful evaluation context is required`);
+		return ctx.invokeStateful({
+			name: callee,
+			path,
+			args
+		});
+	}
+	return builtin.apply(args, ctx.hooks);
 }
 /** Evaluate an AST node against a scope. Throws `ExpressionEvalError` on any
 *  runtime failure (unknown identifier, type mismatch, non-finite result,
@@ -1457,11 +1710,47 @@ function evaluateAst(node, scope, opts) {
 		scope,
 		hooks: opts?.hooks ?? EMPTY_HOOKS,
 		maxSteps: opts?.maxSteps ?? 4096,
+		...opts?.invokeStateful === void 0 ? {} : { invokeStateful: opts.invokeStateful },
 		steps: 0
-	});
+	}, "root");
 }
 //#endregion
 //#region src/expression/expression-source.ts
+function createStatefulExpressionMemory() {
+	return {
+		calls: /* @__PURE__ */ new Map(),
+		acceptedEdgeAt: null
+	};
+}
+function cloneStatefulExpressionMemory(memory) {
+	return {
+		calls: new Map([...memory.calls].map(([path, call]) => [path, { ...call }])),
+		acceptedEdgeAt: memory.acceptedEdgeAt
+	};
+}
+function evaluateStatefulExpressionCall(invocation, memory, env) {
+	const existing = memory.calls.get(invocation.path);
+	switch (invocation.name) {
+		case "rose": {
+			const call = existing?.kind === "rose" ? existing : { kind: "rose" };
+			memory.calls.set(invocation.path, call);
+			const currentOutput = env.currentOutput === null || typeof env.currentOutput === "number" && Number.isFinite(env.currentOutput) ? env.currentOutput : null;
+			return evaluateRose(invocation.args[0], invocation.args[1], invocation.args[2], call, memory, {
+				currentOutput,
+				startedAtMs: env.startedAtMs,
+				nowMs: env.nowMs
+			});
+		}
+		case "count": {
+			const call = existing?.kind === "count" ? existing : {
+				kind: "count",
+				highWater: null
+			};
+			memory.calls.set(invocation.path, call);
+			return evaluateCount(invocation.args[0], call, env.currentOutput);
+		}
+	}
+}
 /** The `now` epoch-ms binding is auto-injected into every evaluation and is a
 *  reserved binding name (authors may not rebind it). */
 var EXPRESSION_INJECTED_NOW = "now";
@@ -1504,9 +1793,10 @@ function validateExpressionSource(src) {
 /**
 * Shared read-path evaluation. Builds a null-proto scope from `bindingValues`
 * plus the injected `now` (supplied by the caller for determinism and
-* testability), compiles via the LRU, and evaluates. Any failure (parse or
-* eval) returns `{ ok: false }` — the caller treats that as "skip this
-* derivation", never as a throw that takes the pass down.
+* testability), compiles via the LRU, and evaluates. Stateful calls are
+* delegated through `opts.invokeStateful` with their stable AST path. Any
+* failure (parse or eval) returns `{ ok: false }` — the caller treats that as
+* "skip this derivation", never as a throw that takes the pass down.
 */
 function evaluateExpressionSource(expr, bindingValues, now, opts) {
 	const compiled = compileExpressionSafe(expr);
@@ -1650,6 +1940,7 @@ var CompositionItemEntrySchema = zod.z.object({
 var CompositionFieldsFeatureSchema = zod.z.object({
 	kind: zod.z.literal("fields"),
 	cap: zod.z.string().min(1),
+	enabled: zod.z.boolean().optional(),
 	fields: zod.z.record(zod.z.string().min(1), CompositionFieldSourceSchema).refine((fields) => Object.keys(fields).length <= 32, { message: `at most 32 fields per capability` }),
 	/**
 	* Items of the cap's item array, keyed by item key (D663). Naming `items`
@@ -1663,9 +1954,14 @@ var CompositionFieldsFeatureSchema = zod.z.object({
 var CompositionPassthroughFeatureSchema = zod.z.object({
 	kind: zod.z.literal("passthrough"),
 	cap: zod.z.string().min(1),
+	enabled: zod.z.boolean().optional(),
 	source: CompositionSourceRefSchema
 });
 var CompositionFeatureSchema = zod.z.discriminatedUnion("kind", [CompositionFieldsFeatureSchema, CompositionPassthroughFeatureSchema]);
+/** Only an explicit `false` disables a feature; omitted preserves the existing wire default. */
+function compositionFeatureEnabled(feature) {
+	return feature.enabled !== false;
+}
 /**
 * A NEW device. It has no `name` of its own: the block's name IS the device's
 * name (2026-08-08). A second copy here would be a second writer of one string (D62).
@@ -1900,6 +2196,12 @@ Object.defineProperty(exports, "CompositionTargetSchema", {
 		return CompositionTargetSchema;
 	}
 });
+Object.defineProperty(exports, "DEFAULT_FIRST_SIGHTING_FRESHNESS_MS", {
+	enumerable: true,
+	get: function() {
+		return DEFAULT_FIRST_SIGHTING_FRESHNESS_MS;
+	}
+});
 Object.defineProperty(exports, "EXPRESSION_BUILTINS", {
 	enumerable: true,
 	get: function() {
@@ -2008,6 +2310,30 @@ Object.defineProperty(exports, "RESERVED_BINDING_NAMES", {
 		return RESERVED_BINDING_NAMES;
 	}
 });
+Object.defineProperty(exports, "SOURCE_CAPS", {
+	enumerable: true,
+	get: function() {
+		return SOURCE_CAPS;
+	}
+});
+Object.defineProperty(exports, "SOURCE_CAP_ACTIVE_FIELD", {
+	enumerable: true,
+	get: function() {
+		return SOURCE_CAP_ACTIVE_FIELD;
+	}
+});
+Object.defineProperty(exports, "SOURCE_CAP_CHANGED_AT_FIELD", {
+	enumerable: true,
+	get: function() {
+		return SOURCE_CAP_CHANGED_AT_FIELD;
+	}
+});
+Object.defineProperty(exports, "SOURCE_DEVICE_TYPES", {
+	enumerable: true,
+	get: function() {
+		return SOURCE_DEVICE_TYPES;
+	}
+});
 Object.defineProperty(exports, "audioPlanFromEncodeProfile", {
 	enumerable: true,
 	get: function() {
@@ -2044,6 +2370,12 @@ Object.defineProperty(exports, "canonicalHash", {
 		return canonicalHash;
 	}
 });
+Object.defineProperty(exports, "cloneStatefulExpressionMemory", {
+	enumerable: true,
+	get: function() {
+		return cloneStatefulExpressionMemory;
+	}
+});
 Object.defineProperty(exports, "compileExpression", {
 	enumerable: true,
 	get: function() {
@@ -2068,6 +2400,12 @@ Object.defineProperty(exports, "composedDeviceStableId", {
 		return composedDeviceStableId;
 	}
 });
+Object.defineProperty(exports, "compositionFeatureEnabled", {
+	enumerable: true,
+	get: function() {
+		return compositionFeatureEnabled;
+	}
+});
 Object.defineProperty(exports, "compositionItemFieldPath", {
 	enumerable: true,
 	get: function() {
@@ -2098,18 +2436,54 @@ Object.defineProperty(exports, "createExpressionScope", {
 		return createExpressionScope;
 	}
 });
+Object.defineProperty(exports, "createStatefulExpressionMemory", {
+	enumerable: true,
+	get: function() {
+		return createStatefulExpressionMemory;
+	}
+});
 Object.defineProperty(exports, "evaluateAst", {
 	enumerable: true,
 	get: function() {
 		return evaluateAst;
 	}
 });
+Object.defineProperty(exports, "evaluateCount", {
+	enumerable: true,
+	get: function() {
+		return evaluateCount;
+	}
+});
 Object.defineProperty(exports, "evaluateExpressionSource", {
 	enumerable: true,
 	get: function() {
 		return evaluateExpressionSource;
 	}
 });
+Object.defineProperty(exports, "evaluateRose", {
+	enumerable: true,
+	get: function() {
+		return evaluateRose;
+	}
+});
+Object.defineProperty(exports, "evaluateSensorEdge", {
+	enumerable: true,
+	get: function() {
+		return evaluateSensorEdge;
+	}
+});
+Object.defineProperty(exports, "evaluateSensorLevelEdge", {
+	enumerable: true,
+	get: function() {
+		return evaluateSensorLevelEdge;
+	}
+});
+Object.defineProperty(exports, "evaluateStatefulExpressionCall", {
+	enumerable: true,
+	get: function() {
+		return evaluateStatefulExpressionCall;
+	}
+});
 Object.defineProperty(exports, "featureFieldEntries", {
 	enumerable: true,
 	get: function() {
@@ -2140,6 +2514,18 @@ Object.defineProperty(exports, "isSoftwareDecode", {
 		return isSoftwareDecode;
 	}
 });
+Object.defineProperty(exports, "isSourceCap", {
+	enumerable: true,
+	get: function() {
+		return isSourceCap;
+	}
+});
+Object.defineProperty(exports, "isStatefulBuiltin", {
+	enumerable: true,
+	get: function() {
+		return isStatefulBuiltin;
+	}
+});
 Object.defineProperty(exports, "logBannerArgs", {
 	enumerable: true,
 	get: function() {
@@ -2164,6 +2550,18 @@ Object.defineProperty(exports, "resolveStreamMaps", {
 		return resolveStreamMaps;
 	}
 });
+Object.defineProperty(exports, "sliceActiveValue", {
+	enumerable: true,
+	get: function() {
+		return sliceActiveValue;
+	}
+});
+Object.defineProperty(exports, "sliceChangedAt", {
+	enumerable: true,
+	get: function() {
+		return sliceChangedAt;
+	}
+});
 Object.defineProperty(exports, "toExpressionValue", {
 	enumerable: true,
 	get: function() {