@camstack/system 1.2.476 → 1.2.478

package/dist/retention-DdVnmXXS.mjs

@@ -0,0 +1,893 @@
+import { _i as HISTORY_DEFAULT_MIN_INTERVAL_MS, aa as historyItemFieldPath, oi as DeviceType } from "./dist-OC-L50JY.mjs";
+//#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$1(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;
+		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(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(entry) ? entry[items.key] : void 0;
+			if (!isRecord(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
+//#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
+export { subjectIdOf as S, readUnit as _, FIVE_MINUTES_MS as a, SeriesRegistry as b, bucketEndOf as c, CAP_KEY_PREFIX as d, CaptureEngine as f, readPath as g, catalogMetrics as h, DAY_MS as i, bucketStartOf as l, capSeriesKey as m, RetentionJob as n, HOUR_MS as o, capItemSeriesKey as p, DepartureTracker as r, ROLLUP_GRACE_MS as s, DEFAULT_RETENTION as t, floorTo as u, DeviceDirectory as v, identityOf as x, isRealDeviceType as y };