@camstack/system 1.2.476 → 1.2.478

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

@@ -1,895 +1,5 @@
-import { $r as DeviceType, B as HISTORY_ITEM_CATALOG, Ct as armRemovalReconcile, D as DEVICE_HISTORY_ENERGY_KEY, Oa as EventCategory, Qi as historyItemFieldPath, Yi as emitReadiness, en as deviceHistoryCapability, nn as deviceRemovalHookCapability, ti as BaseAddon, ui as HISTORY_DEFAULT_MIN_INTERVAL_MS, z as HISTORY_CATALOG } from "../../dist-B_V9r61Z.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).
-	* 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;
-			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
-	* 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}`;
-}
-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;
-	}
-	async load() {
-		this.metrics.clear();
-		this.byIdentity.clear();
-		this.byId.clear();
-		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);
-			for (const s of page) this.index(s);
-			const last = page[page.length - 1];
-			if (last === void 0 || page.length < LOAD_PAGE) break;
-			afterId = last.id;
-		}
-	}
-	index(series) {
-		this.byId.set(series.id, series);
-		this.byIdentity.set(identityOf(series.key, series.subject, series.scope), series);
-	}
-	metric(key) {
-		return this.metrics.get(key);
-	}
-	allMetrics() {
-		return [...this.metrics.values()];
-	}
-	/**
-	* 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);
-		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));
-	}
-	byIdOf(id) {
-		return this.byId.get(id);
-	}
-	all() {
-		return [...this.byId.values()];
-	}
-	forSubject(subjectId) {
-		return this.all().filter((s) => s.subject === subjectId);
-	}
-	forKeyAndSubject(key, subjectId) {
-		return this.all().filter((s) => s.key === key && s.subject === subjectId);
-	}
-	/** The series, created on first sight. `ts` stamps `first_ts`/`last_ts` of a new one. */
-	async ensure(key, subject, scope, ts) {
-		const subjectId = subjectIdOf(subject);
-		const identity = identityOf(key, subjectId, scope);
-		const known = this.byIdentity.get(identity);
-		if (known !== void 0) return known;
-		const pending = this.inflight.get(identity);
-		if (pending !== void 0) return pending;
-		const created = this.create(key, subjectId, deviceIdOf(subject), scope, ts).finally(() => {
-			this.inflight.delete(identity);
-		});
-		this.inflight.set(identity, created);
-		return created;
-	}
-	async create(key, subjectId, deviceId, scope, ts) {
-		const stored = await this.store.findSeries(key, subjectId, scope) ?? await this.store.insertSeries({
-			key,
-			subject: subjectId,
-			deviceId,
-			scope,
-			ts
-		});
-		this.index(stored);
-		return stored;
-	}
-	/** Remember a widened span (the store write is the caller's). */
-	noteSpan(id, firstTs, lastTs) {
-		const current = this.byId.get(id);
-		if (current === void 0) return;
-		this.index({
-			...current,
-			firstTs: Math.min(current.firstTs, firstTs),
-			lastTs: Math.max(current.lastTs, lastTs)
-		});
-	}
-	remove(id) {
-		const current = this.byId.get(id);
-		if (current === void 0) return;
-		this.byId.delete(id);
-		this.byIdentity.delete(identityOf(current.key, current.subject, current.scope));
-		for (const listener of this.removeListeners) listener(current);
-	}
-	/** Per-series state elsewhere (last recorded value, dirty marks, rate limits) is dropped through this. */
-	onRemove(listener) {
-		this.removeListeners.push(listener);
-	}
-};
-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 && JSON.stringify(a.values) === JSON.stringify(b.values);
-}
-//#endregion
-//#region src/builtins/device-history/capture/capture-filter.ts
-/**
-* The per-point capture decision for a cap field (D850, plan §5.3). PURE.
-*
-* A point is written only when the value CHANGED from the last one recorded,
-* by more than the field's deadband, and no sooner than its capture floor:
-*
-*  - `unchanged`  — the same value again; a change-only series stores nothing;
-*  - `deadband`   — a change smaller than `deadband` (absolute) or
-*                   `deadbandPct` (relative to the last recorded value); a slow
-*                   drift is still caught, because the comparison is against
-*                   the last RECORDED value, not the last seen one;
-*  - `defer`      — changed, but inside `minIntervalMs` of the last recorded
-*                   point. NOT dropped: the caller keeps it pending and emits it
-*                   once the floor has passed, so a burst never loses its end.
-*/
-/** Tolerance for floating-point steps such as 21.3 - 21.2 against a 0.1 deadband. */
-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" || spec.kind === "enum" ? 0 : HISTORY_DEFAULT_MIN_INTERVAL_MS;
-}
-function clearsDeadband(spec, last, value) {
-	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) {
-		if (delta < Math.abs(last) * spec.deadbandPct / 100 - DEADBAND_EPSILON) return false;
-	}
-	return true;
-}
-function decideCapture(spec, recorded, value, now, options = {}) {
-	if (!Number.isFinite(value)) return {
-		action: "skip",
-		reason: "non-finite"
-	};
-	if (recorded === null) return { action: "emit" };
-	if (value === recorded.value) return {
-		action: "skip",
-		reason: "unchanged"
-	};
-	if (!clearsDeadband(spec, recorded.value, value)) return {
-		action: "skip",
-		reason: "deadband"
-	};
-	if (options.ignoreFloor !== true) {
-		const notBefore = recorded.ts + minIntervalOf(spec);
-		if (now < notBefore) return {
-			action: "defer",
-			notBefore
-		};
-	}
-	return { action: "emit" };
-}
-//#endregion
-//#region src/builtins/device-history/capture/device-directory.ts
-/**
-* Which devices exist and what type they are — the "real devices only" gate
-* (`hub` and `container` are not devices anyone charts) and the
-* `excludeDeviceTypes` gate of a history field.
-*
-* Built from `deviceManager.listAll({ projection: 'slim' })` at boot and every
-* reconcile, and per device (`getDevice`) the first time a state event names one
-* the map does not know. A FAILED read changes nothing (D49): the previous map
-* stays, and the failure is counted and logged, never read as "no devices".
-*/
-function isRealDeviceType(type) {
-	return type !== DeviceType.Hub && type !== DeviceType.Container;
-}
-var DeviceDirectory = class {
-	source;
-	counters;
-	logger;
-	clock;
-	types = /* @__PURE__ */ new Map();
-	inflight = /* @__PURE__ */ new Map();
-	refreshInflight = null;
-	lastFullRefreshAt = null;
-	constructor(source, counters, logger, clock) {
-		this.source = source;
-		this.counters = counters;
-		this.logger = logger;
-		this.clock = clock;
-	}
-	typeOf(deviceId) {
-		return this.types.get(deviceId);
-	}
-	size() {
-		return this.types.size;
-	}
-	/** When the full listing last ANSWERED; `null` before the first answer. */
-	lastRefreshAt() {
-		return this.lastFullRefreshAt;
-	}
-	/** Ids in the directory now (the last full listing plus per-device lookups). */
-	listedIds() {
-		return new Set(this.types.keys());
-	}
-	knows(deviceId) {
-		return this.types.has(deviceId);
-	}
-	/** Replace the map from the full listing. Returns false (map untouched) when the read failed. */
-	refresh() {
-		if (this.refreshInflight !== null) return this.refreshInflight;
-		const run = this.doRefresh().finally(() => {
-			this.refreshInflight = null;
-		});
-		this.refreshInflight = run;
-		return run;
-	}
-	async doRefresh() {
-		try {
-			const all = await this.source.listAll();
-			this.types = new Map(all.map((d) => [d.id, d.type]));
-			this.lastFullRefreshAt = this.clock();
-			this.counters.directoryRefreshAt = this.lastFullRefreshAt;
-			return true;
-		} catch (err) {
-			this.logger.warn("device directory: listing failed — keeping the previous map", { meta: { error: err instanceof Error ? err.message : String(err) } });
-			return false;
-		}
-	}
-	/** The device's type, asking the hub once when the map does not know it. */
-	ensure(deviceId) {
-		const known = this.types.get(deviceId);
-		if (known !== void 0) return Promise.resolve(known);
-		const pending = this.inflight.get(deviceId);
-		if (pending !== void 0) return pending;
-		const run = this.lookup(deviceId).finally(() => {
-			this.inflight.delete(deviceId);
-		});
-		this.inflight.set(deviceId, run);
-		return run;
-	}
-	async lookup(deviceId) {
-		try {
-			const device = await this.source.getDevice(deviceId);
-			if (device === null) return void 0;
-			this.types.set(device.id, device.type);
-			return device.type;
-		} catch (err) {
-			this.logger.warn("device directory: lookup failed", {
-				tags: { deviceId },
-				meta: { error: err instanceof Error ? err.message : String(err) }
-			});
-			return;
-		}
-	}
-};
-//#endregion
-//#region src/builtins/device-history/capture/field-path.ts
-/**
-* Reading a history field out of a cap slice. A catalog path is a top-level
-* `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$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$2(current)) return void 0;
-		current = current[step];
-	}
-	return current;
-}
-/**
-* The number a field contributes: a finite number for a gauge/counter, 0/1 for
-* a boolean field. Anything else (null, undefined, a string, NaN) is NOT a
-* reading — `null` means unknown and must never become 0.
-*/
-function readNumeric(slice, path, kind) {
-	const raw = readPath(slice, path);
-	if (kind === "boolean") {
-		if (typeof raw === "boolean") return raw ? 1 : 0;
-		return null;
-	}
-	if (typeof raw === "number" && Number.isFinite(raw)) return raw;
-	return null;
-}
-/** A unit string a `unitFrom` sibling field states, or `null` when it states none. */
-function readUnit(slice, unitFrom) {
-	const raw = readPath(slice, unitFrom);
-	return typeof raw === "string" && raw.length > 0 ? raw : null;
-}
-//#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}`;
-}
-function metricOf(key, capName, path, spec, now) {
-	return {
-		key,
-		source: "cap",
-		ownerAddon: "device-history",
-		subjectKind: "device",
-		kind: spec.kind,
-		unit: spec.unit ?? null,
-		displayName: spec.displayName ?? humanize(capName, path),
-		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;
-/** Seeding reads the newest raw row of each cap series, this many at once. */
-var SEED_CONCURRENCY = 8;
-var CaptureEngine = class {
-	deps;
-	recorded = /* @__PURE__ */ new Map();
-	pending = /* @__PURE__ */ new Map();
-	parked = /* @__PURE__ */ new Map();
-	constructor(deps) {
-		this.deps = deps;
-	}
-	/** Learn the last recorded value of every cap series from the store, so a restart repeats nothing. */
-	async seed() {
-		const { registry, store } = this.deps;
-		const capSeries = registry.all().filter((s) => s.key.startsWith(CAP_KEY_PREFIX));
-		for (let i = 0; i < capSeries.length; i += SEED_CONCURRENCY) await Promise.all(capSeries.slice(i, i + SEED_CONCURRENCY).map(async (series) => {
-			const newest = await store.rawBefore(series.id, Number.MAX_SAFE_INTEGER);
-			if (newest === null) return;
-			this.recorded.set(identityOf(series.key, series.subject, series.scope), newest);
-		}));
-	}
-	/** One `DeviceStateChanged`. Synchronous: the bus must never wait on us. */
-	handleState(deviceId, capName, slice, at) {
-		const fields = this.deps.catalog[capName];
-		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)) {
-			counters.skip("opted-out");
-			return;
-		}
-		const type = directory.typeOf(deviceId);
-		if (type === void 0) {
-			this.park(deviceId, capName, slice, at);
-			return;
-		}
-		if (!isRealDeviceType(type)) {
-			counters.skip("not-a-real-device");
-			return;
-		}
-		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) {
-				if (!reconciling) this.deps.counters.skip("excluded-device-type");
-				continue;
-			}
-			const key = capSeriesKey(capName, path);
-			const value = this.readValue(slice, key, path, spec);
-			if (value === null) continue;
-			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);
-			}
-		}
-	}
-	/**
-	* 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, key, 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(key, raw);
-		if (ordinal === null) this.deps.counters.skip("enum-overflow");
-		return ordinal;
-	}
-	consider(deviceId, key, scope, spec, value, at, reconciling) {
-		const subject = {
-			kind: "device",
-			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, scope, value, at);
-			if (reconciling) this.deps.counters.reconciledPoints += 1;
-			return;
-		}
-		if (decision.action === "defer") {
-			this.pending.set(identity, {
-				key,
-				subject,
-				scope,
-				spec,
-				value
-			});
-			return;
-		}
-		this.pending.delete(identity);
-		this.deps.counters.skip(decision.reason);
-	}
-	emit(identity, key, subject, scope, value, ts) {
-		this.recorded.set(identity, {
-			value,
-			ts
-		});
-		this.pending.delete(identity);
-		this.deps.counters.pointsEmitted += 1;
-		this.deps.writer.enqueue({
-			key,
-			subject,
-			scope,
-			ts,
-			value
-		});
-	}
-	/** Emit every pending change whose capture floor has passed, stamped where the floor ended. */
-	tickPending(now) {
-		for (const [identity, p] of this.pending) {
-			const recorded = this.recorded.get(identity);
-			const deviceId = p.subject.kind === "device" ? p.subject.deviceId : -1;
-			if (this.deps.optedOut().has(deviceId)) {
-				this.pending.delete(identity);
-				this.deps.counters.skip("opted-out");
-				continue;
-			}
-			const notBefore = (recorded?.ts ?? now) + minIntervalOf(p.spec);
-			if (now < notBefore) continue;
-			this.emit(identity, p.key, p.subject, p.scope, p.value, notBefore);
-			this.deps.counters.trailingEmitted += 1;
-		}
-	}
-	park(deviceId, capName, slice, at) {
-		const existing = this.parked.get(deviceId);
-		if (existing !== void 0) {
-			existing.set(capName, {
-				capName,
-				slice,
-				at
-			});
-			return;
-		}
-		if (this.parked.size >= MAX_PARKED_DEVICES) {
-			const oldest = this.parked.keys().next();
-			if (oldest.done !== true) this.parked.delete(oldest.value);
-			this.deps.counters.skip("parked-overflow");
-		}
-		this.parked.set(deviceId, new Map([[capName, {
-			capName,
-			slice,
-			at
-		}]]));
-		this.deps.directory.ensure(deviceId).then((type) => {
-			const waiting = this.parked.get(deviceId);
-			this.parked.delete(deviceId);
-			if (waiting === void 0) return;
-			if (type === void 0) {
-				this.deps.counters.skip("unknown-device", waiting.size);
-				return;
-			}
-			for (const p of waiting.values()) this.handleState(deviceId, p.capName, p.slice, p.at);
-		});
-	}
-	/**
-	* Restore a missed change from the state mirror's whole snapshot: a field whose
-	* value differs from the last recorded one gets a point stamped `now`.
-	* Additive only — it never removes anything, and a snapshot that could not be
-	* read is the CALLER's failure to count (D49), not an empty snapshot.
-	*/
-	reconcile(snapshots, now) {
-		const optedOut = this.deps.optedOut();
-		for (const [deviceKey, caps] of Object.entries(snapshots)) {
-			const deviceId = Number(deviceKey);
-			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, slice] of Object.entries(caps)) this.captureSlice(deviceId, type, capName, slice, now, true);
-		}
-	}
-	/**
-	* Forget what was "recorded" for points that never reached the store (dropped),
-	* so the next change-only comparison — and the next reconcile — starts from what
-	* is really there instead of leaving a hole until the value moves.
-	*/
-	forget(points) {
-		for (const p of points) {
-			const identity = identityOf(p.key, subjectIdOf(p.subject), p.scope);
-			this.recorded.delete(identity);
-			this.pending.delete(identity);
-		}
-	}
-	/** A purged series leaves no state behind. */
-	forgetSeries(series) {
-		const identity = identityOf(series.key, series.subject, series.scope);
-		this.recorded.delete(identity);
-		this.pending.delete(identity);
-	}
-	/** For status and specs. */
-	pendingCount() {
-		return this.pending.size;
-	}
-	/** The last recorded state of a series, for specs. */
-	lastRecorded(key, subjectId, scope = "") {
-		return this.recorded.get(identityOf(key, subjectId, scope));
-	}
-};
-//#endregion
+import { B as HISTORY_CATALOG, D as DEVICE_HISTORY_ENERGY_KEY, Fa as EventCategory, Tt as armRemovalReconcile, V as HISTORY_ITEM_CATALOG, an as deviceRemovalHookCapability, ci as BaseAddon, na as emitReadiness, rn as deviceHistoryCapability } from "../../dist-OC-L50JY.mjs";
+import { S as subjectIdOf, _ as readUnit, a as FIVE_MINUTES_MS, b as SeriesRegistry, c as bucketEndOf, d as CAP_KEY_PREFIX, f as CaptureEngine, g as readPath, h as catalogMetrics, i as DAY_MS, l as bucketStartOf, m as capSeriesKey, n as RetentionJob, o as HOUR_MS, p as capItemSeriesKey, r as DepartureTracker, s as ROLLUP_GRACE_MS, t as DEFAULT_RETENTION, u as floorTo, v as DeviceDirectory, x as identityOf, y as isRealDeviceType } from "../../retention-DdVnmXXS.mjs";
 //#region src/builtins/device-history/capture/point-writer.ts
 var FLUSH_INTERVAL_MS = 1e4;
 var MAX_BUFFER_AGE_MS = 6e4;