@camstack/addon-pipeline 1.2.257 → 1.2.259

package/dist/recorder/index.js

@@ -3,10 +3,10 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 const require_chunk = require("../chunk-emK7D4bc.js");
-const require_dist = require("../dist-BMARLLlX.js");
-const require_node = require("../node-Ca-vE0xX.js");
+const require_dist = require("../dist-CsJJPDQW.js");
+const require_node = require("../node-1vbEWzPZ.js");
 const require_hub_hostname = require("../hub-hostname-DAJXlOgV.js");
-const require_restream_intent = require("../restream-intent-VVJiUAkh.js");
+const require_restream_intent = require("../restream-intent-iKGCB9IR.js");
 const require_retire_root_keys = require("../retire-root-keys-Csb8z2f3.js");
 let node_crypto = require("node:crypto");
 let node_fs = require("node:fs");
@@ -820,14 +820,22 @@ function parseSegmentPath(relPath) {
 /** Hour bucket, the granularity the path convention (`.../YYYY/MM/DD/HH/`)
 *  already gives us — so "have I walked this?" costs one Set lookup. */
 var HOUR_MS$9 = 36e5;
-/** A device walked end-to-end. Cheaper and clearer than inserting every hour of
-*  the retention window into the set. */
-var ALL_HOURS = Symbol("all-hours");
 /** The hour buckets a half-open span touches. */
 function* hourBuckets(fromMs, toMs) {
 	const first = Math.floor(fromMs / HOUR_MS$9) * HOUR_MS$9;
 	for (let h = first; h < toMs; h += HOUR_MS$9) yield h;
 }
+/** The hour bucket a segment belongs to — the same one its path encodes. */
+function hourOf$1(startMs) {
+	return Math.floor(startMs / HOUR_MS$9) * HOUR_MS$9;
+}
+/** The production bound. See {@link RecordingIndexBudget} for the measurement. */
+var DEFAULT_RECORDING_INDEX_BUDGET = {
+	residentRowBudget: 25e4,
+	residentHourBudget: 2e4,
+	evictToFraction: .8,
+	pinnedTailHours: 2
+};
 /**
 * Index of the first element whose `startMs` is GREATER than `startMs` (upper
 * bound). Inserting there keeps equal-start rows in arrival order — exactly
@@ -875,10 +883,35 @@ var RecordingIndex = class {
 	/** See {@link HydrateReuseStats}. */
 	rowsReused = 0;
 	rowsAllocated = 0;
-	/** Hour buckets this device has been walked for; `ALL_HOURS` after a full
-	*  hydrate. Empty = nothing has been looked at, which is NOT the same as
-	*  "there is nothing" — see {@link hydrationOf}. */
+	/**
+	* Hour buckets this device has been walked for → when anything last ASKED
+	* about that hour ({@link useTick}, 0 = never since the walk). Empty =
+	* nothing has been looked at, which is NOT the same as "there is nothing" —
+	* see {@link hydrationOf}.
+	*
+	* The tick is the eviction order, and it lives here rather than in a side
+	* map because an evicted hour must lose its marker in the SAME operation
+	* that loses its rows: a walked marker outliving its rows would report
+	* `hydrated` over an hour the index no longer holds, which is the one
+	* failure a forgetting index must not have.
+	*
+	* There used to be an `ALL_HOURS` sentinel here for a device walked
+	* end-to-end. It had no production caller (2026-08-30 census) and a bounded
+	* index can never truthfully claim it, so it is gone.
+	*/
 	walked = /* @__PURE__ */ new Map();
+	/** Monotonic "somebody asked" counter. Only ever compared, never read out. */
+	useTick = 0;
+	/** `null` until {@link armResidency}. An unarmed index never evicts. */
+	residencyDeps = null;
+	evictedRows = 0;
+	evictedHours = 0;
+	evictionPasses = 0;
+	/** Hours dropped per device, for the life of the process. One number per
+	*  camera — the input to {@link droppedDuringWalk}, nothing else. */
+	evictedHoursByDevice = /* @__PURE__ */ new Map();
+	/** {@link evictedHoursByDevice} as it stood when a whole-device walk began. */
+	walkBaseline = /* @__PURE__ */ new Map();
 	/**
 	* Upper bound on the `durMs` of any row the index holds — the ONLY thing that
 	* turns "walk the whole sorted view" into "walk backwards a bounded number of
@@ -1052,7 +1085,9 @@ var RecordingIndex = class {
 	* Deliberately NOT delete-all-then-reinsert: the archive walk re-reports rows
 	* this index already holds, with freshly built path strings, and dropping the
 	* held rows first would make those fresh strings the permanent ones — a
-	* second copy of the whole archive's paths. See {@link retainedPathStrings}.
+	* second copy of the whole archive's paths. See {@link RecordingIndex.rowFor}
+	* for the measurement (`retainedPathStrings`, which this used to point at,
+	* never existed — a leftover that read as a verification, removed 2026-09-17).
 	* @residency mutation
 	*/
 	hydrateDevice(deviceId, locationId, relPaths) {
@@ -1066,6 +1101,7 @@ var RecordingIndex = class {
 		}
 		for (const [path, existing] of m) if (existing.locationId === locationId && !seen.has(path)) m.delete(path);
 		this.invalidateSorted(deviceId);
+		this.enforceResidency();
 	}
 	/**
 	* Whether the index has WALKED `[fromMs, toMs)` for a device.
@@ -1079,7 +1115,6 @@ var RecordingIndex = class {
 	hydrationOf(deviceId, fromMs, toMs) {
 		const w = this.walked.get(deviceId);
 		if (w === void 0) return "unknown";
-		if (w === ALL_HOURS) return "hydrated";
 		let seen = 0;
 		let total = 0;
 		for (const h of hourBuckets(fromMs, toMs)) {
@@ -1091,15 +1126,225 @@ var RecordingIndex = class {
 	}
 	/** Record that `[fromMs, toMs)` has been walked, whatever it contained. @residency mutation */
 	markHydrated(deviceId, fromMs, toMs) {
+		let w = this.walked.get(deviceId);
+		if (w === void 0) {
+			w = /* @__PURE__ */ new Map();
+			this.walked.set(deviceId, w);
+		}
+		const tick = ++this.useTick;
+		for (const h of hourBuckets(fromMs, toMs)) w.set(h, tick);
+	}
+	/**
+	* Bound this index, and give it somewhere to SAY what it dropped.
+	*
+	* Called once, from the recorder addon's initialize — `ctx.logger` does not
+	* exist when the field is constructed. Until it runs the index never evicts,
+	* which is honest for the pre-init window (it holds nothing) and is the one
+	* state in which {@link ResidencyCensus.budget} is `null`.
+	* @residency mutation
+	*/
+	armResidency(deps) {
+		this.residencyDeps = deps;
+		this.enforceResidency();
+	}
+	/**
+	* A whole-device walk is starting: remember how much this index had already
+	* forgotten about that camera, so {@link droppedDuringWalk} can say whether
+	* the walk's result is a COMPLETE view of what it read.
+	* @residency mutation
+	*/
+	beginWalk(deviceId) {
+		this.walkBaseline.set(deviceId, this.evictedHoursByDevice.get(deviceId) ?? 0);
+	}
+	/**
+	* Did this index drop anything for `deviceId` since {@link beginWalk}?
+	*
+	* The one question a PRUNE has to ask. An hour the index dropped is
+	* indistinguishable, from the outside, from an hour disk no longer has — so
+	* a consumer that deletes durable state on the index's silence must refuse
+	* when the answer is `true`. `false` when nobody called `beginWalk`: an
+	* unarmed index never drops, and a caller that never announced a walk is
+	* asking about one that did not happen.
+	* @residency resident-scoped
+	*/
+	droppedDuringWalk(deviceId) {
+		const baseline = this.walkBaseline.get(deviceId);
+		if (baseline === void 0) return false;
+		return (this.evictedHoursByDevice.get(deviceId) ?? 0) > baseline;
+	}
+	/** What is held, what was let go, and under which bound. @residency resident-scoped */
+	residency() {
+		return {
+			residentRows: this.residentRowCount(),
+			residentHours: this.residentHourCount(),
+			evictedRows: this.evictedRows,
+			evictedHours: this.evictedHours,
+			evictionPasses: this.evictionPasses,
+			budget: this.residencyDeps?.budget ?? null
+		};
+	}
+	residentRowCount() {
+		let n = 0;
+		for (const m of this.byDevice.values()) n += m.size;
+		return n;
+	}
+	residentHourCount() {
+		let n = 0;
+		for (const w of this.walked.values()) n += w.size;
+		return n;
+	}
+	/**
+	* Note that something ASKED about `[fromMs, toMs)` — the only input to the
+	* eviction order.
+	*
+	* Walks whichever side is smaller: a read whose span is wider than the
+	* device's whole walked map (a month-wide `ranges`, an availability sweep)
+	* would otherwise iterate one hour at a time across the span.
+	*/
+	touch(deviceId, fromMs, toMs) {
 		const w = this.walked.get(deviceId);
-		if (w === ALL_HOURS) return;
-		const set = w ?? /* @__PURE__ */ new Set();
-		for (const h of hourBuckets(fromMs, toMs)) set.add(h);
-		this.walked.set(deviceId, set);
+		if (w === void 0 || w.size === 0) return;
+		const tick = ++this.useTick;
+		if (Math.ceil(Math.max(0, toMs - fromMs) / HOUR_MS$9) > w.size) {
+			for (const h of w.keys()) if (h < toMs && h + HOUR_MS$9 > fromMs) w.set(h, tick);
+			return;
+		}
+		for (const h of hourBuckets(fromMs, toMs)) if (w.has(h)) w.set(h, tick);
 	}
-	/** Record that the device was walked end-to-end (the background full walk). @residency mutation */
-	markHydratedAll(deviceId) {
-		this.walked.set(deviceId, ALL_HOURS);
+	/**
+	* Drop the least-recently-asked-about hours until the index is back inside
+	* its budget.
+	*
+	* ## What a dropped hour costs, and why that is safe
+	*
+	* The directory is the authority for which segments exist — every row here
+	* is derived from a path the walk read, and `hydrateHour` /
+	* `hydrateWindowFromStorage` rebuild it from one shallow `readdir` (or one
+	* ledger point read). So a drop costs a re-read, never a segment. The
+	* property that makes it costs-a-read rather than loses-a-segment is that
+	* the walked marker goes with the rows: `hydrationOf` then answers `unknown`
+	* and the reader walks. A marker left behind would answer `hydrated` over an
+	* hour holding nothing, which is exactly the silent gap this class spent
+	* D295 learning not to report.
+	*
+	* ## What is never a candidate
+	*
+	* The live tail ({@link RecordingIndexBudget.pinnedTailHours}). Those hours
+	* are write-through from the writer (`addSegment`), not walked, and a
+	* `readdir` of an hour a writer is still filling cannot give back what it
+	* had — D445's lost tail, from the other direction.
+	*/
+	enforceResidency() {
+		const deps = this.residencyDeps;
+		if (deps === null) return;
+		const { budget } = deps;
+		let rows = this.residentRowCount();
+		let hours = this.residentHourCount();
+		if (rows <= budget.residentRowBudget && hours <= budget.residentHourBudget) return;
+		const rowTarget = Math.floor(budget.residentRowBudget * budget.evictToFraction);
+		const hourTarget = Math.floor(budget.residentHourBudget * budget.evictToFraction);
+		const pinnedFrom = hourOf$1(deps.now()) - Math.max(0, budget.pinnedTailHours - 1) * HOUR_MS$9;
+		const counts = this.hourHistogram();
+		const candidates = [];
+		for (const [deviceId, byHour] of counts) {
+			const walkedHours = this.walked.get(deviceId);
+			for (const [hourStartMs, count] of byHour) {
+				if (hourStartMs >= pinnedFrom) continue;
+				candidates.push({
+					deviceId,
+					hourStartMs,
+					rows: count,
+					lastUse: walkedHours?.get(hourStartMs) ?? 0
+				});
+			}
+		}
+		candidates.sort((a, b) => a.lastUse - b.lastUse || a.hourStartMs - b.hourStartMs);
+		const victims = /* @__PURE__ */ new Map();
+		let droppedRows = 0;
+		let droppedHours = 0;
+		for (const c of candidates) {
+			if (rows <= rowTarget && hours <= hourTarget) break;
+			let forDevice = victims.get(c.deviceId);
+			if (!forDevice) {
+				forDevice = /* @__PURE__ */ new Set();
+				victims.set(c.deviceId, forDevice);
+			}
+			forDevice.add(c.hourStartMs);
+			rows -= c.rows;
+			droppedRows += c.rows;
+			if (this.walked.get(c.deviceId)?.has(c.hourStartMs) === true) {
+				hours -= 1;
+				droppedHours += 1;
+			}
+		}
+		if (victims.size === 0) return;
+		this.evictionPasses += 1;
+		this.evictedRows += droppedRows;
+		this.evictedHours += droppedHours;
+		for (const [deviceId, hoursToDrop] of victims) this.dropHours(deviceId, hoursToDrop, rows, budget, deps.logger);
+	}
+	/** `deviceId → hourStartMs → resident rows`, including hours walked and found
+	*  empty (count 0) — those hold no rows and would otherwise never be dropped,
+	*  leaving the walked map to grow without bound on its own. */
+	hourHistogram() {
+		const out = /* @__PURE__ */ new Map();
+		for (const [deviceId, m] of this.byDevice) {
+			const byHour = /* @__PURE__ */ new Map();
+			for (const s of m.values()) {
+				const h = hourOf$1(s.startMs);
+				byHour.set(h, (byHour.get(h) ?? 0) + 1);
+			}
+			out.set(deviceId, byHour);
+		}
+		for (const [deviceId, w] of this.walked) {
+			let byHour = out.get(deviceId);
+			if (!byHour) {
+				byHour = /* @__PURE__ */ new Map();
+				out.set(deviceId, byHour);
+			}
+			for (const h of w.keys()) if (!byHour.has(h)) byHour.set(h, 0);
+		}
+		return out;
+	}
+	/** Delete one device's victim hours — rows and walked markers together — and
+	*  say so. A structure that silently forgets is how this class of bug hides. */
+	dropHours(deviceId, hoursToDrop, residentRowsAfter, budget, logger) {
+		const m = this.byDevice.get(deviceId);
+		let droppedRows = 0;
+		if (m) {
+			for (const [path, s] of m) {
+				if (!hoursToDrop.has(hourOf$1(s.startMs))) continue;
+				m.delete(path);
+				droppedRows += 1;
+			}
+			if (m.size === 0) this.byDevice.delete(deviceId);
+		}
+		const w = this.walked.get(deviceId);
+		if (w) {
+			for (const h of hoursToDrop) w.delete(h);
+			if (w.size === 0) this.walked.delete(deviceId);
+		}
+		this.invalidateSorted(deviceId);
+		this.evictedHoursByDevice.set(deviceId, (this.evictedHoursByDevice.get(deviceId) ?? 0) + hoursToDrop.size);
+		let oldestHourMs = Infinity;
+		let newestHourMs = -Infinity;
+		for (const h of hoursToDrop) {
+			if (h < oldestHourMs) oldestHourMs = h;
+			if (h > newestHourMs) newestHourMs = h;
+		}
+		logger.info("recorder: index dropped resident hours — over the residency budget", {
+			tags: { deviceId },
+			meta: {
+				hours: hoursToDrop.size,
+				rows: droppedRows,
+				oldestHourMs,
+				newestHourMs,
+				residentRowsAfter,
+				rowBudget: budget.residentRowBudget,
+				hourBudget: budget.residentHourBudget,
+				costOfRecovery: "readdir-per-hour"
+			}
+		});
 	}
 	/**
 	* Merge one hour's segments for a location, and mark that hour walked.
@@ -1121,6 +1366,7 @@ var RecordingIndex = class {
 		}
 		if (changed) this.invalidateSorted(deviceId);
 		this.markHydrated(deviceId, hourStartMs, hourStartMs + HOUR_MS$9);
+		this.enforceResidency();
 	}
 	/**
 	* Make one hour of ONE location exactly `relPaths` — merge what is there and
@@ -1151,6 +1397,7 @@ var RecordingIndex = class {
 		for (const path of dropped) m.delete(path);
 		if (dropped.length > 0) this.invalidateSorted(deviceId);
 		this.hydrateHour(deviceId, locationId, hourStartMs, relPaths);
+		this.enforceResidency();
 		return dropped;
 	}
 	/**
@@ -1175,6 +1422,7 @@ var RecordingIndex = class {
 			return;
 		}
 		this.insertIntoSortedViews(s);
+		this.enforceResidency();
 	}
 	/** Remove segments by relative path, routing each path to the correct device map via its encoded deviceId. @residency mutation */
 	removeSegments(paths) {
@@ -1202,6 +1450,7 @@ var RecordingIndex = class {
 	* @residency resident-scoped
 	*/
 	segmentsStartingIn(deviceId, profile, fromMs, toMs) {
+		this.touch(deviceId, fromMs, toMs);
 		const segs = this.sortedSegments(deviceId, profile);
 		let lo = 0;
 		let hi = segs.length;
@@ -1230,6 +1479,7 @@ var RecordingIndex = class {
 	* @residency resident-scoped
 	*/
 	segmentStartingAt(deviceId, profile, startMs) {
+		this.touch(deviceId, startMs, startMs + 1);
 		const segs = this.sortedSegments(deviceId, profile);
 		const at = segs[lowerBoundByStart(segs, startMs)];
 		return at !== void 0 && at.startMs === startMs ? at : null;
@@ -1253,6 +1503,7 @@ var RecordingIndex = class {
 	* @residency resident-scoped
 	*/
 	segmentsOverlapping(deviceId, profile, fromMs, toMs) {
+		this.touch(deviceId, fromMs - this.maxDurMs, toMs);
 		const segs = this.sortedSegments(deviceId, profile);
 		const end = lowerBoundByStart(segs, toMs);
 		let head = lowerBoundByStart(segs, fromMs);
@@ -1414,6 +1665,7 @@ var RecordingIndex = class {
 	}
 	/** The segment whose [startMs, startMs+durMs) window contains `epochMs`, or null if `epochMs` falls in a gap / there is no footage. @residency resident-scoped */
 	segmentAt(deviceId, profile, epochMs) {
+		this.touch(deviceId, epochMs - this.maxDurMs, epochMs + 1);
 		return this.segmentAtIn(this.sortedSegments(deviceId, profile), epochMs);
 	}
 	/**
@@ -1423,6 +1675,7 @@ var RecordingIndex = class {
 	* @residency resident-scoped
 	*/
 	nearestCoveredEdge(deviceId, profile, epochMs) {
+		this.touch(deviceId, epochMs - this.maxDurMs, epochMs + 1);
 		const segs = this.sortedSegments(deviceId, profile);
 		if (segs.length === 0) return null;
 		if (this.segmentAtIn(segs, epochMs) !== null) return epochMs;
@@ -1476,6 +1729,7 @@ var RecordingIndex = class {
 	* @residency resident-scoped
 	*/
 	coveredEdgeBefore(deviceId, profile, epochMs) {
+		this.touch(deviceId, epochMs - this.maxDurMs, epochMs + 1);
 		const segs = this.sortedSegments(deviceId, profile);
 		let best = null;
 		for (let i = upperBoundByStart(segs, epochMs) - 1; i >= 0; i--) {
@@ -1488,6 +1742,7 @@ var RecordingIndex = class {
 	}
 	/** @residency resident-scoped */
 	ranges(deviceId, profile, fromMs, toMs, gapToleranceMs) {
+		this.touch(deviceId, fromMs, toMs);
 		return mergeRanges(this.sortedSegments(deviceId, profile).filter((s) => s.startMs + s.durMs > fromMs && s.startMs < toMs), gapToleranceMs).map((r) => ({
 			startMs: Math.max(r.startMs, fromMs),
 			endMs: Math.min(r.endMs, toMs)
@@ -1722,6 +1977,7 @@ async function resolveRecordingsLocations(api, logger) {
 async function hydrateDeviceFromStorage(_api, index, deviceId, locations, logger, options = {}) {
 	const yieldBetween = options.yieldBetween ?? macrotask$3;
 	const chunkSize = options.chunkSize ?? HYDRATE_CHUNK;
+	index.beginWalk(deviceId);
 	for (const [root, aliases] of aliasesByRoot(locations)) {
 		const deviceDir = node_path.default.join(root, String(deviceId));
 		const startedMs = Date.now();
@@ -10056,10 +10312,16 @@ var SegmentHourLedger = class SegmentHourLedger {
 			else fromIndex.set(key, appendSegmentPath(existing, seg.path));
 		}
 		const refused = this.refusedPrunes(walked, fromIndex);
+		const trimmed = /* @__PURE__ */ new Set();
+		for (const deviceId of walked) {
+			if (!index.droppedDuringWalk(deviceId)) continue;
+			trimmed.add(deviceId);
+			this.logger.warn("recorder: ledger prune REFUSED — the RAM index dropped hours during this walk, so its silence is not evidence", { tags: { deviceId } });
+		}
 		for (const row of this.ledger.snapshot()) {
 			if (!walked.has(row.deviceId)) continue;
 			const disk = fromIndex.get(row.key);
-			const additiveOnly = row.hourStartMs === currentHour || refused.devices.has(row.deviceId) || refused.locations.has(locationKey(row.deviceId, row.locationId));
+			const additiveOnly = row.hourStartMs === currentHour || trimmed.has(row.deviceId) || refused.devices.has(row.deviceId) || refused.locations.has(locationKey(row.deviceId, row.locationId));
 			if (disk === void 0) {
 				if (additiveOnly) continue;
 				await this.ledger.forget(row.key);
@@ -17797,6 +18059,11 @@ var RecorderV2Addon = class extends require_dist.BaseAddon {
 	}
 	async onInitialize() {
 		this.stopStallMonitor = (0, _camstack_system_addon_utils.startEventLoopStallMonitor)(this.ctx.logger);
+		this.index.armResidency({
+			logger: this.ctx.logger,
+			now: () => Date.now(),
+			budget: DEFAULT_RECORDING_INDEX_BUDGET
+		});
 		const raw = this.ctx.kernel.localNodeId ?? this.ctx.id;
 		this.nodeId = raw.includes("/") ? raw.split("/")[0] : raw;
 		const configuredNode = this.config.recordingNodeId;
@@ -18792,9 +19059,16 @@ var RecorderV2Addon = class extends require_dist.BaseAddon {
 		const census = this.index.sortedViewCensus();
 		const views = this.index.sortedViewStats();
 		const reuse = this.index.hydrateReuseStats();
+		const residency = this.index.residency();
 		this.ctx.logger.info("recorder: index census", {
 			...census.largestDeviceId > 0 ? { tags: { deviceId: census.largestDeviceId } } : {},
 			meta: {
+				residentRows: residency.residentRows,
+				residentHours: residency.residentHours,
+				rowBudget: residency.budget?.residentRowBudget ?? null,
+				evictedRows: residency.evictedRows,
+				evictedHours: residency.evictedHours,
+				evictionPasses: residency.evictionPasses,
 				sortedViews: census.views,
 				rowSlots: census.rowSlots,
 				largestViewRows: census.largestRows,