@camstack/addon-pipeline 1.2.144 → 1.2.145

package/dist/recorder/index.js

@@ -1,5 +1,5 @@
-const require_dist = require("../dist-Dpy1KP1q.js");
-const require_node = require("../node-v9ZAGK2b.js");
+const require_dist = require("../dist-DML3mpn9.js");
+const require_node = require("../node-OvVqe9eh.js");
 const require_hub_hostname = require("../hub-hostname-DAJXlOgV.js");
 const require_restream_intent = require("../restream-intent-Cv9x3jmu.js");
 const require_retire_root_keys = require("../retire-root-keys-KE6D6Xh_.js");
@@ -1072,6 +1072,45 @@ var RecordingIndex = class {
 		};
 	}
 	/**
+	* How many materialised sorted views exist and how many row slots they hold.
+	*
+	* The question this answers: **what is in `large_object_space`?** Production
+	* on 2026-08-29 read ~490 MB there, stable across four samples five minutes
+	* apart — retained, not churn — against 110 MB on hub-main with a comparable
+	* total heap. V8 only puts an object there when it does not fit a normal
+	* page (~256 KB and up), and a sorted view is the recorder's obvious
+	* candidate: one `SegmentRow[]` per (device, profile-or-all), materialised
+	* on first read and then kept live. At ~296 k archive rows a single
+	* all-profiles view is a contiguous array of hundreds of thousands of
+	* pointers — megabytes, in one allocation, per device.
+	*
+	* Slots, not bytes: the array's own allocation is `rowSlots × 8 B` on a
+	* 64-bit heap, and the rows it points at are counted once in `byDevice`
+	* regardless. Reporting a byte estimate would be inventing precision this
+	* cannot have; the slot count is the thing that is actually known and it is
+	* what a reader needs to decide whether the views are the 490 MB.
+	*/
+	sortedViewCensus() {
+		let views = 0;
+		let rowSlots = 0;
+		let largestRows = 0;
+		let largestDeviceId = 0;
+		for (const [deviceId, byKey] of this.sortedByDevice) for (const rows of byKey.values()) {
+			views += 1;
+			rowSlots += rows.length;
+			if (rows.length > largestRows) {
+				largestRows = rows.length;
+				largestDeviceId = deviceId;
+			}
+		}
+		return {
+			views,
+			rowSlots,
+			largestRows,
+			largestDeviceId
+		};
+	}
+	/**
 	* Ordered insert of ONE NEW row into every live view it belongs to (the
 	* all-profiles view and its own profile's view). Views not yet materialised
 	* stay unmaterialised — their first read pays the one build. PRECONDITION:
@@ -2029,7 +2068,7 @@ var SegmentStore = class SegmentStore {
 			return counts;
 		};
 		const chunkSize = this.deps.evictChunkSize ?? SegmentStore.DEFAULT_EVICT_CHUNK;
-		const yieldBetween = this.deps.yieldBetween ?? macrotask$2;
+		const yieldBetween = this.deps.yieldBetween ?? macrotask$3;
 		let bucketsRemoved = 0;
 		let handled = 0;
 		for (const [bucketDir, bucketRows] of byBucket) {
@@ -2167,7 +2206,7 @@ var SegmentStore = class SegmentStore {
 		return indexedInBucket === indexedVictims.size;
 	}
 };
-var macrotask$2 = () => new Promise((resolve) => {
+var macrotask$3 = () => new Promise((resolve) => {
 	setImmediate(resolve);
 });
 //#endregion
@@ -7195,7 +7234,7 @@ async function resolveRecordingsLocations(api, logger) {
 * (best-effort), so one bad volume never blocks the rest of the hydrate.
 */
 async function hydrateDeviceFromStorage(_api, index, deviceId, locations, logger, options = {}) {
-	const yieldBetween = options.yieldBetween ?? macrotask$1;
+	const yieldBetween = options.yieldBetween ?? macrotask$2;
 	const chunkSize = options.chunkSize ?? HYDRATE_CHUNK;
 	for (const [root, aliases] of aliasesByRoot(locations)) {
 		const deviceDir = node_path.default.join(root, String(deviceId));
@@ -7263,7 +7302,7 @@ async function hydrateDeviceFromStorage(_api, index, deviceId, locations, logger
 }
 /** Entries classified between yields in {@link hydrateDeviceFromStorage}. */
 var HYDRATE_CHUNK = 2e4;
-var macrotask$1 = () => new Promise((resolve) => {
+var macrotask$2 = () => new Promise((resolve) => {
 	setImmediate(resolve);
 });
 /** `<deviceId>/<profile>/YYYY/MM/DD/HH` for an hour bucket (paths are UTC). */
@@ -7289,9 +7328,56 @@ var HOUR_MS$2 = 36e5;
 *
 * Hours already walked are skipped, so a drag across an hour costs nothing the
 * second time.
-*/
-async function hydrateWindowFromStorage(index, deviceId, fromMs, toMs, locations, logger) {
+*
+* ## The ledger is the first stop for a CLOSED hour (D287)
+*
+* Boot no longer replays the archive into the index, so a ledger-known hour
+* arrives here `unknown` and pays ONE point read of its hour row instead of a
+* `readdir` — measured at ~650 ms per hour directory on the live share under
+* load, against the array the scrub feeder is competing for. Hours the ledger
+* does not know, and every hour if the read fails, fall through to the walk
+* exactly as before: the failure direction is toward the disk, never toward an
+* hour that renders empty because nobody read it.
+*
+* **The live hour is never served from the ledger.** It is the one hour whose
+* durable row is knowably behind the disk: a segment finalized after the last
+* persist and before a crash is on the array and not in the row. Boot used to
+* mark every ledger hour `hydrated`, which made that tail invisible to
+* playback and the timeline FOREVER, not merely under-reported. Excluding the
+* live hour costs exactly one hour-directory read per process — the walk marks
+* it, so the second reader pays nothing — and it is what turns a lost tail
+* back into a recoverable one.
+*
+* A CLOSED hour already walked is skipped, which is what makes that exclusion
+* affordable: without it, every window touching the live hour would re-walk
+* all of its hours. The past is immutable, so re-reading a closed hour
+* directory can only ever return what the index already holds; eviction
+* removes rows through the index directly.
+*/
+async function hydrateWindowFromStorage(index, deviceId, fromMs, toMs, locations, logger, ledger) {
 	if (index.hydrationOf(deviceId, fromMs, toMs) === "hydrated") return;
+	const liveHour = Math.floor(Date.now() / HOUR_MS$2) * HOUR_MS$2;
+	if (ledger !== void 0) {
+		const startedMs = Date.now();
+		const hours = await ledger.detailForWindow(deviceId, fromMs, toMs);
+		let segments = 0;
+		let served = 0;
+		for (const hour of hours) {
+			if (hour.hourStartMs >= liveHour) continue;
+			index.hydrateHour(deviceId, hour.locationId, hour.hourStartMs, hour.paths);
+			segments += hour.paths.length;
+			served += 1;
+		}
+		if (served > 0) logger.info("recorder: hydrated a window from the hour ledger", {
+			tags: { deviceId },
+			meta: {
+				hours: served,
+				segments,
+				ms: Date.now() - startedMs
+			}
+		});
+		if (index.hydrationOf(deviceId, fromMs, toMs) === "hydrated") return;
+	}
 	for (const [root, aliases] of aliasesByRoot(locations)) {
 		const deviceDir = node_path.default.join(root, String(deviceId));
 		let profiles;
@@ -7310,16 +7396,26 @@ async function hydrateWindowFromStorage(index, deviceId, fromMs, toMs, locations
 		const first = Math.floor(fromMs / HOUR_MS$2) * HOUR_MS$2;
 		const reuseBefore = index.hydrateReuseStats();
 		let hoursRead = 0;
-		for (let hour = first; hour < toMs; hour += HOUR_MS$2) for (const profile of profiles) {
-			const rel = hourDirRelPath(deviceId, profile, hour);
-			let files;
-			try {
-				files = await node_fs.promises.readdir(node_path.default.join(root, rel));
-			} catch {
-				continue;
+		let repaired = 0;
+		for (let hour = first; hour < toMs; hour += HOUR_MS$2) {
+			if (hour < liveHour && index.hydrationOf(deviceId, hour, hour + HOUR_MS$2) === "hydrated") continue;
+			for (const profile of profiles) {
+				const rel = hourDirRelPath(deviceId, profile, hour);
+				let files;
+				try {
+					files = await node_fs.promises.readdir(node_path.default.join(root, rel));
+				} catch {
+					continue;
+				}
+				hoursRead += 1;
+				const locationId = locationForHydratedProfile(aliases, profile).id;
+				const relPaths = files.filter((f) => f.endsWith(".m4s")).map((f) => `${rel}/${f}`);
+				index.hydrateHour(deviceId, locationId, hour, relPaths);
+				if (ledger !== void 0 && relPaths.length > 0 && hour + HOUR_MS$2 <= Date.now() && !ledger.knowsHour(deviceId, profile, locationId, hour)) {
+					repaired += 1;
+					await ledger.adoptRebuiltHour(deviceId, profile, locationId, hour, relPaths);
+				}
 			}
-			hoursRead += 1;
-			index.hydrateHour(deviceId, locationForHydratedProfile(aliases, profile).id, hour, files.filter((f) => f.endsWith(".m4s")).map((f) => `${rel}/${f}`));
 		}
 		index.markHydrated(deviceId, fromMs, toMs);
 		if (hoursRead === 0) continue;
@@ -7331,6 +7427,7 @@ async function hydrateWindowFromStorage(index, deviceId, fromMs, toMs, locations
 			meta: {
 				root,
 				hoursRead,
+				repaired,
 				reused,
 				allocated
 			}
@@ -11612,6 +11709,9 @@ var DurableLedger = class DurableLedger {
 //#endregion
 //#region src/recorder/addon/segment-hour-ledger.ts
 var HOUR_MS$1 = 36e5;
+var macrotask$1 = () => new Promise((resolve) => {
+	setImmediate(resolve);
+});
 /**
 * @durable class=mirror owner=recorder
 *   write="write-behind on every finalized segment (hour-row upsert); eviction drops paths; the archive walk reconciles disk into the row set"
@@ -11759,6 +11859,7 @@ function hourAggregate(paths) {
 function segmentHourRow(base) {
 	return {
 		...base,
+		pathsResident: true,
 		...hourAggregate(base.paths)
 	};
 }
@@ -11814,6 +11915,44 @@ var OLDEST_PROBE_COLUMNS = [
 var REPAIR_PROBE_COLUMNS = ["segments"];
 /** Rows repaired per boot. The live archive is ~19 k hour rows. */
 var REPAIR_MAX_ROWS = 5e4;
+/**
+* The boot projection (D287): everything the recorder's always-resident tier
+* needs, and deliberately NOT `paths`.
+*
+* `paths` is ~55 B per segment and the archive is the only thing that grows:
+* ~16 MB of JSON today, a projected ~460 MB at 28 TB of today's bitrate mix
+* and ~5.9 GB at a low-bitrate mix — one tRPC response, parsed on the main
+* thread, before the index exists. The summary half is O(writers × days) and
+* stays ~10–15 MB at any archive size.
+*/
+var SEGMENT_HOUR_SUMMARY_COLUMNS = [
+	"deviceId",
+	"profile",
+	"locationId",
+	"hourStartMs",
+	"bytes",
+	"segments",
+	"minStartMs",
+	"maxStartMs"
+];
+/** Summary rows folded into the mirror between yields. */
+var LOAD_CHUNK = 5e3;
+/** Hour rows materialised per point-read page. One page covers a day of one
+*  camera's three profiles with room to spare. */
+var HOUR_DETAIL_PAGE = 64;
+/**
+* The live tail materialised at boot: the current hour and the one before it.
+*
+* `recordSegment` must gate from RAM (D49), and the hour it appends to at boot
+* is exactly the hour the previous process was writing. Two hours × the active
+* writers is ~60 rows — one point-read page — and it is what makes the write
+* path's materialise a case that essentially never happens.
+*/
+var LIVE_TAIL_HOURS = 2;
+/** Rows the one-shot aggregate repair may materialise in a single boot. The
+*  backfill is bounded so it cannot re-become the whole-archive read D287
+*  removed; a partial pass finishes on the next boot. */
+var REPAIR_MAX_MATERIALIZE = 2e3;
 /** The four scalars an accounting answer is made of, asked in one statement. */
 var ACCOUNTING_FIELDS = [
 	{
@@ -11906,6 +12045,44 @@ function recordToRow(key, data) {
 		paths: raw
 	});
 }
+/** The paths of a summary row: one shared empty array, never a per-row
+*  allocation, and never mistakable for "this hour holds nothing". */
+var NO_PATHS = Object.freeze([]);
+function finiteOr0(raw) {
+	const n = Number(raw);
+	return Number.isFinite(n) ? n : 0;
+}
+/**
+* One row of the boot projection ({@link SEGMENT_HOUR_SUMMARY_COLUMNS}).
+*
+* The identity half is validated exactly as {@link recordToRow} validates it —
+* a row that cannot say which camera, profile, location and hour it is about
+* is skipped, because a summary keyed on garbage would refuse the write path
+* for an hour that is perfectly fine. The aggregate half is taken as the
+* database wrote it: a row that predates the aggregate columns reports zeros,
+* which UNDER-reports its disk (prunes less, never more) until
+* {@link SegmentHourLedger.repairAggregates} rewrites it.
+*/
+function summaryToRow(key, data) {
+	const deviceId = Number(data["deviceId"]);
+	const profile = data["profile"];
+	const locationId = data["locationId"];
+	const hour = Number(data["hourStartMs"]);
+	if (!Number.isFinite(deviceId) || deviceId <= 0 || typeof profile !== "string" || profile.length === 0 || typeof locationId !== "string" || locationId.length === 0 || !Number.isFinite(hour)) return null;
+	return {
+		key,
+		deviceId,
+		profile,
+		locationId,
+		hourStartMs: hour,
+		paths: NO_PATHS,
+		pathsResident: false,
+		bytes: finiteOr0(data["bytes"]),
+		segments: finiteOr0(data["segments"]),
+		minStartMs: finiteOr0(data["minStartMs"]),
+		maxStartMs: finiteOr0(data["maxStartMs"])
+	};
+}
 var SPEC = {
 	collection: RECORDING_SEGMENT_HOURS_COLLECTION,
 	columns: RECORDING_SEGMENT_HOURS_COLUMNS,
@@ -11926,10 +12103,18 @@ var SegmentHourLedger = class {
 	*  accounting number is not a gate. */
 	store;
 	isLocationUsable;
+	now;
+	loadChunk;
+	yieldBetween;
+	rowCap;
 	constructor(deps) {
 		this.logger = deps.logger;
 		this.store = deps.store;
 		this.isLocationUsable = deps.isLocationUsable ?? (() => true);
+		this.now = deps.now ?? (() => Date.now());
+		this.loadChunk = deps.loadPacing?.chunkSize ?? LOAD_CHUNK;
+		this.yieldBetween = deps.loadPacing?.yieldBetween ?? macrotask$1;
+		this.rowCap = deps.loadPacing?.rowCap ?? 25e4;
 		this.ledger = new DurableLedger({
 			spec: SPEC,
 			store: deps.store,
@@ -11942,26 +12127,270 @@ var SegmentHourLedger = class {
 	declare() {
 		return this.ledger.declare();
 	}
+	/**
+	* Boot load — **T1 only** (D287).
+	*
+	* One projected query over {@link SEGMENT_HOUR_SUMMARY_COLUMNS}, folded into
+	* the mirror in chunks with a yield between them, then one point-read page
+	* that materialises the live tail so the write path can gate from RAM.
+	*
+	* It replaces `DurableLedger.load`, which fetches whole rows and therefore
+	* the whole archive's path strings, and it keeps that primitive's two rules:
+	* a failed read RETURNS WHAT IS ALREADY MIRRORED rather than clearing it,
+	* and a malformed row is skipped rather than repaired.
+	*
+	* It deliberately does NOT replay the archive into {@link RecordingIndex}.
+	* `hydrated` now means "the rows are resident", so a ledger-known hour is
+	* merely *hydratable from T3*: the first read of it pays one point read
+	* ({@link detailForWindow}), and an hour whose tail the ledger is missing is
+	* no longer permanently invisible to playback.
+	*/
 	async load() {
-		const rows = await this.ledger.load();
+		const startedMs = this.now();
+		let records;
+		try {
+			records = await this.store.query.query({
+				collection: RECORDING_SEGMENT_HOURS_COLLECTION,
+				columns: SEGMENT_HOUR_SUMMARY_COLUMNS,
+				filter: { limit: this.rowCap }
+			});
+		} catch (err) {
+			this.logger.warn("recorder: segment-hour ledger load failed — keeping the hours already held", { meta: {
+				collection: RECORDING_SEGMENT_HOURS_COLLECTION,
+				held: this.ledger.size,
+				error: String(err)
+			} });
+			return this.ledger.snapshot();
+		}
+		const queriedMs = this.now();
+		let skipped = 0;
+		for (let i = 0; i < records.length; i += this.loadChunk) {
+			const end = Math.min(i + this.loadChunk, records.length);
+			for (let j = i; j < end; j += 1) {
+				const record = records[j];
+				const row = summaryToRow(record.id, record.data);
+				if (row === null) {
+					skipped += 1;
+					continue;
+				}
+				this.ledger.stage(row);
+			}
+			if (end < records.length) await this.yieldBetween();
+		}
+		if (skipped > 0) this.logger.warn("recorder: segment-hour summaries skipped as malformed — they gate NOTHING", { meta: {
+			collection: RECORDING_SEGMENT_HOURS_COLLECTION,
+			skipped
+		} });
+		if (records.length >= this.rowCap) this.logger.warn("recorder: segment-hour ledger load hit its row cap — hours past the cap are UNKNOWN to this process and will be walked from disk", { meta: {
+			limit: this.rowCap,
+			loaded: records.length
+		} });
+		const tail = await this.materializeLiveTail();
 		this.logger.info("recorder: segment-hour ledger loaded", { meta: {
-			hours: rows.length,
+			hours: this.ledger.size,
+			pathsLoaded: false,
+			liveTailHours: tail,
+			skipped,
+			queryMs: queriedMs - startedMs,
+			ms: this.now() - startedMs,
 			collection: RECORDING_SEGMENT_HOURS_COLLECTION
 		} });
-		return rows;
+		return this.ledger.snapshot();
 	}
+	/** Every hour the ledger knows — summaries included. A row whose
+	*  `pathsResident` is false carries real aggregates and empty `paths`. */
 	snapshot() {
 		return this.ledger.snapshot();
 	}
+	/** Does the ledger hold a row for this hour at all? Pure RAM — the gate the
+	*  storage-walk repair consults before it upserts a rebuilt hour. */
+	knowsHour(deviceId, profile, locationId, hour) {
+		return this.ledger.has(segmentHourKey(deviceId, profile, locationId, hour));
+	}
 	/**
-	* Seed {@link RecordingIndex} from the mirrored hour rows.
+	* The hours of `[fromMs, toMs)` the ledger knows, with their paths — the
+	* cold-hour detail read that replaces the boot replay (D287).
+	*
+	* One bounded point read against the settings store, never the media array:
+	* a `readdir` of one hour directory was measured at ~650 ms under load on
+	* the live share, and the array is the resource the scrub feeder is
+	* competing for. Hours the ledger does NOT know are absent from the result,
+	* and the caller walks those from disk exactly as it always did.
 	*
-	* Hours present in the ledger become `hydrated` so a seek in those windows
-	* does not pay for a disk walk. Hours the ledger never held stay `unknown`
-	* — that is the fail-toward-walk direction.
+	* **A read that fails returns what it already had** (D49). The caller sees
+	* fewer hours, the index stays `unknown` for the rest, and the window falls
+	* through to the walk — nothing is destroyed and nothing renders as an
+	* empty hour that was merely unread.
 	*/
-	hydrateIndex(index) {
-		for (const hour of this.ledger.snapshot()) index.hydrateHour(hour.deviceId, hour.locationId, hour.hourStartMs, hour.paths);
+	async detailForWindow(deviceId, fromMs, toMs) {
+		const first = hourStartMs(fromMs);
+		const out = [];
+		const wanted = [];
+		for (const row of this.ledger.snapshot()) {
+			if (row.deviceId !== deviceId) continue;
+			if (row.hourStartMs < first || row.hourStartMs >= toMs) continue;
+			if (row.pathsResident) {
+				out.push({
+					locationId: row.locationId,
+					hourStartMs: row.hourStartMs,
+					paths: row.paths
+				});
+				continue;
+			}
+			wanted.push(row.key);
+		}
+		for (const row of await this.materialize(wanted, deviceId)) out.push({
+			locationId: row.locationId,
+			hourStartMs: row.hourStartMs,
+			paths: row.paths
+		});
+		return out;
+	}
+	/**
+	* Adopt an hour the storage walk rebuilt and the ledger never held.
+	*
+	* The reader repairs the durable index it just reconstructed, so the next
+	* cold read of this hour is a point read instead of another `readdir`
+	* (`docs/design/2026-08-29-scrypted-nvr-recording-model.md` §4.2). Two
+	* constraints, both enforced by the caller and re-stated here because
+	* getting either wrong turns a READ into durable damage: the hour must be
+	* CLOSED (a live hour's directory races the writer, so a walk of it is a
+	* lower bound, not the truth), and the ledger must hold no row for it (an
+	* existing row is the authority; replacing it with a walk's view is the
+	* D148 prune this ledger refuses to do on its own evidence).
+	*/
+	async adoptRebuiltHour(deviceId, profile, locationId, hour, paths) {
+		const key = segmentHourKey(deviceId, profile, locationId, hour);
+		if (paths.length === 0 || this.ledger.has(key)) return;
+		const row = segmentHourRow({
+			key,
+			deviceId,
+			profile,
+			locationId,
+			hourStartMs: hour,
+			paths: uniquePaths(paths)
+		});
+		await this.ledger.put(row);
+		this.logger.info("recorder: adopted a closed hour the disk walk rebuilt and the ledger never held", {
+			tags: { deviceId },
+			meta: {
+				profile,
+				locationId,
+				hourStartMs: hour,
+				segments: row.segments,
+				bytes: row.bytes
+			}
+		});
+	}
+	/**
+	* Fetch whole rows for `keys` and promote them in the mirror.
+	*
+	* Paged and yielding: an export window can name thousands of hours, and one
+	* `whereIn` over all of them would rebuild the very whole-archive response
+	* D287 removed. A page that FAILS ends the materialise and returns what
+	* landed — partial detail is real detail, and the caller's fallback (a disk
+	* walk, or refusing a write) is strictly safer than a guess.
+	*
+	* A row the store returns but this cannot parse is EVICTED from the mirror
+	* rather than left as a summary that can never become resident: it re-seeds
+	* cold on the next write, which is `DurableLedger`'s rule 4 and the only
+	* escape from an hour permanently frozen against its own writer.
+	*/
+	async materialize(keys, deviceId) {
+		const out = [];
+		if (keys.length === 0) return out;
+		const tags = deviceId === void 0 ? {} : { tags: { deviceId } };
+		for (let i = 0; i < keys.length; i += HOUR_DETAIL_PAGE) {
+			const page = keys.slice(i, i + HOUR_DETAIL_PAGE);
+			let records;
+			try {
+				records = await this.store.query.query({
+					collection: RECORDING_SEGMENT_HOURS_COLLECTION,
+					filter: {
+						whereIn: { key: page },
+						limit: page.length
+					}
+				});
+			} catch (err) {
+				this.logger.warn("recorder: hour-detail point read failed — these hours stay summaries, and the caller walks the disk or declines the write", {
+					...tags,
+					meta: {
+						collection: RECORDING_SEGMENT_HOURS_COLLECTION,
+						asked: page.length,
+						materialized: out.length,
+						error: String(err)
+					}
+				});
+				return out;
+			}
+			for (const record of records) {
+				const row = recordToRow(record.id, record.data);
+				if (row === null) {
+					this.ledger.evict(record.id);
+					this.logger.warn("recorder: hour row is unparseable — dropping the summary so the hour re-seeds cold instead of freezing its writer", {
+						...tags,
+						meta: { key: record.id }
+					});
+					continue;
+				}
+				this.ledger.stage(row);
+				out.push(row);
+			}
+			if (i + HOUR_DETAIL_PAGE < keys.length) await this.yieldBetween();
+		}
+		return out;
+	}
+	/**
+	* Materialise every hour these devices hold, and report how many stayed
+	* summaries.
+	*
+	* The reconcile is the one path that DELETES durable rows, so it may not run
+	* against a mirror that only half knows what it holds. This is a whole-device
+	* read and it is deliberately confined here: `reconcileFromIndex` follows an
+	* operator-armed rescan of that same device — a recursive `readdir` over
+	* >1M files — so a paged point read alongside it is noise, and it is the one
+	* caller whose correctness depends on completeness.
+	*/
+	async materializeDevices(deviceIds) {
+		const keys = [];
+		for (const row of this.ledger.snapshot()) if (!row.pathsResident && deviceIds.has(row.deviceId)) keys.push(row.key);
+		if (keys.length === 0) return;
+		await this.materialize(keys);
+		const stillSummary = /* @__PURE__ */ new Map();
+		for (const row of this.ledger.snapshot()) {
+			if (row.pathsResident || !deviceIds.has(row.deviceId)) continue;
+			stillSummary.set(row.deviceId, (stillSummary.get(row.deviceId) ?? 0) + 1);
+		}
+		for (const [deviceId, unreadable] of stillSummary) this.logger.warn("recorder: hours without readable detail take NO part in this reconcile — they are neither pruned nor unioned", {
+			tags: { deviceId },
+			meta: {
+				asked: keys.length,
+				unreadable
+			}
+		});
+	}
+	/** The hour a write path may touch: current + previous. Materialised at boot
+	*  so {@link recordSegment}'s dedup gate answers from RAM (D49). */
+	async materializeLiveTail() {
+		const oldest = hourStartMs(this.now()) - (LIVE_TAIL_HOURS - 1) * HOUR_MS$1;
+		const keys = [];
+		for (const row of this.ledger.snapshot()) if (row.hourStartMs >= oldest && !row.pathsResident) keys.push(row.key);
+		return (await this.materialize(keys)).length;
+	}
+	/**
+	* Promote one HELD row to paths-resident, or answer `null`.
+	*
+	* `null` means "this hour is known and its detail could not be had" — the
+	* only honest answer to a failed point read, and every caller turns it into
+	* "do nothing". It is deliberately distinct from `this.ledger.get(key) ===
+	* undefined`, which means "no such hour" and is what licenses a fresh row.
+	*/
+	async resident(key, deviceId) {
+		const held = this.ledger.get(key);
+		if (held !== void 0 && held.pathsResident) return held;
+		await this.materialize([key], deviceId);
+		const after = this.ledger.get(key);
+		return after !== void 0 && after.pathsResident ? after : null;
 	}
 	/**
 	* Bytes / count / oldest / newest across a SET of storage locations, as ONE
@@ -12062,6 +12491,7 @@ var SegmentHourLedger = class {
 		for (const record of full) {
 			const hour = recordToRow(record.id, record.data);
 			if (hour === null) continue;
+			this.ledger.stage(hour);
 			for (const path of hour.paths) {
 				const parsed = parseSegmentPath(path);
 				if (parsed === null) continue;
@@ -12091,6 +12521,12 @@ var SegmentHourLedger = class {
 	* empties). So `segments = 0` IS the backfill predicate, and after one pass
 	* it selects nothing. A partial repair finishes on the next boot; until then
 	* the affected disks UNDER-report, which prunes less and never more.
+	*
+	* Since D287 the boot load carries no `paths`, and `paths` is the authority
+	* this repair derives from — so the stale rows are MATERIALISED first, at
+	* most {@link REPAIR_MAX_MATERIALIZE} per boot. That bound is the point: an
+	* unbounded materialise here would be the whole-archive read this stage
+	* removed, wearing a different name.
 	*/
 	async repairAggregates() {
 		let repaired = 0;
@@ -12103,9 +12539,15 @@ var SegmentHourLedger = class {
 					limit: REPAIR_MAX_ROWS
 				}
 			});
+			const pending = stale.map((record) => record.id).filter((key) => this.ledger.get(key)?.pathsResident === false);
+			if (pending.length > REPAIR_MAX_MATERIALIZE) this.logger.info("recorder: segment-hour aggregate backfill is bounded this boot — the rest is repaired on the next one", { meta: {
+				pending: pending.length,
+				perBoot: REPAIR_MAX_MATERIALIZE
+			} });
+			await this.materialize(pending.slice(0, REPAIR_MAX_MATERIALIZE));
 			for (const record of stale) {
 				const held = this.ledger.get(record.id);
-				if (held === void 0 || held.segments === 0) continue;
+				if (held === void 0 || !held.pathsResident || held.segments === 0) continue;
 				await this.ledger.put(held);
 				repaired += 1;
 			}
@@ -12133,8 +12575,7 @@ var SegmentHourLedger = class {
 	*/
 	async recordSegment(row) {
 		const { key, hourStartMs: hour } = hourOf(row);
-		const held = this.ledger.get(key);
-		if (held === void 0) {
+		if (!this.ledger.has(key)) {
 			await this.ledger.put(segmentHourRow({
 				key,
 				deviceId: row.deviceId,
@@ -12145,6 +12586,17 @@ var SegmentHourLedger = class {
 			}));
 			return;
 		}
+		const held = await this.resident(key, row.deviceId);
+		if (held === null) {
+			this.logger.warn("recorder: hour detail unavailable — this finalized segment is NOT in the durable hour row yet", {
+				tags: { deviceId: row.deviceId },
+				meta: {
+					key,
+					path: row.path
+				}
+			});
+			return;
+		}
 		if (held.paths.includes(row.path)) return;
 		await this.ledger.put(appendSegmentPath(held, row.path));
 	}
@@ -12156,16 +12608,29 @@ var SegmentHourLedger = class {
 		const doomed = /* @__PURE__ */ new Map();
 		for (const row of rows) {
 			const { key } = hourOf(row);
-			let set = doomed.get(key);
-			if (!set) {
-				set = /* @__PURE__ */ new Set();
-				doomed.set(key, set);
+			const entry = doomed.get(key);
+			if (entry === void 0) {
+				doomed.set(key, {
+					deviceId: row.deviceId,
+					paths: new Set([row.path])
+				});
+				continue;
 			}
-			set.add(row.path);
+			entry.paths.add(row.path);
 		}
-		for (const [key, paths] of doomed) {
-			const held = this.ledger.get(key);
-			if (held === void 0) continue;
+		for (const [key, { deviceId, paths }] of doomed) {
+			if (!this.ledger.has(key)) continue;
+			const held = await this.resident(key, deviceId);
+			if (held === null) {
+				this.logger.warn("recorder: hour detail unavailable — these evicted paths stay in the durable hour row until a walk or the next eviction confirms them", {
+					tags: { deviceId },
+					meta: {
+						key,
+						paths: paths.size
+					}
+				});
+				continue;
+			}
 			const next = held.paths.filter((p) => !paths.has(p));
 			if (next.length === 0) {
 				await this.ledger.forget(key);
@@ -12194,10 +12659,17 @@ var SegmentHourLedger = class {
 	* And a walk this ledger does not TRUST prunes nothing at all — see
 	* {@link refusedPrunes}. What such a walk FOUND is still real, so its paths
 	* are unioned in; what it did not find decides nothing (D49).
+	*
+	* Since D287 the walked devices' hours are MATERIALISED first: every
+	* comparison below reads `row.paths`, and a summary's empty `paths` would
+	* read as "the ledger holds nothing here" — which is the union collapsing to
+	* the walk's own view, i.e. the prune the refusal machinery exists to
+	* prevent. An hour whose detail could not be read is left additive-only.
 	*/
 	async reconcileFromIndex(index, deviceIds, nowMs) {
 		const walked = new Set(deviceIds);
 		const currentHour = hourStartMs(nowMs);
+		await this.materializeDevices(walked);
 		const fromIndex = /* @__PURE__ */ new Map();
 		for (const deviceId of deviceIds) for (const seg of index.segments(deviceId)) {
 			const { key, hourStartMs: hour } = hourOf(seg);
@@ -12215,6 +12687,7 @@ var SegmentHourLedger = class {
 		const refused = this.refusedPrunes(walked, fromIndex);
 		for (const row of this.ledger.snapshot()) {
 			if (!walked.has(row.deviceId)) continue;
+			if (!row.pathsResident) 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));
 			if (disk === void 0) {
@@ -13302,7 +13775,7 @@ var RecorderV2Addon = class extends require_dist.BaseAddon {
 			},
 			calendar: this.calendar,
 			mfraFor: (deviceId, profile, startMs) => this.mfraTables.get(deviceId, profile, startMs),
-			hydrateWindow: (deviceId, fromMs, toMs) => hydrateWindowFromStorage(this.index, deviceId, fromMs, toMs, this.resolvedLocations, this.ctx.logger),
+			hydrateWindow: (deviceId, fromMs, toMs) => hydrateWindowFromStorage(this.index, deviceId, fromMs, toMs, this.resolvedLocations, this.ctx.logger, this.segmentHours ?? void 0),
 			onConfigChanged: async (deviceId) => {
 				await this.refreshSensorTriggerBindings();
 				await (this.controller?.onConfigChanged(deviceId) ?? Promise.resolve());
@@ -13401,7 +13874,7 @@ var RecorderV2Addon = class extends require_dist.BaseAddon {
 			state: exportsState,
 			engine: this.exportEngine,
 			index: { segmentsInWindow: async (deviceId, profile, fromMs, toMs) => {
-				if (this.index.hydrationOf(deviceId, fromMs, toMs) !== "hydrated") await hydrateWindowFromStorage(this.index, deviceId, fromMs, toMs, this.resolvedLocations, this.ctx.logger);
+				if (this.index.hydrationOf(deviceId, fromMs, toMs) !== "hydrated") await hydrateWindowFromStorage(this.index, deviceId, fromMs, toMs, this.resolvedLocations, this.ctx.logger, this.segmentHours ?? void 0);
 				return this.index.segments(deviceId, profile);
 			} },
 			now: () => Date.now(),
@@ -13628,7 +14101,6 @@ var RecorderV2Addon = class extends require_dist.BaseAddon {
 		}
 		try {
 			await this.segmentHours?.load();
-			this.segmentHours?.hydrateIndex(this.index);
 			this.segmentHours?.repairAggregates();
 		} catch (err) {
 			this.ctx.logger.warn("recorder: segment-hour ledger load failed — hours stay unknown until a read walks them", { meta: { error: require_dist.errMsg(err) } });
@@ -13764,6 +14236,7 @@ var RecorderV2Addon = class extends require_dist.BaseAddon {
 		}
 		if (this.exportSweepTimer === null) {
 			const sweep = () => {
+				this.logIndexCensus();
 				sweepExpiredExports(Date.now(), this.exportJanitorDeps()).catch((err) => {
 					this.ctx.logger.warn("recorder: export expiry sweep failed", { meta: { error: require_dist.errMsg(err) } });
 				});
@@ -13774,6 +14247,41 @@ var RecorderV2Addon = class extends require_dist.BaseAddon {
 		}
 	}
 	/**
+	* What the RAM index is actually holding, on the 5-minute cadence the
+	* `[mem]` heartbeat already samples on.
+	*
+	* `RecordingIndex` has exposed `sortedViewStats` and `hydrateReuseStats`
+	* since the churn work and NOTHING has ever read them — so the two numbers
+	* that would have told us where the recorder's heap goes have never appeared
+	* in a log line. Production on 2026-08-29 reads ~490 MB in
+	* `large_object_space`, stable across four samples five minutes apart
+	* (retained, not churn) against 110 MB on hub-main; the sorted views are the
+	* shape that lands there, and `rowSlots × 8 B` is the arithmetic that either
+	* accounts for it or rules it out.
+	*
+	* `tags: { deviceId }` names the camera with the LARGEST view, because
+	* "which camera" is the only form the follow-up question ever takes. Absent
+	* when nothing is materialised — a device id of 0 is not a camera.
+	*/
+	logIndexCensus() {
+		const census = this.index.sortedViewCensus();
+		const views = this.index.sortedViewStats();
+		const reuse = this.index.hydrateReuseStats();
+		this.ctx.logger.info("recorder: index census", {
+			...census.largestDeviceId > 0 ? { tags: { deviceId: census.largestDeviceId } } : {},
+			meta: {
+				sortedViews: census.views,
+				rowSlots: census.rowSlots,
+				largestViewRows: census.largestRows,
+				fullRebuilds: views.fullRebuilds,
+				incrementalInserts: views.incrementalInserts,
+				rowsReused: reuse.rowsReused,
+				rowsAllocated: reuse.rowsAllocated,
+				ledgerHours: this.segmentHours?.snapshot().length ?? 0
+			}
+		});
+	}
+	/**
 	* One-time boot cleanup of the retired sprite-sheet scrub-thumbnail dirs
 	* (`<locationRoot>/.thumbs`). Scrub previews now use the WebCodecs keyframe
 	* packs + the on-demand still route, so the sheets are dead weight on the
@@ -14157,7 +14665,7 @@ var RecorderV2Addon = class extends require_dist.BaseAddon {
 		const started = now;
 		const liveHour = Math.floor(now / HOUR_MS) * HOUR_MS;
 		for (const deviceId of deviceIds) try {
-			await hydrateWindowFromStorage(this.index, deviceId, liveHour, liveHour + HOUR_MS, this.resolvedLocations, this.ctx.logger);
+			await hydrateWindowFromStorage(this.index, deviceId, liveHour, liveHour + HOUR_MS, this.resolvedLocations, this.ctx.logger, this.segmentHours ?? void 0);
 		} catch {}
 		this.ctx.logger.info("recorder: today warmed", { meta: {
 			devices: deviceIds.length,