@camstack/addon-post-analysis 1.2.292 → 1.2.294

package/dist/pipeline-analytics/index.js

@@ -2,7 +2,7 @@ Object.defineProperties(exports, {
 	__esModule: { value: true },
 	[Symbol.toStringTag]: { value: "Module" }
 });
-const require_clip_model_registry = require("../clip-model-registry-CTY5co6P.js");
+const require_clip_model_registry = require("../clip-model-registry-BVhju940.js");
 let node_fs = require("node:fs");
 node_fs = require_clip_model_registry.__toESM(node_fs, 1);
 let node_path = require("node:path");
@@ -67587,15 +67587,17 @@ function resolveMediaSettings(raw) {
 * `recording` became a device collection on 2026-09-24 (D625): a camera may
 * have several sources of recorded coverage and every read names one. Every
 * read in this addon wants the same one — the footage OUR recorder wrote,
-* because everything downstream of it (a recorded clip cut, a timelapse, the
-* earliest-footage floor of a retention sweep) is about bytes we hold and can
-* export. A camera's own SD card is not an answer to any of those questions.
+* because everything downstream of it (a recorded clip cut, a timelapse) is
+* about bytes we hold and can export. The retention sweep's earliest-footage
+* floor is NOT asked here any more: it is one number the archive's ledger
+* already folds, and asking it as coverage from the epoch walked every hour
+* since 1970 (D674, `retention/archive-footage-floor.ts`). A camera's own SD card is not an answer to any of those questions.
 *
 * It also owns the `read: 'unreadable'` rule, in one place: a read that FAILED
 * throws here rather than arriving downstream as an empty range list. Every
 * caller of this module treats "no ranges" as "recording is off for this
-* camera" and acts on it — dropping the attachment, skipping the render,
-* lowering the sweep floor — so folding a failed read into that shape would
+* camera" and acts on it — dropping the attachment, skipping the render —
+* so folding a failed read into that shape would
 * make an unreachable recorder look exactly like a camera nobody records
 * (D393). The callers already handle a throw and log it as a read failure.
 */
@@ -67614,6 +67616,248 @@ async function ourRecordingAvailability(api, input) {
 		profilesWithFootage: answer.profilesWithFootage
 	};
 }
