@camstack/types 1.2.422 → 1.2.424

package/dist/{composition-CpETZ4HL.mjs → composition-Bb8iwHEJ.mjs}

@@ -1138,7 +1138,7 @@ var ExpressionEvalError = class extends Error {
 //#endregion
 //#region src/expression/builtins.ts
 function isStatefulBuiltin(name) {
-	return name === "rose" || name === "count" || name === "dwell" || name === "latchedAt";
+	return name === "rose" || name === "count" || name === "dwell" || name === "latchedAt" || name === "schmitt";
 }
 function asFiniteNumber(value, name, index) {
 	if (typeof value !== "number" || !Number.isFinite(value)) throw new ExpressionEvalError(`${name}: argument ${index + 1} must be a finite number`);
@@ -1266,6 +1266,41 @@ function evaluateDwell(activeRaw, onForMsRaw, offForMsRaw, call, nowMs, hooks) {
 	hooks?.noteDeadline?.(call.pendingSince + delay);
 	return call.latched;
 }
+/**
+* `schmitt(x, high, low[, onForMs, offForMs])`: true once `x >= high`, false
+* once `x <= low`, and the last answer in between. A transition waits its delay
+* and is dropped if `x` returns to the held side first. The first answer needs
+* a crossing, or the restored output as `seed`: a reading inside the band with
+* nothing to hold is unknown, never off (D393). A null reading throws, so the
+* field is unavailable and the latch is kept.
+*/
+function evaluateSchmitt(args, call, nowMs, seed, hooks) {
+	const x = asFiniteNumber(args[0], "schmitt", 0);
+	const high = asFiniteNumber(args[1], "schmitt", 1);
+	const low = asFiniteNumber(args[2], "schmitt", 2);
+	const onForMs = args.length > 3 ? asNonNegativeMs(args[3], "schmitt", 3) : 0;
+	const offForMs = args.length > 4 ? asNonNegativeMs(args[4], "schmitt", 4) : 0;
+	if (low > high) throw new ExpressionEvalError("schmitt: the low edge is above the high edge");
+	if (call.latched === null && seed !== null) call.latched = seed;
+	const wants = x >= high ? true : x <= low ? false : call.latched;
+	if (call.latched === null) {
+		if (wants !== null) call.latched = wants;
+		return call.latched;
+	}
+	if (wants === null || wants === call.latched) {
+		call.pendingSince = null;
+		return call.latched;
+	}
+	if (call.pendingSince === null) call.pendingSince = nowMs;
+	const delay = wants ? onForMs : offForMs;
+	if (nowMs - call.pendingSince >= delay) {
+		call.latched = wants;
+		call.pendingSince = null;
+		return call.latched;
+	}
+	hooks?.noteDeadline?.(call.pendingSince + delay);
+	return call.latched;
+}
 /** `latchedAt(value)`: epoch ms when `value` last changed; null clears the stamp. */
 function evaluateLatchedAt(value, call, nowMs) {
 	if (value === null) {
@@ -1463,6 +1498,13 @@ var table = {
 		apply: () => {
 			throw new ExpressionEvalError("latchedAt: stateful evaluation context is required");
 		}
+	},
+	schmitt: {
+		minArgs: 3,
+		maxArgs: 5,
+		apply: () => {
+			throw new ExpressionEvalError("schmitt: stateful evaluation context is required");
+		}
 	}
 };
 /** Frozen, null-prototype builtin table. */
@@ -2072,6 +2114,16 @@ function evaluateStatefulExpressionCall(invocation, memory, env, hooks) {
 			memory.calls.set(invocation.path, call);
 			return evaluateDwell(invocation.args[0], invocation.args[1], invocation.args[2], call, env.nowMs, hooks);
 		}
+		case "schmitt": {
+			const call = existing?.kind === "schmitt" ? existing : {
+				kind: "schmitt",
+				latched: null,
+				pendingSince: null
+			};
+			memory.calls.set(invocation.path, call);
+			const seed = typeof env.currentOutput === "boolean" ? env.currentOutput : null;
+			return evaluateSchmitt(invocation.args, call, env.nowMs, seed, hooks);
+		}
 		case "latchedAt": {
 			const call = existing?.kind === "latchedAt" ? existing : {
 				kind: "latchedAt",
@@ -2442,6 +2494,58 @@ function integrateReading(read, scale) {
 	for (const segment of covered.segments) unitMs += segment.value * segment.ms;
 	return numberValue(scale === "energy-kwh" ? wattMillisecondsToKwh(unitMs) : unitMs / 1e3, covered.included, covered.gaps, GAP_REASON);
 }
+function samplesOf(read) {
+	const out = [];
+	if (read.before !== null && finite(read.before.value)) out.push({
+		at: read.from,
+		value: read.before.value
+	});
+	for (const point of read.points) {
+		if (point.t < read.from || point.t > read.to) continue;
+		const value = pointValue(point);
+		if (value === null) continue;
+		const at = read.tier === "raw" || !finite(point.twMs) ? point.t : point.t + point.twMs;
+		out.push({
+			at: Math.min(at, read.to),
+			value
+		});
+	}
+	return out.toSorted((a, b) => a.at - b.at);
+}
+/** A sample-less tail or head longer than this share of the window is counted as a gap. */
+var UNCOVERED_LIMIT = .1;
+var DERIVATIVE_GAP_REASON = "history stops short of the window — the rate is over the part that was measured";
+function derivativeValue(change, spanMs, perMs, included, windowMs) {
+	return numberValue(change / (spanMs / perMs), included, windowMs - spanMs > windowMs * UNCOVERED_LIMIT ? 1 : 0, DERIVATIVE_GAP_REASON);
+}
+/**
+* Rate of change over a window, per `perMs`. The slope is taken between the
+* first and the last measured sample, so a hole inside the window neither
+* counts as zero nor stretches the elapsed time. A gauge that reported
+* nothing after the value held at the start is flat (rate 0); fewer than two
+* samples and no held value is a known gap (D393).
+*/
+function evaluateDerivative(read, perMs) {
+	if (read.truncated) return hold("the history query was truncated — the last rate is kept");
+	if (read.to <= read.from) return gapValue("the range is empty", 0);
+	const windowMs = read.to - read.from;
+	const samples = samplesOf(read);
+	const first = samples[0];
+	const last = samples[samples.length - 1];
+	if (first === void 0 || last === void 0) return gapValue("history has no reading in this window", 0);
+	if (read.kind === "counter") {
+		const heldAtStart = read.before !== null && finite(read.before.value);
+		const startsAt = heldAtStart ? read.from : first.at;
+		const deltas = read.points.flatMap((point) => point.t >= read.from && point.t <= read.to && finite(point.delta) && (heldAtStart || point.t > first.at) ? [point.delta] : []);
+		const spanMs = last.at - startsAt;
+		if (deltas.length === 0 || spanMs <= 0) return gapValue("the counter has no growth in this window", samples.length);
+		return derivativeValue(deltas.reduce((sum, delta) => sum + delta, 0), spanMs, perMs, samples.length, windowMs);
+	}
+	if (samples.length === 1 && first.at === read.from && read.before !== null) return numberValue(0, 1, 0, null);
+	const spanMs = last.at - first.at;
+	if (samples.length < 2 || spanMs <= 0) return gapValue("the rate needs two readings in the window", samples.length);
+	return derivativeValue(last.value - first.value, spanMs, perMs, samples.length, windowMs);
+}
 //#endregion
 //#region src/composition/helpers/history-window.ts
 /**
@@ -2805,7 +2909,13 @@ var GROUP_TEMPLATE_IDS = [
 	"occupancy",
 	"binary",
 	"switch",
-	"light"
+	"light",
+	"fan",
+	"cover",
+	"valve",
+	"lock",
+	"media-player",
+	"climate"
 ];
 var NUMERIC_AGGREGATES = [
 	"mean",
@@ -2868,19 +2978,73 @@ var integralHelperObject = z.object({
 	source: HelperMemberSchema
 });
 var IntegralHelperSpecSchema = integralHelperObject;
+var thresholdHelperObject = z.object({
+	kind: z.literal("threshold"),
+	source: HelperMemberSchema,
+	high: z.number(),
+	low: z.number(),
+	onForMs: z.number().int().nonnegative(),
+	offForMs: z.number().int().nonnegative()
+});
+var ThresholdHelperSpecSchema = thresholdHelperObject;
+var ARITHMETIC_OPS = [
+	"sum",
+	"difference",
+	"ratio"
+];
+var arithmeticHelperObject = z.object({
+	kind: z.literal("arithmetic"),
+	op: z.enum(ARITHMETIC_OPS),
+	inputs: z.array(HelperMemberSchema).min(2).max(64)
+});
+var ArithmeticHelperSpecSchema = arithmeticHelperObject;
+var EXPRESSION_OUTPUTS = ["number", "boolean"];
+var expressionHelperObject = z.object({
+	kind: z.literal("expression"),
+	expr: z.string().min(1),
+	inputs: z.array(z.object({
+		name: z.string().min(1),
+		member: HelperMemberSchema
+	})).min(1).max(64),
+	output: z.enum(EXPRESSION_OUTPUTS)
+});
+var ExpressionHelperSpecSchema = expressionHelperObject;
+var DERIVATIVE_UNITS = [
+	"second",
+	"minute",
+	"hour"
+];
+var derivativeHelperObject = z.object({
+	kind: z.literal("derivative"),
+	window: RollingWindowSchema,
+	per: z.enum(DERIVATIVE_UNITS),
+	source: HelperMemberSchema
+});
+var DerivativeHelperSpecSchema = derivativeHelperObject;
 var HelperSpecSchema = z.discriminatedUnion("kind", [
 	GroupHelperSpecSchema,
 	ApplianceHelperSpecSchema,
 	statisticHelperObject,
-	integralHelperObject
+	integralHelperObject,
+	thresholdHelperObject,
+	arithmeticHelperObject,
+	expressionHelperObject,
+	derivativeHelperObject
 ]);
+function isHistoryHelper(spec) {
+	return spec.kind === "statistic" || spec.kind === "integral" || spec.kind === "derivative";
+}
 /** Every member a helper reads. A group has many; the others have one. */
 function helperMembers(spec) {
 	switch (spec.kind) {
 		case "group": return spec.members;
 		case "appliance": return [spec.member];
 		case "statistic":
-		case "integral": return [spec.source];
+		case "integral":
+		case "threshold":
+		case "derivative": return [spec.source];
+		case "arithmetic": return spec.inputs;
+		case "expression": return spec.inputs.map((input) => input.member);
 	}
 }
 //#endregion
@@ -2978,6 +3142,12 @@ var CompositionAggregateSourceSchema = z.object({
 		"all"
 	]),
 	reads: z.array(CompositionFieldReadSchema).min(1).max(64),
+	/**
+	* Set when the reads are an enum state, not a yes/no: the listed states
+	* count as active (a cover is `open`). A state outside the list is inactive;
+	* a read that is not a state at all is left out. Only `any` / `all` use it.
+	*/
+	activeWhen: z.array(z.string().min(1)).min(1).optional(),
 	/** `value` is the reading; the others are the member counts. */
 	publish: z.enum([
 		"value",
@@ -3168,4 +3338,4 @@ function featureSources(feature) {
 	return featureFieldEntries(feature).map((e) => e.source);
 }
 //#endregion
-export { NUMERIC_AGGREGATES as $, MAX_EXPRESSION_AST_NODES as $t, composedDeviceStableId as A, Fmp4BoxSplitter as An, KWH_PER_WATT_MS as At, AGGREGATE_REDUCERS as B, pickVideoEncoder as Bn, createStatefulExpressionMemory as Bt, CompositionSeriesSourceSchema as C, FFMPEG_PATH_ENV as Cn, planStatisticTier as Ct, MAX_COMPOSITION_FIELDS_PER_FEATURE as D, getFfmpegArtifact as Dn, STATISTIC_STATS as Dt, MAX_COMPOSITION_FEATURES as E, FFMPEG_RELEASE as En, SERIES_KINDS as Et, compositionSourceKey as F, buildInputArgs as Fn, applianceDeviceType as Ft, GROUP_TEMPLATE_IDS as G, createExpressionScope as Gt, AggregateReducerSchema as H, evaluateStatefulExpressionCall as Ht, featureFieldEntries as I, buildVideoArgs as In, isApplianceKind as It, HelperMemberSchema as J, compileExpressionSafe as Jt, GroupHelperSpecSchema as K, evaluateAst as Kt, featureSources as L, invocationFromEncodeProfile as Ln, sourcePickForAppliance as Lt, compositionItemFieldPath as M, audioPlanFromEncodeProfile as Mn, APPLIANCE_DEFAULTS as Mt, compositionReadKey as N, buildAudioArgs as Nn, APPLIANCE_KINDS as Nt, MAX_COMPOSITION_ITEMS as O, getFfmpegDownloadUrl as On, evaluateStatistic as Ot, compositionSliceKey as P, buildFfmpegArgs as Pn, APPLIANCE_TEMPLATE_ID as Pt, MAX_HELPER_MEMBERS as Q, EXPRESSION_IDENTIFIER_RE as Qt, fieldReads as R, isSoftwareDecode as Rn, EXPRESSION_INJECTED_NOW as Rt, CompositionSchema as S, sliceChangedAt as Sn, planResetTier as St, MAX_COMPOSITION_CODE_LENGTH as T, ffmpegBinaryName as Tn, statisticCadenceMs as Tt, ApplianceHelperSpecSchema as U, toExpressionValue as Ut, ActiveCriterionSchema as V, resolveStreamMaps as Vn, evaluateExpressionSource as Vt, BINARY_AGGREGATES as W, validateExpressionSource as Wt, INTEGRAL_OUTPUTS as X, tokenize as Xt, HelperSpecSchema as Y, parseExpression as Yt, IntegralHelperSpecSchema as Z, EXPRESSION_COMPILE_CACHE_CAPACITY as Zt, CompositionFromSourceSchema as _, SOURCE_DEVICE_TYPES as _n, integralCadenceMs as _t, CUSTOMIZATION_BLOCK_NAME_PREFIX as a, EXPRESSION_BUILTINS as an, DAY_MS as at, CompositionNewTargetSchema as b, isSourceCap as bn, openReset as bt, CompositionCodeSourceSchema as c, evaluateCount as cn, HISTORY_SLOW_MS as ct, CompositionExpressionSourceSchema as d, ExpressionEvalError as dn, MINUTE_MS as dt, MAX_EXPRESSION_BINDINGS as en, StatisticHelperSpecSchema as et, CompositionFeatureSchema as f, ExpressionParseError as fn, MIN_CUSTOM_MINUTES as ft, CompositionForwardCommandSchema as g, SOURCE_CAP_CHANGED_AT_FIELD as gn, StatisticWindowSchema as gt, CompositionFieldsFeatureSchema as h, SOURCE_CAP_ACTIVE_FIELD as hn, RollingWindowSchema as ht, COMPOSITION_ITEM_KEY_RE as i, RESERVED_BINDING_NAMES as in, CalendarWindowSchema as it, compositionFeatureEnabled as j, AUDIO_PRESETS as jn, wattMillisecondsToKwh as jt, composedDeviceRef as k, canonicalHash as kn, integrateReading as kt, CompositionCommandTargetSchema as l, evaluateRose as ln, HISTORY_TIERS as lt, CompositionFieldSourceSchema as m, SOURCE_CAPS as mn, ROLLING_SPANS as mt, COMPOSER_ADDON_ID as n, MAX_EXPRESSION_EVAL_STEPS as nn, CompositionSourceRefSchema as nt, CompositionAggregateSourceSchema as o, EXPRESSION_BUILTIN_NAMES as on, DEFAULT_HISTORY_RETENTION as ot, CompositionFieldReadSchema as p, DEFAULT_FIRST_SIGHTING_FRESHNESS_MS as pn, RESET_PERIODS as pt, GroupTemplateIdSchema as q, compileExpression as qt, COMPOSITION_ITEM_ARRAY_PATH as r, MAX_EXPRESSION_SOURCE_LENGTH as rn, CALENDAR_PERIODS as rt, CompositionBindingSchema as s, disarmRoseMemory as sn, HISTORY_FAST_MS as st, COMPOSED_DEVICE_STABLE_ID_PREFIX as t, MAX_EXPRESSION_CALL_ARGS as tn, helperMembers as tt, CompositionExistingTargetSchema as u, isStatefulBuiltin as un, HOUR_MS as ut, CompositionItemEntrySchema as v, evaluateSensorEdge as vn, maxDurationMs as vt, CompositionTargetSchema as w, chooseFfmpegBinary as wn, rollingDurationMs as wt, CompositionPassthroughFeatureSchema as x, sliceActiveValue as xn, openStatistic as xt, CompositionLiteralBindingSchema as y, evaluateSensorLevelEdge as yn, nextLocalMidnight as yt, ACTIVE_CRITERIA as z, logBannerArgs as zn, cloneStatefulExpressionMemory as zt };
+export { GroupTemplateIdSchema as $, validateExpressionSource as $t, composedDeviceStableId as A, sliceActiveValue as An, planResetTier as At, AGGREGATE_REDUCERS as B, AUDIO_PRESETS as Bn, wattMillisecondsToKwh as Bt, CompositionSeriesSourceSchema as C, SOURCE_CAPS as Cn, RollingWindowSchema as Ct, MAX_COMPOSITION_FIELDS_PER_FEATURE as D, evaluateSensorEdge as Dn, nextLocalMidnight as Dt, MAX_COMPOSITION_FEATURES as E, SOURCE_DEVICE_TYPES as En, maxDurationMs as Et, compositionSourceKey as F, FFMPEG_RELEASE as Fn, STATISTIC_STATS as Ft, ArithmeticHelperSpecSchema as G, buildVideoArgs as Gn, isApplianceKind as Gt, ActiveCriterionSchema as H, buildAudioArgs as Hn, APPLIANCE_KINDS as Ht, featureFieldEntries as I, getFfmpegArtifact as In, evaluateDerivative as It, DerivativeHelperSpecSchema as J, logBannerArgs as Jn, cloneStatefulExpressionMemory as Jt, BINARY_AGGREGATES as K, invocationFromEncodeProfile as Kn, sourcePickForAppliance as Kt, featureSources as L, getFfmpegDownloadUrl as Ln, evaluateStatistic as Lt, compositionItemFieldPath as M, FFMPEG_PATH_ENV as Mn, rollingDurationMs as Mt, compositionReadKey as N, chooseFfmpegBinary as Nn, statisticCadenceMs as Nt, MAX_COMPOSITION_ITEMS as O, evaluateSensorLevelEdge as On, openReset as Ot, compositionSliceKey as P, ffmpegBinaryName as Pn, SERIES_KINDS as Pt, GroupHelperSpecSchema as Q, toExpressionValue as Qt, fieldReads as R, canonicalHash as Rn, integrateReading as Rt, CompositionSchema as S, DEFAULT_FIRST_SIGHTING_FRESHNESS_MS as Sn, ROLLING_SPANS as St, MAX_COMPOSITION_CODE_LENGTH as T, SOURCE_CAP_CHANGED_AT_FIELD as Tn, integralCadenceMs as Tt, AggregateReducerSchema as U, buildFfmpegArgs as Un, APPLIANCE_TEMPLATE_ID as Ut, ARITHMETIC_OPS as V, audioPlanFromEncodeProfile as Vn, APPLIANCE_DEFAULTS as Vt, ApplianceHelperSpecSchema as W, buildInputArgs as Wn, applianceDeviceType as Wt, ExpressionHelperSpecSchema as X, resolveStreamMaps as Xn, evaluateExpressionSource as Xt, EXPRESSION_OUTPUTS as Y, pickVideoEncoder as Yn, createStatefulExpressionMemory as Yt, GROUP_TEMPLATE_IDS as Z, evaluateStatefulExpressionCall as Zt, CompositionFromSourceSchema as _, evaluateCount as _n, HISTORY_TIERS as _t, CUSTOMIZATION_BLOCK_NAME_PREFIX as a, tokenize as an, NUMERIC_AGGREGATES as at, CompositionNewTargetSchema as b, ExpressionEvalError as bn, MIN_CUSTOM_MINUTES as bt, CompositionCodeSourceSchema as c, MAX_EXPRESSION_AST_NODES as cn, helperMembers as ct, CompositionExpressionSourceSchema as d, MAX_EXPRESSION_EVAL_STEPS as dn, CALENDAR_PERIODS as dt, createExpressionScope as en, HelperMemberSchema as et, CompositionFeatureSchema as f, MAX_EXPRESSION_SOURCE_LENGTH as fn, CalendarWindowSchema as ft, CompositionForwardCommandSchema as g, disarmRoseMemory as gn, HISTORY_SLOW_MS as gt, CompositionFieldsFeatureSchema as h, EXPRESSION_BUILTIN_NAMES as hn, HISTORY_FAST_MS as ht, COMPOSITION_ITEM_KEY_RE as i, parseExpression as in, MAX_HELPER_MEMBERS as it, compositionFeatureEnabled as j, sliceChangedAt as jn, planStatisticTier as jt, composedDeviceRef as k, isSourceCap as kn, openStatistic as kt, CompositionCommandTargetSchema as l, MAX_EXPRESSION_BINDINGS as ln, isHistoryHelper as lt, CompositionFieldSourceSchema as m, EXPRESSION_BUILTINS as mn, DEFAULT_HISTORY_RETENTION as mt, COMPOSER_ADDON_ID as n, compileExpression as nn, INTEGRAL_OUTPUTS as nt, CompositionAggregateSourceSchema as o, EXPRESSION_COMPILE_CACHE_CAPACITY as on, StatisticHelperSpecSchema as ot, CompositionFieldReadSchema as p, RESERVED_BINDING_NAMES as pn, DAY_MS as pt, DERIVATIVE_UNITS as q, isSoftwareDecode as qn, EXPRESSION_INJECTED_NOW as qt, COMPOSITION_ITEM_ARRAY_PATH as r, compileExpressionSafe as rn, IntegralHelperSpecSchema as rt, CompositionBindingSchema as s, EXPRESSION_IDENTIFIER_RE as sn, ThresholdHelperSpecSchema as st, COMPOSED_DEVICE_STABLE_ID_PREFIX as t, evaluateAst as tn, HelperSpecSchema as tt, CompositionExistingTargetSchema as u, MAX_EXPRESSION_CALL_ARGS as un, CompositionSourceRefSchema as ut, CompositionItemEntrySchema as v, evaluateRose as vn, HOUR_MS as vt, CompositionTargetSchema as w, SOURCE_CAP_ACTIVE_FIELD as wn, StatisticWindowSchema as wt, CompositionPassthroughFeatureSchema as x, ExpressionParseError as xn, RESET_PERIODS as xt, CompositionLiteralBindingSchema as y, isStatefulBuiltin as yn, MINUTE_MS as yt, ACTIVE_CRITERIA as z, Fmp4BoxSplitter as zn, KWH_PER_WATT_MS as zt };

package/dist/{composition-CPRAP41h.js → composition-CpAc0YfQ.js}

@@ -1138,7 +1138,7 @@ var ExpressionEvalError = class extends Error {
 //#endregion
 //#region src/expression/builtins.ts
 function isStatefulBuiltin(name) {
-	return name === "rose" || name === "count" || name === "dwell" || name === "latchedAt";
+	return name === "rose" || name === "count" || name === "dwell" || name === "latchedAt" || name === "schmitt";
 }
 function asFiniteNumber(value, name, index) {
 	if (typeof value !== "number" || !Number.isFinite(value)) throw new ExpressionEvalError(`${name}: argument ${index + 1} must be a finite number`);
@@ -1266,6 +1266,41 @@ function evaluateDwell(activeRaw, onForMsRaw, offForMsRaw, call, nowMs, hooks) {
 	hooks?.noteDeadline?.(call.pendingSince + delay);
 	return call.latched;
 }
+/**
+* `schmitt(x, high, low[, onForMs, offForMs])`: true once `x >= high`, false
+* once `x <= low`, and the last answer in between. A transition waits its delay
+* and is dropped if `x` returns to the held side first. The first answer needs
+* a crossing, or the restored output as `seed`: a reading inside the band with
+* nothing to hold is unknown, never off (D393). A null reading throws, so the
+* field is unavailable and the latch is kept.
+*/
+function evaluateSchmitt(args, call, nowMs, seed, hooks) {
+	const x = asFiniteNumber(args[0], "schmitt", 0);
+	const high = asFiniteNumber(args[1], "schmitt", 1);
+	const low = asFiniteNumber(args[2], "schmitt", 2);
+	const onForMs = args.length > 3 ? asNonNegativeMs(args[3], "schmitt", 3) : 0;
+	const offForMs = args.length > 4 ? asNonNegativeMs(args[4], "schmitt", 4) : 0;
+	if (low > high) throw new ExpressionEvalError("schmitt: the low edge is above the high edge");
+	if (call.latched === null && seed !== null) call.latched = seed;
+	const wants = x >= high ? true : x <= low ? false : call.latched;
+	if (call.latched === null) {
+		if (wants !== null) call.latched = wants;
+		return call.latched;
+	}
+	if (wants === null || wants === call.latched) {
+		call.pendingSince = null;
+		return call.latched;
+	}
+	if (call.pendingSince === null) call.pendingSince = nowMs;
+	const delay = wants ? onForMs : offForMs;
+	if (nowMs - call.pendingSince >= delay) {
+		call.latched = wants;
+		call.pendingSince = null;
+		return call.latched;
+	}
+	hooks?.noteDeadline?.(call.pendingSince + delay);
+	return call.latched;
+}
 /** `latchedAt(value)`: epoch ms when `value` last changed; null clears the stamp. */
 function evaluateLatchedAt(value, call, nowMs) {
 	if (value === null) {
@@ -1463,6 +1498,13 @@ var table = {
 		apply: () => {
 			throw new ExpressionEvalError("latchedAt: stateful evaluation context is required");
 		}
+	},
+	schmitt: {
+		minArgs: 3,
+		maxArgs: 5,
+		apply: () => {
+			throw new ExpressionEvalError("schmitt: stateful evaluation context is required");
+		}
 	}
 };
 /** Frozen, null-prototype builtin table. */
@@ -2072,6 +2114,16 @@ function evaluateStatefulExpressionCall(invocation, memory, env, hooks) {
 			memory.calls.set(invocation.path, call);
 			return evaluateDwell(invocation.args[0], invocation.args[1], invocation.args[2], call, env.nowMs, hooks);
 		}
+		case "schmitt": {
+			const call = existing?.kind === "schmitt" ? existing : {
+				kind: "schmitt",
+				latched: null,
+				pendingSince: null
+			};
+			memory.calls.set(invocation.path, call);
+			const seed = typeof env.currentOutput === "boolean" ? env.currentOutput : null;
+			return evaluateSchmitt(invocation.args, call, env.nowMs, seed, hooks);
+		}
 		case "latchedAt": {
 			const call = existing?.kind === "latchedAt" ? existing : {
 				kind: "latchedAt",
@@ -2442,6 +2494,58 @@ function integrateReading(read, scale) {
 	for (const segment of covered.segments) unitMs += segment.value * segment.ms;
 	return numberValue(scale === "energy-kwh" ? wattMillisecondsToKwh(unitMs) : unitMs / 1e3, covered.included, covered.gaps, GAP_REASON);
 }
+function samplesOf(read) {
+	const out = [];
+	if (read.before !== null && finite(read.before.value)) out.push({
+		at: read.from,
+		value: read.before.value
+	});
+	for (const point of read.points) {
+		if (point.t < read.from || point.t > read.to) continue;
+		const value = pointValue(point);
+		if (value === null) continue;
+		const at = read.tier === "raw" || !finite(point.twMs) ? point.t : point.t + point.twMs;
+		out.push({
+			at: Math.min(at, read.to),
+			value
+		});
+	}
+	return out.toSorted((a, b) => a.at - b.at);
+}
+/** A sample-less tail or head longer than this share of the window is counted as a gap. */
+var UNCOVERED_LIMIT = .1;
+var DERIVATIVE_GAP_REASON = "history stops short of the window — the rate is over the part that was measured";
+function derivativeValue(change, spanMs, perMs, included, windowMs) {
+	return numberValue(change / (spanMs / perMs), included, windowMs - spanMs > windowMs * UNCOVERED_LIMIT ? 1 : 0, DERIVATIVE_GAP_REASON);
+}
+/**
+* Rate of change over a window, per `perMs`. The slope is taken between the
+* first and the last measured sample, so a hole inside the window neither
+* counts as zero nor stretches the elapsed time. A gauge that reported
+* nothing after the value held at the start is flat (rate 0); fewer than two
+* samples and no held value is a known gap (D393).
+*/
+function evaluateDerivative(read, perMs) {
+	if (read.truncated) return hold("the history query was truncated — the last rate is kept");
+	if (read.to <= read.from) return gapValue("the range is empty", 0);
+	const windowMs = read.to - read.from;
+	const samples = samplesOf(read);
+	const first = samples[0];
+	const last = samples[samples.length - 1];
+	if (first === void 0 || last === void 0) return gapValue("history has no reading in this window", 0);
+	if (read.kind === "counter") {
+		const heldAtStart = read.before !== null && finite(read.before.value);
+		const startsAt = heldAtStart ? read.from : first.at;
+		const deltas = read.points.flatMap((point) => point.t >= read.from && point.t <= read.to && finite(point.delta) && (heldAtStart || point.t > first.at) ? [point.delta] : []);
+		const spanMs = last.at - startsAt;
+		if (deltas.length === 0 || spanMs <= 0) return gapValue("the counter has no growth in this window", samples.length);
+		return derivativeValue(deltas.reduce((sum, delta) => sum + delta, 0), spanMs, perMs, samples.length, windowMs);
+	}
+	if (samples.length === 1 && first.at === read.from && read.before !== null) return numberValue(0, 1, 0, null);
+	const spanMs = last.at - first.at;
+	if (samples.length < 2 || spanMs <= 0) return gapValue("the rate needs two readings in the window", samples.length);
+	return derivativeValue(last.value - first.value, spanMs, perMs, samples.length, windowMs);
+}
 //#endregion
 //#region src/composition/helpers/history-window.ts
 /**
@@ -2805,7 +2909,13 @@ var GROUP_TEMPLATE_IDS = [
 	"occupancy",
 	"binary",
 	"switch",
-	"light"
+	"light",
+	"fan",
+	"cover",
+	"valve",
+	"lock",
+	"media-player",
+	"climate"
 ];
 var NUMERIC_AGGREGATES = [
 	"mean",
@@ -2868,19 +2978,73 @@ var integralHelperObject = zod.z.object({
 	source: HelperMemberSchema
 });
 var IntegralHelperSpecSchema = integralHelperObject;
+var thresholdHelperObject = zod.z.object({
+	kind: zod.z.literal("threshold"),
+	source: HelperMemberSchema,
+	high: zod.z.number(),
+	low: zod.z.number(),
+	onForMs: zod.z.number().int().nonnegative(),
+	offForMs: zod.z.number().int().nonnegative()
+});
+var ThresholdHelperSpecSchema = thresholdHelperObject;
+var ARITHMETIC_OPS = [
+	"sum",
+	"difference",
+	"ratio"
+];
+var arithmeticHelperObject = zod.z.object({
+	kind: zod.z.literal("arithmetic"),
+	op: zod.z.enum(ARITHMETIC_OPS),
+	inputs: zod.z.array(HelperMemberSchema).min(2).max(64)
+});
+var ArithmeticHelperSpecSchema = arithmeticHelperObject;
+var EXPRESSION_OUTPUTS = ["number", "boolean"];
+var expressionHelperObject = zod.z.object({
+	kind: zod.z.literal("expression"),
+	expr: zod.z.string().min(1),
+	inputs: zod.z.array(zod.z.object({
+		name: zod.z.string().min(1),
+		member: HelperMemberSchema
+	})).min(1).max(64),
+	output: zod.z.enum(EXPRESSION_OUTPUTS)
+});
+var ExpressionHelperSpecSchema = expressionHelperObject;
+var DERIVATIVE_UNITS = [
+	"second",
+	"minute",
+	"hour"
+];
+var derivativeHelperObject = zod.z.object({
+	kind: zod.z.literal("derivative"),
+	window: RollingWindowSchema,
+	per: zod.z.enum(DERIVATIVE_UNITS),
+	source: HelperMemberSchema
+});
+var DerivativeHelperSpecSchema = derivativeHelperObject;
 var HelperSpecSchema = zod.z.discriminatedUnion("kind", [
 	GroupHelperSpecSchema,
 	ApplianceHelperSpecSchema,
 	statisticHelperObject,
-	integralHelperObject
+	integralHelperObject,
+	thresholdHelperObject,
+	arithmeticHelperObject,
+	expressionHelperObject,
+	derivativeHelperObject
 ]);
+function isHistoryHelper(spec) {
+	return spec.kind === "statistic" || spec.kind === "integral" || spec.kind === "derivative";
+}
 /** Every member a helper reads. A group has many; the others have one. */
 function helperMembers(spec) {
 	switch (spec.kind) {
 		case "group": return spec.members;
 		case "appliance": return [spec.member];
 		case "statistic":
-		case "integral": return [spec.source];
+		case "integral":
+		case "threshold":
+		case "derivative": return [spec.source];
+		case "arithmetic": return spec.inputs;
+		case "expression": return spec.inputs.map((input) => input.member);
 	}
 }
 //#endregion
@@ -2978,6 +3142,12 @@ var CompositionAggregateSourceSchema = zod.z.object({
 		"all"
 	]),
 	reads: zod.z.array(CompositionFieldReadSchema).min(1).max(64),
+	/**
+	* Set when the reads are an enum state, not a yes/no: the listed states
+	* count as active (a cover is `open`). A state outside the list is inactive;
+	* a read that is not a state at all is left out. Only `any` / `all` use it.
+	*/
+	activeWhen: zod.z.array(zod.z.string().min(1)).min(1).optional(),
 	/** `value` is the reading; the others are the member counts. */
 	publish: zod.z.enum([
 		"value",
@@ -3198,6 +3368,12 @@ Object.defineProperty(exports, "APPLIANCE_TEMPLATE_ID", {
 		return APPLIANCE_TEMPLATE_ID;
 	}
 });
+Object.defineProperty(exports, "ARITHMETIC_OPS", {
+	enumerable: true,
+	get: function() {
+		return ARITHMETIC_OPS;
+	}
+});
 Object.defineProperty(exports, "AUDIO_PRESETS", {
 	enumerable: true,
 	get: function() {
@@ -3222,6 +3398,12 @@ Object.defineProperty(exports, "ApplianceHelperSpecSchema", {
 		return ApplianceHelperSpecSchema;
 	}
 });
+Object.defineProperty(exports, "ArithmeticHelperSpecSchema", {
+	enumerable: true,
+	get: function() {
+		return ArithmeticHelperSpecSchema;
+	}
+});
 Object.defineProperty(exports, "BINARY_AGGREGATES", {
 	enumerable: true,
 	get: function() {
@@ -3408,6 +3590,18 @@ Object.defineProperty(exports, "DEFAULT_HISTORY_RETENTION", {
 		return DEFAULT_HISTORY_RETENTION;
 	}
 });
+Object.defineProperty(exports, "DERIVATIVE_UNITS", {
+	enumerable: true,
+	get: function() {
+		return DERIVATIVE_UNITS;
+	}
+});
+Object.defineProperty(exports, "DerivativeHelperSpecSchema", {
+	enumerable: true,
+	get: function() {
+		return DerivativeHelperSpecSchema;
+	}
+});
 Object.defineProperty(exports, "EXPRESSION_BUILTINS", {
 	enumerable: true,
 	get: function() {
@@ -3438,12 +3632,24 @@ Object.defineProperty(exports, "EXPRESSION_INJECTED_NOW", {
 		return EXPRESSION_INJECTED_NOW;
 	}
 });
+Object.defineProperty(exports, "EXPRESSION_OUTPUTS", {
+	enumerable: true,
+	get: function() {
+		return EXPRESSION_OUTPUTS;
+	}
+});
 Object.defineProperty(exports, "ExpressionEvalError", {
 	enumerable: true,
 	get: function() {
 		return ExpressionEvalError;
 	}
 });
+Object.defineProperty(exports, "ExpressionHelperSpecSchema", {
+	enumerable: true,
+	get: function() {
+		return ExpressionHelperSpecSchema;
+	}
+});
 Object.defineProperty(exports, "ExpressionParseError", {
 	enumerable: true,
 	get: function() {
@@ -3690,6 +3896,12 @@ Object.defineProperty(exports, "StatisticWindowSchema", {
 		return StatisticWindowSchema;
 	}
 });
+Object.defineProperty(exports, "ThresholdHelperSpecSchema", {
+	enumerable: true,
+	get: function() {
+		return ThresholdHelperSpecSchema;
+	}
+});
 Object.defineProperty(exports, "applianceDeviceType", {
 	enumerable: true,
 	get: function() {
@@ -3828,6 +4040,12 @@ Object.defineProperty(exports, "evaluateCount", {
 		return evaluateCount;
 	}
 });
+Object.defineProperty(exports, "evaluateDerivative", {
+	enumerable: true,
+	get: function() {
+		return evaluateDerivative;
+	}
+});
 Object.defineProperty(exports, "evaluateExpressionSource", {
 	enumerable: true,
 	get: function() {
@@ -3930,6 +4148,12 @@ Object.defineProperty(exports, "isApplianceKind", {
 		return isApplianceKind;
 	}
 });
+Object.defineProperty(exports, "isHistoryHelper", {
+	enumerable: true,
+	get: function() {
+		return isHistoryHelper;
+	}
+});
 Object.defineProperty(exports, "isSoftwareDecode", {
 	enumerable: true,
 	get: function() {

package/dist/device/cap-vocabulary/entries/sensors.d.ts

@@ -1,5 +1,5 @@
 import type { CapVocabularySlice } from '../types.js';
-type SensorCap = 'air-quality-sensor' | 'ambient-light-sensor' | 'binary' | 'carbon-monoxide' | 'connectivity' | 'contact' | 'enum-sensor' | 'flood' | 'gas' | 'group-commands' | 'group-status' | 'humidity-sensor' | 'meter' | 'motion' | 'numeric-sensor' | 'power-meter' | 'presence' | 'pressure-sensor' | 'smoke' | 'tamper' | 'temperature-sensor' | 'vibration' | 'weather' | 'battery' | 'network-link' | 'device-status' | 'doorbell' | 'event-emitter';
+type SensorCap = 'air-quality-sensor' | 'ambient-light-sensor' | 'binary' | 'carbon-monoxide' | 'connectivity' | 'contact' | 'enum-sensor' | 'flood' | 'gas' | 'group-active' | 'group-commands' | 'group-status' | 'humidity-sensor' | 'meter' | 'motion' | 'numeric-sensor' | 'power-meter' | 'presence' | 'pressure-sensor' | 'smoke' | 'tamper' | 'temperature-sensor' | 'vibration' | 'weather' | 'battery' | 'network-link' | 'device-status' | 'doorbell' | 'event-emitter';
 /** The sensor family of the vocabulary. */
 export declare const SENSOR_CAP_VOCABULARY: CapVocabularySlice<SensorCap>;
 export {};

package/dist/expression/builtins.d.ts

@@ -16,7 +16,7 @@
  * closed rather than emitting a garbage value.
  */
 import type { ExpressionValue } from './ast.js';
-import type { CountCallState, DwellCallState, LatchedAtCallState, RoseCallState, StatefulExpressionMemory } from './expression-source.js';
+import type { CountCallState, DwellCallState, LatchedAtCallState, RoseCallState, SchmittCallState, StatefulExpressionMemory } from './expression-source.js';
 /** Optional runtime hooks the evaluator threads through to builtins. */
 export interface ExpressionEvalHooks {
     /** Convert `value` from unit `from` to unit `to`; `null` when the pair is
@@ -41,7 +41,7 @@ export interface ExpressionBuiltin {
     readonly maxArgs: number;
     readonly apply: (args: readonly ExpressionValue[], hooks: ExpressionEvalHooks) => ExpressionValue;
 }
-export type StatefulExpressionBuiltin = 'rose' | 'count' | 'dwell' | 'latchedAt';
+export type StatefulExpressionBuiltin = 'rose' | 'count' | 'dwell' | 'latchedAt' | 'schmitt';
 export declare function isStatefulBuiltin(name: string): name is StatefulExpressionBuiltin;
 export declare function evaluateRose(level: unknown, changedAt: unknown, debounceMs: unknown, call: RoseCallState, field: StatefulExpressionMemory, env: {
     readonly currentOutput: number | null;
@@ -55,6 +55,15 @@ export declare function disarmRoseMemory(memory: StatefulExpressionMemory): void
  * the latched boolean through gaps shorter than the opposing delay (D933).
  */
 export declare function evaluateDwell(activeRaw: unknown, onForMsRaw: unknown, offForMsRaw: unknown, call: DwellCallState, nowMs: number, hooks?: ExpressionEvalHooks): boolean | null;
+/**
+ * `schmitt(x, high, low[, onForMs, offForMs])`: true once `x >= high`, false
+ * once `x <= low`, and the last answer in between. A transition waits its delay
+ * and is dropped if `x` returns to the held side first. The first answer needs
+ * a crossing, or the restored output as `seed`: a reading inside the band with
+ * nothing to hold is unknown, never off (D393). A null reading throws, so the
+ * field is unavailable and the latch is kept.
+ */
+export declare function evaluateSchmitt(args: readonly unknown[], call: SchmittCallState, nowMs: number, seed: boolean | null, hooks?: ExpressionEvalHooks): boolean | null;
 /** `latchedAt(value)`: epoch ms when `value` last changed; null clears the stamp. */
 export declare function evaluateLatchedAt(value: unknown, call: LatchedAtCallState, nowMs: number): number | null;
 export declare function evaluateCount(input: unknown, call: CountCallState, currentOutput: unknown): number;

package/dist/expression/expression-source.d.ts

@@ -39,7 +39,12 @@ export interface LatchedAtCallState {
     last: ExpressionValue | undefined;
     at: number | null;
 }
-export type StatefulCallState = RoseCallState | CountCallState | DwellCallState | LatchedAtCallState;
+export interface SchmittCallState {
+    readonly kind: 'schmitt';
+    latched: boolean | null;
+    pendingSince: number | null;
+}
+export type StatefulCallState = RoseCallState | CountCallState | DwellCallState | LatchedAtCallState | SchmittCallState;
 export interface StatefulExpressionMemory {
     readonly calls: Map<string, StatefulCallState>;
     acceptedEdgeAt: number | null;