@camstack/system 1.2.468 → 1.2.470

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

@@ -1,4 +1,4 @@
-import { $r as BaseAddon, $t as deviceHistoryCapability, D as DEVICE_HISTORY_ENERGY_KEY, St as armRemovalReconcile, Ta as EventCategory, Zr as DeviceType, ci as HISTORY_DEFAULT_MIN_INTERVAL_MS, qi as emitReadiness, tn as deviceRemovalHookCapability, z as HISTORY_CATALOG } from "../../dist-BpUtAgqR.mjs";
+import { B as HISTORY_ITEM_CATALOG, Ct as armRemovalReconcile, D as DEVICE_HISTORY_ENERGY_KEY, Da as EventCategory, Ji as emitReadiness, Qr as DeviceType, Zi as historyItemFieldPath, ei as BaseAddon, en as deviceHistoryCapability, li as HISTORY_DEFAULT_MIN_INTERVAL_MS, nn as deviceRemovalHookCapability, z as HISTORY_CATALOG } from "../../dist-X1r44BdF.mjs";
 //#region src/builtins/device-history/time/bucket-time.ts
 /**
 * Bucket arithmetic for the three rollup tiers (D850, plan §4/§5.5).
@@ -185,13 +185,25 @@ var RetentionJob = class {
 		}
 		return deleted;
 	}
-	/** Tier by tier in slices, then the series row (and whatever the slices missed). */
+	/**
+	* Tier by tier in slices, then the series row (and whatever the slices missed).
+	* Answers the rows the slices deleted per tier. The caller removes the series
+	* from the registry, which releases its per-series state.
+	*/
 	async purgeSeries(series, now) {
+		const deleted = {
+			raw: 0,
+			"5m": 0,
+			"1h": 0,
+			"1d": 0
+		};
 		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);
+			deleted[tier] = await this.deleteSliced(tier, series.id, Math.max(0, lo), now + DAY_MS);
+			this.deps.counters.addDeleted(tier, deleted[tier]);
 		}
 		await this.deps.store.deleteSeries(series.id);
+		return deleted;
 	}
 	/**
 	* Delete every series of a DELETED device now (D865). Driven by a tombstone
@@ -558,14 +570,14 @@ var DeviceDirectory = class {
 * `runtimeState` key or a path into a FIXED object (`dustBin.level`); the
 * catalog guard keeps it out of arrays and records, so a plain walk is enough.
 */
