@camstack/system 1.2.456 → 1.2.457

package/dist/builtins/device-history/device-history.addon.js

@@ -3,7 +3,7 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 require("../../chunk-Cek0wNdY.js");
-const require_dist = require("../../dist-BpqA2CT0.js");
+const require_dist = require("../../dist-C89nqNnn.js");
 //#region src/builtins/device-history/store/series-registry.ts
 function subjectIdOf(subject) {
 	return subject.kind === "device" ? `d:${subject.deviceId}` : `n:${subject.nodeId}`;
@@ -11,16 +11,29 @@ function subjectIdOf(subject) {
 function deviceIdOf(subject) {
 	return subject.kind === "device" ? subject.deviceId : null;
 }
+/** Every metric key is a cap field (`cap:`), an addon's series (`addon:`) or derived. */
+function isMetricKey(key) {
+	return key.startsWith("cap:") || key.startsWith("addon:");
+}
 function identityOf(key, subjectId, scope) {
 	return `${key}\u0000${subjectId}\u0000${scope}`;
 }
 var LOAD_PAGE = 5e3;
+/** Append what `next` names that `stored` lacks, in `next`'s order: an ordinal never moves. */
+function mergeEnumValues(stored, next) {
+	if (stored === null) return next;
+	if (next === null) return stored;
+	const missing = next.filter((v) => !stored.includes(v));
+	return missing.length === 0 ? stored : [...stored, ...missing];
+}
 var SeriesRegistry = class {
 	store;
 	metrics = /* @__PURE__ */ new Map();
 	byIdentity = /* @__PURE__ */ new Map();
 	byId = /* @__PURE__ */ new Map();
 	inflight = /* @__PURE__ */ new Map();
+	/** Enum metrics whose value list grew in memory and is not stored yet. */
+	dirtyMetrics = /* @__PURE__ */ new Set();
 	removeListeners = [];
 	constructor(store) {
 		this.store = store;
@@ -29,7 +42,10 @@ var SeriesRegistry = class {
 		this.metrics.clear();
 		this.byIdentity.clear();
 		this.byId.clear();
-		for (const m of await this.store.loadMetrics()) this.metrics.set(m.key, m);
+		const stray = [];
+		for (const m of await this.store.loadMetrics()) if (isMetricKey(m.key)) this.metrics.set(m.key, m);
+		else stray.push(m.key);
+		if (stray.length > 0) await this.store.deleteMetrics(stray);
 		let afterId = 0;
 		for (;;) {
 			const page = await this.store.loadSeriesPage(afterId, LOAD_PAGE);
@@ -49,12 +65,48 @@ var SeriesRegistry = class {
 	allMetrics() {
 		return [...this.metrics.values()];
 	}
-	/** Persist and remember a metric; idempotent. */
+	/**
+	* Persist and remember a metric; idempotent. An `enum` value list is MERGED
+	* append-only with the stored one, so reordering a `z.enum` never changes
+	* what a stored ordinal means.
+	*/
 	async declareMetric(metric) {
 		const existing = this.metrics.get(metric.key);
-		if (existing !== void 0 && sameMetric(existing, metric)) return;
-		await this.store.upsertMetric(metric);
-		this.metrics.set(metric.key, metric);
+		const merged = {
+			...metric,
+			values: mergeEnumValues(existing?.values ?? null, metric.values)
+		};
+		if (existing !== void 0 && sameMetric(existing, merged)) return;
+		await this.store.upsertMetric(merged);
+		this.metrics.set(metric.key, merged);
+	}
+	/**
+	* The ordinal of `value` in an `enum` metric's list, learning (appending) a
+	* value seen for the first time. `null` when the key is not an enum metric or
+	* its list is full ({@link MAX_ENUM_VALUES}). A learned value is stored by
+	* {@link persistDirtyMetrics} BEFORE any point that uses it.
+	*/
+	ordinalOf(key, value) {
+		const metric = this.metrics.get(key);
+		if (metric === void 0 || metric.kind !== "enum") return null;
+		const values = metric.values ?? [];
+		const known = values.indexOf(value);
+		if (known >= 0) return known;
+		if (values.length >= 1024) return null;
+		this.metrics.set(key, {
+			...metric,
+			values: [...values, value]
+		});
+		this.dirtyMetrics.add(key);
+		return values.length;
+	}
+	/** Store every value list that grew in memory. Throws (and keeps them dirty) on a failed write. */
+	async persistDirtyMetrics() {
+		for (const key of this.dirtyMetrics) {
+			const metric = this.metrics.get(key);
+			if (metric !== void 0) await this.store.upsertMetric(metric);
+			this.dirtyMetrics.delete(key);
+		}
 	}
 	find(key, subjectId, scope) {
 		return this.byIdentity.get(identityOf(key, subjectId, scope));
@@ -119,7 +171,7 @@ var SeriesRegistry = class {
 	}
 };
 function sameMetric(a, b) {
-	return a.source === b.source && a.ownerAddon === b.ownerAddon && a.subjectKind === b.subjectKind && a.kind === b.kind && a.unit === b.unit && a.displayName === b.displayName && a.ingest === b.ingest;
+	return a.source === b.source && a.ownerAddon === b.ownerAddon && a.subjectKind === b.subjectKind && a.kind === b.kind && a.unit === b.unit && a.displayName === b.displayName && a.ingest === b.ingest && JSON.stringify(a.values) === JSON.stringify(b.values);
 }
 //#endregion
 //#region src/builtins/device-history/capture/capture-filter.ts
@@ -143,10 +195,10 @@ var DEADBAND_EPSILON = 1e-9;
 /** The capture floor of a field: its own `minIntervalMs`, else the kind's default. */
 function minIntervalOf(spec) {
 	if (spec.minIntervalMs !== void 0) return spec.minIntervalMs;
-	return spec.kind === "boolean" ? 0 : require_dist.HISTORY_DEFAULT_MIN_INTERVAL_MS;
+	return spec.kind === "boolean" || spec.kind === "enum" ? 0 : require_dist.HISTORY_DEFAULT_MIN_INTERVAL_MS;
 }
 function clearsDeadband(spec, last, value) {
-	if (spec.kind === "boolean") return true;
+	if (spec.kind === "boolean" || spec.kind === "enum") return true;
 	const delta = Math.abs(value - last);
 	if (spec.deadband !== void 0 && delta < spec.deadband - DEADBAND_EPSILON) return false;
 	if (spec.deadbandPct !== void 0) {
@@ -331,7 +383,8 @@ function catalogMetrics(catalog, now) {
 		unit: spec.unit ?? null,
 		displayName: spec.displayName ?? humanize(capName, path),
 		ingest: "points",
-		declaredAt: now
+		declaredAt: now,
+		values: spec.kind === "enum" ? spec.values ?? [] : null
 	})));
 }
 /** Devices waiting on a type lookup; beyond this the oldest is dropped (and counted). */
@@ -380,11 +433,28 @@ var CaptureEngine = class {
 				counters.skip("excluded-device-type");
 				continue;
 			}
-			const value = readNumeric(slice, path, spec.kind);
+			const value = this.readValue(slice, capName, path, spec);
 			if (value === null) continue;
 			this.consider(deviceId, capName, path, spec, value, at, false);
 		}
 	}
+	/**
+	* The number a field contributes, or `null` (not a reading — never 0). An
+	* `enum` state becomes the ordinal of its value in the metric's list; a value
+	* the full list cannot take is refused and counted (`enum-overflow`).
+	*/
+	readValue(slice, capName, path, spec) {
+		if (spec.skipWhenSet !== void 0) {
+			const gate = readPath(slice, spec.skipWhenSet);
+			if (gate !== void 0 && gate !== null) return null;
+		}
+		if (spec.kind !== "enum") return readNumeric(slice, path, spec.kind);
+		const raw = readPath(slice, path);
+		if (typeof raw !== "string" || raw.length === 0) return null;
+		const ordinal = this.deps.registry.ordinalOf(capSeriesKey(capName, path), raw);
+		if (ordinal === null) this.deps.counters.skip("enum-overflow");
+		return ordinal;
+	}
 	consider(deviceId, capName, path, spec, value, at, reconciling) {
 		const key = capSeriesKey(capName, path);
 		const subject = {
@@ -490,7 +560,7 @@ var CaptureEngine = class {
 				if (slice === void 0) continue;
 				for (const [path, spec] of Object.entries(fields)) {
 					if (spec.excludeDeviceTypes?.includes(type) === true) continue;
-					const value = readNumeric(slice, path, spec.kind);
+					const value = this.readValue(slice, capName, path, spec);
 					if (value === null) continue;
 					this.consider(deviceId, capName, path, spec, value, now, true);
 				}
@@ -573,6 +643,7 @@ var PointWriter = class {
 		this.queue = [];
 		const { registry, store, counters, logger, clock } = this.deps;
 		try {
+			await registry.persistDirtyMetrics();
 			const bySeries = /* @__PURE__ */ new Map();
 			for (const point of batch) {
 				const series = await registry.ensure(point.key, point.subject, point.scope, point.ts);
@@ -748,7 +819,8 @@ var ProducerIngest = class {
 			unit: input.unit ?? null,
 			displayName: input.displayName,
 			ingest: input.ingest,
-			declaredAt: this.deps.clock()
+			declaredAt: this.deps.clock(),
+			values: null
 		};
 		await this.deps.registry.declareMetric(metric);
 		return { key };
@@ -835,7 +907,8 @@ var ProducerIngest = class {
 				last: bucket.last,
 				lastTs: bucket.lastTs,
 				twSum: null,
-				twMs: null
+				twMs: null,
+				states: null
 			});
 		}
 		await store.upsertRollups("5m", rows);
@@ -874,7 +947,109 @@ var ProducerIngest = class {
 	}
 };
 //#endregion
+//#region src/builtins/device-history/query/point-shape.ts
+/** kWh in one W·ms: 1 kWh = 1 000 W × 3 600 000 ms. */
+var KWH_PER_WATT_MS = 1 / 36e8;
+/** Growth from `prev` to `cur`; a drop is a reset counted from zero. `fallback` when `prev` is unknown. */
+function counterDelta(prev, cur, fallback) {
+	if (cur === null) return null;
+	if (prev === null) return fallback;
+	return cur >= prev ? cur - prev : cur;
+}
+/** The name of an ordinal, or `null` when the series is not an enum or the ordinal is unknown. */
+function stateName(meaning, ordinal) {
+	if (meaning.kind !== "enum" || meaning.values === null || ordinal === null) return null;
+	return meaning.values[ordinal] ?? null;
+}
+function namedStates(meaning, states) {
+	if (meaning.kind !== "enum" || states === null) return null;
+	const out = {};
+	for (const [ordinal, ms] of Object.entries(states)) {
+		const name = stateName(meaning, Number(ordinal));
+		if (name !== null) out[name] = (out[name] ?? 0) + ms;
+	}
+	return out;
+}
+/** Raw points, oldest first; `prev` is the value of the point before the first one. */
+function rawPoints(rows, meaning, prev) {
+	const isEnum = meaning.kind === "enum";
+	let held = prev;
+	return rows.map((r) => {
+		const delta = meaning.kind === "counter" ? counterDelta(held, r.value, null) : null;
+		held = r.value;
+		return {
+			t: r.ts,
+			samples: 1,
+			mean: isEnum ? null : r.value,
+			twMean: null,
+			min: r.value,
+			max: r.value,
+			last: r.value,
+			delta,
+			state: stateName(meaning, r.value),
+			states: null
+		};
+	});
+}
+/** Rollup rows, oldest first; `prevLast` is the `last` of the bucket before the first one. */
+function rollupPoints(rows, meaning, prevLast) {
+	const isEnum = meaning.kind === "enum";
+	let held = prevLast;
+	return rows.map((row) => {
+		const delta = meaning.kind === "counter" ? counterDelta(held, row.last, row.last === null ? null : row.last - row.min) : null;
+		if (row.last !== null) held = row.last;
+		return {
+			t: row.bucketStart,
+			samples: row.samples,
+			mean: isEnum || row.samples <= 0 ? null : row.sum / row.samples,
+			twMean: !isEnum && row.twSum !== null && row.twMs !== null && row.twMs > 0 ? row.twSum / row.twMs : null,
+			min: row.min,
+			max: row.max,
+			last: row.last,
+			delta,
+			state: stateName(meaning, row.last),
+			states: namedStates(meaning, row.states)
+		};
+	});
+}
+/** Energy used in each bucket of a `watts` gauge: its time-weighted integral, in kWh. */
+function integratedEnergyPoints(rows) {
+	return rows.map((row) => ({
+		t: row.bucketStart,
+		samples: row.samples,
+		mean: null,
+		twMean: null,
+		min: row.min,
+		max: row.max,
+		last: null,
+		delta: row.twSum === null ? null : row.twSum * KWH_PER_WATT_MS,
+		state: null,
+		states: null
+	}));
+}
+//#endregion
 //#region src/builtins/device-history/query/history-query.ts
+/**
+* Reads: `listSeries`, `query` and `queryMany` (plan §5.1).
+*
+* `auto` resolution picks the finest tier whose retention covers `from` and
+* whose point count fits `maxPoints`: a rollup tier fits when
+* `ceil(range / bucket) <= maxPoints`, raw fits when a read of `maxPoints + 1`
+* rows comes back short. The coarsest covering tier is the last resort and is
+* truncated to its newest `maxPoints` points (`truncated: true`) rather than
+* answering nothing. A series fed by closed buckets has NO raw rows, so raw is
+* never a candidate for it: an empty raw read "fits" every window.
+*
+* `before` is the last point strictly before the window in the chosen tier, so a
+* step chart can start at the value in force when the window opens — a quiet
+* bucket has no row, and the held value is otherwise invisible.
+*
+* {@link DEVICE_HISTORY_ENERGY_KEY} is computed here at read time, never stored:
+* the device's `kwhTotal` meter when it has one (per-bucket growth), else the
+* time-weighted integral of its `watts` (`tw_sum`, already in every rollup).
+* One place makes that choice, so two charts of one device cannot disagree, and
+* it covers every hour of history recorded before the key existed.
+*/
 var TIER_ORDER = [
 	"raw",
 	"5m",
@@ -888,33 +1063,25 @@ var BUCKET_MS = {
 };
 /** A key with more scopes than this is cut (a zone x class matrix, not a chart). */
 var MAX_SCOPES = 50;
+/** The power-meter series the energy key is derived from, meter first. */
+var ENERGY_METER_KEY = capSeriesKey("power-meter", "kwhTotal");
+var ENERGY_POWER_KEY = capSeriesKey("power-meter", "watts");
 function retentionMsOf(tier, policy) {
 	if (tier === "raw") return policy.rawDays * DAY_MS;
 	if (tier === "5m") return policy.fiveMinuteDays * DAY_MS;
 	if (tier === "1h") return policy.hourDays * DAY_MS;
 	return policy.dayDays === null || policy.dayDays <= 0 ? null : policy.dayDays * DAY_MS;
 }
-function rawPoint(ts, value) {
+/** Rows arrive newest first and one over the bound; keep the newest `maxPoints`, oldest first. */
+function bounded(newestFirst, maxPoints) {
+	const overflow = newestFirst.length > maxPoints;
 	return {
-		t: ts,
-		samples: 1,
-		mean: value,
-		twMean: null,
-		min: value,
-		max: value,
-		last: value
+		rows: (overflow ? newestFirst.slice(0, maxPoints) : newestFirst).toReversed(),
+		overflow
 	};
 }
-function rollupPoint(row) {
-	return {
-		t: row.bucketStart,
-		samples: row.samples,
-		mean: row.samples > 0 ? row.sum / row.samples : null,
-		twMean: row.twSum !== null && row.twMs !== null && row.twMs > 0 ? row.twSum / row.twMs : null,
-		min: row.min,
-		max: row.max,
-		last: row.last
-	};
+function errorText(err) {
+	return err instanceof Error ? err.message : String(err);
 }
 var HistoryQuery = class {
 	deps;
@@ -922,12 +1089,75 @@ var HistoryQuery = class {
 		this.deps = deps;
 	}
 	async query(input) {
+		if (input.key === "derived:energy.kwh") return this.queryEnergy(input);
 		const { registry } = this.deps;
-		const subjectId = subjectIdOf(input.subject);
-		const wanted = registry.forKeyAndSubject(input.key, subjectId).filter((s) => input.scope === void 0 || s.scope === input.scope).toSorted((a, b) => a.scope.localeCompare(b.scope)).slice(0, MAX_SCOPES);
-		const candidates = this.coveringTiers(input.from);
+		const wanted = this.seriesOf(input);
+		const metric = registry.metric(input.key);
+		const meaning = {
+			kind: metric?.kind ?? "gauge",
+			values: metric?.values ?? null
+		};
+		const { chosen, reads } = await this.choose(input, wanted, metric?.ingest === "buckets");
+		const series = [];
+		for (const [s, read] of reads) {
+			const before = await this.before(chosen, s, input.from, meaning);
+			const points = read.tier === "raw" ? rawPoints(read.rows, meaning, before?.value ?? null) : rollupPoints(read.rows, meaning, before?.value ?? null);
+			series.push({
+				scope: s.scope,
+				before,
+				points,
+				derivedFrom: null
+			});
+		}
+		return {
+			resolution: chosen,
+			series,
+			truncated: reads.some(([, r]) => r.overflow)
+		};
+	}
+	/** Several reads over one window; one failing item answers its error, not the batch's. */
+	async queryMany(input) {
+		const out = [];
+		for (const item of input.items) {
+			const subject = "deviceId" in item ? {
+				kind: "device",
+				deviceId: item.deviceId
+			} : {
+				kind: "node",
+				nodeId: item.forNodeId
+			};
+			try {
+				const result = await this.query({
+					key: item.key,
+					subject,
+					...item.scope !== void 0 ? { scope: item.scope } : {},
+					from: input.from,
+					to: input.to,
+					resolution: input.resolution,
+					maxPoints: input.maxPoints
+				});
+				out.push({
+					ok: true,
+					result
+				});
+			} catch (err) {
+				out.push({
+					ok: false,
+					error: errorText(err)
+				});
+			}
+		}
+		return out;
+	}
+	seriesOf(input) {
+		return this.deps.registry.forKeyAndSubject(input.key, subjectIdOf(input.subject)).filter((s) => input.scope === void 0 || s.scope === input.scope).toSorted((a, b) => a.scope.localeCompare(b.scope)).slice(0, MAX_SCOPES);
+	}
+	/** The tier to answer from and its reads. `noRaw`: the series has no raw rows to read. */
+	async choose(input, wanted, noRaw) {
+		const covering = this.coveringTiers(input.from);
+		const candidates = noRaw ? withoutRaw(covering) : covering;
 		const forced = input.resolution === "auto" ? null : input.resolution;
-		const order = forced === null ? candidates : [forced];
+		const order = forced === null ? candidates : [noRaw && forced === "raw" ? "5m" : forced];
 		let chosen = order[order.length - 1] ?? "1d";
 		let reads = [];
 		for (const [index, tier] of order.entries()) {
@@ -938,16 +1168,9 @@ var HistoryQuery = class {
 			if (reads.some(([, r]) => r.overflow) && !last) continue;
 			break;
 		}
-		const series = [];
-		for (const [s, read] of reads) series.push({
-			scope: s.scope,
-			before: await this.before(chosen, s, input.from),
-			points: read.points
-		});
 		return {
-			resolution: chosen,
-			series,
-			truncated: reads.some(([, r]) => r.overflow)
+			chosen,
+			reads
 		};
 	}
 	/** Tiers whose retention covers `from`, finest first; the coarsest is always present. */
@@ -969,35 +1192,79 @@ var HistoryQuery = class {
 	async readTier(tier, series, input) {
 		const { store } = this.deps;
 		const limit = input.maxPoints + 1;
-		if (tier === "raw") {
-			const rows = await store.readRaw(series.id, input.from, input.to, limit, "desc");
-			return this.shape(rows.map((r) => rawPoint(r.ts, r.value)), input.maxPoints);
-		}
+		if (tier === "raw") return {
+			tier,
+			...bounded(await store.readRaw(series.id, input.from, input.to, limit, "desc"), input.maxPoints)
+		};
 		const lower = bucketStartOf(tier, input.from);
-		const rows = await store.readRollups(tier, series.id, lower, input.to, limit, "desc");
-		return this.shape(rows.map(rollupPoint), input.maxPoints);
-	}
-	/** Rows arrive newest first and one over the bound; keep the newest `maxPoints`, oldest first. */
-	shape(newestFirst, maxPoints) {
-		const overflow = newestFirst.length > maxPoints;
 		return {
-			points: (overflow ? newestFirst.slice(0, maxPoints) : newestFirst).toReversed(),
-			overflow
+			tier,
+			...bounded(await store.readRollups(tier, series.id, lower, input.to, limit, "desc"), input.maxPoints)
 		};
 	}
-	async before(tier, series, from) {
+	async before(tier, series, from, meaning) {
 		const { store } = this.deps;
 		if (tier === "raw") {
 			const p = await store.rawBefore(series.id, from);
 			return p === null ? null : {
 				t: p.ts,
-				value: p.value
+				value: p.value,
+				state: stateName(meaning, p.value)
 			};
 		}
 		const row = await store.rollupBefore(tier, series.id, bucketStartOf(tier, from));
 		return row === null ? null : {
 			t: row.bucketStart,
-			value: row.last
+			value: row.last,
+			state: stateName(meaning, row.last)
+		};
+	}
+	/** The series energy is derived from for a device: the meter when it has one, else its power. */
+	energySource(subject) {
+		if (subject.kind !== "device") return null;
+		const subjectId = subjectIdOf(subject);
+		const meter = this.deps.registry.find(ENERGY_METER_KEY, subjectId, "");
+		if (meter !== void 0) return {
+			series: meter,
+			from: "meter"
+		};
+		const power = this.deps.registry.find(ENERGY_POWER_KEY, subjectId, "");
+		return power === void 0 ? null : {
+			series: power,
+			from: "power"
+		};
+	}
+	async queryEnergy(input) {
+		const source = this.energySource(input.subject);
+		if (source === null || input.scope !== void 0 && input.scope !== "") return {
+			resolution: "5m",
+			series: [],
+			truncated: false
+		};
+		const { chosen, reads } = await this.choose(input, [source.series], true);
+		const read = reads[0]?.[1];
+		if (read === void 0 || read.tier === "raw") return {
+			resolution: chosen,
+			series: [],
+			truncated: false
+		};
+		let points;
+		if (source.from === "meter") {
+			const prev = await this.deps.store.rollupBefore(read.tier, source.series.id, bucketStartOf(read.tier, input.from));
+			points = rollupPoints(read.rows, {
+				kind: "counter",
+				values: null
+			}, prev?.last ?? null);
+		} else points = integratedEnergyPoints(read.rows);
+		return {
+			resolution: chosen,
+			series: [{
+				scope: "",
+				before: null,
+				points,
+				derivedFrom: source.series.key
+			}],
+			truncated: read.overflow
 		};
 	}
 	async listSeries(subject) {
@@ -1014,10 +1281,23 @@ var HistoryQuery = class {
 				unit: await this.unitOf(subject, s, metric.unit, slices),
 				displayName: metric.displayName,
 				source: metric.source,
+				values: metric.kind === "enum" ? metric.values ?? [] : null,
 				firstTs: s.firstTs,
 				lastTs: s.lastTs
 			});
 		}
+		const energy = this.energySource(subject);
+		if (energy !== null) infos.push({
+			key: require_dist.DEVICE_HISTORY_ENERGY_KEY,
+			scope: "",
+			kind: "counter",
+			unit: "kWh",
+			displayName: "Energy",
+			source: "derived",
+			values: null,
+			firstTs: energy.series.firstTs,
+			lastTs: energy.series.lastTs
+		});
 		return infos.toSorted((a, b) => a.key.localeCompare(b.key) || a.scope.localeCompare(b.scope));
 	}
 	/** The metric's fixed unit, else the device's own (a `unitFrom` field), else unknown. */
@@ -1038,6 +1318,11 @@ var HistoryQuery = class {
 		return this.deps.catalog[body.slice(0, dot)]?.[body.slice(dot + 1)];
 	}
 };
+/** Every covering tier but raw; the coarsest stays when it is the only one. */
+function withoutRaw(tiers) {
+	const rollups = tiers.filter((t) => t !== "raw");
+	return rollups.length > 0 ? rollups : ["5m"];
+}
 //#endregion
 //#region src/builtins/device-history/retention/departure-tracker.ts
 var DEPARTED_ABSENCE_MS = 7 * DAY_MS;
@@ -1086,7 +1371,7 @@ var DepartureTracker = class {
 //#region src/builtins/device-history/retention/retention.ts
 var DEFAULT_RETENTION = {
 	rawDays: 7,
-	fiveMinuteDays: 14,
+	fiveMinuteDays: 30,
 	hourDays: 365,
 	dayDays: null
 };
@@ -1292,6 +1577,10 @@ function rollupDeclaration(collection) {
 			{
 				name: "tw_ms",
 				type: "INTEGER"
+			},
+			{
+				name: "state_ms",
+				type: "TEXT"
 			}
 		]
 	};
@@ -1346,6 +1635,10 @@ var HISTORY_DECLARATIONS = [
 				name: "declared_at",
 				type: "INTEGER",
 				notNull: true
+			},
+			{
+				name: "enum_values",
+				type: "TEXT"
 			}
 		]
 	},
@@ -1519,9 +1812,34 @@ function chunks(items, size) {
 	return out;
 }
 function parseKind(value) {
-	if (value === "gauge" || value === "counter" || value === "boolean") return value;
+	if (value === "gauge" || value === "counter" || value === "boolean" || value === "enum") return value;
 	throw new Error(`history row: unknown kind "${value}"`);
 }
+/** A JSON TEXT column: the engine hands back the decoded value, or the text itself. */
+function jsonColumn(data, column) {
+	const raw = data[column];
+	if (raw === null || raw === void 0) return null;
+	return typeof raw === "string" ? JSON.parse(raw) : raw;
+}
+/** A JSON column that must hold a string array, or nothing. */
+function parseValues(data) {
+	const parsed = jsonColumn(data, "enum_values");
+	if (parsed === null) return null;
+	if (Array.isArray(parsed) && parsed.every((v) => typeof v === "string")) return parsed;
+	throw new Error("history row: column \"enum_values\" is not a JSON string array");
+}
+/** A JSON column that must hold `{ "<ordinal>": ms }`, or nothing. */
+function parseStates(data) {
+	const parsed = jsonColumn(data, "state_ms");
+	if (parsed === null) return null;
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw new Error("history row: column \"state_ms\" is not a JSON object");
+	const out = {};
+	for (const [k, v] of Object.entries(parsed)) {
+		if (typeof v !== "number" || !Number.isFinite(v)) throw new Error("history row: column \"state_ms\" holds a non-number");
+		out[k] = v;
+	}
+	return out;
+}
 function parseMetric(data) {
 	const source = readText(data, "source");
 	const subjectKind = readText(data, "subject_kind");
@@ -1538,7 +1856,8 @@ function parseMetric(data) {
 		unit: readTextOrNull(data, "unit"),
 		displayName: readText(data, "display_name"),
 		ingest,
-		declaredAt: readNumber(data, "declared_at")
+		declaredAt: readNumber(data, "declared_at"),
+		values: parseValues(data)
 	};
 }
 function parseSeries(data) {
@@ -1563,7 +1882,8 @@ function parseRollup(data) {
 		last: readNumberOrNull(data, "last"),
 		lastTs: readNumberOrNull(data, "last_ts"),
 		twSum: readNumberOrNull(data, "tw_sum"),
-		twMs: readNumberOrNull(data, "tw_ms")
+		twMs: readNumberOrNull(data, "tw_ms"),
+		states: parseStates(data)
 	};
 }
 function rollupData(row) {
@@ -1577,7 +1897,8 @@ function rollupData(row) {
 		last: row.last,
 		last_ts: row.lastTs,
 		tw_sum: row.twSum,
-		tw_ms: row.twMs
+		tw_ms: row.twMs,
+		state_ms: row.states === null ? null : JSON.stringify(row.states)
 	};
 }
 function collectionOf(tier) {
@@ -1601,22 +1922,37 @@ var HistoryStore = class {
 			filter: { limit: 2e4 }
 		})).map((r) => parseMetric(r.data));
 	}
+	/**
+	* Delete metric rows no lookup can reach: rows an earlier build wrote under an
+	* engine-minted random key (every metric key is `cap:` / `addon:` prefixed).
+	*/
+	async deleteMetrics(keys) {
+		for (const batch of chunks(keys, WRITE_CHUNK)) await this.door.deleteWhere.mutate({
+			namespace: HISTORY_NAMESPACE,
+			collection: COLLECTIONS.metrics,
+			filter: { whereIn: { key: [...batch] } }
+		});
+	}
 	async upsertMetric(metric) {
 		await this.door.upsertMany.mutate({
 			namespace: HISTORY_NAMESPACE,
 			collection: COLLECTIONS.metrics,
 			conflict: ["key"],
-			records: [{ data: {
-				key: metric.key,
-				source: metric.source,
-				owner_addon: metric.ownerAddon,
-				subject_kind: metric.subjectKind,
-				kind: metric.kind,
-				unit: metric.unit,
-				display_name: metric.displayName,
-				ingest: metric.ingest,
-				declared_at: metric.declaredAt
-			} }]
+			records: [{
+				id: metric.key,
+				data: {
+					key: metric.key,
+					source: metric.source,
+					owner_addon: metric.ownerAddon,
+					subject_kind: metric.subjectKind,
+					kind: metric.kind,
+					unit: metric.unit,
+					display_name: metric.displayName,
+					ingest: metric.ingest,
+					declared_at: metric.declaredAt,
+					enum_values: metric.values === null ? null : JSON.stringify(metric.values)
+				}
+			}]
 		});
 	}
 	/** Series with `id > afterId`, ascending — the boot load pages with this. */
@@ -1863,6 +2199,11 @@ var HistoryStore = class {
 * The held value also counts toward `min`/`max` when it was in force at the
 * start of a bucket, because it really was the series' value then.
 */
+function credit(states, value, ms) {
+	if (states === null || ms <= 0) return;
+	const key = String(value);
+	states[key] = (states[key] ?? 0) + ms;
+}
 /** One row per 5-minute bucket that has at least one point. */
 function rawToFiveMinuteRows(input) {
 	const rows = [];
@@ -1881,6 +2222,7 @@ function rawToFiveMinuteRows(input) {
 		let max = Number.NEGATIVE_INFINITY;
 		let twSum = 0;
 		let twMs = 0;
+		const states = input.trackStates === true ? {} : null;
 		let cursor = bucketStart;
 		let value = held;
 		if (value !== null) {
@@ -1895,6 +2237,7 @@ function rawToFiveMinuteRows(input) {
 				const dt = p.ts - cursor;
 				twSum += value * dt;
 				twMs += dt;
+				credit(states, value, dt);
 			}
 			cursor = p.ts;
 			value = p.value;
@@ -1908,6 +2251,7 @@ function rawToFiveMinuteRows(input) {
 		if (value !== null && coverageEnd > cursor) {
 			twSum += value * (coverageEnd - cursor);
 			twMs += coverageEnd - cursor;
+			credit(states, value, coverageEnd - cursor);
 		}
 		held = last.value;
 		rows.push({
@@ -1920,7 +2264,8 @@ function rawToFiveMinuteRows(input) {
 			last: last.value,
 			lastTs: last.ts,
 			twSum,
-			twMs
+			twMs,
+			states
 		});
 	}
 	return rows;
@@ -1937,6 +2282,7 @@ function combineRows(input) {
 	let max = Number.NEGATIVE_INFINITY;
 	let twSum = 0;
 	let twMs = 0;
+	const states = input.trackStates === true ? {} : null;
 	let held = input.carryIn;
 	let cursor = input.windowStart;
 	for (const row of rows) {
@@ -1948,6 +2294,7 @@ function combineRows(input) {
 		if (hasTw && gap > 0 && held !== null) {
 			twSum += held * gap;
 			twMs += gap;
+			credit(states, held, gap);
 			if (held < min) min = held;
 			if (held > max) max = held;
 		}
@@ -1955,6 +2302,7 @@ function combineRows(input) {
 			twSum += row.twSum;
 			twMs += row.twMs;
 		}
+		if (states !== null && row.states !== null) for (const [state, ms] of Object.entries(row.states)) states[state] = (states[state] ?? 0) + ms;
 		cursor = row.bucketStart + input.childWidthMs;
 		held = row.last;
 	}
@@ -1962,6 +2310,7 @@ function combineRows(input) {
 	if (hasTw && held !== null && coverageEnd > cursor) {
 		twSum += held * (coverageEnd - cursor);
 		twMs += coverageEnd - cursor;
+		credit(states, held, coverageEnd - cursor);
 	}
 	return {
 		seriesId: input.seriesId,
@@ -1973,7 +2322,8 @@ function combineRows(input) {
 		last: lastRow.last,
 		lastTs: lastRow.lastTs,
 		twSum: hasTw ? twSum : null,
-		twMs: hasTw ? twMs : null
+		twMs: hasTw ? twMs : null,
+		states
 	};
 }
 /** How far back a boot rebuilds from raw and re-marks the upper tiers. */
@@ -2114,6 +2464,11 @@ var RollupEngine = class {
 		}
 		if (handled > 0) this.deps.counters.last1dAt = now;
 	}
+	/** An `enum` series keeps the time spent in each state in its rollups. */
+	isEnum(seriesId) {
+		const series = this.deps.registry.byIdOf(seriesId);
+		return series !== void 0 && this.deps.registry.metric(series.key)?.kind === "enum";
+	}
 	/** Raw → 5m rows for buckets in `[from, toExclusive)`; writes them and marks their hours. */
 	async recomputeFiveMinute(seriesId, from, toExclusive, horizon) {
 		const { store } = this.deps;
@@ -2130,7 +2485,8 @@ var RollupEngine = class {
 			seriesId,
 			points,
 			carryIn: await store.rawBefore(seriesId, from),
-			horizon
+			horizon,
+			trackStates: this.isEnum(seriesId)
 		});
 		if (rows.length === 0) return 0;
 		await store.upsertRollups("5m", rows);
@@ -2154,7 +2510,8 @@ var RollupEngine = class {
 			childWidthMs,
 			rows: await store.readRollups(child, seriesId, windowStart, windowEnd - 1, READ_PAGE),
 			carryIn: (await store.rollupBefore(child, seriesId, windowStart))?.last ?? null,
-			horizon: now
+			horizon: now,
+			trackStates: this.isEnum(seriesId)
 		});
 		if (combined === null) return;
 		await store.upsertRollups(parent, [combined]);
@@ -2661,7 +3018,7 @@ var DeviceHistoryAddon = class extends require_dist.BaseAddon {
 			}),
 			listNodeSeries: async (input) => this.requireRuntime().query.listSeries({
 				kind: "node",
-				nodeId: input.nodeId
+				nodeId: input.forNodeId
 			}),
 			query: async ({ deviceId, ...window }) => this.requireRuntime().query.query({
 				...window,
@@ -2670,13 +3027,14 @@ var DeviceHistoryAddon = class extends require_dist.BaseAddon {
 					deviceId
 				}
 			}),
-			queryNode: async ({ nodeId, ...window }) => this.requireRuntime().query.query({
+			queryNode: async ({ forNodeId, ...window }) => this.requireRuntime().query.query({
 				...window,
 				subject: {
 					kind: "node",
-					nodeId
+					nodeId: forNodeId
 				}
 			}),
+			queryMany: async (input) => ({ results: await this.requireRuntime().query.queryMany(input) }),
 			declareSeries: async (input) => this.requireRuntime().ingest.declareSeries(callerOf(input), input),
 			record: async (input) => this.requireRuntime().ingest.record(callerOf(input), input.points),
 			recordBuckets: async (input) => this.requireRuntime().ingest.recordBuckets(callerOf(input), input.buckets),