@camstack/system 1.2.456 → 1.2.458

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

@@ -1,4 +1,236 @@
-import { $r as BaseAddon, $t as deviceHistoryCapability, St as armRemovalReconcile, Ta as EventCategory, Zr as DeviceType, ci as HISTORY_DEFAULT_MIN_INTERVAL_MS, tn as deviceRemovalHookCapability, z as HISTORY_CATALOG } from "../../dist-BSF_C8W2.mjs";
+import { B as HISTORY_CATALOG, Ji as emitReadiness, O as DEVICE_HISTORY_ENERGY_KEY, Oa as EventCategory, Tt as armRemovalReconcile, di as HISTORY_DEFAULT_MIN_INTERVAL_MS, ei as DeviceType, in as deviceRemovalHookCapability, ni as BaseAddon, nn as deviceHistoryCapability } from "../../dist-B_GRPhnY.mjs";
+//#region src/builtins/device-history/time/bucket-time.ts
+/**
+* Bucket arithmetic for the three rollup tiers (D850, plan §4/§5.5).
+*
+* 5m and 1h buckets are aligned to UTC; a 1d bucket starts at HUB-LOCAL
+* midnight, so a day is 23, 24 or 25 hours long across a DST change (operator
+* answer Q4). Pure: the zone is the process zone (`TZ`), nothing is read from
+* the environment here.
+*/
+var FIVE_MINUTES_MS = 5 * 6e4;
+var HOUR_MS = 60 * 6e4;
+var DAY_MS = 24 * HOUR_MS;
+function floorTo(ts, widthMs) {
+	return Math.floor(ts / widthMs) * widthMs;
+}
+/** Hub-local midnight at or before `ts`. */
+function startOfLocalDay(ts) {
+	const d = new Date(ts);
+	d.setHours(0, 0, 0, 0);
+	return d.getTime();
+}
+/** The local midnight following the local midnight `dayStart`. */
+function nextLocalDayStart(dayStart) {
+	const d = new Date(dayStart);
+	d.setDate(d.getDate() + 1);
+	d.setHours(0, 0, 0, 0);
+	return d.getTime();
+}
+/** Start of the `tier` bucket containing `ts`. */
+function bucketStartOf(tier, ts) {
+	if (tier === "5m") return floorTo(ts, FIVE_MINUTES_MS);
+	if (tier === "1h") return floorTo(ts, HOUR_MS);
+	return startOfLocalDay(ts);
+}
+/** Exclusive end of the `tier` bucket that starts at `start`. */
+function bucketEndOf(tier, start) {
+	if (tier === "5m") return start + FIVE_MINUTES_MS;
+	if (tier === "1h") return start + HOUR_MS;
+	return nextLocalDayStart(start);
+}
+/** Quiet time after a bucket closes before it is rolled up (late writers). */
+var ROLLUP_GRACE_MS = {
+	"5m": 3e4,
+	"1h": 5 * 6e4,
+	"1d": 15 * 6e4
+};
+//#endregion
+//#region src/builtins/device-history/retention/departure-tracker.ts
+var DEPARTED_ABSENCE_MS = 7 * DAY_MS;
+var DepartureTracker = class {
+	store;
+	registry;
+	logger;
+	missing = /* @__PURE__ */ new Map();
+	constructor(store, registry, logger) {
+		this.store = store;
+		this.registry = registry;
+		this.logger = logger;
+	}
+	async load() {
+		this.missing = await this.store.loadDepartures();
+	}
+	missingSince(deviceId) {
+		return this.missing.get(deviceId);
+	}
+	/** Forget a device's clock — its series were removed because it was DELETED (D865). */
+	async forget(deviceId) {
+		await this.store.clearMissing([deviceId]);
+		const next = new Map(this.missing);
+		next.delete(deviceId);
+		this.missing = next;
+	}
+	/** Feed one SUCCESSFUL listing. A failed read never reaches here. */
+	async observe(listed, now) {
+		const withSeries = new Set(this.registry.all().flatMap((s) => s.deviceId === null ? [] : [s.deviceId]));
+		const back = [...this.missing.keys()].filter((id) => listed.has(id));
+		const gone = [...withSeries].filter((id) => !listed.has(id) && !this.missing.has(id));
+		try {
+			await this.store.clearMissing(back);
+			await this.store.markMissing(gone, now);
+		} catch (err) {
+			this.logger.warn("device-history: departure clock not written", { meta: { error: err instanceof Error ? err.message : String(err) } });
+			return;
+		}
+		const next = new Map(this.missing);
+		for (const id of back) next.delete(id);
+		for (const id of gone) next.set(id, now);
+		this.missing = next;
+	}
+};
+//#endregion
+//#region src/builtins/device-history/retention/retention.ts
+var DEFAULT_RETENTION = {
+	rawDays: 7,
+	fiveMinuteDays: 30,
+	hourDays: 365,
+	dayDays: null
+};
+/** Cutoff per tier: rows strictly older are deleted. `null` = keep forever. */
+function retentionCutoffs(policy, now) {
+	return {
+		raw: now - policy.rawDays * DAY_MS,
+		"5m": now - policy.fiveMinuteDays * DAY_MS,
+		"1h": now - policy.hourDays * DAY_MS,
+		"1d": policy.dayDays === null || policy.dayDays <= 0 ? null : now - policy.dayDays * DAY_MS
+	};
+}
+var TIERS = [
+	"raw",
+	"5m",
+	"1h",
+	"1d"
+];
+var RETENTION_STEP_MS = {
+	raw: HOUR_MS,
+	"5m": HOUR_MS,
+	"1h": DAY_MS,
+	"1d": DAY_MS
+};
+var MAX_PURGES_PER_RUN = 20;
+/** Width of one delete statement's time range, per tier. */
+var SLICE_MS = {
+	raw: DAY_MS,
+	"5m": DAY_MS,
+	"1h": 30 * DAY_MS,
+	"1d": 30 * DAY_MS
+};
+/** A bucket's start may precede the series' first point by up to a day. */
+var BUCKET_LEAD_MS = 2 * DAY_MS;
+/** The short tiers hold nothing older than this unless the operator configured more. */
+var SHORT_TIER_LOOKBACK_MS = 400 * DAY_MS;
+var yieldToEventLoop = () => new Promise((resolve) => setImmediate(resolve));
+var RetentionJob = class {
+	deps;
+	appliedUpTo = /* @__PURE__ */ new Map();
+	running = null;
+	constructor(deps) {
+		this.deps = deps;
+	}
+	run(policy, now) {
+		if (this.running !== null) return this.running;
+		const run = this.doRun(policy, now).finally(() => {
+			this.running = null;
+		});
+		this.running = run;
+		return run;
+	}
+	async doRun(policy, now) {
+		const { registry, counters, logger } = this.deps;
+		const cutoffs = retentionCutoffs(policy, now);
+		try {
+			for (const tier of TIERS) {
+				const cutoff = cutoffs[tier];
+				if (cutoff === null) continue;
+				for (const series of registry.all()) {
+					if (series.firstTs - 864e5 >= cutoff) continue;
+					if (tier === "raw" && registry.metric(series.key)?.ingest === "buckets") continue;
+					const marker = `${tier}:${series.id}`;
+					const applied = this.appliedUpTo.get(marker);
+					if (applied !== void 0 && cutoff - applied < RETENTION_STEP_MS[tier]) continue;
+					const lo = Math.max(0, applied === void 0 ? series.firstTs - BUCKET_LEAD_MS : applied - RETENTION_STEP_MS[tier]);
+					counters.addDeleted(tier, await this.deleteSliced(tier, series.id, lo, cutoff - 1));
+					this.appliedUpTo.set(marker, cutoff);
+				}
+			}
+			await this.purgeDeparted(now);
+			counters.retentionLastRunAt = now;
+		} catch (err) {
+			logger.warn("device-history: retention pass failed — retried at the next run", { meta: { error: err instanceof Error ? err.message : String(err) } });
+		}
+	}
+	/** Delete `[lo, hiInclusive]` of one tier in time slices, yielding between them. */
+	/** Drop the visit markers of a purged series. */
+	forgetSeries(seriesId) {
+		for (const tier of TIERS) this.appliedUpTo.delete(`${tier}:${seriesId}`);
+	}
+	async deleteSliced(tier, seriesId, lo, hiInclusive) {
+		const yieldNow = this.deps.yieldNow ?? yieldToEventLoop;
+		let deleted = 0;
+		for (let from = lo; from <= hiInclusive; from += SLICE_MS[tier]) {
+			const to = Math.min(from + SLICE_MS[tier] - 1, hiInclusive);
+			deleted += await this.deps.store.deleteRange(tier, seriesId, from, to);
+			await yieldNow();
+		}
+		return deleted;
+	}
+	/** Tier by tier in slices, then the series row (and whatever the slices missed). */
+	async purgeSeries(series, now) {
+		for (const tier of TIERS) {
+			const lo = tier === "raw" || tier === "5m" ? Math.max(series.firstTs - BUCKET_LEAD_MS, now - SHORT_TIER_LOOKBACK_MS) : series.firstTs - BUCKET_LEAD_MS;
+			await this.deleteSliced(tier, series.id, Math.max(0, lo), now + DAY_MS);
+		}
+		await this.deps.store.deleteSeries(series.id);
+	}
+	/**
+	* Delete every series of a DELETED device now (D865). Driven by a tombstone
+	* through the `device-removal-hook`, never by a listing: the week-long
+	* absence clock above remains the backstop for a device removed before
+	* tombstones existed.
+	*/
+	async purgeDevice(deviceId, now) {
+		const { registry, counters } = this.deps;
+		let purged = 0;
+		for (const series of registry.all()) {
+			if (series.deviceId !== deviceId) continue;
+			await this.purgeSeries(series, now);
+			registry.remove(series.id);
+			counters.purgedSeries += 1;
+			purged += 1;
+		}
+		return purged;
+	}
+	async purgeDeparted(now) {
+		const { registry, departures, counters, logger } = this.deps;
+		let purged = 0;
+		for (const series of registry.all()) {
+			if (purged >= MAX_PURGES_PER_RUN) break;
+			if (series.deviceId === null) continue;
+			const since = departures.missingSince(series.deviceId);
+			if (since === void 0 || now - since < DEPARTED_ABSENCE_MS) continue;
+			await this.purgeSeries(series, now);
+			registry.remove(series.id);
+			counters.purgedSeries += 1;
+			purged += 1;
+			logger.info("device-history: purged the series of an unregistered device", {
+				tags: { deviceId: series.deviceId },
+				meta: { key: series.key }
+			});
+		}
+	}
+};
+//#endregion
 //#region src/builtins/device-history/store/series-registry.ts
 function subjectIdOf(subject) {
 	return subject.kind === "device" ? `d:${subject.deviceId}` : `n:${subject.nodeId}`;
@@ -6,16 +238,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;
@@ -24,7 +269,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);
@@ -44,12 +292,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));
@@ -114,7 +398,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
@@ -138,10 +422,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 : HISTORY_DEFAULT_MIN_INTERVAL_MS;
+	return spec.kind === "boolean" || spec.kind === "enum" ? 0 : 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) {
@@ -326,7 +610,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). */
@@ -375,11 +660,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 = {
@@ -485,7 +787,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);
 				}
