@camstack/types 1.2.268 → 1.2.269

package/dist/index.js

@@ -1,7 +1,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_sleep = require("./sleep-BSzia-xT.js");
+const require_sleep = require("./sleep-Bg0IB7gg.js");
 const require_event_category = require("./event-category-MbnB-6AN.js");
-const require_composition = require("./composition-QlOB7QTG.js");
+const require_composition = require("./composition-BAH3n-zq.js");
 const require_err_msg = require("./err-msg-Dx2Kor0g.js");
 const require_enums = require("./enums.js");
 let zod = require("zod");
@@ -9333,6 +9333,197 @@ function kebabToCamel(s) {
 	return s.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
 }
 //#endregion
+//#region src/device/schema-fields.ts
+/** Unwrap ZodNullable / ZodOptional / ZodDefault wrappers to reach the inner type.
+*  Zod v4 exposes `.unwrap()` on all three wrapper classes. */
+function unwrapSchema(schema) {
+	let s = schema;
+	while (s instanceof zod.z.ZodNullable || s instanceof zod.z.ZodOptional || s instanceof zod.z.ZodDefault) s = s.unwrap();
+	return s;
+}
+function leafKind(schema) {
+	const s = unwrapSchema(schema);
+	if (s instanceof zod.z.ZodEnum) return {
+		kind: "enum",
+		enumValues: s.options
+	};
+	if (s instanceof zod.z.ZodNumber) return { kind: "number" };
+	if (s instanceof zod.z.ZodString) return { kind: "string" };
+	if (s instanceof zod.z.ZodBoolean) return { kind: "boolean" };
+	return null;
+}
+/** Walk a cap status schema into flat wireable leaf fields (dotted paths).
+*  Recurses into nested ZodObject (unwrapping nullable/optional/default first),
+*  so fields with null live values are still offered. Arrays / unknown shapes
+*  are skipped — never throws. */
+function enumerateSchemaFields(schema, prefix = "") {
+	const root = unwrapSchema(schema);
+	if (!(root instanceof zod.z.ZodObject)) return [];
+	const out = [];
+	const shape = root.shape;
+	for (const [key, field] of Object.entries(shape)) {
+		const path = prefix ? `${prefix}.${key}` : key;
+		const inner = unwrapSchema(field);
+		if (inner instanceof zod.z.ZodObject) {
+			out.push(...enumerateSchemaFields(inner, path));
+			continue;
+		}
+		const leaf = leafKind(field);
+		if (leaf) out.push({
+			path,
+			kind: leaf.kind,
+			...leaf.enumValues ? { enumValues: leaf.enumValues } : {}
+		});
+	}
+	return out;
+}
+/** Enumerate the per-item wireable fields of an item-array cap (see
+*  `CapabilityStatusItemArray`): the item schema's leaf fields, minus the
+*  `keyField` (the key comes from the link's `itemKey`, never from a wired
+*  source), each tagged `item: true` so the authoring UI collects an
+*  `itemKey` alongside the field. Never throws. */
+function enumerateItemArrayFields(itemArray) {
+	return enumerateSchemaFields(itemArray.itemSchema).filter((f) => f.path !== itemArray.keyField).map((f) => ({
+		...f,
+		item: true
+	}));
+}
+//#endregion
+//#region src/composition/state-fields.ts
+/**
+* What a capability's state field IS: kind, nullability, whether required. The
+* validator needs nullability, which `enumerateSchemaFields` does not report,
+* and that decides a field's unavailable mode (D393).
+*/
+function fieldAt(schema, path) {
+	let current = schema;
+	for (const segment of path.split(".")) {
+		const container = unwrapSchema(current);
+		if (!(container instanceof zod.z.ZodObject)) return null;
+		const next = container.shape[segment];
+		if (!(next instanceof zod.z.ZodType)) return null;
+		current = next;
+	}
+	return current;
+}
+function describeStateField(schema, path) {
+	const leaf = enumerateSchemaFields(schema).find((f) => f.path === path);
+	if (leaf === void 0) return null;
+	const field = fieldAt(schema, path);
+	if (field === null) return null;
+	return {
+		path,
+		kind: leaf.kind,
+		nullable: field.safeParse(null).success,
+		required: !field.safeParse(void 0).success,
+		...leaf.enumValues === void 0 ? {} : { enumValues: leaf.enumValues }
+	};
+}
+function describeTopLevelStateFields(schema) {
+	return new Map(enumerateSchemaFields(schema).filter((f) => !f.path.includes(".")).flatMap((f) => {
+		const described = describeStateField(schema, f.path);
+		return described === null ? [] : [[f.path, described]];
+	}));
+}
+/** Top-level keys a value MUST carry: those whose schema refuses `undefined`. */
+function requiredTopLevelKeys(schema) {
+	const root = unwrapSchema(schema);
+	if (!(root instanceof zod.z.ZodObject)) return [];
+	return Object.entries(root.shape).flatMap(([key, field]) => field instanceof zod.z.ZodType && !field.safeParse(void 0).success ? [key] : []);
+}
+/**
+* The proper prefixes of `path` whose schema accepts `undefined`: a required
+* leaf under one of them is required only once something writes that parent
+* (`remaining.unit` is required only when `remaining` is present).
+*/
+function optionalAncestors(schema, path) {
+	const segments = path.split(".");
+	return segments.slice(0, -1).flatMap((_, i) => {
+		const prefix = segments.slice(0, i + 1).join(".");
+		const field = fieldAt(schema, prefix);
+		return field !== null && field.safeParse(void 0).success ? [prefix] : [];
+	});
+}
+//#endregion
+//#region src/composition/composition-events.ts
+var COMPOSITION_EVENT_CATEGORY = { "doorbell.onPressed": require_event_category.EventCategory.DoorbellOnPressed };
+var EVENT_CATEGORIES = COMPOSITION_EVENT_CATEGORY;
+var CompositionEventPlanSchema = zod.z.object({
+	featureIndex: zod.z.number().int().nonnegative(),
+	cap: zod.z.string(),
+	eventName: zod.z.string(),
+	category: zod.z.enum(require_event_category.EventCategory),
+	stateField: zod.z.string(),
+	fieldKey: zod.z.string()
+});
+function eventProblem(code, path, message) {
+	return {
+		code,
+		path,
+		message
+	};
+}
+function payloadReason(error) {
+	return error.issues.map((issue) => `${issue.path.length === 0 ? "payload" : issue.path.join(".")}: ${issue.message}`).join("; ");
+}
+/**
+* Plan one capability's state-derived events after its feature mode and fields
+* are known. A native replacement never becomes a second event authority.
+*/
+function planCompositionEvents(def, feature, fields) {
+	if (feature.mode === "replace") return {
+		problems: [],
+		events: []
+	};
+	const problems = [];
+	const events = [];
+	for (const [eventName, declaration] of Object.entries(def.events ?? {})) {
+		const fromState = declaration.fromState;
+		if (fromState === void 0) continue;
+		const statePath = `features[${feature.featureIndex}].fields.${fromState.field}`;
+		const state = def.runtimeState ? describeStateField(def.runtimeState, fromState.field) : null;
+		if (state === null) {
+			problems.push(eventProblem("unknown-field", statePath, `\`${def.name}.${eventName}\` derives from missing state field \`${fromState.field}\``));
+			continue;
+		}
+		if (state.kind !== "number") {
+			problems.push(eventProblem("kind-mismatch", statePath, `\`${def.name}.${eventName}\` needs a numeric state field; \`${fromState.field}\` is ${state.kind}`));
+			continue;
+		}
+		const eventKey = `${def.name}.${eventName}`;
+		const category = EVENT_CATEGORIES[eventKey];
+		if (category === void 0) {
+			problems.push(eventProblem("not-composable", `features[${feature.featureIndex}].cap`, `\`${eventKey}\` has no explicit composition event-category mapping`));
+			continue;
+		}
+		const payload = declaration.data.safeParse({
+			deviceId: 1,
+			timestamp: 1
+		});
+		if (!payload.success) {
+			problems.push(eventProblem("not-composable", `features[${feature.featureIndex}].cap`, `\`${eventKey}\` cannot be derived from { deviceId, timestamp }: ${payloadReason(payload.error)}`));
+			continue;
+		}
+		const field = fields.find((candidate) => candidate.featureIndex === feature.featureIndex && candidate.cap === def.name && candidate.path === fromState.field && candidate.item === void 0);
+		if (field === void 0) {
+			problems.push(eventProblem("unknown-field", statePath, `\`${eventKey}\` derives from \`${fromState.field}\`, but that field is not composed`));
+			continue;
+		}
+		events.push({
+			featureIndex: feature.featureIndex,
+			cap: def.name,
+			eventName,
+			category,
+			stateField: fromState.field,
+			fieldKey: `${field.cap}.${field.path}`
+		});
+	}
+	return {
+		problems,
+		events
+	};
+}
+//#endregion
 //#region src/composition/composition-report.ts
 /**
 * What the validator says about a composition and what the composer says about
@@ -9388,12 +9579,14 @@ var CompositionUnavailableModeSchema = zod.z.enum([
 ]);
 /**
 * `derived` reads a source · `clock` reads only `now`, recomputed when a sibling
-* field of its cap changes value · `constant` reads nothing, computed once.
+* field of its cap changes value · `constant` reads nothing, computed once ·
+* `accumulator` advances from the target's seed/current output.
 */
 var CompositionFieldRoleSchema = zod.z.enum([
 	"derived",
 	"clock",
-	"constant"
+	"constant",
+	"accumulator"
 ]);
 /** The item a planned field belongs to; its `path` is then the dotted path INSIDE the item. */
 var CompositionFieldItemSchema = zod.z.object({
@@ -9434,6 +9627,7 @@ var CompositionFeatureModeSchema = zod.z.enum([
 	"replace"
 ]);
 var CompositionFeaturePlanSchema = zod.z.object({
+	/** Index in the stored feature array; disabled features are omitted rather than re-indexed. */
 	featureIndex: zod.z.number().int().nonnegative(),
 	cap: zod.z.string(),
 	mode: CompositionFeatureModeSchema
@@ -9442,7 +9636,8 @@ var CompositionValidationSchema = zod.z.object({
 	ok: zod.z.boolean(),
 	problems: zod.z.array(CompositionProblemSchema),
 	fields: zod.z.array(CompositionFieldPlanSchema),
-	features: zod.z.array(CompositionFeaturePlanSchema)
+	features: zod.z.array(CompositionFeaturePlanSchema),
+	events: zod.z.array(CompositionEventPlanSchema)
 });
 /**
 * Mirrors `CoreBlockStatus`, pinned by `core-blocks-source.spec.ts`. `degraded`:
@@ -29781,172 +29976,6 @@ var CLIP_PLAYBACK_OPTIONS = {
 	}
 };
 //#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;
-/**
-* 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 (input.prior === void 0) {
-		if (!value) return {
-			edge: "none",
-			value,
-			reason: "baseline-seeded-inactive"
-		};
-		const changedAt = sliceChangedAt(input.capName, input.slice);
-		const floor = Math.max(input.startedAtMs, input.nowMs - input.firstSightingFreshnessMs);
-		if (changedAt === null || changedAt < floor) return {
-			edge: "none",
-			value,
-			reason: "baseline-seeded-stale-active"
-		};
-		return {
-			edge: "rising",
-			value: true
-		};
-	}
-	if (input.prior === value) return {
-		edge: "none",
-		value,
-		reason: "no-change"
-	};
-	if (!value) return {
-		edge: "none",
-		value,
-		reason: "falling-edge"
-	};
-	return {
-		edge: "rising",
-		value: true
-	};
-}
-//#endregion
 //#region src/capabilities/doorbell.cap.ts
 /**
 * Doorbell button cap. Two kinds of providers coexist behind this cap
@@ -30001,7 +30030,7 @@ var DOORBELL_SOURCE_SLOT = {
 	description: "Any of these becoming active rings this camera's virtual doorbell: a binary sensor when it goes active, a switch when it turns on.",
 	shape: "association",
 	hostDeviceTypes: [require_err_msg.DeviceType.Camera],
-	sourceCaps: SOURCE_CAPS,
+	sourceCaps: require_composition.SOURCE_CAPS,
 	cardinality: "many",
 	value: DoorbellSourceSlotValueSchema
 };
@@ -30021,7 +30050,13 @@ var doorbellCapability = {
 	* push (`ReolinkSimpleEvent.type === 'doorbell'`). There is no
 	* release/duration — it's a pulse.
 	*/
-onPressed: { data: DoorbellPressEventSchema } },
+onPressed: {
+		data: DoorbellPressEventSchema,
+		fromState: {
+			field: "lastPressedAt",
+			on: "advance"
+		}
+	} },
 	status: {
 		schema: DoorbellStatusSchema,
 		kind: "push"
@@ -44506,7 +44541,7 @@ function createDeviceExtensionProvider(options) {
 var CompositionGraphError = class extends Error {};
 /** `"cap.field"` of every field a peer writes — the same spelling as `compositionFieldKey`. */
 function writtenFields(peer) {
-	return new Set(peer.composition.features.flatMap((feature) => feature.kind !== "fields" ? [] : require_composition.featureFieldEntries(feature).map(({ fieldPath }) => `${feature.cap}.${fieldPath}`)));
+	return new Set(peer.composition.features.flatMap((feature) => !require_composition.compositionFeatureEnabled(feature) || feature.kind !== "fields" ? [] : require_composition.featureFieldEntries(feature).map(({ fieldPath }) => `${feature.cap}.${fieldPath}`)));
 }
 /** A read of the peer's OWN device is an edge only when it reads the peer's own output (rule 5, D663). */
 function readsComposedValue(peer, written, read) {
@@ -44516,7 +44551,7 @@ function readsComposedValue(peer, written, read) {
 }
 function peerEdges(peer) {
 	const written = writtenFields(peer);
-	return peer.composition.features.flatMap((feature) => feature.kind !== "fields" ? [] : require_composition.featureFieldEntries(feature).map(({ fieldPath, source }) => [require_composition.compositionReadKey({
+	return peer.composition.features.flatMap((feature) => !require_composition.compositionFeatureEnabled(feature) || feature.kind !== "fields" ? [] : require_composition.featureFieldEntries(feature).map(({ fieldPath, source }) => [require_composition.compositionReadKey({
 		source: peer.target,
 		cap: feature.cap,
 		fieldPath
@@ -44642,118 +44677,6 @@ function findCandidateCycles(candidate, stored) {
 	});
 }
 //#endregion
-//#region src/device/schema-fields.ts
-/** Unwrap ZodNullable / ZodOptional / ZodDefault wrappers to reach the inner type.
-*  Zod v4 exposes `.unwrap()` on all three wrapper classes. */
-function unwrapSchema(schema) {
-	let s = schema;
-	while (s instanceof zod.z.ZodNullable || s instanceof zod.z.ZodOptional || s instanceof zod.z.ZodDefault) s = s.unwrap();
-	return s;
-}
-function leafKind(schema) {
-	const s = unwrapSchema(schema);
-	if (s instanceof zod.z.ZodEnum) return {
-		kind: "enum",
-		enumValues: s.options
-	};
-	if (s instanceof zod.z.ZodNumber) return { kind: "number" };
-	if (s instanceof zod.z.ZodString) return { kind: "string" };
-	if (s instanceof zod.z.ZodBoolean) return { kind: "boolean" };
-	return null;
-}
-/** Walk a cap status schema into flat wireable leaf fields (dotted paths).
-*  Recurses into nested ZodObject (unwrapping nullable/optional/default first),
-*  so fields with null live values are still offered. Arrays / unknown shapes
-*  are skipped — never throws. */
-function enumerateSchemaFields(schema, prefix = "") {
-	const root = unwrapSchema(schema);
-	if (!(root instanceof zod.z.ZodObject)) return [];
-	const out = [];
-	const shape = root.shape;
-	for (const [key, field] of Object.entries(shape)) {
-		const path = prefix ? `${prefix}.${key}` : key;
-		const inner = unwrapSchema(field);
-		if (inner instanceof zod.z.ZodObject) {
-			out.push(...enumerateSchemaFields(inner, path));
-			continue;
-		}
-		const leaf = leafKind(field);
-		if (leaf) out.push({
-			path,
-			kind: leaf.kind,
-			...leaf.enumValues ? { enumValues: leaf.enumValues } : {}
-		});
-	}
-	return out;
-}
-/** Enumerate the per-item wireable fields of an item-array cap (see
-*  `CapabilityStatusItemArray`): the item schema's leaf fields, minus the
-*  `keyField` (the key comes from the link's `itemKey`, never from a wired
-*  source), each tagged `item: true` so the authoring UI collects an
-*  `itemKey` alongside the field. Never throws. */
-function enumerateItemArrayFields(itemArray) {
-	return enumerateSchemaFields(itemArray.itemSchema).filter((f) => f.path !== itemArray.keyField).map((f) => ({
-		...f,
-		item: true
-	}));
-}
-//#endregion
-//#region src/composition/state-fields.ts
-/**
-* What a capability's state field IS: kind, nullability, whether required. The
-* validator needs nullability, which `enumerateSchemaFields` does not report,
-* and that decides a field's unavailable mode (D393).
-*/
-function fieldAt(schema, path) {
-	let current = schema;
-	for (const segment of path.split(".")) {
-		const container = unwrapSchema(current);
-		if (!(container instanceof zod.z.ZodObject)) return null;
-		const next = container.shape[segment];
-		if (!(next instanceof zod.z.ZodType)) return null;
-		current = next;
-	}
-	return current;
-}
-function describeStateField(schema, path) {
-	const leaf = enumerateSchemaFields(schema).find((f) => f.path === path);
-	if (leaf === void 0) return null;
-	const field = fieldAt(schema, path);
-	if (field === null) return null;
-	return {
-		path,
-		kind: leaf.kind,
-		nullable: field.safeParse(null).success,
-		required: !field.safeParse(void 0).success,
-		...leaf.enumValues === void 0 ? {} : { enumValues: leaf.enumValues }
-	};
-}
-function describeTopLevelStateFields(schema) {
-	return new Map(enumerateSchemaFields(schema).filter((f) => !f.path.includes(".")).flatMap((f) => {
-		const described = describeStateField(schema, f.path);
-		return described === null ? [] : [[f.path, described]];
-	}));
-}
-/** Top-level keys a value MUST carry: those whose schema refuses `undefined`. */
-function requiredTopLevelKeys(schema) {
-	const root = unwrapSchema(schema);
-	if (!(root instanceof zod.z.ZodObject)) return [];
-	return Object.entries(root.shape).flatMap(([key, field]) => field instanceof zod.z.ZodType && !field.safeParse(void 0).success ? [key] : []);
-}
-/**
-* The proper prefixes of `path` whose schema accepts `undefined`: a required
-* leaf under one of them is required only once something writes that parent
-* (`remaining.unit` is required only when `remaining` is present).
-*/
-function optionalAncestors(schema, path) {
-	const segments = path.split(".");
-	return segments.slice(0, -1).flatMap((_, i) => {
-		const prefix = segments.slice(0, i + 1).join(".");
-		const field = fieldAt(schema, prefix);
-		return field !== null && field.safeParse(void 0).success ? [prefix] : [];
-	});
-}
-//#endregion
 //#region src/composition/plan-result.ts
 function problem(code, path, message) {
 	return {
@@ -44766,7 +44689,8 @@ function refused(...problems) {
 	return {
 		problems,
 		fields: [],
-		features: []
+		features: [],
+		events: []
 	};
 }
 /** Where a planned field sits in the composition: `features[N].fields.<path>` or `features[N].items.<key>.fields.<path>`. */
@@ -44810,7 +44734,12 @@ var BUILTIN_RESULT_KINDS = Object.freeze({
 	number: {
 		kind: "fixed",
 		result: ["number", "null"]
-	}
+	},
+	rose: {
+		kind: "fixed",
+		result: ["number", "null"]
+	},
+	count: NUMBER
 });
 var KindInferenceError = class extends Error {};
 function kindOfValue(value) {
@@ -44869,6 +44798,21 @@ function kindsOf(node, bindings) {
 		case "call": return callKinds(node.callee, node.args.map((a) => kindsOf(a, bindings)));
 	}
 }
+function nodeContainsCall(node, callee) {
+	switch (node.kind) {
+		case "literal":
+		case "identifier": return false;
+		case "unary": return nodeContainsCall(node.operand, callee);
+		case "binary":
+		case "logical": return nodeContainsCall(node.left, callee) || nodeContainsCall(node.right, callee);
+		case "conditional": return nodeContainsCall(node.test, callee) || nodeContainsCall(node.consequent, callee) || nodeContainsCall(node.alternate, callee);
+		case "call": return node.callee === callee || node.args.some((arg) => nodeContainsCall(arg, callee));
+	}
+}
+function expressionContainsBuiltinCall(expr, callee) {
+	const compiled = require_composition.compileExpressionSafe(expr);
+	return compiled.ok && nodeContainsCall(compiled.parsed.ast, callee);
+}
 function inferExpressionKinds(input) {
 	const compiled = require_composition.compileExpressionSafe(input.expr);
 	if (!compiled.ok) return {
@@ -44991,6 +44935,7 @@ function enumLiteralProblem(cap, target, source, at) {
 }
 function roleOf(source) {
 	if (source.kind !== "expression") return "derived";
+	if (expressionContainsBuiltinCall(source.expr, "count")) return "accumulator";
 	if (require_composition.fieldReads(source).length > 0) return "derived";
 	const compiled = require_composition.compileExpressionSafe(source.expr);
 	return compiled.ok && compiled.parsed.identifiers.has("now") ? "clock" : "constant";
@@ -45002,13 +44947,13 @@ function roleOf(source) {
 * field that READS a source never gets `offline`.
 */
 function unavailableFor(tf, role, mode, cap, at) {
-	if (mode === "new" || role !== "derived") return {
+	if (mode === "replace" && (role === "derived" || role === "accumulator")) return {
 		ok: true,
-		unavailable: tf.nullable ? "null" : "offline"
+		unavailable: "release"
 	};
-	if (mode === "replace") return {
+	if (mode === "new" || role !== "derived") return {
 		ok: true,
-		unavailable: "release"
+		unavailable: tf.nullable ? "null" : "offline"
 	};
 	if (tf.nullable) return {
 		ok: true,
@@ -45083,7 +45028,8 @@ function planItemField(ctx, leaf) {
 	return {
 		problems: [...compatibility(capName, tf, kinds.kinds, at), ...enumProblem === null ? [] : [enumProblem]],
 		fields: [plan],
-		features: []
+		features: [],
+		events: []
 	};
 }
 function planItems(def, feature, featureIndex, lookupCap, mode = "new") {
@@ -45102,7 +45048,8 @@ function planItems(def, feature, featureIndex, lookupCap, mode = "new") {
 	const results = Object.entries(feature.items ?? {}).flatMap(([key, item]) => [{
 		problems: missingLeaves(ctx, item, `${at}.${key}`),
 		fields: [],
-		features: []
+		features: [],
+		events: []
 	}, ...Object.entries(item.fields).map(([path, source]) => planItemField(ctx, {
 		key,
 		label: item.label,
@@ -45112,7 +45059,8 @@ function planItems(def, feature, featureIndex, lookupCap, mode = "new") {
 	return {
 		problems: results.flatMap((r) => r.problems),
 		fields: results.flatMap((r) => r.fields),
-		features: []
+		features: [],
+		events: []
 	};
 }
 //#endregion
@@ -45138,7 +45086,7 @@ function fromReading(reading, read) {
 		deadline: null
 	};
 }
-function expressionOutcome(source, read, now) {
+function expressionOutcome(source, read, now, stateful) {
 	const values = {};
 	const staleReasons = [];
 	let fatalUnavailable = null;
@@ -45167,10 +45115,31 @@ function expressionOutcome(source, read, now) {
 		values[name] = reading.value;
 		if (reading.state === "stale") staleReasons.push(`\`${name}\`: ${reading.reason}`);
 	}
-	if (fatalUnavailable !== null) return fatalUnavailable;
-	if (nonFatalUnavailable !== null) return nonFatalUnavailable;
+	const unavailable = fatalUnavailable ?? nonFatalUnavailable;
+	if (unavailable !== null) {
+		if (stateful !== void 0 && stateful.currentOutput !== void 0 && expressionContainsBuiltinCall(source.expr, "count")) return {
+			state: "stale",
+			value: require_composition.evaluateCount(null, {
+				kind: "count",
+				highWater: null
+			}, stateful.currentOutput),
+			reason: `${unavailable.reason}; holding the last accumulator value`,
+			deadline: null
+		};
+		return unavailable;
+	}
 	const deadlines = [];
-	const result = require_composition.evaluateExpressionSource(source.expr, values, now, { hooks: { noteDeadline: (at) => deadlines.push(at) } });
+	const result = require_composition.evaluateExpressionSource(source.expr, values, now, {
+		hooks: { noteDeadline: (at) => deadlines.push(at) },
+		...stateful === void 0 ? {} : { invokeStateful: (invocation) => require_composition.evaluateStatefulExpressionCall(stateful.callPathPrefix === void 0 ? invocation : {
+			...invocation,
+			path: `${stateful.callPathPrefix}@${invocation.path}`
+		}, stateful.expressionMemory, {
+			currentOutput: stateful.currentOutput,
+			startedAtMs: stateful.startedAtMs,
+			nowMs: now
+		}) }
+	});
 	if (!result.ok) return {
 		state: "unavailable",
 		value: null,
@@ -45189,7 +45158,7 @@ function evaluateCompositionField(input) {
 	const { source } = input;
 	switch (source.kind) {
 		case "from": return fromReading(input.read(source), source);
-		case "expression": return expressionOutcome(source, input.read, input.now);
+		case "expression": return expressionOutcome(source, input.read, input.now, input.stateful);
 		case "code": return {
 			state: "unavailable",
 			value: null,
@@ -45471,7 +45440,8 @@ function planTopLevelField({ def, fields }, field, mode, lookupCap) {
 	return {
 		problems: [...compatibility(def.name, tf, kinds.kinds, fieldAt), ...enumProblem === null ? [] : [enumProblem]],
 		fields: [plan],
-		features: []
+		features: [],
+		events: []
 	};
 }
 function planFeature(feature, featureIndex, target, lookupCap) {
@@ -45487,14 +45457,22 @@ function planFeature(feature, featureIndex, target, lookupCap) {
 	}, target.mode, lookupCap));
 	const items = feature.items === void 0 ? [] : [planItems(cap.def, feature, featureIndex, lookupCap, target.mode)];
 	const all = [...perField, ...items];
+	const fields = all.flatMap((result) => result.fields);
+	const featurePlan = {
+		featureIndex,
+		cap: cap.def.name,
+		mode: target.mode
+	};
+	const eventPlan = planCompositionEvents(cap.def, featurePlan, fields);
 	return {
-		problems: [...capProblems, ...all.flatMap((r) => r.problems)],
-		fields: all.flatMap((r) => r.fields),
-		features: [{
-			featureIndex,
-			cap: cap.def.name,
-			mode: target.mode
-		}]
+		problems: [
+			...capProblems,
+			...all.flatMap((r) => r.problems),
+			...eventPlan.problems
+		],
+		fields,
+		features: [featurePlan],
+		events: eventPlan.events
 	};
 }
 /** A cap the device serves itself; one the composer grafted (an earlier ADD) is not native. */
@@ -45536,17 +45514,23 @@ function planComposition(composition, lookupCap, target) {
 	const planTarget = planTargetOf(composition, target);
 	if ("code" in planTarget) return refused(planTarget);
 	const results = composition.features.map((feature, index) => {
-		if (feature.kind === "passthrough") return refused(problem("reserved-variant", `features[${index}]`, `whole-capability passthrough of \`${feature.cap}\` arrives in slice 3`));
-		return planFeature(feature, index, featureTargetOf(planTarget, feature.cap), lookupCap);
+		const result = feature.kind === "passthrough" ? refused(problem("reserved-variant", `features[${index}]`, `whole-capability passthrough of \`${feature.cap}\` arrives in slice 3`)) : planFeature(feature, index, featureTargetOf(planTarget, feature.cap), lookupCap);
+		return require_composition.compositionFeatureEnabled(feature) ? result : {
+			problems: result.problems,
+			fields: [],
+			features: [],
+			events: []
+		};
 	});
 	return {
 		problems: results.flatMap((r) => r.problems),
 		fields: results.flatMap((r) => r.fields),
-		features: results.flatMap((r) => r.features)
+		features: results.flatMap((r) => r.features),
+		events: results.flatMap((r) => r.events)
 	};
 }
 function compositionSourceRefs(composition) {
-	const refs = composition.features.flatMap((f) => f.kind === "fields" ? require_composition.featureSources(f).flatMap(require_composition.fieldReads).map((r) => r.source) : []);
+	const refs = composition.features.flatMap((f) => require_composition.compositionFeatureEnabled(f) && f.kind === "fields" ? require_composition.featureSources(f).flatMap(require_composition.fieldReads).map((r) => r.source) : []);
 	return [...new Map(refs.map((r) => [require_composition.compositionSourceKey(r), r])).values()];
 }
 /**
@@ -45681,7 +45665,8 @@ function validateComposition(composition, ctx) {
 		ok: problems.length === 0,
 		problems,
 		fields: [...plan.fields],
-		features: [...plan.features]
+		features: [...plan.features],
+		events: [...plan.events]
 	};
 }
 //#endregion
@@ -64185,7 +64170,7 @@ var NC_SENSOR_TRANSITION_NEVER_FIRES_WARNING = "This rule belongs to the alarm,
 */
 /** Event kind → the boolean field of its cap slice that means "raised". */
 var NC_SENSOR_RAISED_FIELD_BY_KIND = Object.freeze(Object.fromEntries(Object.entries(EVENT_KIND_BY_CAP).flatMap(([capName, descriptor]) => {
-	const field = SOURCE_CAP_ACTIVE_FIELD[capName];
+	const field = require_composition.SOURCE_CAP_ACTIVE_FIELD[capName];
 	if (field === void 0 || descriptor.category !== "sensor") return [];
 	return [[descriptor.kind, field]];
 })));
@@ -68287,6 +68272,7 @@ exports.COMPOSED_DEVICE_STABLE_ID_PREFIX = require_composition.COMPOSED_DEVICE_S
 exports.COMPOSED_ITEM_FIXED_FIELDS = COMPOSED_ITEM_FIXED_FIELDS;
 exports.COMPOSER_ADDON_ID = require_composition.COMPOSER_ADDON_ID;
 exports.COMPOSER_RUNNER_ID = COMPOSER_RUNNER_ID;
+exports.COMPOSITION_EVENT_CATEGORY = COMPOSITION_EVENT_CATEGORY;
 exports.COMPOSITION_ITEM_ARRAY_PATH = require_composition.COMPOSITION_ITEM_ARRAY_PATH;
 exports.COMPOSITION_ITEM_KEY_RE = require_composition.COMPOSITION_ITEM_KEY_RE;
 exports.CONNECTION_TEST_TIMEOUT_MS = CONNECTION_TEST_TIMEOUT_MS;
@@ -68371,6 +68357,7 @@ exports.CompositionBlockStateSchema = CompositionBlockStateSchema;
 exports.CompositionCodeSourceSchema = require_composition.CompositionCodeSourceSchema;
 exports.CompositionCommandTargetSchema = require_composition.CompositionCommandTargetSchema;
 exports.CompositionCustomizationReadSchema = CompositionCustomizationReadSchema;
+exports.CompositionEventPlanSchema = CompositionEventPlanSchema;
 exports.CompositionExistingTargetSchema = require_composition.CompositionExistingTargetSchema;
 exports.CompositionExpressionSourceSchema = require_composition.CompositionExpressionSourceSchema;
 exports.CompositionFeatureModeSchema = CompositionFeatureModeSchema;
@@ -68451,7 +68438,7 @@ exports.DEFAULT_DETAIL_CROP_CONVENTION = DEFAULT_DETAIL_CROP_CONVENTION;
 exports.DEFAULT_EVENTS_BAND_BUFFER_SEC = DEFAULT_EVENTS_BAND_BUFFER_SEC;
 exports.DEFAULT_EVENT_COLOR = DEFAULT_EVENT_COLOR;
 exports.DEFAULT_FEATURES = DEFAULT_FEATURES;
-exports.DEFAULT_FIRST_SIGHTING_FRESHNESS_MS = DEFAULT_FIRST_SIGHTING_FRESHNESS_MS;
+exports.DEFAULT_FIRST_SIGHTING_FRESHNESS_MS = require_composition.DEFAULT_FIRST_SIGHTING_FRESHNESS_MS;
 exports.DEFAULT_MIN_LANDMARK_FACE_SIZE_PX = DEFAULT_MIN_LANDMARK_FACE_SIZE_PX;
 exports.DEFAULT_NATIVE_LEASE_SETTINGS = DEFAULT_NATIVE_LEASE_SETTINGS;
 exports.DEFAULT_OVERLAY_LAYERS = DEFAULT_OVERLAY_LAYERS;
@@ -69245,10 +69232,10 @@ exports.SCOPE_PRESETS = SCOPE_PRESETS;
 exports.SENSOR_FEATURES = SENSOR_FEATURES;
 exports.SENSOR_MAP = SENSOR_MAP;
 exports.SHARE_VIEW_KINDS = require_sleep.SHARE_VIEW_KINDS;
-exports.SOURCE_CAPS = SOURCE_CAPS;
-exports.SOURCE_CAP_ACTIVE_FIELD = SOURCE_CAP_ACTIVE_FIELD;
-exports.SOURCE_CAP_CHANGED_AT_FIELD = SOURCE_CAP_CHANGED_AT_FIELD;
-exports.SOURCE_DEVICE_TYPES = SOURCE_DEVICE_TYPES;
+exports.SOURCE_CAPS = require_composition.SOURCE_CAPS;
+exports.SOURCE_CAP_ACTIVE_FIELD = require_composition.SOURCE_CAP_ACTIVE_FIELD;
+exports.SOURCE_CAP_CHANGED_AT_FIELD = require_composition.SOURCE_CAP_CHANGED_AT_FIELD;
+exports.SOURCE_DEVICE_TYPES = require_composition.SOURCE_DEVICE_TYPES;
 exports.SOURCE_INFO_METADATA_KEY = SOURCE_INFO_METADATA_KEY;
 exports.STATIONARY_OVERLAY_STYLE = STATIONARY_OVERLAY_STYLE;
 exports.STORAGE_ACCESS_FALLBACK = STORAGE_ACCESS_FALLBACK;
@@ -69560,6 +69547,7 @@ exports.climateControlCapability = climateControlCapability;
 exports.clipExportFailure = clipExportFailure;
 exports.clipExportFailureOf = clipExportFailureOf;
 exports.clipReasonHeaderValue = clipReasonHeaderValue;
+exports.cloneStatefulExpressionMemory = require_composition.cloneStatefulExpressionMemory;
 exports.clusterModelSettingKey = clusterModelSettingKey;
 exports.clusterStepSettingFieldsFor = clusterStepSettingFieldsFor;
 exports.clusterStepSettingKey = clusterStepSettingKey;
@@ -69578,6 +69566,7 @@ exports.composedDeviceRef = require_composition.composedDeviceRef;
 exports.composedDeviceStableId = require_composition.composedDeviceStableId;
 exports.composerCapability = composerCapability;
 exports.compositionEdges = compositionEdges;
+exports.compositionFeatureEnabled = require_composition.compositionFeatureEnabled;
 exports.compositionFieldKey = compositionFieldKey;
 exports.compositionItemFieldPath = require_composition.compositionItemFieldPath;
 exports.compositionReadKey = require_composition.compositionReadKey;
@@ -69614,6 +69603,7 @@ exports.createLogChannelsProvider = createLogChannelsProvider;
 exports.createMirrorSource = require_sleep.createMirrorSource;
 exports.createRuntimeStateBridge = createRuntimeStateBridge;
 exports.createSliceHandle = require_sleep.createSliceHandle;
+exports.createStatefulExpressionMemory = require_composition.createStatefulExpressionMemory;
 exports.createSystemProxy = createSystemProxy;
 exports.customAction = require_sleep.customAction;
 exports.customModelRegistryCapability = customModelRegistryCapability;
@@ -69680,9 +69670,13 @@ exports.enumerateSchemaFields = enumerateSchemaFields;
 exports.errMsg = require_err_msg.errMsg;
 exports.evaluateAst = require_composition.evaluateAst;
 exports.evaluateCompositionField = evaluateCompositionField;
+exports.evaluateCount = require_composition.evaluateCount;
 exports.evaluateExpressionSource = require_composition.evaluateExpressionSource;
 exports.evaluatePoolMemory = evaluatePoolMemory;
-exports.evaluateSensorEdge = evaluateSensorEdge;
+exports.evaluateRose = require_composition.evaluateRose;
+exports.evaluateSensorEdge = require_composition.evaluateSensorEdge;
+exports.evaluateSensorLevelEdge = require_composition.evaluateSensorLevelEdge;
+exports.evaluateStatefulExpressionCall = require_composition.evaluateStatefulExpressionCall;
 exports.evaluateZoneRules = evaluateZoneRules;
 exports.event = require_sleep.event;
 exports.eventEmitterCapability = eventEmitterCapability;
@@ -69692,6 +69686,7 @@ exports.expandAudioChunkToF32le = require_sleep.expandAudioChunkToF32le;
 exports.expandCapMethods = require_sleep.expandCapMethods;
 exports.expandContainer = expandContainer;
 exports.exportSubjectOf = exportSubjectOf;
+exports.expressionContainsBuiltinCall = expressionContainsBuiltinCall;
 exports.extensionSlotRef = extensionSlotRef;
 exports.extractNestedAddonId = extractNestedAddonId;
 exports.extractSourceInfoFromMetadata = extractSourceInfoFromMetadata;
@@ -69771,7 +69766,8 @@ exports.isSameAddonId = isSameAddonId;
 exports.isScheduleActive = isScheduleActive;
 exports.isSecretConfigField = isSecretConfigField;
 exports.isSoftwareDecode = require_composition.isSoftwareDecode;
-exports.isSourceCap = isSourceCap;
+exports.isSourceCap = require_composition.isSourceCap;
+exports.isStatefulBuiltin = require_composition.isStatefulBuiltin;
 exports.isStorageLocationMode = isStorageLocationMode;
 exports.isSystemDelivery = isSystemDelivery;
 exports.isSystemEventFamily = isSystemEventFamily;
@@ -69887,6 +69883,7 @@ exports.pipelineExecutorCapability = pipelineExecutorCapability;
 exports.pipelineOrchestratorCapability = pipelineOrchestratorCapability;
 exports.pipelineRunnerCapability = pipelineRunnerCapability;
 exports.planComposition = planComposition;
+exports.planCompositionEvents = planCompositionEvents;
 exports.planItems = planItems;
 exports.plateGalleryCapability = plateGalleryCapability;
 exports.platformProbeCapability = platformProbeCapability;
@@ -69986,8 +69983,8 @@ exports.signalPercentFromRssi = signalPercentFromRssi;
 exports.siteZoneKey = siteZoneKey;
 exports.sleep = require_sleep.sleep;
 exports.sleepCancellable = require_sleep.sleepCancellable;
-exports.sliceActiveValue = sliceActiveValue;
-exports.sliceChangedAt = sliceChangedAt;
+exports.sliceActiveValue = require_composition.sliceActiveValue;
+exports.sliceChangedAt = require_composition.sliceChangedAt;
 exports.smokeCapability = smokeCapability;
 exports.smtpProviderCapability = smtpProviderCapability;
 exports.snapshotCapability = snapshotCapability;