@camstack/addon-post-analysis 1.2.231 → 1.2.232

package/dist/pipeline-analytics/index.js

@@ -2,7 +2,7 @@ Object.defineProperties(exports, {
 	__esModule: { value: true },
 	[Symbol.toStringTag]: { value: "Module" }
 });
-const require_dist = require("../dist-DAXBbWmc.js");
+const require_dist = require("../dist-Dbf6ceXh.js");
 let node_fs = require("node:fs");
 node_fs = require_dist.__toESM(node_fs, 1);
 let node_path = require("node:path");
@@ -1972,8 +1972,8 @@ var NC_ARTIFACTS_INDEXES = [
 	}
 ];
 /** Upper bound for a half-open `whereBetween` — the store has no `>=`. */
-var TIME_MAX = 864e13;
-var TIME_MIN = -864e13;
+var TIME_MAX$1 = 864e13;
+var TIME_MIN$1 = -864e13;
 /** Prune scan ceiling — the index is bounded by the shelf it mirrors (2000
 *  entries by default), so this only has to be comfortably above it. */
 var NC_ARTIFACT_PRUNE_SCAN_LIMIT = 2e4;
@@ -2213,7 +2213,7 @@ var NcArtifactIndex = class {
 		try {
 			const expired = await this.store.deleteWhere.mutate({
 				collection: NC_ARTIFACTS_COLLECTION,
-				filter: { whereBetween: { expiresAt: [TIME_MIN, this.now() - 1] } }
+				filter: { whereBetween: { expiresAt: [TIME_MIN$1, this.now() - 1] } }
 			});
 			removed += expired.deleted;
 			if (keptIds === null) {
@@ -2255,8 +2255,8 @@ var NcArtifactIndex = class {
 		whereIn["kind"] = query.kinds !== void 0 && query.kinds.length > 0 ? [...query.kinds] : [...NC_GALLERY_ARTIFACT_KINDS];
 		if (query.deviceIds !== void 0 && query.deviceIds.length > 0) whereIn["deviceId"] = [...query.deviceIds];
 		const whereBetween = {
-			capturedAt: [query.fromMs ?? TIME_MIN, query.toMs ?? TIME_MAX],
-			expiresAt: [this.now(), TIME_MAX]
+			capturedAt: [query.fromMs ?? TIME_MIN$1, query.toMs ?? TIME_MAX$1],
+			expiresAt: [this.now(), TIME_MAX$1]
 		};
 		return {
 			...query.ruleId !== void 0 ? { where: { ruleId: query.ruleId } } : {},
@@ -2281,6 +2281,23 @@ var NcArtifactIndex = class {
 		return out;
 	}
 };
+/**
+* A sentence explaining why this node must not keep the shelf, or `null` when
+* it may. The sentence is the log line: an operator reading it should learn
+* WHICH node owns the shelf without opening the storage page.
+*/
+function artifactShelfRefusal(locations, localNodeId) {
+	if (localNodeId === null || localNodeId.length === 0) return null;
+	const here = localNodeId.includes("/") ? localNodeId.split("/")[0] ?? "" : localNodeId;
+	if (here.length === 0) return null;
+	for (const location of locations) {
+		if (!location.id.startsWith("artifacts")) continue;
+		const owner = location.nodeId;
+		if (owner === void 0 || owner.length === 0 || owner === here) continue;
+		return `the artefact shelf lives on node "${owner}" (location "${location.id}"), not on "${here}" — the path it resolves to is that node's disk, and creating it here would make a directory of the same name that nothing reads. Artefacts are produced, stored and served by "${owner}".`;
+	}
+	return null;
+}
 //#endregion
 //#region ../types/dist/node.mjs
 var node_exports = /* @__PURE__ */ require_dist.__exportAll({
@@ -18693,6 +18710,52 @@ function buildSummaryOutboxInputs(input) {
 	});
 }
 //#endregion
+//#region src/notification-center/summary/summary-group-collapse.ts
+function collapseToGroups(candidates, groups) {
+	const claim = /* @__PURE__ */ new Map();
+	for (const group of groups) for (const trackId of group.memberTrackIds) if (!claim.has(trackId)) claim.set(trackId, group);
+	const survivorsByGroup = /* @__PURE__ */ new Map();
+	for (const candidate of candidates) {
+		const group = claim.get(candidate.trackId);
+		if (group === void 0) continue;
+		const bucket = survivorsByGroup.get(group.summaryId);
+		if (bucket === void 0) survivorsByGroup.set(group.summaryId, [candidate]);
+		else bucket.push(candidate);
+	}
+	const representative = /* @__PURE__ */ new Map();
+	for (const [summaryId, survivors] of survivorsByGroup) {
+		const group = groups.find((g) => g.summaryId === summaryId);
+		if (group === void 0) continue;
+		const chosen = survivors.find((c) => c.trackId === group.primaryTrackId) ?? survivors[0];
+		if (chosen === void 0) continue;
+		representative.set(summaryId, {
+			...chosen,
+			groupSize: survivors.length,
+			...group.groupShotMediaId !== null ? { groupShotMediaId: group.groupShotMediaId } : {}
+		});
+	}
+	const kept = [];
+	let collapsed = 0;
+	for (const candidate of candidates) {
+		const group = claim.get(candidate.trackId);
+		if (group === void 0) {
+			kept.push(candidate);
+			continue;
+		}
+		const chosen = representative.get(group.summaryId);
+		if (chosen === void 0) {
+			kept.push(candidate);
+			continue;
+		}
+		if (chosen.trackId === candidate.trackId) kept.push(chosen);
+		else collapsed += 1;
+	}
+	return {
+		kept,
+		collapsed
+	};
+}
+//#endregion
 //#region src/notification-center/summary/summary-selection.ts
 /**
 * Which tracks become tiles — filter, rank, and the per-camera quota.
@@ -19265,7 +19328,8 @@ var NcSummaryProducer = class {
 		try {
 			const candidates = await this.collectCandidates(rule, window);
 			const filtered = filterSummaryCandidates(candidates, rule.filters, this.deps.zoneOwner);
-			const selection = selectSummaryTiles(filtered.kept, {
+			const grouped = await this.collapseIfGrouping(rule, window, filtered.kept);
+			const selection = selectSummaryTiles(grouped.kept, {
 				maxTiles: rule.maxTiles,
 				rank: rule.rank
 			});
@@ -19294,7 +19358,7 @@ var NcSummaryProducer = class {
 			const tileLoad = await this.loadTiles({
 				rule,
 				preferred: selection.tiles,
-				refill: remainingSummaryCandidates(filtered.kept, selection.tiles, rule.rank),
+				refill: remainingSummaryCandidates(grouped.kept, selection.tiles, rule.rank),
 				maxTiles: rule.maxTiles
 			});
 			const loaded = tileLoad.tiles;
@@ -19335,7 +19399,7 @@ var NcSummaryProducer = class {
 				priority: rule.priority,
 				tileCount: loaded.length,
 				cameraCount: new Set(loaded.map((t) => t.candidate.deviceId)).size,
-				matchedCount: filtered.kept.length,
+				matchedCount: grouped.kept.length,
 				detections,
 				...mosaic.ref !== null ? { mosaic: mosaic.ref } : {},
 				generatedAt: this.deps.now(),
@@ -19347,7 +19411,7 @@ var NcSummaryProducer = class {
 			this.deps.logger.info("summary produced", { meta: {
 				...meta,
 				scanned: candidates.length,
-				matched: filtered.kept.length,
+				matched: grouped.kept.length,
 				droppedStationary: filtered.droppedStationary,
 				droppedUnconfirmed: filtered.droppedUnconfirmed,
 				unknownConfirmation: filtered.unknownConfirmation,
@@ -19370,7 +19434,7 @@ var NcSummaryProducer = class {
 				window,
 				tiles: loaded.length,
 				cameras: new Set(loaded.map((t) => t.candidate.deviceId)).size,
-				matched: filtered.kept.length,
+				matched: grouped.kept.length,
 				droppedStationary: filtered.droppedStationary,
 				enqueued,
 				...mosaic.bytes > 0 ? { mosaicBytes: mosaic.bytes } : {},
@@ -19391,6 +19455,54 @@ var NcSummaryProducer = class {
 			};
 		}
 	}
+	/**
+	* Fold each session summary's surviving members into one entry — or do
+	* nothing at all, which is what `tracks` (the default) means.
+	*
+	* A failure to read the groups does NOT fail the digest: it falls back to
+	* subjects and says so. A digest of four lines instead of one is a worse
+	* reading, not a lost one, and losing the night's record over a store read
+	* is the wrong trade.
+	*/
+	async collapseIfGrouping(rule, window, kept) {
+		if (rule.subject !== "groups") return {
+			kept,
+			collapsed: 0
+		};
+		const listGroups = this.deps.listSummaryGroups;
+		if (listGroups === void 0) {
+			this.deps.logger.warn("summary rule asks for groups but this node cannot read them", { meta: { ruleId: rule.id } });
+			return {
+				kept,
+				collapsed: 0
+			};
+		}
+		const groups = [];
+		for (const deviceId of rule.deviceIds) try {
+			groups.push(...await listGroups({
+				deviceId,
+				sinceMs: window.startMs,
+				untilMs: window.endMs
+			}));
+		} catch (err) {
+			this.deps.logger.warn("summary could not read a camera’s groups — read as subjects", {
+				tags: { deviceId },
+				meta: {
+					ruleId: rule.id,
+					error: String(err)
+				}
+			});
+		}
+		const outcome = collapseToGroups(kept, groups);
+		this.deps.logger.info("summary read as groups", { meta: {
+			ruleId: rule.id,
+			groups: groups.length,
+			subjects: kept.length,
+			lines: outcome.kept.length,
+			collapsed: outcome.collapsed
+		} });
+		return outcome;
+	}
 	/** Every camera's tracks in the window, capped per camera and counted. */
 	async collectCandidates(rule, window) {
 		const all = [];
@@ -19440,6 +19552,25 @@ var NcSummaryProducer = class {
 			seenIds.add(candidate.trackId);
 			const tags = { deviceId: candidate.deviceId };
 			try {
+				const groupShot = candidate.groupShotMediaId;
+				if (groupShot !== void 0) {
+					const jpeg = await this.deps.readMedia(groupShot);
+					if (jpeg !== null && jpeg.byteLength > 0) {
+						tiles.push({
+							candidate,
+							jpeg
+						});
+						continue;
+					}
+					this.deps.logger.info("summary tile: group shot unreadable — using a member", {
+						tags,
+						meta: {
+							ruleId: input.rule.id,
+							trackId: candidate.trackId,
+							mediaId: groupShot
+						}
+					});
+				}
 				const rows = await this.deps.listMediaInfo(candidate.trackId);
 				const picked = pickSummaryMedia(rows, (candidate.firstSeen + candidate.lastSeen) / 2);
 				if (picked === null) {
@@ -19902,6 +20033,21 @@ var NcSummaryRuleInputSchema = require_dist.object({
 	deviceIds: DeviceIdsField,
 	window: NcSummaryWindowSchema,
 	filters: NcSummaryFiltersSchema.optional(),
+	/**
+	* What ONE line of this digest is: a subject, or a group of subjects that
+	* arrived together.
+	*
+	* `tracks` is what the digest has always done and stays the default — the
+	* operator's instruction when groups were added was that the first behaviour
+	* remains. `groups` collapses the members of each session summary to one
+	* entry, so a family walking in is one line and not four
+	* (`summary-group-collapse.ts`).
+	*
+	* `.default('tracks')` is safe here where `NcSummaryFiltersSchema` fields are
+	* not: this is a field of the RULE, not of the partial `filters` object that
+	* a patch materialises wholesale.
+	*/
+	subject: require_dist._enum(["tracks", "groups"]).default("tracks"),
 	maxTiles: MaxTilesField.default(12),
 	maxAiImages: MaxAiImagesField.default(6),
 	rank: NcSummaryRankSchema.default("importance"),
@@ -19936,6 +20082,7 @@ var NcSummaryRulePatchSchema = require_dist.object({
 	maxTiles: MaxTilesField.optional(),
 	maxAiImages: MaxAiImagesField.optional(),
 	rank: NcSummaryRankSchema.optional(),
+	subject: require_dist._enum(["tracks", "groups"]).optional(),
 	barrierSeconds: BarrierSecondsField.optional(),
 	targets: TargetsField.optional(),
 	template: NcSummaryTemplateSchema.nullable().optional(),
@@ -61329,15 +61476,48 @@ var SUMMARY_MEMBERS_COLUMNS = [
 	{
 		name: "className",
 		type: "TEXT"
+	}),
+	(
+	/**
+	* The member's tier-1 label (`dog`, `van`) and tier-2 instance (a name, a
+	* plate), STAMPED AT SEAL.
+	*
+	* Not at the join, and the timing is the whole point: recognition lands
+	* during a track's life, almost always after it joined, so a label written at
+	* the join would be empty on exactly the members worth naming. At the seal
+	* every member's track has closed, so its label is final — there is nothing
+	* left to change it.
+	*
+	* They are COLUMNS because a filter has to be able to ask for them: "show me
+	* the arrivals with a dog" is a query over members, and answering it from the
+	* tracks would mean reading every track of every summary in the window.
+	*/
+	{
+		name: "label",
+		type: "TEXT"
+	}),
+	{
+		name: "subLabel",
+		type: "TEXT"
+	}
+];
+var SUMMARY_MEMBERS_INDEXES = [
+	{
+		name: "summary_members_summary",
+		columns: ["summaryId"]
+	},
+	{
+		name: "summary_members_track",
+		columns: ["trackId"]
+	},
+	(
+	/** The filter's own index: "which groups hold an `animal`" walks members by
+	*  class, never summaries by hope. */
+	{
+		name: "summary_members_class",
+		columns: ["className"]
 	})
 ];
-var SUMMARY_MEMBERS_INDEXES = [{
-	name: "summary_members_summary",
-	columns: ["summaryId"]
-}, {
-	name: "summary_members_track",
-	columns: ["trackId"]
-}];
 /**
 * A stored role, or `null`. An unrecognised value reads as `null` rather than
 * being passed through: a consumer switching on this must not receive a string
@@ -61347,6 +61527,16 @@ var SUMMARY_MEMBERS_INDEXES = [{
 function readRole(raw) {
 	return raw === "primary" || raw === "sibling" || raw === "child" ? raw : null;
 }
+/** The two stamped labels, present only when they hold something. An empty
+*  string is not a label and must never reach a filter as one. */
+function labelFields(data) {
+	const label = data["label"];
+	const subLabel = data["subLabel"];
+	return {
+		...typeof label === "string" && label.length > 0 ? { label } : {},
+		...typeof subLabel === "string" && subLabel.length > 0 ? { subLabel } : {}
+	};
+}
 function readClassName(raw) {
 	return typeof raw === "string" && raw.length > 0 ? raw : null;
 }
@@ -61360,6 +61550,22 @@ function readClassName(raw) {
 * case on a gate camera, not a race. With the track in the key a retry still
 * collapses (same birth, same track) and two births stay two groups.
 */
+/** The widest a JS Date can name — the open end of a half-bounded window. */
+var TIME_MIN = -864e13;
+var TIME_MAX = 864e13;
+/**
+* How many rows one paged read may materialise before the merge.
+*
+* The page is cut AFTER ordering, so the read must be able to serve any cursor
+* position — but it must also be bounded, because an unbounded read of this
+* table on a busy hub is the shape D447 measured holding the settings thread
+* for seconds. Summaries are far fewer than tracks by construction (14 940
+* against 30 583 on this hub), so this ceiling is generous.
+*/
+var RECENT_SUMMARY_SCAN_LIMIT = 5e3;
+/** How many member rows one filter pass may read per tier. Bounded for the same
+*  reason as the scan above, and generous: members are one row per subject. */
+var MEMBER_MATCH_SCAN_LIMIT = 2e4;
 function summaryId(deviceId, openedAt, foundingTrackId) {
 	return `sum-${deviceId}-${openedAt}-${foundingTrackId}`;
 }
@@ -61444,7 +61650,8 @@ var SummaryStore = class {
 			deviceId: num$1(r.data["deviceId"]),
 			joinedAt: num$1(r.data["timestamp"]),
 			role: readRole(r.data["role"]),
-			className: readClassName(r.data["className"])
+			className: readClassName(r.data["className"]),
+			...labelFields(r.data)
 		}));
 	}
 	/**
@@ -61632,6 +61839,23 @@ var SummaryStore = class {
 			memberCount: leaving.length
 		};
 	}
+	/** Stamp a member's final labels. Best-effort and loud: a missing stamp
+	*  costs a filter a match, never a membership. */
+	async stampMemberLabels(summaryIdValue, trackId, labels) {
+		try {
+			await this.store.update.mutate({
+				collection: SUMMARY_MEMBERS_COLLECTION$1,
+				id: memberRowId(summaryIdValue, trackId),
+				data: { ...labels }
+			});
+		} catch (err) {
+			this.logger.warn("summary: could not stamp a member label", { meta: {
+				summaryId: summaryIdValue,
+				trackId,
+				error: String(err)
+			} });
+		}
+	}
 	/**
 	* Put every OTHER member back to `sibling` after a new primary took the role.
 	*
@@ -61757,6 +61981,8 @@ var SummaryStore = class {
 	*/
 	async listRecent(input) {
 		if (input.deviceIds.length === 0) return [];
+		const matching = await this.summaryIdsMatching(input.classes);
+		if (matching !== null && matching.size === 0) return [];
 		const limit = Math.max(1, input.limit);
 		return (await this.store.query.query({
 			collection: SUMMARIES_COLLECTION,
@@ -61769,9 +61995,132 @@ var SummaryStore = class {
 				},
 				limit
 			}
-		})).map((r) => toRow$1(r.id, r.data)).sort((a, b) => b.openedAt - a.openedAt).slice(0, limit);
+		})).map((r) => toRow$1(r.id, r.data)).filter((row) => matching === null || matching.has(row.id)).sort((a, b) => b.openedAt - a.openedAt).slice(0, limit);
 	}
 	/** One summary with its members, or `null`. */
+	/**
+	* One PAGE of summaries across a camera set, newest activity first.
+	*
+	* The same contract as `listRecentTracks` and for the same consumers: the
+	* reel on the cameras page and the Events gallery both ride a cursor, so a
+	* feed that could only answer "the last N" would make groups available in the
+	* timeline and nowhere else. `recent-cursor.ts` is reused verbatim — the
+	* ordering is the stable total order (`lastActiveAt` DESC, id DESC), and a
+	* second implementation of that is a second place for two feeds to disagree
+	* about what "newest" means.
+	*
+	* The window is on LAST ACTIVITY, not on the open: a session that started
+	* before the window and ran into it belongs to the window, because it
+	* happened there.
+	*
+	* Members for the WHOLE page come back in one read. One query per row is how
+	* a page of two hundred becomes two hundred round trips — the shape that made
+	* the old digest read two thousand tracks a camera.
+	*/
+	async queryRecent(input) {
+		const deviceIds = [...new Set(input.deviceIds)];
+		if (deviceIds.length === 0) return {
+			summaries: [],
+			nextCursor: null
+		};
+		const cursor = input.cursor === void 0 ? null : decodeRecentCursor(input.cursor);
+		const matching = await this.summaryIdsMatching(input.classes);
+		if (matching !== null && matching.size === 0) return {
+			summaries: [],
+			nextCursor: null
+		};
+		const ordered = (await this.store.query.query({
+			collection: SUMMARIES_COLLECTION,
+			filter: {
+				whereIn: { deviceId: deviceIds },
+				...input.since !== void 0 || input.until !== void 0 ? { whereBetween: { lastActiveAt: [input.since ?? TIME_MIN, input.until ?? TIME_MAX] } } : {},
+				limit: RECENT_SUMMARY_SCAN_LIMIT
+			}
+		})).map((r) => toRow$1(r.id, r.data)).filter((row) => matching === null || matching.has(row.id)).map((row) => ({
+			row,
+			key: {
+				lastSeen: row.lastActiveAt,
+				id: row.id
+			}
+		})).filter((entry) => cursor === null || isAfterCursor(entry.key, cursor)).toSorted((a, b) => compareRecentDesc(a.key, b.key));
+		const page = ordered.slice(0, input.limit);
+		const last = page.at(-1);
+		const nextCursor = last !== void 0 && ordered.length > page.length ? encodeRecentCursor({
+			lastSeen: last.row.lastActiveAt,
+			trackId: last.row.id
+		}) : null;
+		const members = await this.membersOfMany(page.map((e) => e.row.id));
+		return {
+			summaries: page.map((e) => ({
+				summary: e.row,
+				members: members.get(e.row.id) ?? []
+			})),
+			nextCursor
+		};
+	}
+	/**
+	* The summaries whose MEMBERS match any of `classes`, or `null` for no filter.
+	*
+	* Narrows first, on the members table, and only then reads summary rows.
+	* Filtering the other way round — a page of summaries, then their members —
+	* returns a short or empty page while matches sit further down the list, and
+	* the operator reads that as "there were none".
+	*
+	* Three queries because the filter compiler has no OR across fields, and one
+	* term can be any of the three tiers: `animal` is a class, `dog` is a
+	* sub-class, `Roberta` is an instance. The caller does not have to know
+	* which — that is the whole point of the operator's example.
+	*/
+	async summaryIdsMatching(classes) {
+		const wanted = (classes ?? []).filter((t) => t.length > 0);
+		if (wanted.length === 0) return null;
+		const ids = /* @__PURE__ */ new Set();
+		for (const field of [
+			"className",
+			"label",
+			"subLabel"
+		]) {
+			const rows = await this.store.query.query({
+				collection: SUMMARY_MEMBERS_COLLECTION$1,
+				filter: {
+					whereIn: { [field]: [...wanted] },
+					limit: MEMBER_MATCH_SCAN_LIMIT
+				}
+			});
+			for (const row of rows) ids.add(String(row.data["summaryId"] ?? ""));
+		}
+		ids.delete("");
+		return ids;
+	}
+	/** Members of many summaries, in ONE read, grouped by summary id. */
+	async membersOfMany(summaryIds) {
+		const out = /* @__PURE__ */ new Map();
+		if (summaryIds.length === 0) return out;
+		const rows = await this.store.query.query({
+			collection: SUMMARY_MEMBERS_COLLECTION$1,
+			filter: {
+				whereIn: { summaryId: [...summaryIds] },
+				limit: 1e4
+			}
+		});
+		for (const r of rows) {
+			const summaryIdValue = String(r.data["summaryId"] ?? "");
+			const member = {
+				summaryId: summaryIdValue,
+				trackId: String(r.data["trackId"] ?? ""),
+				deviceId: num$1(r.data["deviceId"]),
+				joinedAt: num$1(r.data["timestamp"]),
+				role: readRole(r.data["role"]),
+				className: readClassName(r.data["className"]),
+				...labelFields(r.data)
+			};
+			const bucket = out.get(summaryIdValue);
+			if (bucket === void 0) out.set(summaryIdValue, [member]);
+			else bucket.push(member);
+		}
+		for (const bucket of out.values()) bucket.sort((a, b) => a.joinedAt - b.joinedAt);
+		return out;
+	}
 	async get(id) {
 		const raw = await this.store.get.query({
 			collection: SUMMARIES_COLLECTION,
@@ -72062,6 +72411,33 @@ async function persistSummaryGroupShot(deps, input) {
 	}
 }
 //#endregion
+//#region src/pipeline-analytics/summary/summary-composition.ts
+function summaryComposition(members) {
+	const counts = /* @__PURE__ */ new Map();
+	for (const member of members) counts.set(member.className, (counts.get(member.className) ?? 0) + 1);
+	return { classes: [...counts].map(([className, count]) => ({
+		className,
+		count
+	})).toSorted((a, b) => a.count !== b.count ? b.count - a.count : (a.className ?? "").localeCompare(b.className ?? "")) };
+}
+//#endregion
+//#region src/pipeline-analytics/summary/summary-member-labels.ts
+function present(value) {
+	return typeof value === "string" && value.length > 0;
+}
+function withMemberLabels(members, tracks) {
+	const byId = new Map(tracks.map((t) => [t.trackId, t]));
+	return members.map((member) => {
+		const track = byId.get(member.trackId);
+		return {
+			...member,
+			className: member.className ?? (present(track?.className) ? track.className : null),
+			...present(track?.label) ? { label: track.label } : {},
+			...present(track?.subLabel) ? { subLabel: track.subLabel } : {}
+		};
+	});
+}
+//#endregion
 //#region src/pipeline-analytics/summary/summary-join.ts
 /**
 * Which open group a newborn track joins — or none, and it opens its own.
@@ -72407,7 +72783,21 @@ var SummarySealer = class {
 			return null;
 		}
 	}
-	async sealIfDone(summary) {
+	/**
+	* Is this group finished?
+	*
+	* Both questions are about THIS group's members, not about the camera. A
+	* camera holds as many groups as it has (D489), so a camera-wide gate means
+	* no group seals until every subject on the camera has gone — and on a busy
+	* camera they never all go at once. Measured: eight summaries open on one
+	* camera over seventeen minutes, none sealed, each new subject opening a
+	* ninth because a group whose members have closed has no positions left for
+	* the proximity rule to judge.
+	*
+	* `null` means "could not find out", and the caller treats that as NOT done —
+	* a read that failed must never seal a live session (D49).
+	*/
+	async isGroupFinished(summary, members) {
 		const { id: summaryId, deviceId } = summary;
 		let openTracks;
 		try {
@@ -72420,12 +72810,13 @@ var SummarySealer = class {
 					error: errMsg(err)
 				}
 			});
-			return;
+			return null;
 		}
-		if (openTracks.length > 0) return;
-		let quiet;
+		const stillOpen = new Set(openTracks);
+		if (members.some((m) => stillOpen.has(m))) return false;
+		let parked;
 		try {
-			quiet = await this.deps.isCameraQuiet(deviceId);
+			parked = await this.deps.parkedTrackIds(deviceId);
 		} catch (err) {
 			this.deps.logger.warn("summary sweep: could not read the stationary registry — seal aborted this sweep", {
 				tags: { deviceId },
@@ -72434,10 +72825,28 @@ var SummarySealer = class {
 					error: errMsg(err)
 				}
 			});
+			return null;
+		}
+		return !members.some((m) => parked.has(m));
+	}
+	async sealIfDone(summary) {
+		const { id: summaryId, deviceId } = summary;
+		let members;
+		try {
+			members = (await this.deps.summaries.membersOf(summaryId)).map((m) => m.trackId);
+		} catch (err) {
+			this.deps.logger.warn("summary sweep: could not read members — seal aborted this sweep", {
+				tags: { deviceId },
+				meta: {
+					summaryId,
+					error: errMsg(err)
+				}
+			});
 			return;
 		}
-		if (!quiet) return;
+		if (await this.isGroupFinished(summary, members) !== true) return;
 		const sealedAt = this.deps.now();
+		await this.stampLabels(summary, members);
 		try {
 			if (await this.deps.summaries.seal(summary, sealedAt)) {
 				const members = this.forgetGroup(deviceId, summaryId);
@@ -72470,6 +72879,37 @@ var SummarySealer = class {
 		if (members === void 0) groups.set(summaryIdValue, new Set([trackId]));
 		else members.add(trackId);
 	}
+	/**
+	* Write each member's final label onto its row.
+	*
+	* At the seal every member's track has closed, so what the pipeline decided
+	* about it is final — this is the first and last moment the stamp can be
+	* both complete and correct.
+	*/
+	async stampLabels(summary, members) {
+		const read = this.deps.labelsFor;
+		if (read === void 0 || members.length === 0) return;
+		try {
+			const labels = await read(members);
+			for (const [trackId, value] of labels) {
+				const label = value.label;
+				const subLabel = value.subLabel;
+				if ((label === void 0 || label.length === 0) && (subLabel === void 0 || subLabel.length === 0)) continue;
+				await this.deps.summaries.stampMemberLabels(summary.id, trackId, {
+					...label !== void 0 && label.length > 0 ? { label } : {},
+					...subLabel !== void 0 && subLabel.length > 0 ? { subLabel } : {}
+				});
+			}
+		} catch (err) {
+			this.deps.logger.warn("summary: could not stamp member labels — the seal stands", {
+				tags: { deviceId: summary.deviceId },
+				meta: {
+					summaryId: summary.id,
+					error: errMsg(err)
+				}
+			});
+		}
+	}
 	/** Follows a split in the mirror, so the frame path scores each half on its
 	*  own members from the very next frame. */
 	moveMirrorMembers(deviceId, fromId, toId, trackIds) {
@@ -74042,6 +74482,21 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_dist.B
 				await secretState.set(secret);
 			}
 			const shelfWindows = await this.pruneWindows();
+			const index = new NcArtifactIndex({
+				store: this.ctx.api.settingsStore,
+				logger: this.ctx.logger.child("nc-artifacts"),
+				addonId: this.ctx.id,
+				retentionMs: shelfWindows.artifactShelfMs
+			});
+			this.ncArtifactIndex = index;
+			const refusal = artifactShelfRefusal(await this.ctx.api.storage.listLocations.query({}), this.ctx.kernel.localNodeId ?? null);
+			if (refusal !== null) {
+				this.ctx.logger.info("nc-artifact shelf not served on this node", { meta: {
+					reason: refusal,
+					indexServed: true
+				} });
+				return;
+			}
 			const store = new NcArtifactStore({
 				rootDir: await this.resolveNcArtifactRoot(),
 				logger: this.ctx.logger.child("nc-artifacts"),
@@ -74049,13 +74504,6 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_dist.B
 			});
 			await store.start();
 			this.ncArtifactStore = store;
-			const index = new NcArtifactIndex({
-				store: this.ctx.api.settingsStore,
-				logger: this.ctx.logger.child("nc-artifacts"),
-				addonId: this.ctx.id,
-				retentionMs: store.retentionMs
-			});
-			this.ncArtifactIndex = index;
 			const plane = new NcArtifactPlane({
 				store,
 				secret,
@@ -75415,7 +75863,25 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_dist.B
 			summaries: this.summaryStore,
 			analysedDeviceIds: () => [...this.lastFrameDimsByDevice.keys()],
 			openTrackIds: async (deviceId) => this.residents.trackIdsForDevice(deviceId),
-			isCameraQuiet: async (deviceId) => (this.stationaryRegistry?.count(deviceId) ?? 0) === 0,
+			parkedTrackIds: async (deviceId) => {
+				const ids = /* @__PURE__ */ new Set();
+				for (const entry of this.stationaryRegistry?.list(deviceId) ?? []) if (entry.sourceTrackId !== void 0) ids.add(entry.sourceTrackId);
+				return ids;
+			},
+			labelsFor: async (trackIds) => {
+				const out = /* @__PURE__ */ new Map();
+				const tracks = await this.trackStore?.getPersistedByTrackIds(trackIds) ?? [];
+				for (const track of tracks) {
+					const label = track.label;
+					const subLabel = track.subLabel;
+					if (label === void 0 && subLabel === void 0) continue;
+					out.set(track.trackId, {
+						...label !== void 0 ? { label } : {},
+						...subLabel !== void 0 ? { subLabel } : {}
+					});
+				}
+				return out;
+			},
 			now: () => Date.now(),
 			logger: this.ctx.logger.child("summary-sealer"),
 			frameSize: (deviceId) => {
@@ -76120,6 +76586,30 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_dist.B
 					confirmed: t.observations !== void 0 && t.observations >= minHits
 				}));
 			},
+			listSummaryGroups: async ({ deviceId, sinceMs, untilMs }) => {
+				const summaryStore = this.summaryStore;
+				if (!summaryStore) return [];
+				const rows = await summaryStore.listRecent({
+					deviceIds: [deviceId],
+					since: sinceMs,
+					until: untilMs,
+					limit: 500
+				});
+				const out = [];
+				for (const row of rows) {
+					const members = await summaryStore.membersOf(row.id);
+					const files = await this.mediaStore?.listInfoByOwner("summary", row.id) ?? [];
+					const shot = files.find((f) => f.kind === "keyFrameSmall") ?? files.find((f) => f.kind === "keyFrame");
+					out.push({
+						summaryId: row.id,
+						deviceId: row.deviceId,
+						memberTrackIds: members.map((m) => m.trackId),
+						primaryTrackId: members.find((m) => m.role === "primary")?.trackId ?? null,
+						groupShotMediaId: shot?.mediaId ?? null
+					});
+				}
+				return out;
+			},
 			listMediaInfo: async (id) => {
 				return (await stores.mediaStore.listInfoByOwner("track", id)).map((r) => ({
 					mediaId: r.mediaId,
@@ -81268,23 +81758,96 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_dist.B
 			deviceIds: input.deviceIds,
 			...input.since !== void 0 ? { since: input.since } : {},
 			...input.until !== void 0 ? { until: input.until } : {},
-			limit: input.limit ?? 50
+			limit: input.limit ?? 50,
+			...input.classes !== void 0 ? { classes: input.classes } : {}
 		});
-		return { summaries: await Promise.all(rows.map((row) => this.toSummary(row))) };
+		return { summaries: await this.listItemsFor(rows) };
 	}
-	async getSummary(input) {
-		const detail = await this.summaryStore?.get(input.id);
-		if (!detail) return null;
+	/**
+	* Rows → what a LIST draws: the envelope plus the composition.
+	*
+	* Two bulk reads for the whole page, never per row: the members in one, their
+	* tracks (for the names) in one. The MEMBERS themselves stay off the list —
+	* a page of two hundred groups would otherwise carry a thousand records so
+	* the client could count them. `getSummary` is where the links live.
+	*/
+	async listItemsFor(rows) {
+		const store = this.summaryStore;
+		if (!store || rows.length === 0) return [];
+		const members = await store.membersOfMany(rows.map((r) => r.id));
+		return await Promise.all(rows.map(async (row) => ({
+			summary: await this.toSummary(row),
+			...summaryComposition(members.get(row.id) ?? [])
+		})));
+	}
+	/** The members of a page of summaries, with the labels a card can show —
+	*  in ONE read of the members and ONE of their tracks. */
+	async labelledMembersFor(rows) {
+		const out = /* @__PURE__ */ new Map();
+		const store = this.summaryStore;
+		if (!store || rows.length === 0) return out;
+		const membersBySummary = await store.membersOfMany(rows.map((r) => r.id));
+		const trackIds = [...new Set([...membersBySummary.values()].flatMap((ms) => ms.map((m) => m.trackId)))];
+		let tracks = [];
+		try {
+			tracks = await this.trackStore?.getPersistedByTrackIds(trackIds) ?? [];
+		} catch (err) {
+			this.ctx.logger.warn("summary members: labels unavailable for this page", { meta: {
+				summaries: rows.length,
+				members: trackIds.length,
+				error: require_dist.errMsg(err)
+			} });
+		}
+		for (const row of rows) out.set(row.id, withMemberLabels(membersBySummary.get(row.id) ?? [], tracks));
+		return out;
+	}
+	/**
+	* Rows → the shape every summary surface answers with: the envelope, its
+	* members, and what a thumbnail can render for each of them.
+	*
+	* THREE reads for the whole page, never per row: the members in one, their
+	* tracks in one, and the group shots through `toSummary`. A read per member
+	* is what made a sixty-group page take twenty seconds on the events feed.
+	*/
+	/** ONE summary, with every member and the link each of them carries. */
+	async detailFor(row) {
+		const labelled = (await this.labelledMembersFor([row])).get(row.id) ?? [];
 		return {
-			summary: await this.toSummary(detail.summary),
-			members: detail.members.map((m) => ({
+			summary: await this.toSummary(row),
+			members: labelled.map((m) => ({
 				trackId: m.trackId,
 				className: m.className,
 				role: m.role,
-				joinedAt: m.joinedAt
+				joinedAt: m.joinedAt,
+				...m.label !== void 0 ? { label: m.label } : {},
+				...m.subLabel !== void 0 ? { subLabel: m.subLabel } : {}
 			}))
 		};
 	}
+	async listRecentSummaries(input) {
+		const store = this.summaryStore;
+		if (!store) return {
+			summaries: [],
+			nextCursor: null
+		};
+		const page = await store.queryRecent({
+			deviceIds: input.deviceIds,
+			...input.since !== void 0 ? { since: input.since } : {},
+			...input.until !== void 0 ? { until: input.until } : {},
+			limit: input.limit,
+			...input.cursor !== void 0 ? { cursor: input.cursor } : {},
+			...input.classes !== void 0 ? { classes: input.classes } : {}
+		});
+		return {
+			summaries: await this.listItemsFor(page.summaries.map((d) => d.summary)),
+			nextCursor: page.nextCursor
+		};
+	}
+	async getSummary(input) {
+		const detail = await this.summaryStore?.get(input.id);
+		if (!detail) return null;
+		return await this.detailFor(detail.summary);
+	}
 	/** The row plus its group shot: the web companion when it landed, else the native key frame. */
 	async toSummary(row) {
 		const files = await this.mediaStore?.listInfoByOwner("summary", row.id) ?? [];