@@ -568,6 +870,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);
@@ -659,52 +962,27 @@ var PointWriter = class {
 	}
 };
 //#endregion
-//#region src/builtins/device-history/time/bucket-time.ts
+//#region src/builtins/device-history/ingest/producer-ingest.ts
+/** One point per series per this many ms, sustained. */
+var RECORD_MIN_INTERVAL_MS = 1e4;
 /**
-* Bucket arithmetic for the three rollup tiers (D850, plan §4/§5.5).
-*
-* 5m and 1h buckets are aligned to UTC; a 1d bucket starts at HUB-LOCAL
-* midnight, so a day is 23, 24 or 25 hours long across a DST change (operator
-* answer Q4). Pure: the zone is the process zone (`TZ`), nothing is read from
-* the environment here.
+* The slot after accepting a point at `ts`. A point older than the newest
+* accepted one (a late arrival) moves nothing. Otherwise the consumed slot is
+* the later of the one that was due and `ts` itself: an early point uses the
+* due slot (the grid holds, so slack never compounds into a higher rate), a
+* late one restarts the grid at `ts` (no credit is banked for a gap).
 */
-var FIVE_MINUTES_MS = 5 * 6e4;
-var HOUR_MS = 60 * 6e4;
-var DAY_MS = 24 * HOUR_MS;
-function floorTo(ts, widthMs) {
-	return Math.floor(ts / widthMs) * widthMs;
-}
-/** Hub-local midnight at or before `ts`. */
-function startOfLocalDay(ts) {
-	const d = new Date(ts);
-	d.setHours(0, 0, 0, 0);
-	return d.getTime();
-}
-/** The local midnight following the local midnight `dayStart`. */
-function nextLocalDayStart(dayStart) {
-	const d = new Date(dayStart);
-	d.setDate(d.getDate() + 1);
-	d.setHours(0, 0, 0, 0);
-	return d.getTime();
-}
-/** Start of the `tier` bucket containing `ts`. */
-function bucketStartOf(tier, ts) {
-	if (tier === "5m") return floorTo(ts, FIVE_MINUTES_MS);
-	if (tier === "1h") return floorTo(ts, HOUR_MS);
-	return startOfLocalDay(ts);
-}
-/** Exclusive end of the `tier` bucket that starts at `start`. */
-function bucketEndOf(tier, start) {
-	if (tier === "5m") return start + FIVE_MINUTES_MS;
-	if (tier === "1h") return start + HOUR_MS;
-	return nextLocalDayStart(start);
+function nextSlot(slot, ts) {
+	if (slot === void 0) return {
+		lastTs: ts,
+		nextDue: ts + RECORD_MIN_INTERVAL_MS
+	};
+	if (ts < slot.lastTs) return slot;
+	return {
+		lastTs: ts,
+		nextDue: Math.max(slot.nextDue, ts) + RECORD_MIN_INTERVAL_MS
+	};
 }
-/** Quiet time after a bucket closes before it is rolled up (late writers). */
-var ROLLUP_GRACE_MS = {
-	"5m": 3e4,
-	"1h": 5 * 6e4,
-	"1d": 15 * 6e4
-};
 function addRefusal(refusals, key, reason) {
 	const byReason = refusals.get(key) ?? /* @__PURE__ */ new Map();
 	byReason.set(reason, (byReason.get(reason) ?? 0) + 1);
@@ -722,7 +1000,7 @@ function toResult(accepted, refusals) {
 }
 var ProducerIngest = class {
 	deps;
-	/** Last accepted point time per series, for the sustained-rate bound. */
+	/** Rate state per series identity, for the sustained-rate bound. */
 	lastAccepted = /* @__PURE__ */ new Map();
 	constructor(deps) {
 		this.deps = deps;
@@ -743,7 +1021,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 };
@@ -780,13 +1059,13 @@ var ProducerIngest = class {
 				continue;
 			}
 			const identity = identityOf(point.key, subjectIdOf(point.subject), point.scope);
-			const last = this.lastAccepted.get(identity);
-			if (last !== void 0 && point.ts >= last && point.ts - last < 1e4) {
+			const slot = this.lastAccepted.get(identity);
+			if (slot !== void 0 && point.ts >= slot.lastTs && point.ts < slot.nextDue - 1e3) {
 				addRefusal(refusals, point.key, "rate");
 				counters.refuse("rate");
 				continue;
 			}
-			this.lastAccepted.set(identity, Math.max(last ?? point.ts, point.ts));
+			this.lastAccepted.set(identity, nextSlot(slot, point.ts));
 			this.deps.writer.enqueue({
 				key: point.key,
 				subject: point.subject,
@@ -830,7 +1109,8 @@ var ProducerIngest = class {
 				last: bucket.last,
 				lastTs: bucket.lastTs,
 				twSum: null,
-				twMs: null
+				twMs: null,
+				states: null
 			});
 		}
 		await store.upsertRollups("5m", rows);
@@ -869,7 +1149,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",
@@ -883,46 +1265,101 @@ 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;
 	constructor(deps) {
 		this.deps = deps;
 	}
-	async query(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);
+	async query(input) {
+		if (input.key === "derived:energy.kwh") return this.queryEnergy(input);
+		const { registry } = this.deps;
+		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()) {
@@ -933,16 +1370,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. */
@@ -964,35 +1394,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) {
@@ -1009,10 +1483,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: 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. */
@@ -1033,191 +1520,11 @@ var HistoryQuery = class {
 		return this.deps.catalog[body.slice(0, dot)]?.[body.slice(dot + 1)];
 	}
 };
-//#endregion
-//#region src/builtins/device-history/retention/departure-tracker.ts
-var DEPARTED_ABSENCE_MS = 7 * DAY_MS;
-var DepartureTracker = class {
-	store;
-	registry;
-	logger;
-	missing = /* @__PURE__ */ new Map();
-	constructor(store, registry, logger) {
-		this.store = store;
-		this.registry = registry;
-		this.logger = logger;
-	}
-	async load() {
-		this.missing = await this.store.loadDepartures();
-	}
-	missingSince(deviceId) {
-		return this.missing.get(deviceId);
-	}
-	/** Forget a device's clock — its series were removed because it was DELETED (D865). */
-	async forget(deviceId) {
-		await this.store.clearMissing([deviceId]);
-		const next = new Map(this.missing);
-		next.delete(deviceId);
-		this.missing = next;
-	}
-	/** Feed one SUCCESSFUL listing. A failed read never reaches here. */
-	async observe(listed, now) {
-		const withSeries = new Set(this.registry.all().flatMap((s) => s.deviceId === null ? [] : [s.deviceId]));
-		const back = [...this.missing.keys()].filter((id) => listed.has(id));
-		const gone = [...withSeries].filter((id) => !listed.has(id) && !this.missing.has(id));
-		try {
-			await this.store.clearMissing(back);
-			await this.store.markMissing(gone, now);
-		} catch (err) {
-			this.logger.warn("device-history: departure clock not written", { meta: { error: err instanceof Error ? err.message : String(err) } });
-			return;
-		}
-		const next = new Map(this.missing);
-		for (const id of back) next.delete(id);
-		for (const id of gone) next.set(id, now);
-		this.missing = next;
-	}
-};
-//#endregion
-//#region src/builtins/device-history/retention/retention.ts
-var DEFAULT_RETENTION = {
-	rawDays: 7,
-	fiveMinuteDays: 14,
-	hourDays: 365,
-	dayDays: null
-};
-/** Cutoff per tier: rows strictly older are deleted. `null` = keep forever. */
-function retentionCutoffs(policy, now) {
-	return {
-		raw: now - policy.rawDays * DAY_MS,
-		"5m": now - policy.fiveMinuteDays * DAY_MS,
-		"1h": now - policy.hourDays * DAY_MS,
-		"1d": policy.dayDays === null || policy.dayDays <= 0 ? null : now - policy.dayDays * DAY_MS
-	};
+/** 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"];
 }
-var TIERS = [
-	"raw",
-	"5m",
-	"1h",
-	"1d"
-];
-var RETENTION_STEP_MS = {
-	raw: HOUR_MS,
-	"5m": HOUR_MS,
-	"1h": DAY_MS,
-	"1d": DAY_MS
-};
-var MAX_PURGES_PER_RUN = 20;
-/** Width of one delete statement's time range, per tier. */
-var SLICE_MS = {
-	raw: DAY_MS,
-	"5m": DAY_MS,
-	"1h": 30 * DAY_MS,
-	"1d": 30 * DAY_MS
-};
-/** A bucket's start may precede the series' first point by up to a day. */
-var BUCKET_LEAD_MS = 2 * DAY_MS;
-/** The short tiers hold nothing older than this unless the operator configured more. */
-var SHORT_TIER_LOOKBACK_MS = 400 * DAY_MS;
-var yieldToEventLoop = () => new Promise((resolve) => setImmediate(resolve));
-var RetentionJob = class {
-	deps;
-	appliedUpTo = /* @__PURE__ */ new Map();
-	running = null;
-	constructor(deps) {
-		this.deps = deps;
-	}
-	run(policy, now) {
-		if (this.running !== null) return this.running;
-		const run = this.doRun(policy, now).finally(() => {
-			this.running = null;
-		});
-		this.running = run;
-		return run;
-	}
-	async doRun(policy, now) {
-		const { registry, counters, logger } = this.deps;
-		const cutoffs = retentionCutoffs(policy, now);
-		try {
-			for (const tier of TIERS) {
-				const cutoff = cutoffs[tier];
-				if (cutoff === null) continue;
-				for (const series of registry.all()) {
-					if (series.firstTs - 864e5 >= cutoff) continue;
-					if (tier === "raw" && registry.metric(series.key)?.ingest === "buckets") continue;
-					const marker = `${tier}:${series.id}`;
-					const applied = this.appliedUpTo.get(marker);
-					if (applied !== void 0 && cutoff - applied < RETENTION_STEP_MS[tier]) continue;
-					const lo = Math.max(0, applied === void 0 ? series.firstTs - BUCKET_LEAD_MS : applied - RETENTION_STEP_MS[tier]);
-					counters.addDeleted(tier, await this.deleteSliced(tier, series.id, lo, cutoff - 1));
-					this.appliedUpTo.set(marker, cutoff);
-				}
-			}
-			await this.purgeDeparted(now);
-			counters.retentionLastRunAt = now;
-		} catch (err) {
-			logger.warn("device-history: retention pass failed — retried at the next run", { meta: { error: err instanceof Error ? err.message : String(err) } });
-		}
-	}
-	/** Delete `[lo, hiInclusive]` of one tier in time slices, yielding between them. */
-	/** Drop the visit markers of a purged series. */
-	forgetSeries(seriesId) {
-		for (const tier of TIERS) this.appliedUpTo.delete(`${tier}:${seriesId}`);
-	}
-	async deleteSliced(tier, seriesId, lo, hiInclusive) {
-		const yieldNow = this.deps.yieldNow ?? yieldToEventLoop;
-		let deleted = 0;
-		for (let from = lo; from <= hiInclusive; from += SLICE_MS[tier]) {
-			const to = Math.min(from + SLICE_MS[tier] - 1, hiInclusive);
-			deleted += await this.deps.store.deleteRange(tier, seriesId, from, to);
-			await yieldNow();
-		}
-		return deleted;
-	}
-	/** Tier by tier in slices, then the series row (and whatever the slices missed). */
-	async purgeSeries(series, now) {
-		for (const tier of TIERS) {
-			const lo = tier === "raw" || tier === "5m" ? Math.max(series.firstTs - BUCKET_LEAD_MS, now - SHORT_TIER_LOOKBACK_MS) : series.firstTs - BUCKET_LEAD_MS;
-			await this.deleteSliced(tier, series.id, Math.max(0, lo), now + DAY_MS);
-		}
-		await this.deps.store.deleteSeries(series.id);
-	}
-	/**
-	* Delete every series of a DELETED device now (D865). Driven by a tombstone
-	* through the `device-removal-hook`, never by a listing: the week-long
-	* absence clock above remains the backstop for a device removed before
-	* tombstones existed.
-	*/
-	async purgeDevice(deviceId, now) {
-		const { registry, counters } = this.deps;
-		let purged = 0;
-		for (const series of registry.all()) {
-			if (series.deviceId !== deviceId) continue;
-			await this.purgeSeries(series, now);
-			registry.remove(series.id);
-			counters.purgedSeries += 1;
-			purged += 1;
-		}
-		return purged;
-	}
-	async purgeDeparted(now) {
-		const { registry, departures, counters, logger } = this.deps;
-		let purged = 0;
-		for (const series of registry.all()) {
-			if (purged >= MAX_PURGES_PER_RUN) break;
-			if (series.deviceId === null) continue;
-			const since = departures.missingSince(series.deviceId);
-			if (since === void 0 || now - since < DEPARTED_ABSENCE_MS) continue;
-			await this.purgeSeries(series, now);
-			registry.remove(series.id);
-			counters.purgedSeries += 1;
-			purged += 1;
-			logger.info("device-history: purged the series of an unregistered device", {
-				tags: { deviceId: series.deviceId },
-				meta: { key: series.key }
-			});
-		}
-	}
-};
 //#endregion
 //#region src/builtins/device-history/store/history-schema.ts
 var HISTORY_NAMESPACE = "device-history";
@@ -1287,6 +1594,10 @@ function rollupDeclaration(collection) {
 			{
 				name: "tw_ms",
 				type: "INTEGER"
+			},
+			{
+				name: "state_ms",
+				type: "TEXT"
 			}
 		]
 	};
@@ -1341,6 +1652,10 @@ var HISTORY_DECLARATIONS = [
 				name: "declared_at",
 				type: "INTEGER",
 				notNull: true
+			},
+			{
+				name: "enum_values",
+				type: "TEXT"
 			}
 		]
 	},
@@ -1514,9 +1829,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");
@@ -1533,7 +1873,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) {
@@ -1558,7 +1899,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) {
@@ -1572,7 +1914,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) {
@@ -1596,22 +1939,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. */
@@ -1858,6 +2216,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 = [];
@@ -1876,6 +2239,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) {
@@ -1890,6 +2254,7 @@ function rawToFiveMinuteRows(input) {
 				const dt = p.ts - cursor;
 				twSum += value * dt;
 				twMs += dt;
+				credit(states, value, dt);
 			}
 			cursor = p.ts;
 			value = p.value;
@@ -1903,6 +2268,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({
@@ -1915,7 +2281,8 @@ function rawToFiveMinuteRows(input) {
 			last: last.value,
 			lastTs: last.ts,
 			twSum,
-			twMs
+			twMs,
+			states
 		});
 	}
 	return rows;
@@ -1932,6 +2299,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) {
@@ -1943,6 +2311,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;
 		}
@@ -1950,6 +2319,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;
 	}