-function isRecord$1(value) {
+function isRecord$2(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 /** The value at `path`, or `undefined` when any step is missing or not an object. */
 function readPath(slice, path) {
 	let current = slice;
 	for (const step of path.split(".")) {
-		if (!isRecord$1(current)) return void 0;
+		if (!isRecord$2(current)) return void 0;
 		current = current[step];
 	}
 	return current;
@@ -591,18 +603,41 @@ function readUnit(slice, unitFrom) {
 }
 //#endregion
 //#region src/builtins/device-history/capture/capture-engine.ts
+/**
+* Capture of capability fields (D850, plan §5.3), driven by the GENERATED
+* history catalog — a field is recorded because its `*.cap.ts` says so, never
+* because someone listed it here.
+*
+* For a `DeviceStateChanged { deviceId, capName, slice }` the engine:
+*   1. ignores a cap with no catalog entry (the common case — cheap, uncounted);
+*   2. skips an opted-out device (counted), a device whose type is not yet
+*      known (parked, then replayed once the hub answers), and a `hub` /
+*      `container` (counted: not a real device);
+*   3. per field: skips an excluded device type, an absent or non-numeric value
+*      (null is UNKNOWN, never 0), then runs {@link decideCapture} against the
+*      last RECORDED value — change-only, deadband, capture floor;
+*   4. buffers the point for the batched write.
+*
+* A change inside the capture floor is kept PENDING and emitted when the floor
+* has passed ({@link CaptureEngine.tickPending}), so the end of a burst is never
+* lost. Reconcile ({@link CaptureEngine.reconcile}) restores what a dropped
+* event missed from the state mirror's snapshot.
+*/
 var CAP_KEY_PREFIX = "cap:";
 function capSeriesKey(capName, fieldPath) {
 	return `${CAP_KEY_PREFIX}${capName}.${fieldPath}`;
 }
+/** The series key of an item field: `cap:<capName>.<path>[].<field>`. */
+function capItemSeriesKey(capName, items, field) {
+	return capSeriesKey(capName, historyItemFieldPath(items.path, field));
+}
 function humanize(capName, fieldPath) {
 	const field = fieldPath.replace(/([A-Z])/g, " $1").replace(/\./g, " ").toLowerCase();
 	return `${capName.replace(/-/g, " ")} ${field}`;
 }
-/** The metric rows of every catalog field (owner `device-history`). */
-function catalogMetrics(catalog, now) {
-	return Object.entries(catalog).flatMap(([capName, fields]) => Object.entries(fields).map(([path, spec]) => ({
-		key: capSeriesKey(capName, path),
+function metricOf(key, capName, path, spec, now) {
+	return {
+		key,
 		source: "cap",
 		ownerAddon: "device-history",
 		subjectKind: "device",
@@ -612,7 +647,16 @@ function catalogMetrics(catalog, now) {
 		ingest: "points",
 		declaredAt: now,
 		values: spec.kind === "enum" ? spec.values ?? [] : null
-	})));
+	};
+}
+/** The metric rows of every catalog field and keyed-item field (owner `device-history`). */
+function catalogMetrics(catalog, itemCatalog, now) {
+	const fields = Object.entries(catalog).flatMap(([capName, specs]) => Object.entries(specs).map(([path, spec]) => metricOf(capSeriesKey(capName, path), capName, path, spec, now)));
+	const items = Object.entries(itemCatalog).flatMap(([capName, block]) => Object.entries(block.fields).map(([field, spec]) => metricOf(capItemSeriesKey(capName, block, field), capName, field, spec, now)));
+	return [...fields, ...items];
+}
+function isRecord$1(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 /** Devices waiting on a type lookup; beyond this the oldest is dropped (and counted). */
 var MAX_PARKED_DEVICES = 5e3;
@@ -639,7 +683,8 @@ var CaptureEngine = class {
 	/** One `DeviceStateChanged`. Synchronous: the bus must never wait on us. */
 	handleState(deviceId, capName, slice, at) {
 		const fields = this.deps.catalog[capName];
-		if (fields === void 0) return;
+		const items = this.deps.itemCatalog[capName];
+		if (fields === void 0 && items === void 0) return;
 		const { counters, directory } = this.deps;
 		counters.eventsSeen += 1;
 		if (this.deps.optedOut().has(deviceId)) {
@@ -655,14 +700,46 @@ var CaptureEngine = class {
 			counters.skip("not-a-real-device");
 			return;
 		}
-		for (const [path, spec] of Object.entries(fields)) {
+		this.captureSlice(deviceId, type, capName, slice, at, false);
+	}
+	/** Every catalogued field and keyed item of one cap slice, for a real device. */
+	captureSlice(deviceId, type, capName, slice, at, reconciling) {
+		for (const [path, spec] of Object.entries(this.deps.catalog[capName] ?? {})) {
 			if (spec.excludeDeviceTypes?.includes(type) === true) {
-				counters.skip("excluded-device-type");
+				if (!reconciling) this.deps.counters.skip("excluded-device-type");
 				continue;
 			}
-			const value = this.readValue(slice, capName, path, spec);
+			const key = capSeriesKey(capName, path);
+			const value = this.readValue(slice, key, path, spec);
 			if (value === null) continue;
-			this.consider(deviceId, capName, path, spec, value, at, false);
+			this.consider(deviceId, key, "", spec, value, at, reconciling);
+		}
+		const items = this.deps.itemCatalog[capName];
+		if (items !== void 0) this.captureItems(deviceId, type, capName, items, slice, at, reconciling);
+	}
+	/**
+	* A keyed array (D917): each item with a usable key contributes its fields
+	* under that key as the series scope. A value that is not an array is no
+	* reading; an item without a string key cannot be followed and is counted.
+	*/
+	captureItems(deviceId, type, capName, items, slice, at, reconciling) {
+		const list = readPath(slice, items.path);
+		if (!Array.isArray(list)) return;
+		const { counters } = this.deps;
+		if (list.length > 64) counters.skip("item-overflow", list.length - 64);
+		for (const entry of list.slice(0, 64)) {
+			const scope = isRecord$1(entry) ? entry[items.key] : void 0;
+			if (!isRecord$1(entry) || typeof scope !== "string" || scope.length === 0 || scope.length > 128) {
+				counters.skip("item-key-invalid");
+				continue;
+			}
+			for (const [field, spec] of Object.entries(items.fields)) {
+				if (spec.excludeDeviceTypes?.includes(type) === true) continue;
+				const key = capItemSeriesKey(capName, items, field);
+				const value = this.readValue(entry, key, field, spec);
+				if (value === null) continue;
+				this.consider(deviceId, key, scope, spec, value, at, reconciling);
+			}
 		}
 	}
 	/**
@@ -670,7 +747,7 @@ var CaptureEngine = class {
 	* `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) {
+	readValue(slice, key, path, spec) {
 		if (spec.skipWhenSet !== void 0) {
 			const gate = readPath(slice, spec.skipWhenSet);
 			if (gate !== void 0 && gate !== null) return null;
@@ -678,20 +755,19 @@ var CaptureEngine = class {
 		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);
+		const ordinal = this.deps.registry.ordinalOf(key, 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);
+	consider(deviceId, key, scope, spec, value, at, reconciling) {
 		const subject = {
 			kind: "device",
 			deviceId
 		};
-		const identity = identityOf(key, `d:${deviceId}`, "");
+		const identity = identityOf(key, `d:${deviceId}`, scope);
 		const decision = decideCapture(spec, this.recorded.get(identity) ?? null, value, at, { ignoreFloor: reconciling });
 		if (decision.action === "emit") {
-			this.emit(identity, key, subject, value, at);
+			this.emit(identity, key, subject, scope, value, at);
 			if (reconciling) this.deps.counters.reconciledPoints += 1;
 			return;
 		}
@@ -699,6 +775,7 @@ var CaptureEngine = class {
 			this.pending.set(identity, {
 				key,
 				subject,
+				scope,
 				spec,
 				value
 			});
@@ -707,7 +784,7 @@ var CaptureEngine = class {
 		this.pending.delete(identity);
 		this.deps.counters.skip(decision.reason);
 	}
-	emit(identity, key, subject, value, ts) {
+	emit(identity, key, subject, scope, value, ts) {
 		this.recorded.set(identity, {
 			value,
 			ts
@@ -717,7 +794,7 @@ var CaptureEngine = class {
 		this.deps.writer.enqueue({
 			key,
 			subject,
-			scope: "",
+			scope,
 			ts,
 			value
 		});
@@ -734,7 +811,7 @@ var CaptureEngine = class {
 			}
 			const notBefore = (recorded?.ts ?? now) + minIntervalOf(p.spec);
 			if (now < notBefore) continue;
-			this.emit(identity, p.key, p.subject, p.value, notBefore);
+			this.emit(identity, p.key, p.subject, p.scope, p.value, notBefore);
 			this.deps.counters.trailingEmitted += 1;
 		}
 	}
@@ -782,16 +859,7 @@ var CaptureEngine = class {
 			if (!Number.isInteger(deviceId) || optedOut.has(deviceId)) continue;
 			const type = this.deps.directory.typeOf(deviceId);
 			if (type === void 0 || !isRealDeviceType(type)) continue;
-			for (const [capName, fields] of Object.entries(this.deps.catalog)) {
-				const slice = caps[capName];
-				if (slice === void 0) continue;
-				for (const [path, spec] of Object.entries(fields)) {
-					if (spec.excludeDeviceTypes?.includes(type) === true) continue;
-					const value = this.readValue(slice, capName, path, spec);
-					if (value === null) continue;
-					this.consider(deviceId, capName, path, spec, value, now, true);
-				}
-			}
+			for (const [capName, slice] of Object.entries(caps)) this.captureSlice(deviceId, type, capName, slice, now, true);
 		}
 	}
 	/**
@@ -817,8 +885,8 @@ var CaptureEngine = class {
 		return this.pending.size;
 	}
 	/** The last recorded state of a series, for specs. */
-	lastRecorded(key, subjectId) {
-		return this.recorded.get(identityOf(key, subjectId, ""));
+	lastRecorded(key, subjectId, scope = "") {
+		return this.recorded.get(identityOf(key, subjectId, scope));
 	}
 };
 //#endregion
@@ -1287,8 +1355,10 @@ function errorText(err) {
 }
 var HistoryQuery = class {
 	deps;
+	itemFields;
 	constructor(deps) {
 		this.deps = deps;
+		this.itemFields = itemFieldsByKey(deps.itemCatalog);
 	}
 	async query(input) {
 		if (input.key === "derived:energy.kwh") return this.queryEnergy(input);
@@ -1476,12 +1546,14 @@ var HistoryQuery = class {
 		for (const s of registry.forSubject(subjectIdOf(subject))) {
 			const metric = registry.metric(s.key);
 			if (metric === void 0) continue;
+			const item = this.itemFields.get(s.key);
+			const named = item === void 0 || subject.kind !== "device" ? null : await this.itemNaming(subject.deviceId, item, s.scope, metric.unit, slices);
 			infos.push({
 				key: s.key,
 				scope: s.scope,
 				kind: metric.kind,
-				unit: await this.unitOf(subject, s, metric.unit, slices),
-				displayName: metric.displayName,
+				unit: named !== null ? named.unit : await this.unitOf(subject, s, metric.unit, slices),
+				displayName: named !== null ? `${named.label} · ${metric.displayName}` : metric.displayName,
 				source: metric.source,
 				values: metric.kind === "enum" ? metric.values ?? [] : null,
 				firstTs: s.firstTs,
@@ -1502,15 +1574,38 @@ var HistoryQuery = class {
 		});
 		return infos.toSorted((a, b) => a.key.localeCompare(b.key) || a.scope.localeCompare(b.scope));
 	}
+	/**
+	* An item series (D917) is named after its item and takes its `unitFrom`
+	* from it, both read from the device's CURRENT slice: the item's `label`,
+	* else its key (the scope) when the item is gone or the slice unreadable.
+	*/
+	async itemNaming(deviceId, item, scope, fixed, slices) {
+		const slice = await this.sliceOf(deviceId, item.capName, slices);
+		const list = slice === null ? void 0 : readPath(slice, item.items.path);
+		const entry = Array.isArray(list) ? list.find((e) => isObject(e) && e[item.items.key] === scope) : void 0;
+		const rawLabel = entry !== void 0 && item.items.label !== void 0 ? entry[item.items.label] : void 0;
+		const label = typeof rawLabel === "string" && rawLabel.length > 0 ? rawLabel : scope;
+		if (fixed !== null || item.spec.unitFrom === void 0) return {
+			label,
+			unit: fixed
+		};
+		return {
+			label,
+			unit: entry === void 0 ? null : readUnit(entry, item.spec.unitFrom)
+		};
+	}
+	sliceOf(deviceId, capName, slices) {
+		const pending = slices.get(capName) ?? this.deps.readCapSlice(deviceId, capName).catch(() => null);
+		slices.set(capName, pending);
+		return pending;
+	}
 	/** The metric's fixed unit, else the device's own (a `unitFrom` field), else unknown. */
 	async unitOf(subject, series, fixed, slices) {
 		if (fixed !== null || subject.kind !== "device" || !series.key.startsWith("cap:")) return fixed;
 		const spec = this.specOf(series.key);
 		if (spec?.unitFrom === void 0) return null;
 		const capName = series.key.slice(CAP_KEY_PREFIX.length, series.key.indexOf("."));
-		const pending = slices.get(capName) ?? this.deps.readCapSlice(subject.deviceId, capName).catch(() => null);
-		slices.set(capName, pending);
-		const slice = await pending;
+		const slice = await this.sliceOf(subject.deviceId, capName, slices);
 		return slice === null ? null : readUnit(slice, spec.unitFrom);
 	}
 	specOf(key) {
@@ -1520,12 +1615,158 @@ var HistoryQuery = class {
 		return this.deps.catalog[body.slice(0, dot)]?.[body.slice(dot + 1)];
 	}
 };
+function isObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Series key → keyed-item field, for every item field of the catalog. */
+function itemFieldsByKey(itemCatalog) {
+	return new Map(Object.entries(itemCatalog).flatMap(([capName, items]) => Object.entries(items.fields).map(([field, spec]) => [capItemSeriesKey(capName, items, field), {
+		capName,
+		items,
+		spec
+	}])));
+}
 /** 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/orphans.ts
+/**
+* The orphan verdict of one series, or `null` when it is linked. PURE. A node
+* series is never orphan here (its subject is a node, not a device).
+*/
+function judgeOrphan(series, declaredCapKeys, missingSince) {
+	if (series.deviceId === null) return null;
+	if (missingSince !== void 0) return {
+		reason: "device-gone",
+		missingSince
+	};
+	if (series.key.startsWith("cap:") && !declaredCapKeys.has(series.key)) return {
+		reason: "undeclared",
+		missingSince: null
+	};
+	return null;
+}
+var OrphanSeries = class {
+	deps;
+	constructor(deps) {
+		this.deps = deps;
+	}
+	verdictOf(series) {
+		const { departures, declaredCapKeys } = this.deps;
+		return judgeOrphan(series, declaredCapKeys, series.deviceId === null ? void 0 : departures.missingSince(series.deviceId));
+	}
+	/** Every orphan, ordered by device, key and scope, the first {@link DEVICE_HISTORY_ORPHAN_LIST_MAX} counted. */
+	async list() {
+		const found = this.deps.registry.all().flatMap((series) => {
+			const verdict = this.verdictOf(series);
+			return verdict === null || series.deviceId === null ? [] : [{
+				series,
+				deviceId: series.deviceId,
+				verdict
+			}];
+		}).toSorted((a, b) => a.deviceId - b.deviceId || a.series.key.localeCompare(b.series.key) || a.series.scope.localeCompare(b.series.scope));
+		const out = [];
+		for (const { series, deviceId, verdict } of found.slice(0, 200)) out.push({
+			seriesId: series.id,
+			deviceId,
+			key: series.key,
+			scope: series.scope,
+			displayName: this.deps.registry.metric(series.key)?.displayName ?? null,
+			reason: verdict.reason,
+			missingSince: verdict.missingSince,
+			firstTs: series.firstTs,
+			lastTs: series.lastTs,
+			rows: await this.rowsOf(series.id)
+		});
+		return {
+			series: out,
+			truncated: found.length > 200
+		};
+	}
+	async rowsOf(seriesId) {
+		const { store } = this.deps;
+		return {
+			raw: await store.countSeriesRows("raw", seriesId),
+			"5m": await store.countSeriesRows("5m", seriesId),
+			"1h": await store.countSeriesRows("1h", seriesId),
+			"1d": await store.countSeriesRows("1d", seriesId)
+		};
+	}
+	/** Delete orphans by id, one at a time, each re-judged now. One entry per id, in order. */
+	async delete(seriesIds) {
+		const out = [];
+		for (const seriesId of seriesIds) out.push(await this.deleteOne(seriesId));
+		return out;
+	}
+	async deleteOne(seriesId) {
+		const { registry, retention, logger, clock } = this.deps;
+		const series = registry.all().find((s) => s.id === seriesId);
+		if (series === void 0) return {
+			seriesId,
+			ok: false,
+			reason: "not-found"
+		};
+		const verdict = this.verdictOf(series);
+		if (verdict === null || series.deviceId === null) {
+			logger.info("device-history: refused to delete a series that is not orphan", {
+				...series.deviceId === null ? {} : { tags: { deviceId: series.deviceId } },
+				meta: {
+					seriesId,
+					key: series.key,
+					scope: series.scope
+				}
+			});
+			return {
+				seriesId,
+				ok: false,
+				reason: "not-orphan"
+			};
+		}
+		try {
+			const deleted = await retention.purgeSeries(series, clock());
+			registry.remove(series.id);
+			const rows = {
+				raw: deleted.raw,
+				"5m": deleted["5m"],
+				"1h": deleted["1h"],
+				"1d": deleted["1d"]
+			};
+			logger.info("device-history: deleted an orphan series", {
+				tags: { deviceId: series.deviceId },
+				meta: {
+					seriesId,
+					key: series.key,
+					scope: series.scope,
+					reason: verdict.reason,
+					rows
+				}
+			});
+			return {
+				seriesId,
+				ok: true,
+				deleted: rows
+			};
+		} catch (err) {
+			logger.warn("device-history: deleting an orphan series failed — it stays listed, retry the delete", {
+				tags: { deviceId: series.deviceId },
+				meta: {
+					seriesId,
+					key: series.key,
+					error: err instanceof Error ? err.message : String(err)
+				}
+			});
+			return {
+				seriesId,
+				ok: false,
+				reason: "failed"
+			};
+		}
+	}
+};
+//#endregion
 //#region src/builtins/device-history/store/history-schema.ts
 var HISTORY_NAMESPACE = "device-history";
 var COLLECTIONS = {
@@ -2136,6 +2377,17 @@ var HistoryStore = class {
 			key: String(seriesId)
 		});
 	}
+	/**
+	* One series' rows of a tier: a range of the primary key (`series_id = ?`),
+	* never a scan of the tier (D447, asserted in `history-query-plans.spec.ts`).
+	*/
+	async countSeriesRows(tier, seriesId) {
+		return this.door.count.query({
+			namespace: HISTORY_NAMESPACE,
+			collection: collectionOf(tier),
+			filter: { where: { series_id: seriesId } }
+		});
+	}
 	async countRows(tier) {
 		return this.door.count.query({
 			namespace: HISTORY_NAMESPACE,
@@ -2696,6 +2948,7 @@ var HistoryRuntime = class {
 	query;
 	retentionJob;
 	departures;
+	orphans;
 	optedOutDevices = /* @__PURE__ */ new Set();
 	tierCounts = /* @__PURE__ */ new Map();
 	startedAt;
@@ -2704,7 +2957,7 @@ var HistoryRuntime = class {
 	ready = false;
 	constructor(deps) {
 		this.deps = deps;
-		const { logger, clock, catalog } = deps;
+		const { logger, clock, catalog, itemCatalog } = deps;
 		this.startedAt = clock();
 		this.store = new HistoryStore(deps.door);
 		this.registry = new SeriesRegistry(this.store);
@@ -2728,6 +2981,7 @@ var HistoryRuntime = class {
 		const optedOut = () => this.optedOutDevices;
 		this.capture = new CaptureEngine({
 			catalog,
+			itemCatalog,
 			registry: this.registry,
 			store: this.store,
 			directory: this.directory,
@@ -2761,6 +3015,7 @@ var HistoryRuntime = class {
 			clock,
 			retention: deps.retention,
 			catalog,
+			itemCatalog,
 			readCapSlice: deps.readCapSlice
 		});
 		this.departures = new DepartureTracker(this.store, this.registry, logger);
@@ -2777,11 +3032,20 @@ var HistoryRuntime = class {
 			counters: this.counters,
 			logger
 		});
+		this.orphans = new OrphanSeries({
+			store: this.store,
+			registry: this.registry,
+			departures: this.departures,
+			retention: this.retentionJob,
+			declaredCapKeys: new Set(catalogMetrics(catalog, itemCatalog, 0).map((m) => m.key)),
+			logger,
+			clock
+		});
 	}
 	async prepare() {
 		await this.store.declare();
 		await this.registry.load();
-		for (const metric of catalogMetrics(this.deps.catalog, this.deps.clock())) await this.registry.declareMetric(metric);
+		for (const metric of catalogMetrics(this.deps.catalog, this.deps.itemCatalog, this.deps.clock())) await this.registry.declareMetric(metric);
 		this.optedOutDevices = await this.store.loadOptOuts();
 		await this.departures.load();
 		await this.directory.refresh();
@@ -2900,6 +3164,14 @@ var HistoryRuntime = class {
 		this.optedOutDevices = new Set([...this.optedOutDevices].filter((id) => id !== deviceId));
 		return { series };
 	}
+	/** Device series no longer linked to a device — reported, never purged here. */
+	listOrphans() {
+		return this.orphans.list();
+	}
+	/** Delete orphan series by id; a series that is not orphan NOW is refused. */
+	deleteOrphans(seriesIds) {
+		return this.orphans.delete(seriesIds);
+	}
 	/** Series held per device, for the admin clean-up listing. */
 	seriesByDevice() {
 		const out = /* @__PURE__ */ new Map();
@@ -3095,7 +3367,9 @@ var DeviceHistoryAddon = class extends BaseAddon {
 			recordBuckets: async (input) => this.requireRuntime().ingest.recordBuckets(callerOf(input), input.buckets),
 			getDeviceEnabled: async (input) => ({ enabled: this.requireRuntime().isEnabled(input.deviceId) }),
 			setDeviceEnabled: async (input) => ({ enabled: await this.requireRuntime().setEnabled(input.deviceId, input.enabled) }),
-			getStatus: async () => this.requireRuntime().status()
+			getStatus: async () => this.requireRuntime().status(),
+			listOrphanSeries: async () => this.requireRuntime().listOrphans(),
+			deleteOrphanSeries: async (input) => ({ results: await this.requireRuntime().deleteOrphans(input.seriesIds) })
 		};
 		this.emitStoreReadiness("starting");
 		this.ctx.logger.info("Initialized — device-history provider registered (store opens on hub link)");
@@ -3131,6 +3405,7 @@ var DeviceHistoryAddon = class extends BaseAddon {
 		const runtime = new HistoryRuntime({
 			door: api.settingsStore,
 			catalog: HISTORY_CATALOG,
+			itemCatalog: HISTORY_ITEM_CATALOG,
 			deviceSource: {
 				listAll: async () => {
 					return (await api.deviceManager.listAll.query({ projection: "slim" })).map((d) => ({

package/dist/builtins/device-history/query/history-query.d.ts

@@ -19,11 +19,11 @@
 * 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.
 */
-import { type DeviceHistoryQueryManyEntry, type DeviceHistoryQueryManyItem, type DeviceHistoryQueryPoint, type DeviceHistoryResolution, type DeviceHistorySeriesInfo, type DeviceHistorySubject } from "@camstack/types";
+import { type CapabilityHistoryField, type CapabilityHistoryItems, type DeviceHistoryQueryManyEntry, type DeviceHistoryQueryManyItem, type DeviceHistoryQueryPoint, type DeviceHistoryResolution, type DeviceHistorySeriesInfo, type DeviceHistorySubject } from "@camstack/types";
 import { type RetentionPolicy } from "../retention/retention.js";
 import type { HistoryStore } from "../store/history-store.js";
 import { type SeriesRegistry } from "../store/series-registry.js";
-import { type HistoryCatalog } from "../capture/capture-engine.js";
+import { type HistoryCatalog, type HistoryItemCatalog } from "../capture/capture-engine.js";
 type Tier = DeviceHistoryResolution;
 /** The power-meter series the energy key is derived from, meter first. */
 export declare const ENERGY_METER_KEY: string;
@@ -66,11 +66,13 @@ export interface QueryDeps {
 	readonly clock: () => number;
 	readonly retention: () => RetentionPolicy;
 	readonly catalog: HistoryCatalog;
+	readonly itemCatalog: HistoryItemCatalog;
 	/** The device's current slice of a cap, for a `unitFrom` series; `null` when unreadable. */
 	readonly readCapSlice: (deviceId: number, capName: string) => Promise<Readonly<Record<string, unknown>> | null>;
 }
 export declare class HistoryQuery {
 	private readonly deps;
+	private readonly itemFields;
 	constructor(deps: QueryDeps);
 	query(input: QueryInput): Promise<QueryOutput>;
 	/** Several reads over one window; one failing item answers its error, not the batch's. */
@@ -88,8 +90,23 @@ export declare class HistoryQuery {
 	private energySource;
 	private queryEnergy;
 	listSeries(subject: DeviceHistorySubject): Promise<readonly DeviceHistorySeriesInfo[]>;
+	/**
+	* An item series (D917) is named after its item and takes its `unitFrom`
+	* from it, both read from the device's CURRENT slice: the item's `label`,
+	* else its key (the scope) when the item is gone or the slice unreadable.
+	*/
+	private itemNaming;
+	private sliceOf;
 	/** The metric's fixed unit, else the device's own (a `unitFrom` field), else unknown. */
 	private unitOf;
 	private specOf;
 }
+/** One keyed-item field (D917), by its series key. */
+interface ItemField {
+	readonly capName: string;
+	readonly items: CapabilityHistoryItems;
+	readonly spec: CapabilityHistoryField;
+}
+/** Series key → keyed-item field, for every item field of the catalog. */
+export declare function itemFieldsByKey(itemCatalog: HistoryItemCatalog): ReadonlyMap<string, ItemField>;
 export {};