@camstack/addon-provider-homeassistant 1.2.617 → 1.2.619

package/dist/ha-export/ha-export.addon.js

@@ -24,7 +24,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 	enumerable: true
 }) : target, mod));
 //#endregion
-const require_dist = require("../dist-CfZUXrNa.js");
+const require_dist = require("../dist-DwxJnRNc.js");
 let node_crypto = require("node:crypto");
 require("node:zlib");
 let node_fs = require("node:fs");
@@ -699,6 +699,234 @@ var ComponentSupportTracker = class {
 	}
 };
 //#endregion
+//#region src/ha-export/item-entities.ts
+/**
+* Per-item entities — the reconcile-time mint `CAP_ENTITY_MAP` cannot express.
+*
+* `CAP_ENTITY_MAP` is static per capability: one row, a fixed set of
+* entities, each reading one flat field. A capability whose value is an
+* ARRAY of provider-named items (`consumables.items`: a brush, a filter, a
+* clean-water tank, a dishwasher's salt) has a different entity set on every
+* device, and the set changes when the provider reports a new item. This
+* module mints that set from the device's OWN slice, pure:
+*
+*   slice → `ItemEntity[]` (structure, announced by the catalog)
+*   slice → `StateValue[]` (values, pushed by the addon)
+*
+* Both halves come from the same function per capability, so an entity can
+* never be announced under one id and fed under another.
+*
+* The STRUCTURE goes through a `ReadMirror` in the addon before it reaches
+* the plan: an item that appears is announced at once, an item that leaves
+* is removed only when two consecutive reads agree (D49) — a removal deletes
+* the entity and its recorder history in Home Assistant.
+*
+* A capability listed here is CLASSIFIED for the export-coverage guard
+* (`scripts/check-export-coverage.ts`), which checks `itemsField` against the
+* capability's status schema exactly as it checks a `CAP_ENTITY_MAP` field.
+*/
+var CONSUMABLE_PREFIX = "consumable";
+/** Outside `ConsumableStatusSchema` on purpose: the component reads it as unknown. */
+var STATUS_UNKNOWN = "unknown";
+function consumableEntity(key, facet) {
+	return `${CONSUMABLE_PREFIX}_${toSlug(key)}_${facet}`;
+}
+/** Home Assistant's own duration units; a cycle count is a plain count. */
+var REMAINING_UNIT = {
+	days: "d",
+	hours: "h",
+	cycles: "cycles"
+};
+/**
+* The item's form (the capability's own derivation, `consumableFormOf`): the one
+* the provider declared when it is a form the capability knows, else the one its
+* kind implies. An unknown spelling is not trusted — it falls back to the kind
+* rather than to an icon for nothing.
+*/
+function consumableForm(item) {
+	const declared = require_dist.ConsumableFormSchema.safeParse(item.form);
+	return require_dist.consumableFormOf({
+		...item.kind !== void 0 ? { kind: item.kind } : {},
+		...declared.success ? { form: declared.data } : {}
+	});
+}
+/** A part is drawn by what it is when its key or label says so. */
+function partIcon(key, label) {
+	if (`${key} ${label}`.toLowerCase().includes("brush")) return "mdi:brush";
+	return "mdi:air-filter";
+}
+function formIcon(item, form) {
+	switch (form) {
+		case "part": return partIcon(item.key, item.label);
+		case "tank": return require_dist.consumableKindOf(item) === "waste" ? "mdi:water-off" : "mdi:water";
+		case "product": return "mdi:shaker-outline";
+		case "bin": return "mdi:delete";
+	}
+}
+/**
+* The item as this export reads it: the capability's own item, plus a
+* `form` read as `unknown` and narrowed by {@link consumableForm} — so a
+* form this export does not know degrades one icon instead of refusing the
+* whole slice.
+*/
+var ExportConsumableItemSchema = require_dist.ConsumableItemSchema.extend({ form: require_dist.unknown().optional() });
+var ExportConsumablesSchema = require_dist.object({ items: require_dist.array(ExportConsumableItemSchema) });
+/**
+* A worn part's life is a diagnostic; a tank's fill is what the device page
+* is for (a vacuum's clean water, a dishwasher's salt), so it is not hidden.
+*/
+function levelCategory(kind) {
+	return kind === "wear" ? "diagnostic" : void 0;
+}
+function consumableEntities(item) {
+	const base = {
+		capName: "consumables",
+		itemKey: item.key
+	};
+	const kind = require_dist.consumableKindOf(item);
+	const form = consumableForm(item);
+	const icon = formIcon(item, form);
+	/** What the item IS, on the sensors that describe it (not on a counter or a button). */
+	const attributes = {
+		form,
+		kind,
+		label: item.label
+	};
+	const out = [];
+	const unique = (facet) => `${CONSUMABLE_PREFIX}_${item.key}_${facet}`;
+	if (item.level !== null) {
+		const category = levelCategory(kind);
+		out.push({
+			...base,
+			facet: "level",
+			entity: consumableEntity(item.key, "level"),
+			uniqueSuffix: unique("level"),
+			platform: "sensor",
+			label: item.label,
+			unit: "%",
+			stateClass: "measurement",
+			icon,
+			attributes,
+			...category !== void 0 ? { entityCategory: category } : {}
+		});
+	}
+	if (item.status !== null)
+ /**
+	* An `enum` sensor over the cap's own vocabulary — the options come from
+	* `ConsumableStatusSchema`, never a second list here.
+	*/
+	out.push({
+		...base,
+		facet: "status",
+		entity: consumableEntity(item.key, "status"),
+		uniqueSuffix: unique("status"),
+		platform: "sensor",
+		label: `${item.label} status`,
+		deviceClass: "enum",
+		options: require_dist.ConsumableStatusSchema.options,
+		icon,
+		attributes,
+		entityCategory: "diagnostic"
+	});
+	if (item.remaining !== void 0) {
+		const isDuration = item.remaining.unit !== "cycles";
+		out.push({
+			...base,
+			facet: "remaining",
+			entity: consumableEntity(item.key, "remaining"),
+			uniqueSuffix: unique("remaining"),
+			platform: "sensor",
+			label: `${item.label} remaining`,
+			unit: REMAINING_UNIT[item.remaining.unit],
+			stateClass: "measurement",
+			...isDuration ? { deviceClass: "duration" } : {},
+			icon: isDuration ? "mdi:timer-sand" : "mdi:counter",
+			entityCategory: "diagnostic"
+		});
+	}
+	if (item.resettable) out.push({
+		...base,
+		facet: "reset",
+		entity: consumableEntity(item.key, "reset"),
+		uniqueSuffix: unique("reset"),
+		platform: "button",
+		label: `Reset ${item.label}`,
+		icon: "mdi:restore",
+		entityCategory: "config"
+	});
+	return out;
+}
+function consumableValues(item) {
+	const out = [];
+	if (item.level !== null) out.push({
+		entity: consumableEntity(item.key, "level"),
+		value: String(item.level)
+	});
+	/**
+	* A null verdict is published OUTSIDE the enum, which the component reads
+	* as `unknown` — publishing nothing would leave the last verdict standing
+	* (D393: unknown is never the previous value).
+	*/
+	out.push({
+		entity: consumableEntity(item.key, "status"),
+		value: item.status ?? STATUS_UNKNOWN
+	});
+	if (item.remaining !== void 0 && item.remaining.value !== null) out.push({
+		entity: consumableEntity(item.key, "remaining"),
+		value: String(item.remaining.value)
+	});
+	return out;
+}
+function parseConsumables(slice) {
+	const parsed = ExportConsumablesSchema.safeParse(slice);
+	return parsed.success ? parsed.data.items : null;
+}
+/**
+* Two items whose keys slug alike would claim one entity id. The first
+* keeps it; the second is left out rather than announced twice under one
+* component key, where Home Assistant would show either value at random.
+*/
+function firstPerEntity(rows) {
+	const seen = /* @__PURE__ */ new Set();
+	return rows.filter((row) => {
+		if (seen.has(row.entity)) return false;
+		seen.add(row.entity);
+		return true;
+	});
+}
+/** capability → its per-item mint. */
+var ITEM_ENTITY_MAP = { consumables: {
+	itemsField: "items",
+	entities: (slice) => {
+		const items = parseConsumables(slice);
+		return items === null ? null : firstPerEntity(items.flatMap(consumableEntities));
+	},
+	values: (slice) => {
+		const items = parseConsumables(slice);
+		return items === null ? null : firstPerEntity(items.flatMap(consumableValues));
+	}
+} };
+/** The entities one capability's slice mints, or `null` for a malformed slice. */
+function itemEntitiesFor(capName, slice) {
+	const mapping = ITEM_ENTITY_MAP[capName];
+	return mapping === void 0 ? null : mapping.entities(slice);
+}
+/** The values one capability's slice carries, on their state topics. */
+function projectItemSlice(deviceKey, capName, slice) {
+	const mapping = ITEM_ENTITY_MAP[capName];
+	if (mapping === void 0) return null;
+	const values = mapping.values(slice);
+	if (values === null) return null;
+	return values.map((v) => ({
+		topic: stateTopic(deviceKey, v.entity),
+		value: v.value
+	}));
+}
+/** True for a capability whose entities are minted per item. */
+function isItemEntityCap(capName) {
+	return Object.prototype.hasOwnProperty.call(ITEM_ENTITY_MAP, capName);
+}
+//#endregion
 //#region src/ha-export/native-platforms.ts
 /**
 * The NATIVE half of the Home Assistant export.
@@ -1396,6 +1624,8 @@ function buildComponent(device, spec) {
 		...spec.writable === true && COMMANDABLE_PLATFORMS.has(spec.platform) ? { command_topic: commandTopic(deviceKey, spec.entity) } : {},
 		...spec.deviceClass !== void 0 ? { device_class: spec.deviceClass } : {},
 		...spec.unit !== void 0 ? { unit_of_measurement: spec.unit } : {},
+		...spec.stateClass !== void 0 ? { state_class: spec.stateClass } : {},
+		...spec.attributes !== void 0 ? { attributes: spec.attributes } : {},
 		...spec.icon !== void 0 ? { icon: spec.icon } : {},
 		...spec.options !== void 0 ? { options: spec.options } : {},
 		...spec.range !== void 0 ? {
@@ -1825,9 +2055,36 @@ function assemble(device, specs) {
 		cmps
 	};
 }
-/** The hand-written half: a camera's entities come from analytics. */
+/**
+* The per-item entities of every per-item capability the device binds
+* (`item-entities.ts`), as the reconcile settled them. A button is a
+* command, so it is the one writable kind.
+*/
+function itemEntitySpecs(device, capName) {
+	return (device.itemEntities?.[capName] ?? []).map((item) => ({
+		entity: item.entity,
+		platform: item.platform,
+		label: item.label,
+		uniqueSuffix: item.uniqueSuffix,
+		enabledByDefault: true,
+		...item.deviceClass !== void 0 ? { deviceClass: item.deviceClass } : {},
+		...item.unit !== void 0 ? { unit: item.unit } : {},
+		...item.stateClass !== void 0 ? { stateClass: item.stateClass } : {},
+		...item.attributes !== void 0 ? { attributes: item.attributes } : {},
+		...item.options !== void 0 ? { options: item.options } : {},
+		...item.icon !== void 0 ? { icon: item.icon } : {},
+		...item.entityCategory !== void 0 ? { entityCategory: item.entityCategory } : {},
+		...item.platform === "button" ? { writable: true } : {}
+	}));
+}
+/**
+* The hand-written half: a camera's entities come from analytics — plus
+* the per-item capabilities, which bind on every device type (a camera can
+* report consumables like anything else) and mint the same ids either way.
+*/
 function buildCameraPlan(device) {
-	return assemble(device, cameraSpecs(device));
+	const items = device.boundCaps.filter((cap) => isItemEntityCap(cap)).flatMap((cap) => itemEntitySpecs(device, cap));
+	return assemble(device, [...cameraSpecs(device), ...items]);
 }
 /**
 * capability → the entities it produces.
@@ -1870,13 +2127,14 @@ function buildCameraPlan(device) {
 *
 * ── Why a nested object is never a field ────────────────────────────────
 *
-* `renderCapValue` carries strings, numbers and booleans. `color.rgb`,
-* `vacuum-control.dustBin`, `event-emitter.lastEvent` and
-* `consumables.items` are objects and arrays: mapping one would publish
+* `renderCapValue` carries strings, numbers and booleans. `color.rgb` and
+* `event-emitter.lastEvent` are objects: mapping one would publish
 * an entity that reports `unrenderable` on every single delivery. Where a
 * capability's headline value is only expressible as an object, the flat
 * neighbours are exported and the object is named in the doc comment
-* rather than mapped.
+* rather than mapped. An ARRAY of named items (`consumables.items`) is not
+* a row here either: `ITEM_ENTITY_MAP` (`item-entities.ts`) mints one
+* entity set per item from the device's own slice.
 */
 var CAP_ENTITY_MAP = {
 	switch: {
@@ -2613,18 +2871,6 @@ var CAP_ENTITY_MAP = {
 				entityCategory: "config",
 				enabledByDefault: false
 			},
-			salt: {
-				platform: "sensor",
-				field: "saltLevel",
-				label: "Salt level",
-				enabledByDefault: false
-			},
-			"rinse-aid": {
-				platform: "sensor",
-				field: "rinseAidLevel",
-				label: "Rinse aid level",
-				enabledByDefault: false
-			},
 			error: {
 				platform: "sensor",
 				field: "errorLabel",
@@ -3377,13 +3623,9 @@ var CAPS_NOT_EXPORTED = [
 		cap: "events",
 		reason: "A paginated event LOG, not a state. Its natural target is HA's `event` platform, which the component does not build (Tier B)."
 	},
-	{
-		cap: "consumables",
-		reason: "The value is `items`, an ARRAY of per-device consumables named by the provider (a filter, a brush, a cartridge). This table is static per capability, so it cannot mint one sensor per item; doing it needs a reconcile-time entity mint keyed on the device, which is a design, not a row."
-	},
 	{
 		cap: "scene-monitor",
-		reason: "Per-ROI reference-region state, `monitors` being an array of operator-named regions. Same shape as consumables: the entity set is per device and changes when the operator adds a region, which a static descriptor cannot express."
+		reason: "Per-ROI reference-region state, `monitors` being an array of operator-named regions. The entity set is per device and changes when the operator adds a region, which a static descriptor cannot express. `ITEM_ENTITY_MAP` (`item-entities.ts`) is the per-item mint that could carry it; what each region should become in Home Assistant is not decided."
 	},
 	{
 		cap: "audio-metrics",
@@ -3432,7 +3674,11 @@ function degradeUnsupported(spec, options) {
 }
 /** A capability in neither list — the thing the guard exists to surface. */
 function unclassifiedCaps(caps) {
-	const known = new Set([...Object.keys(CAP_ENTITY_MAP), ...CAPS_NOT_EXPORTED.map((e) => e.cap)]);
+	const known = new Set([
+		...Object.keys(CAP_ENTITY_MAP),
+		...Object.keys(ITEM_ENTITY_MAP),
+		...CAPS_NOT_EXPORTED.map((e) => e.cap)
+	]);
 	return [...new Set(caps)].filter((cap) => !known.has(cap)).sort();
 }
 /**
@@ -3477,6 +3723,11 @@ function buildDerivedPlan(device, options = UNNEGOTIATED_PLAN_OPTIONS) {
 		* two halves of this file would build the same entity id twice.
 		*/
 		if (CAMERA_DERIVED_CAPS.includes(cap)) continue;
+		/** Per-item: the entity set comes from the slice, not from a row. */
+		if (isItemEntityCap(cap)) {
+			specs.push(...itemEntitySpecs(device, cap).map((spec) => degradeUnsupported(spec, options)));
+			continue;
+		}
 		/**
 		* `control` is slice-shaped: select options and number bounds are not
 		* on the static row. Mint the announced platform here; the CAP_ENTITY_MAP
@@ -4176,7 +4427,33 @@ var TEMPERATURE_MIN = -20;
 var TEMPERATURE_MAX = 90;
 var MIRED_MIN = 50;
 var MIRED_MAX = 1e3;
+/**
+* capability → what pressing one of its per-item buttons does. The builder
+* receives the item's KEY in place of a payload (a button's payload is
+* always `PRESS`). Keyed like `ITEM_ENTITY_MAP`; the spec asserts every cap
+* there that mints a button has a route here.
+*/
+var ITEM_COMMAND_ROUTES = { consumables: (deviceId, key) => key.length === 0 ? null : {
+	kind: "consumable-reset",
+	deviceId,
+	key
+} };
 function resolveCommand(target, entity, value) {
+	/**
+	* The per-item half — first, because a camera binds per-item caps too.
+	* Only a `button` is a command; the item it addresses is the one the plan
+	* announced, so a press for an item that left the
+	* slice (or was never resettable) is `unknown-entity`, never a guess.
+	*/
+	const item = target.itemEntities?.find((candidate) => candidate.entity === entity && candidate.platform === "button");
+	if (item !== void 0) {
+		if (!target.boundCaps.includes(item.capName)) return {
+			ok: false,
+			reason: "cap-not-bound",
+			capName: item.capName
+		};
+		return build(ITEM_COMMAND_ROUTES[item.capName], target.deviceId, item.itemKey, item.capName);
+	}
 	if (target.type === "camera") {
 		const switchId = CAMERA_SWITCH_BY_SLUG[entity];
 		if (switchId !== void 0) {
@@ -4579,6 +4856,7 @@ async function applyCapCommand(device, command) {
 				case "vario-speed-plus": return dishwasher.setVarioSpeedPlus({ on: command.on });
 			}
 		});
+		case "consumable-reset": return call(device.consumables, "consumables", (consumables) => consumables.reset({ key: command.key }));
 	}
 }
 /**
@@ -6469,6 +6747,12 @@ var HaExportAddon = class extends require_dist.BaseAddon {
 	streamsMirror = new ReadMirror((stream) => stream.id);
 	presetsMirror = new ReadMirror((preset) => preset);
 	switchesMirror = new ReadMirror((fn) => fn.id);
+	/**
+	* Per-item capability → its mirror, keyed by entity id. An item that
+	* leaves the slice deletes its entities (and their history) in Home
+	* Assistant, so the removal waits for a second read to agree (D49).
+	*/
+	itemEntityMirrors = new Map(Object.keys(ITEM_ENTITY_MAP).map((cap) => [cap, new ReadMirror((item) => item.entity)]));
 	/** A held-back read is retried soon, not at the next 300 s pass. */
 	readTimer = null;
 	entityCount = 0;
@@ -6654,6 +6938,11 @@ var HaExportAddon = class extends require_dist.BaseAddon {
 		if (deviceId === null || capName === null || slice === null) return;
 		const deviceKey = this.keyByDeviceId.get(deviceId);
 		if (deviceKey === void 0) return;
+		/** Per-item: on a camera and a base device alike, minted from the slice. */
+		if (isItemEntityCap(capName)) {
+			this.pushItemCap(deviceId, deviceKey, capName, slice);
+			return;
+		}
 		if (capName !== "device-status" && capName !== "battery" && !this.isCamera(deviceKey)) {
 			this.pushDerivedCap(deviceId, deviceKey, capName, slice);
 			return;
@@ -6793,6 +7082,51 @@ var HaExportAddon = class extends require_dist.BaseAddon {
 				return;
 		}
 	}
+	/** The per-item values of one slice that land on an entity the plan announced. */
+	announcedItemValues(entry, capName, slice) {
+		const key = entry.plan.deviceKey;
+		const topics = new Set((entry.target.itemEntities ?? []).filter((item) => item.capName === capName).map((item) => stateTopic(key, item.entity)));
+		return (projectItemSlice(key, capName, slice) ?? []).filter((value) => topics.has(value.topic));
+	}
+	/**
+	* The per-item push (`item-entities.ts`).
+	*
+	* Values land only on entities the plan announced. When the slice mints a
+	* different entity SET than the plan holds — an item appeared, left, or
+	* started reporting a level — the structure is re-derived by a debounced
+	* reconcile; the item mirror there decides whether a removal is believed.
+	*/
+	pushItemCap(deviceId, deviceKey, capName, slice) {
+		const minted = itemEntitiesFor(capName, slice);
+		if (minted === null) {
+			this.warnOnce(deviceId, capName, "items", {
+				message: "ha-export: a per-item slice is not the capability shape, nothing published",
+				meta: {
+					capName,
+					sliceFields: Object.keys(slice)
+				}
+			});
+			return;
+		}
+		const entry = this.exported.get(deviceKey);
+		if (entry === void 0) return;
+		const announced = (entry.target.itemEntities ?? []).filter((item) => item.capName === capName);
+		const landing = this.announcedItemValues(entry, capName, slice);
+		if (landing.length > 0) this.push(deviceId, landing);
+		const mintedIds = minted.map((item) => item.entity).toSorted();
+		const announcedIds = announced.map((item) => item.entity).toSorted();
+		if (mintedIds.join("\0") !== announcedIds.join("\0")) {
+			this.ctx.logger.info("ha-export: a per-item entity set changed, re-announcing the device", {
+				tags: { deviceId },
+				meta: {
+					capName,
+					added: mintedIds.filter((id) => !announcedIds.includes(id)),
+					removed: announcedIds.filter((id) => !mintedIds.includes(id))
+				}
+			});
+			this.reconcileSoon();
+		}
+	}
 	/** deviceId:cap:field already reported. Bounded by devices × mapped caps. */
 	warnedCapFields = /* @__PURE__ */ new Set();
 	warnOnce(deviceId, capName, field, line) {
@@ -7117,7 +7451,8 @@ var HaExportAddon = class extends require_dist.BaseAddon {
 					target: {
 						deviceId: numericId,
 						type: device.type,
-						boundCaps: catalogDevice.boundCaps
+						boundCaps: catalogDevice.boundCaps,
+						itemEntities: Object.values(catalogDevice.itemEntities ?? {}).flat()
 					},
 					brokerIds,
 					streams: catalogDevice.streams ?? [],
@@ -7512,6 +7847,10 @@ var HaExportAddon = class extends require_dist.BaseAddon {
 			const isCamera = entry.target.type === "camera";
 			for (const [capName, capSlice] of Object.entries(snapshot)) {
 				if (capName === "device-status" || capName === "battery") continue;
+				if (isItemEntityCap(capName)) {
+					values.push(...this.announcedItemValues(entry, capName, capSlice));
+					continue;
+				}
 				if (isCamera && !CAMERA_DERIVED_CAPS.includes(capName)) continue;
 				const projection = projectCapSlice(key, capName, capSlice);
 				if (projection.kind === "values") values.push(...projection.values);
@@ -7616,6 +7955,8 @@ var HaExportAddon = class extends require_dist.BaseAddon {
 			device: null,
 			heldBack
 		};
+		const items = this.settleItemEntities(device.id, boundCaps, snapshot);
+		if (items.held) heldBack = true;
 		const manufacturer = readString(device.metadata ?? {}, "manufacturer");
 		const model = readString(device.metadata ?? {}, "model");
 		return {
@@ -7638,11 +7979,60 @@ var HaExportAddon = class extends require_dist.BaseAddon {
 				* `availableModes` is on the slice and nowhere else. See
 				* `CatalogDevice.capSlices`.
 				*/
-				capSlices: snapshot
+				capSlices: snapshot,
+				itemEntities: items.entities
 			},
 			heldBack
 		};
 	}
+	/**
+	* The per-item entities of every per-item capability the device binds,
+	* through each capability's mirror.
+	*
+	* An ABSENT slice is an answer — the capability is inert until a provider
+	* sets items — so it reads as "no items", and a set that was announced
+	* shrinks only when the next read agrees. A slice that is not the
+	* capability's shape is a failed read: the held set is announced again,
+	* and with nothing held the device is announced WITHOUT those entities
+	* rather than held back whole, because a malformed consumables slice must
+	* not take a vacuum's every other entity out of Home Assistant.
+	*/
+	settleItemEntities(deviceId, boundCaps, snapshot) {
+		const entities = {};
+		let held = false;
+		for (const cap of boundCaps) {
+			const mirror = this.itemEntityMirrors.get(cap);
+			if (mirror === void 0) continue;
+			const slice = snapshot[cap];
+			const minted = slice === void 0 ? [] : itemEntitiesFor(cap, slice);
+			const outcome = minted === null ? {
+				kind: "failed",
+				reason: `the ${cap} slice is not the capability shape`
+			} : {
+				kind: "answered",
+				items: minted
+			};
+			const resolution = mirror.resolve(deviceId, outcome);
+			if (resolution.status === "unknown") {
+				this.ctx.logger.warn("ha-export: a per-item slice is not the capability shape and nothing was exported yet, announcing the device without its items", {
+					tags: { deviceId },
+					meta: {
+						capName: cap,
+						reason: resolution.reason
+					}
+				});
+				entities[cap] = [];
+				continue;
+			}
+			if (resolution.status !== "fresh") held = true;
+			this.logHeldRead(deviceId, cap, resolution);
+			entities[cap] = resolution.items;
+		}
+		return {
+			entities,
+			held
+		};
+	}
 	/** One WARN per held part, with the device tag and the reason. */
 	logHeldRead(deviceId, part, resolution) {
 		if (resolution.status === "fresh") return;