@@ -1957,6 +2327,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,
@@ -1968,7 +2339,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. */
@@ -2109,6 +2481,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;
@@ -2125,7 +2502,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);
@@ -2149,7 +2527,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]);
@@ -2609,6 +2988,13 @@ var HistoryRuntime = class {
 * are hub capabilities, and a forked runner cannot call them from
 * `onInitialize`. Until then the provider answers "starting" rather than an
 * empty history (an unanswered query is not an empty one, D315).
+*
+* Readiness follows the STORE, not the registration: the provider registers at
+* `onInitialize`, but `ready` is emitted only once the runtime is open in
+* `onHubReachable` (`autoEmitReadiness` is off). Producers declare their
+* series on `ready`; the automatic emit at registration sent every one of
+* them into "device-history is starting" on each boot (`.50`, 1.2.607:
+* metrics-native and pipeline-analytics).
 */
 var DEFAULT_CONFIG = {
 	rawDays: DEFAULT_RETENTION.rawDays,
@@ -2632,9 +3018,40 @@ var DeviceHistoryAddon = class extends BaseAddon {
 	runtime = null;
 	unsubscribe = null;
 	removalHook = null;
+	/** This instance's readiness generation (the base class keeps its own private). */
+	readinessGeneration = `device-history-${Date.now().toString(36)}`;
 	constructor() {
 		super({ ...DEFAULT_CONFIG });
 	}
+	/** `ready` is the store being open, emitted by {@link emitStoreReadiness}. */
+	get autoEmitReadiness() {
+		return false;
+	}
+	/** Readiness of both provided caps, on the bare node this runner belongs to. */
+	emitStoreReadiness(state) {
+		const ctx = this.ctxIfReady;
+		if (ctx === null) return;
+		const raw = ctx.kernel?.localNodeId ?? "hub";
+		const nodeId = raw.includes("/") ? raw.split("/")[0] ?? raw : raw;
+		for (const capName of [deviceHistoryCapability.name, deviceRemovalHookCapability.name]) try {
+			emitReadiness(ctx.eventBus, {
+				capName,
+				scope: {
+					type: "node",
+					nodeId
+				},
+				state,
+				generation: this.readinessGeneration,
+				sourceNodeId: nodeId
+			});
+		} catch (err) {
+			ctx.logger.warn("device-history: readiness not emitted", { meta: {
+				capName,
+				state,
+				error: err instanceof Error ? err.message : String(err)
+			} });
+		}
+	}
 	retention() {
 		const c = this.config;
 		return {
@@ -2656,7 +3073,7 @@ var DeviceHistoryAddon = class extends 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,
@@ -2665,13 +3082,14 @@ var DeviceHistoryAddon = class extends 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),
@@ -2679,6 +3097,7 @@ var DeviceHistoryAddon = class extends BaseAddon {
 			setDeviceEnabled: async (input) => ({ enabled: await this.requireRuntime().setEnabled(input.deviceId, input.enabled) }),
 			getStatus: async () => this.requireRuntime().status()
 		};
+		this.emitStoreReadiness("starting");
 		this.ctx.logger.info("Initialized — device-history provider registered (store opens on hub link)");
 		const removalHook = {
 			onDeviceRemoved: async (input) => {
@@ -2755,6 +3174,7 @@ var DeviceHistoryAddon = class extends BaseAddon {
 			logger: this.ctx.logger,
 			remove: (input) => removalHook.onDeviceRemoved(input)
 		}));
+		this.emitStoreReadiness("ready");
 		this.ctx.logger.info("device-history: capturing", { meta: {
 			series: runtime.status().series,
 			metrics: runtime.status().metrics
@@ -2766,6 +3186,7 @@ var DeviceHistoryAddon = class extends BaseAddon {
 		await this.runtime?.stop();
 	}
 	async onShutdown() {
+		this.emitStoreReadiness("down");
 		await this.stopRuntime();
 		this.runtime = null;
 	}