+//#endregion
+//#region src/pipeline-analytics/retention-policy.ts
+/**
+* Analytics retention policy — **ONE window per device** (D62).
+*
+* A device has one retention window, and everything scoped to that device is
+* deleted on it: the track (which cascades to its object events, their child
+* crops, its media, its unassigned face/plate rows and crops, and its CLIP
+* vector) AND the trackless roots (motion, audio, sensor events). The only
+* thing outside it is the ops log, which is global and longer than any device
+* window because it records what retention did — including for devices that no
+* longer exist.
+*
+* Two modes:
+*
+*  - `follow-recordings` (the DEFAULT): the window is the instant of the oldest
+*    segment still on disk. That follows the recorder's age retention AND its
+*    disk-pressure eviction automatically, with no second policy to keep in
+*    sync. A camera with no footage at all (recording off / brand new) falls
+*    back to `trackRetentionDays`, so analytics stay bounded either way.
+*
+*  - `custom`: `trackRetentionDays`, and nothing else. `0` = keep forever, and
+*    that is the ONE way retention is off for a device.
+*
+* ## Why there is only one number here
+*
+* There used to be four: `trackRetentionDays` plus a day window per event
+* family (motion / object / audio). [D61](../../../../docs/decisions/adr-0061.md)
+* made object events, faces, plates, crops and vectors TRACK-OWNED — they leave
+* through the cascade and by no other path — which silently disconnected
+* `retentionObjectDays` from the thing it was named after. An operator could set
+* object retention to 30 days, the form would save it, and the events would die
+* with their track at 7. A knob that decides nothing is worse than a missing
+* one: it reads as a decision that was made.
+*
+* So the per-family windows are gone (D62), not merely ignored, and the
+* surviving surface is ENUMERATED in {@link RETENTION_SETTING_KEYS} so
+* `scripts/check-retention-settings-consumed.ts` can fail the build the next
+* time a knob and its reader come apart.
+*
+* Follow-mode floor: nothing younger than {@link FOLLOW_FLOOR_DAYS} is ever
+* pruned, even when footage is younger (a camera that STARTED recording
+* yesterday must not nuke its whole history back to the first segment).
+*/
+var DAY_MS$1 = 1440 * 60 * 1e3;
+/**
+* Per-device analytics retention settings as stored in the device blob.
+* `retentionMode` absent = follow-recordings (the default).
+*/
+var RetentionSettingsSchema = require_clip_model_registry.object({
+	retentionMode: require_clip_model_registry._enum(["follow-recordings", "custom"]).default("follow-recordings"),
+	trackRetentionDays: require_clip_model_registry.number().min(0).default(7)
+});
+/** The default retention window, in days. The form's default reads from here so
+*  the schema is the single source. */
+var TRACK_RETENTION_DEFAULT_DAYS = RetentionSettingsSchema.parse({}).trackRetentionDays;
+/** Resolve the settings from a raw device-store blob — invalid or missing
+*  fields fall back to defaults, never throw. */
+function resolveRetentionSettings(raw) {
+	const parsed = RetentionSettingsSchema.safeParse(raw);
+	if (parsed.success) return parsed.data;
+	const shape = RetentionSettingsSchema.shape;
+	const defaults = RetentionSettingsSchema.parse({});
+	const mode = shape.retentionMode.safeParse(raw["retentionMode"]);
+	const days = shape.trackRetentionDays.safeParse(raw["trackRetentionDays"]);
+	return {
+		retentionMode: mode.success ? mode.data : defaults.retentionMode,
+		trackRetentionDays: days.success ? days.data : defaults.trackRetentionDays
+	};
+}
+/**
+* Follow-mode cutoff: the oldest retained footage instant, floored so anything
+* younger than {@link FOLLOW_FLOOR_DAYS} survives. `null` footage (none on
+* disk) → `null`, and the caller falls back to the custom window.
+*/
+function followCutoffMs(nowMs, earliestFootageMs) {
+	if (earliestFootageMs === null) return null;
+	return Math.min(earliestFootageMs, nowMs - 7 * DAY_MS$1);
+}
+/** Compute the effective cutoff for one device at `nowMs`. */
+function resolveRetentionCutoffs(settings, nowMs, earliestFootageMs) {
+	if (settings.retentionMode === "follow-recordings") {
+		const cutoff = followCutoffMs(nowMs, earliestFootageMs);
+		if (cutoff !== null) return {
+			cutoffMs: cutoff,
+			effectiveMode: "follow-recordings"
+		};
+	}
+	return {
+		cutoffMs: settings.trackRetentionDays <= 0 ? null : nowMs - settings.trackRetentionDays * DAY_MS$1,
+		effectiveMode: "custom"
+	};
+}
+//#endregion
+//#region src/pipeline-analytics/retention/archive-footage-floor.ts
+/**
+* How long one archive answer serves every camera. The ledger's floor moves
+* only when retention deletes an hour (minutes-to-days granularity), and the
+* sweep it feeds runs every 5 min — the same 10 min the walk was cached for.
+*/
+var FOOTAGE_FLOOR_TTL_MS = 10 * 6e4;
+/**
+* How long a FAILED read is reused before it is asked again. Short, so the
+* first sweep after the recorder answers is a real one; long enough that one
+* pass over ~24 cameras is one failed call, not twenty-four.
+*/
+var FOOTAGE_FLOOR_RETRY_MS = 6e4;
+/** What a follow-recordings camera gets when its floor could not be read:
+*  retention OFF for this pass — nothing is deleted on a guess. */
+var UNREADABLE_FLOOR_CUTOFFS = {
+	cutoffMs: null,
+	effectiveMode: "follow-recordings",
+	floorUnreadable: true
+};
+var NO_FOOTAGE = {
+	kind: "read",
+	oldestMs: null
+};
+/**
+* Turn one `getStorageUsage` answer into per-camera floors — or say why it
+* cannot be.
+*
+*  - `devicesRead !== 'archive'`: the rows are UNKNOWN (`unavailable`: no
+*    ledger, a ledger not loaded yet, no location resolved) or come from a
+*    recorder predating D418, whose rows are RESIDENCY. No floor may be read.
+*  - `complete !== true`: the ledger load was cut at its row cap, or the
+*    recorder predates the field. A camera ABSENT from such an answer may hold
+*    footage, and a PRESENT row's `oldestMs` is the oldest of a fraction (the
+*    load keeps the newest hours) — too young, i.e. a delete. So the whole
+*    answer is unreadable, not only the absent cameras.
+*  - A row whose `oldestMs` is ABSENT comes from a recorder predating the
+*    field — unknown for that camera, never "no footage".
+*  - A camera with no row in a COMPLETE answer, or a row whose `oldestMs` is
+*    `null`: the archive holds no footage for it — the custom window applies.
+*/
+function footageFloorsOf(usage) {
+	if (usage.devicesRead !== "archive") return `recordingArchive.getStorageUsage answered devicesRead=${usage.devicesRead ?? "absent"} — the per-camera rows are not the archive`;
+	if (usage.complete !== true) return `recordingArchive.getStorageUsage answered complete=${String(usage.complete ?? "absent")} — the per-camera rows may be a fraction of the archive`;
+	const floors = /* @__PURE__ */ new Map();
+	for (const row of usage.devices) floors.set(row.deviceId, row.oldestMs === void 0 ? {
+		kind: "unreadable",
+		reason: "the recorder omitted oldestMs for this camera"
+	} : {
+		kind: "read",
+		oldestMs: row.oldestMs
+	});
+	return floors;
+}
+/**
+* Per-camera floors, one archive call per {@link FOOTAGE_FLOOR_TTL_MS} for the
+* whole fleet, single-flight.
+*/
+var ArchiveFootageFloors = class {
+	deps;
+	answer = null;
+	inFlight = null;
+	/** Cameras whose sweep is currently skipped — one line per episode, not per
+	*  pass: two sweeps × every camera × every 5 min would be a flood. */
+	skipped = /* @__PURE__ */ new Set();
+	/** Is the archive currently unreadable? The read-failure line is said once
+	*  per EPISODE (and its end once), not once per ~sweep per runner. */
+	readFailing = false;
+	constructor(deps) {
+		this.deps = deps;
+	}
+	nowMs() {
+		return this.deps.now?.() ?? Date.now();
+	}
+	async floorOf(deviceId) {
+		const answer = await this.current();
+		if ("unreadable" in answer) return {
+			kind: "unreadable",
+			reason: answer.unreadable
+		};
+		return answer.floors.get(deviceId) ?? NO_FOOTAGE;
+	}
+	/**
+	* The per-device effective cutoffs (mode + footage → numbers). A follow
+	* camera whose floor is unreadable is NOT swept this pass, and that is logged.
+	*/
+	async cutoffsFor(deviceId, settings, nowMs) {
+		if (settings.retentionMode !== "follow-recordings") return resolveRetentionCutoffs(settings, nowMs, null);
+		const floor = await this.floorOf(deviceId);
+		if (floor.kind === "unreadable") {
+			if (!this.skipped.has(deviceId)) {
+				this.skipped.add(deviceId);
+				this.deps.logger.warn("retention: follow-recordings floor unreadable — this camera is not swept until the archive answers", {
+					tags: { deviceId },
+					meta: { reason: floor.reason }
+				});
+			}
+			return UNREADABLE_FLOOR_CUTOFFS;
+		}
+		if (this.skipped.delete(deviceId)) this.deps.logger.info("retention: follow-recordings floor readable again — sweeping", {
+			tags: { deviceId },
+			meta: { oldestMs: floor.oldestMs }
+		});
+		return resolveRetentionCutoffs(settings, nowMs, floor.oldestMs);
+	}
+	async current() {
+		const held = this.answer;
+		const now = this.nowMs();
+		if (held !== null) {
+			const ttl = "unreadable" in held ? FOOTAGE_FLOOR_RETRY_MS : FOOTAGE_FLOOR_TTL_MS;
+			if (now - held.atMs < ttl) return held;
+		}
+		this.inFlight ??= this.read().finally(() => {
+			this.inFlight = null;
+		});
+		return this.inFlight;
+	}
+	async read() {
+		let answer;
+		try {
+			const floors = footageFloorsOf(await this.deps.api.recordingArchive.getStorageUsage.query({}));
+			answer = typeof floors === "string" ? {
+				atMs: this.nowMs(),
+				unreadable: floors
+			} : {
+				atMs: this.nowMs(),
+				floors
+			};
+		} catch (err) {
+			answer = {
+				atMs: this.nowMs(),
+				unreadable: `recordingArchive.getStorageUsage failed: ${err instanceof Error ? err.message : String(err)}`
+			};
+		}
+		if ("unreadable" in answer && !this.readFailing) {
+			this.readFailing = true;
+			this.deps.logger.warn("retention: the archive floor could not be read — follow-recordings cameras are not swept on a guess", { meta: {
+				reason: answer.unreadable,
+				retryMs: FOOTAGE_FLOOR_RETRY_MS
+			} });
+		} else if (!("unreadable" in answer) && this.readFailing) {
+			this.readFailing = false;
+			this.deps.logger.info("retention: the archive floor is readable again", { meta: { cameras: answer.floors.size } });
+		}
+		this.answer = answer;
+		return answer;
+	}
+};
 function toDetectionBbox(bbox) {
 	return {
 		x: bbox.x,
@@ -79042,7 +79286,7 @@ async function sweepTracklessRoots(deps) {
 			const cutoffs = await deps.resolveCutoffs(deviceId, deps.nowMs);
 			const cutoffMs = cutoffs.cutoffMs;
 			if (cutoffMs === null) {
-				deps.onRetentionDisabled(deviceId);
+				if (cutoffs.floorUnreadable !== true) deps.onRetentionDisabled(deviceId);
 				continue;
 			}
 			const events = await deps.evictTracklessEvents({
@@ -79064,99 +79308,6 @@ async function sweepTracklessRoots(deps) {
 	}
 }
 //#endregion
-//#region src/pipeline-analytics/retention-policy.ts
-/**
-* Analytics retention policy — **ONE window per device** (D62).
-*
-* A device has one retention window, and everything scoped to that device is
-* deleted on it: the track (which cascades to its object events, their child
-* crops, its media, its unassigned face/plate rows and crops, and its CLIP
-* vector) AND the trackless roots (motion, audio, sensor events). The only
-* thing outside it is the ops log, which is global and longer than any device
-* window because it records what retention did — including for devices that no
-* longer exist.
-*
-* Two modes:
-*
-*  - `follow-recordings` (the DEFAULT): the window is the instant of the oldest
-*    segment still on disk. That follows the recorder's age retention AND its
-*    disk-pressure eviction automatically, with no second policy to keep in
-*    sync. A camera with no footage at all (recording off / brand new) falls
-*    back to `trackRetentionDays`, so analytics stay bounded either way.
-*
-*  - `custom`: `trackRetentionDays`, and nothing else. `0` = keep forever, and
-*    that is the ONE way retention is off for a device.
-*
-* ## Why there is only one number here
-*
-* There used to be four: `trackRetentionDays` plus a day window per event
-* family (motion / object / audio). [D61](../../../../docs/decisions/adr-0061.md)
-* made object events, faces, plates, crops and vectors TRACK-OWNED — they leave
-* through the cascade and by no other path — which silently disconnected
-* `retentionObjectDays` from the thing it was named after. An operator could set
-* object retention to 30 days, the form would save it, and the events would die
-* with their track at 7. A knob that decides nothing is worse than a missing
-* one: it reads as a decision that was made.
-*
-* So the per-family windows are gone (D62), not merely ignored, and the
-* surviving surface is ENUMERATED in {@link RETENTION_SETTING_KEYS} so
-* `scripts/check-retention-settings-consumed.ts` can fail the build the next
-* time a knob and its reader come apart.
-*
-* Follow-mode floor: nothing younger than {@link FOLLOW_FLOOR_DAYS} is ever
-* pruned, even when footage is younger (a camera that STARTED recording
-* yesterday must not nuke its whole history back to the first segment).
-*/
-var DAY_MS$1 = 1440 * 60 * 1e3;
-/**
-* Per-device analytics retention settings as stored in the device blob.
-* `retentionMode` absent = follow-recordings (the default).
-*/
-var RetentionSettingsSchema = require_clip_model_registry.object({
-	retentionMode: require_clip_model_registry._enum(["follow-recordings", "custom"]).default("follow-recordings"),
-	trackRetentionDays: require_clip_model_registry.number().min(0).default(7)
-});
-/** The default retention window, in days. The form's default reads from here so
-*  the schema is the single source. */
-var TRACK_RETENTION_DEFAULT_DAYS = RetentionSettingsSchema.parse({}).trackRetentionDays;
-/** Resolve the settings from a raw device-store blob — invalid or missing
-*  fields fall back to defaults, never throw. */
-function resolveRetentionSettings(raw) {
-	const parsed = RetentionSettingsSchema.safeParse(raw);
-	if (parsed.success) return parsed.data;
-	const shape = RetentionSettingsSchema.shape;
-	const defaults = RetentionSettingsSchema.parse({});
-	const mode = shape.retentionMode.safeParse(raw["retentionMode"]);
-	const days = shape.trackRetentionDays.safeParse(raw["trackRetentionDays"]);
-	return {
-		retentionMode: mode.success ? mode.data : defaults.retentionMode,
-		trackRetentionDays: days.success ? days.data : defaults.trackRetentionDays
-	};
-}
-/**
-* Follow-mode cutoff: the oldest retained footage instant, floored so anything
-* younger than {@link FOLLOW_FLOOR_DAYS} survives. `null` footage (none on
-* disk) → `null`, and the caller falls back to the custom window.
-*/
-function followCutoffMs(nowMs, earliestFootageMs) {
-	if (earliestFootageMs === null) return null;
-	return Math.min(earliestFootageMs, nowMs - 7 * DAY_MS$1);
-}
-/** Compute the effective cutoff for one device at `nowMs`. */
-function resolveRetentionCutoffs(settings, nowMs, earliestFootageMs) {
-	if (settings.retentionMode === "follow-recordings") {
-		const cutoff = followCutoffMs(nowMs, earliestFootageMs);
-		if (cutoff !== null) return {
-			cutoffMs: cutoff,
-			effectiveMode: "follow-recordings"
-		};
-	}
-	return {
-		cutoffMs: settings.trackRetentionDays <= 0 ? null : nowMs - settings.trackRetentionDays * DAY_MS$1,
-		effectiveMode: "custom"
-	};
-}
-//#endregion
 //#region src/pipeline-analytics/runtime/binding-cache.ts
 var BindingCache = class {
 	api;
@@ -95410,37 +95561,26 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_clip_m
 		await this.trackCloser.sweep();
 		await this.summarySealer?.sweep();
 	}
-	/** Unified retention (Phase 1): earliest retained footage per device — the
-	*  follow-recordings cutoff source. Cached 10 min: availability answers in
-	*  ~70 ms but the sweep asks once per device per pass. `null` = no footage
-	*  (or recorder unreachable) → the policy falls back to the custom windows. */
-	earliestFootageCache = /* @__PURE__ */ new Map();
-	async earliestFootageMs(deviceId) {
-		const cached = this.earliestFootageCache.get(deviceId);
-		if (cached && Date.now() - cached.at < 10 * 6e4) return cached.value;
-		let value = null;
-		try {
-			const res = await ourRecordingAvailability(this.ctx.api, {
-				deviceId,
-				fromMs: 0,
-				toMs: Date.now()
-			});
-			let min = Number.POSITIVE_INFINITY;
-			for (const r of res.ranges) if (r.startMs < min) min = r.startMs;
-			value = Number.isFinite(min) ? min : null;
-		} catch {
-			value = null;
-		}
-		this.earliestFootageCache.set(deviceId, {
-			at: Date.now(),
-			value
+	/**
+	* The follow-recordings floor per camera, read from the ARCHIVE's hour ledger
+	* (`recordingArchive.getStorageUsage`, one call for every camera) — never an
+	* availability walk from the epoch, which cost the recorder 2.2 GB and an OOM
+	* (D674). LAZY: `ctx` is not assigned when field initialisers run.
+	*/
+	footageFloorsInstance = null;
+	get footageFloors() {
+		this.footageFloorsInstance ??= new ArchiveFootageFloors({
+			api: this.ctx.api,
+			logger: this.ctx.logger
 		});
-		return value;
+		return this.footageFloorsInstance;
 	}
-	/** The per-device effective cutoffs (mode + footage → numbers). */
+	/** The per-device effective cutoffs (mode + footage → numbers). A
+	*  follow-recordings camera whose floor could not be read gets NO cutoff this
+	*  pass (logged in `ArchiveFootageFloors`), never the custom window. */
 	async deviceRetentionCutoffs(deviceId, nowMs) {
-		const settings = resolveRetentionSettings(await this.readDeviceBlob(deviceId));
-		return resolveRetentionCutoffs(settings, nowMs, settings.retentionMode === "follow-recordings" ? await this.earliestFootageMs(deviceId) : null);
+		const raw = await this.readDeviceBlob(deviceId);
+		return this.footageFloors.cutoffsFor(deviceId, resolveRetentionSettings(raw), nowMs);
 	}
 	/**
 	* The devices one retention pass covers — see `retention/retention-scope.ts`