@camstack/types 1.2.268 → 1.2.270

package/dist/{composition-CPFIlFfw.mjs → composition-D5BQywfe.mjs}

@@ -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 = z.object({
 var CompositionFieldsFeatureSchema = z.object({
 	kind: z.literal("fields"),
 	cap: z.string().min(1),
+	enabled: z.boolean().optional(),
 	fields: z.record(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 = z.object({
 var CompositionPassthroughFeatureSchema = z.object({
 	kind: z.literal("passthrough"),
 	cap: z.string().min(1),
+	enabled: z.boolean().optional(),
 	source: CompositionSourceRefSchema
 });
 var CompositionFeatureSchema = 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).
@@ -1756,4 +2052,4 @@ function featureSources(feature) {
 	return featureFieldEntries(feature).map((e) => e.source);
 }
 //#endregion
-export { MAX_EXPRESSION_SOURCE_LENGTH as $, compositionItemFieldPath as A, validateExpressionSource as B, CompositionTargetSchema as C, MAX_COMPOSITION_ITEMS as D, MAX_COMPOSITION_FIELDS_PER_FEATURE as E, featureSources as F, parseExpression as G, evaluateAst as H, fieldReads as I, EXPRESSION_IDENTIFIER_RE as J, tokenize as K, EXPRESSION_INJECTED_NOW as L, compositionSliceKey as M, compositionSourceKey as N, composedDeviceRef as O, featureFieldEntries as P, MAX_EXPRESSION_EVAL_STEPS as Q, evaluateExpressionSource as R, CompositionSourceRefSchema as S, MAX_COMPOSITION_FEATURES as T, compileExpression as U, createExpressionScope as V, compileExpressionSafe as W, MAX_EXPRESSION_BINDINGS as X, MAX_EXPRESSION_AST_NODES as Y, MAX_EXPRESSION_CALL_ARGS as Z, CompositionItemEntrySchema as _, resolveStreamMaps as _t, CUSTOMIZATION_BLOCK_NAME_PREFIX as a, canonicalHash as at, CompositionPassthroughFeatureSchema as b, CompositionCommandTargetSchema as c, audioPlanFromEncodeProfile as ct, CompositionFeatureSchema as d, buildInputArgs as dt, RESERVED_BINDING_NAMES as et, CompositionFieldReadSchema as f, buildVideoArgs as ft, CompositionFromSourceSchema as g, pickVideoEncoder as gt, CompositionForwardCommandSchema as h, logBannerArgs as ht, COMPOSITION_ITEM_KEY_RE as i, ExpressionParseError as it, compositionReadKey as j, composedDeviceStableId as k, CompositionExistingTargetSchema as l, buildAudioArgs as lt, CompositionFieldsFeatureSchema as m, isSoftwareDecode as mt, COMPOSER_ADDON_ID as n, EXPRESSION_BUILTIN_NAMES as nt, CompositionBindingSchema as o, Fmp4BoxSplitter as ot, CompositionFieldSourceSchema as p, invocationFromEncodeProfile as pt, EXPRESSION_COMPILE_CACHE_CAPACITY as q, COMPOSITION_ITEM_ARRAY_PATH as r, ExpressionEvalError as rt, CompositionCodeSourceSchema as s, AUDIO_PRESETS as st, COMPOSED_DEVICE_STABLE_ID_PREFIX as t, EXPRESSION_BUILTINS as tt, CompositionExpressionSourceSchema as u, buildFfmpegArgs as ut, CompositionLiteralBindingSchema as v, MAX_COMPOSITION_CODE_LENGTH as w, CompositionSchema as x, CompositionNewTargetSchema as y, toExpressionValue as z };
+export { MAX_EXPRESSION_AST_NODES as $, compositionFeatureEnabled as A, invocationFromEncodeProfile as At, createStatefulExpressionMemory as B, CompositionTargetSchema as C, Fmp4BoxSplitter as Ct, MAX_COMPOSITION_ITEMS as D, buildFfmpegArgs as Dt, MAX_COMPOSITION_FIELDS_PER_FEATURE as E, buildAudioArgs as Et, featureFieldEntries as F, createExpressionScope as G, evaluateStatefulExpressionCall as H, featureSources as I, compileExpressionSafe as J, evaluateAst as K, fieldReads as L, compositionReadKey as M, logBannerArgs as Mt, compositionSliceKey as N, pickVideoEncoder as Nt, composedDeviceRef as O, buildInputArgs as Ot, compositionSourceKey as P, resolveStreamMaps as Pt, EXPRESSION_IDENTIFIER_RE as Q, EXPRESSION_INJECTED_NOW as R, CompositionSourceRefSchema as S, canonicalHash as St, MAX_COMPOSITION_FEATURES as T, audioPlanFromEncodeProfile as Tt, toExpressionValue as U, evaluateExpressionSource as V, validateExpressionSource as W, tokenize as X, parseExpression as Y, EXPRESSION_COMPILE_CACHE_CAPACITY as Z, CompositionItemEntrySchema as _, evaluateSensorEdge as _t, CUSTOMIZATION_BLOCK_NAME_PREFIX as a, EXPRESSION_BUILTINS as at, CompositionPassthroughFeatureSchema as b, sliceActiveValue as bt, CompositionCommandTargetSchema as c, evaluateRose as ct, CompositionFeatureSchema as d, ExpressionParseError as dt, MAX_EXPRESSION_BINDINGS as et, CompositionFieldReadSchema as f, DEFAULT_FIRST_SIGHTING_FRESHNESS_MS as ft, CompositionFromSourceSchema as g, SOURCE_DEVICE_TYPES as gt, CompositionForwardCommandSchema as h, SOURCE_CAP_CHANGED_AT_FIELD as ht, COMPOSITION_ITEM_KEY_RE as i, RESERVED_BINDING_NAMES as it, compositionItemFieldPath as j, isSoftwareDecode as jt, composedDeviceStableId as k, buildVideoArgs as kt, CompositionExistingTargetSchema as l, isStatefulBuiltin as lt, CompositionFieldsFeatureSchema as m, SOURCE_CAP_ACTIVE_FIELD as mt, COMPOSER_ADDON_ID as n, MAX_EXPRESSION_EVAL_STEPS as nt, CompositionBindingSchema as o, EXPRESSION_BUILTIN_NAMES as ot, CompositionFieldSourceSchema as p, SOURCE_CAPS as pt, compileExpression as q, COMPOSITION_ITEM_ARRAY_PATH as r, MAX_EXPRESSION_SOURCE_LENGTH as rt, CompositionCodeSourceSchema as s, evaluateCount as st, COMPOSED_DEVICE_STABLE_ID_PREFIX as t, MAX_EXPRESSION_CALL_ARGS as tt, CompositionExpressionSourceSchema as u, ExpressionEvalError as ut, CompositionLiteralBindingSchema as v, evaluateSensorLevelEdge as vt, MAX_COMPOSITION_CODE_LENGTH as w, AUDIO_PRESETS as wt, CompositionSchema as x, sliceChangedAt as xt, CompositionNewTargetSchema as y, isSourceCap as yt, cloneStatefulExpressionMemory as z };

package/dist/expression/ast.d.ts

@@ -14,6 +14,8 @@
  */
 /** The only value types the engine produces or consumes. */
 export type ExpressionValue = number | string | boolean | null;
+/** Stable structural address of a node within one parsed expression AST. */
+export type ExpressionNodePath = string;
 export type ExpressionBinaryOperator = '+' | '-' | '*' | '/' | '%' | '==' | '!=' | '<' | '<=' | '>' | '>=';
 export type ExpressionLogicalOperator = '&&' | '||';
 export type ExpressionUnaryOperator = '-' | '!';

package/dist/expression/builtins.d.ts

@@ -16,6 +16,7 @@
  * closed rather than emitting a garbage value.
  */
 import type { ExpressionValue } from './ast.js';
+import type { CountCallState, RoseCallState, 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
@@ -40,6 +41,14 @@ export interface ExpressionBuiltin {
     readonly maxArgs: number;
     readonly apply: (args: readonly ExpressionValue[], hooks: ExpressionEvalHooks) => ExpressionValue;
 }
+export type StatefulExpressionBuiltin = 'rose' | 'count';
+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;
+    readonly startedAtMs: number;
+    readonly nowMs: number;
+}): number | null;
+export declare function evaluateCount(input: unknown, call: CountCallState, currentOutput: unknown): number;
 /** Frozen, null-prototype builtin table. */
 export declare const EXPRESSION_BUILTINS: Readonly<Record<string, ExpressionBuiltin>>;
 /** The set of valid builtin names — used by the parser to reject unknown

package/dist/expression/evaluator.d.ts

@@ -1,8 +1,14 @@
-import { type ExpressionEvalHooks } from './builtins.js';
-import type { ExpressionNode, ExpressionValue } from './ast.js';
+import { type ExpressionEvalHooks, type StatefulExpressionBuiltin } from './builtins.js';
+import type { ExpressionNode, ExpressionNodePath, ExpressionValue } from './ast.js';
+export interface StatefulCallInvocation {
+    readonly name: StatefulExpressionBuiltin;
+    readonly path: ExpressionNodePath;
+    readonly args: readonly ExpressionValue[];
+}
 export interface ExpressionEvalOptions {
     readonly hooks?: ExpressionEvalHooks;
     readonly maxSteps?: number;
+    readonly invokeStateful?: (call: StatefulCallInvocation) => ExpressionValue;
 }
 /** Build a null-prototype scope from own-enumerable binding entries. Inherited
  *  keys of the input (e.g. from a `{__proto__: {...}}` payload) are NOT copied,

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

@@ -9,7 +9,28 @@
  * positions (derive a value, gate a trigger, compute an argument).
  */
 import type { ExpressionValue } from './ast.js';
-import { type ExpressionEvalOptions } from './evaluator.js';
+import { type ExpressionEvalOptions, type StatefulCallInvocation } from './evaluator.js';
+export interface RoseCallState {
+    readonly kind: 'rose';
+    priorLevel?: boolean;
+}
+export interface CountCallState {
+    readonly kind: 'count';
+    highWater: number | null;
+}
+export type StatefulCallState = RoseCallState | CountCallState;
+export interface StatefulExpressionMemory {
+    readonly calls: Map<string, StatefulCallState>;
+    acceptedEdgeAt: number | null;
+}
+export declare function createStatefulExpressionMemory(): StatefulExpressionMemory;
+export declare function cloneStatefulExpressionMemory(memory: StatefulExpressionMemory): StatefulExpressionMemory;
+export interface StatefulExpressionEnvironment {
+    readonly currentOutput: unknown;
+    readonly startedAtMs: number;
+    readonly nowMs: number;
+}
+export declare function evaluateStatefulExpressionCall(invocation: StatefulCallInvocation, memory: StatefulExpressionMemory, env: StatefulExpressionEnvironment): ExpressionValue;
 /** The `now` epoch-ms binding is auto-injected into every evaluation and is a
  *  reserved binding name (authors may not rebind it). */
 export declare const EXPRESSION_INJECTED_NOW = "now";
@@ -46,8 +67,9 @@ export type EvaluateExpressionSourceResult = {
 /**
  * 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.
  */
 export declare function evaluateExpressionSource(expr: string, bindingValues: Readonly<Record<string, ExpressionValue>>, now: number, opts?: ExpressionEvalOptions): EvaluateExpressionSourceResult;

package/dist/expression/index.d.ts

@@ -9,18 +9,18 @@
  * the deep modules (e.g. `../expression/compile.js`), never through this file
  * OR the root barrel (see biome-plugins/no-types-barrel-leaf-import.grit).
  */
-export type { ExpressionBinaryNode, ExpressionBinaryOperator, ExpressionCallNode, ExpressionConditionalNode, ExpressionIdentifierNode, ExpressionLiteralNode, ExpressionLogicalNode, ExpressionLogicalOperator, ExpressionNode, ExpressionUnaryNode, ExpressionUnaryOperator, ExpressionValue, } from './ast.js';
+export type { ExpressionBinaryNode, ExpressionBinaryOperator, ExpressionCallNode, ExpressionConditionalNode, ExpressionIdentifierNode, ExpressionLiteralNode, ExpressionLogicalNode, ExpressionLogicalOperator, ExpressionNode, ExpressionNodePath, ExpressionUnaryNode, ExpressionUnaryOperator, ExpressionValue, } from './ast.js';
 export type { ExpressionBindingSource, ExpressionFieldBinding, ExpressionGlobalBinding, ExpressionLiteralBinding, ExpressionSource, } from './binding-source.js';
 export { ExpressionBindingSourceSchema, ExpressionFieldBindingSchema, ExpressionGlobalBindingSchema, ExpressionLiteralBindingSchema, ExpressionSourceSchema, } from './binding-source.js';
-export type { ExpressionBuiltin, ExpressionEvalHooks } from './builtins.js';
-export { EXPRESSION_BUILTIN_NAMES, EXPRESSION_BUILTINS, } from './builtins.js';
+export type { ExpressionBuiltin, ExpressionEvalHooks, StatefulExpressionBuiltin, } from './builtins.js';
+export { evaluateCount, evaluateRose, EXPRESSION_BUILTIN_NAMES, EXPRESSION_BUILTINS, isStatefulBuiltin, } from './builtins.js';
 export type { CompileResult } from './compile.js';
 export { compileExpression, compileExpressionSafe } from './compile.js';
 export { ExpressionEvalError, ExpressionParseError } from './errors.js';
-export type { ExpressionEvalOptions } from './evaluator.js';
+export type { ExpressionEvalOptions, StatefulCallInvocation } from './evaluator.js';
 export { createExpressionScope, evaluateAst } from './evaluator.js';
-export type { EvaluateExpressionSourceResult, ExpressionSourceInput, } from './expression-source.js';
-export { EXPRESSION_INJECTED_NOW, evaluateExpressionSource, toExpressionValue, validateExpressionSource, } from './expression-source.js';
+export type { CountCallState, EvaluateExpressionSourceResult, ExpressionSourceInput, RoseCallState, StatefulCallState, StatefulExpressionEnvironment, StatefulExpressionMemory, } from './expression-source.js';
+export { cloneStatefulExpressionMemory, createStatefulExpressionMemory, EXPRESSION_INJECTED_NOW, evaluateExpressionSource, evaluateStatefulExpressionCall, toExpressionValue, validateExpressionSource, } from './expression-source.js';
 export { EXPRESSION_COMPILE_CACHE_CAPACITY, EXPRESSION_IDENTIFIER_RE, MAX_EXPRESSION_AST_NODES, MAX_EXPRESSION_BINDINGS, MAX_EXPRESSION_CALL_ARGS, MAX_EXPRESSION_EVAL_STEPS, MAX_EXPRESSION_SOURCE_LENGTH, RESERVED_BINDING_NAMES, } from './limits.js';
 export type { ParsedExpression } from './parser.js';
 export { parseExpression } from './parser.js';

package/dist/index.d.ts

@@ -150,7 +150,7 @@ export { COCO_80_LABELS, COCO_TO_MACRO, DETECTION_MACRO_CLASSES, isDetectionMacr
 export { DEVICE_STATE_READERS, readDeviceStateFrom, stateVocabularyFor, } from './catalogs/device-state-vocabulary.js';
 export { colorForKind, DEFAULT_EVENT_COLOR, EVENT_TAXONOMY, type EventTaxonomyCategory, type EventTaxonomyEntry, type EventTaxonomyLevel, getTaxonomyEntry, subKindsOf, TAXONOMY_COLORS, } from './catalogs/event-taxonomy.js';
 export { buildNcTaxonomy, NC_TAXONOMY, type NcTaxonomy, type NcTaxonomyEntry, NcTaxonomyEntrySchema, NcTaxonomySchema, } from './catalogs/nc-taxonomy.js';
-export { DEFAULT_FIRST_SIGHTING_FRESHNESS_MS, evaluateSensorEdge, isSourceCap, type SensorEdgeIgnoreReason, type SensorEdgeInput, type SensorEdgeVerdict, SOURCE_CAP_ACTIVE_FIELD, SOURCE_CAP_CHANGED_AT_FIELD, SOURCE_CAPS, SOURCE_DEVICE_TYPES, sliceActiveValue, sliceChangedAt, } from './catalogs/sensor-active-state.js';
+export { DEFAULT_FIRST_SIGHTING_FRESHNESS_MS, evaluateSensorEdge, evaluateSensorLevelEdge, isSourceCap, type SensorEdgeIgnoreReason, type SensorEdgeInput, type SensorEdgeVerdict, type SensorLevelEdgeInput, type SensorLevelEdgeVerdict, SOURCE_CAP_ACTIVE_FIELD, SOURCE_CAP_CHANGED_AT_FIELD, SOURCE_CAPS, SOURCE_DEVICE_TYPES, sliceActiveValue, sliceChangedAt, } from './catalogs/sensor-active-state.js';
 export * from './constants.js';
 export type { AccessoryKindValue } from './device/accessory.js';
 export { ACCESSORY_LABEL, AccessoryKind, accessoryStableId, } from './device/accessory.js';
@@ -201,8 +201,8 @@ export type { DeviceConfigEntry } from './device/zod-to-config-ui.js';
 export { zodEntriesToConfigUI } from './device/zod-to-config-ui.js';
 export { EventCategory, isOwnerOnlyEventCategory, OWNER_ONLY_EVENT_CATEGORIES, publicEventCategories, } from './enums/event-category.js';
 export * from './enums/index.js';
-export type { CompileResult, EvaluateExpressionSourceResult, ExpressionBinaryOperator, ExpressionBindingSource, ExpressionBuiltin, ExpressionEvalHooks, ExpressionEvalOptions, ExpressionFieldBinding, ExpressionGlobalBinding, ExpressionLiteralBinding, ExpressionLogicalOperator, ExpressionNode, ExpressionSource, ExpressionSourceInput, ExpressionUnaryOperator, ExpressionValue, Keyword, ParsedExpression, Punctuator, Token, } from './expression/index.js';
-export { compileExpression, compileExpressionSafe, createExpressionScope, EXPRESSION_BUILTIN_NAMES, EXPRESSION_BUILTINS, EXPRESSION_COMPILE_CACHE_CAPACITY, EXPRESSION_IDENTIFIER_RE, EXPRESSION_INJECTED_NOW, ExpressionBindingSourceSchema, ExpressionEvalError, ExpressionFieldBindingSchema, ExpressionGlobalBindingSchema, ExpressionLiteralBindingSchema, ExpressionParseError, ExpressionSourceSchema, evaluateAst, evaluateExpressionSource, MAX_EXPRESSION_AST_NODES, MAX_EXPRESSION_BINDINGS, MAX_EXPRESSION_CALL_ARGS, MAX_EXPRESSION_EVAL_STEPS, MAX_EXPRESSION_SOURCE_LENGTH, parseExpression, RESERVED_BINDING_NAMES, toExpressionValue, tokenize, validateExpressionSource, } from './expression/index.js';
+export type { CompileResult, EvaluateExpressionSourceResult, ExpressionBinaryOperator, ExpressionBindingSource, ExpressionBuiltin, ExpressionEvalHooks, ExpressionEvalOptions, ExpressionFieldBinding, ExpressionGlobalBinding, ExpressionLiteralBinding, ExpressionLogicalOperator, ExpressionNode, ExpressionNodePath, ExpressionSource, ExpressionSourceInput, ExpressionUnaryOperator, ExpressionValue, CountCallState, RoseCallState, StatefulCallState, StatefulCallInvocation, StatefulExpressionEnvironment, StatefulExpressionMemory, StatefulExpressionBuiltin, Keyword, ParsedExpression, Punctuator, Token, } from './expression/index.js';
+export { compileExpression, compileExpressionSafe, cloneStatefulExpressionMemory, createExpressionScope, createStatefulExpressionMemory, EXPRESSION_BUILTIN_NAMES, EXPRESSION_BUILTINS, EXPRESSION_COMPILE_CACHE_CAPACITY, EXPRESSION_IDENTIFIER_RE, EXPRESSION_INJECTED_NOW, ExpressionBindingSourceSchema, ExpressionEvalError, ExpressionFieldBindingSchema, ExpressionGlobalBindingSchema, ExpressionLiteralBindingSchema, ExpressionParseError, ExpressionSourceSchema, evaluateAst, evaluateCount, evaluateExpressionSource, evaluateRose, evaluateStatefulExpressionCall, isStatefulBuiltin, MAX_EXPRESSION_AST_NODES, MAX_EXPRESSION_BINDINGS, MAX_EXPRESSION_CALL_ARGS, MAX_EXPRESSION_EVAL_STEPS, MAX_EXPRESSION_SOURCE_LENGTH, parseExpression, RESERVED_BINDING_NAMES, toExpressionValue, tokenize, validateExpressionSource, } from './expression/index.js';
 export type { AddonApi, AppRouter } from './generated/addon-api.js';
 export type { CapNameWithStatus, CapStatusTypeMap } from './generated/cap-status-types.js';
 export { CAP_NAMES_WITH_STATUS } from './generated/cap-status-types.js';