@camstack/addon-post-analysis 1.2.110 → 1.2.115

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-RzJseCJP.js");
+const require_dist = require("../dist-C0uPGtBv.js");
 let node_fs = require("node:fs");
 node_fs = require_dist.__toESM(node_fs, 1);
 let node_path = require("node:path");
@@ -3029,8 +3029,8 @@ async function raceTimeout(call, timeoutMs) {
 * detail the encoder can see.
 */
 async function downscaleJpeg(bytes, maxPx) {
-	const { default: sharp$15 } = await import("sharp");
-	const out = await sharp$15(Buffer.from(bytes)).resize({
+	const { default: sharp$16 } = await import("sharp");
+	const out = await sharp$16(Buffer.from(bytes)).resize({
 		width: maxPx,
 		height: maxPx,
 		fit: "inside",
@@ -5354,24 +5354,17 @@ function buildAlarmButtons(input) {
 *
 * ── TWO EXCLUSIVE MODES (operator decision 2026-08-14, D157) ───────────────
 *
-* **LABEL mode** — the rule NAMES SOUNDS (`labels`). It confirms on the FIRST
-* frame the classifier labels with one of them. No window, no percentage, no
-* waiting.
-*
-* That is not a convenience: it is the only shape that can fire at all. The
-* analyzer emits ~1 inference frame per second, but YAMNet puts a macro label
-* on only one to three of them per episode — even through continuous crying.
-* The maximum `hitPercent` ever measured on this installation's whole history
-* was 40, under the shipped default of 60, so the previous windowed semantics
-* meant a label rule could NEVER confirm. A percentage of frames is the wrong
-* question to ask of a sparse classifier. The per-label confidence floor still
-* applies — it is the analyzer's own `classificationMinScore`, applied per
-* device before a label ever reaches this module.
-*
-* The rule's `throttle` cooldown is the ONLY brake in this mode. There is
-* deliberately no re-arm timer here: a second brake nobody can see in the
-* editor is how a rule ends up silently not firing, which is the failure this
-* change exists to remove.
+* **LABEL mode** — the rule NAMES SOUNDS (`labels`). It confirms when
+* `confirmHits` labelled frames land inside `confirmWindowSec` (default 2
+* in 5 s). That is a COUNT of sparse frames, not a percentage of the
+* stream: YAMNet still labels only one to three frames per episode, so a
+* 60%-of-10s window can never fire, but two of those frames two seconds
+* apart can. A single-frame false positive (the live "Pianti" pattern)
+* never reaches 2. `confirmHits: 1` is the old first-frame behaviour.
+*
+* The per-label confidence floor still applies — it is the analyzer's own
+* `classificationMinScore`, applied per device before a label ever reaches
+* this module. The rule's `throttle` cooldown is the OTHER brake.
 *
 * **LEVEL mode** — the rule NAMES A LEVEL (`dbThreshold`). Unchanged, and the
 * window is the whole point: over `samplingSeconds`, at least `hitPercent`% of
@@ -5434,7 +5427,9 @@ function audioSpecFromCondition(condition) {
 	const mode = require_dist.audioModeOf(condition);
 	if (mode === "label") return {
 		mode: "label",
-		labels: [...new Set((condition.labels ?? []).map(normalizeAudioLabel))].sort()
+		labels: [...new Set((condition.labels ?? []).map(normalizeAudioLabel))].sort(),
+		confirmHits: condition.confirmHits ?? 2,
+		confirmWindowSec: condition.confirmWindowSec ?? 5
 	};
 	const dbThreshold = condition.dbThreshold;
 	if (mode === "level" && dbThreshold !== void 0) return {
@@ -5447,7 +5442,7 @@ function audioSpecFromCondition(condition) {
 }
 /** Stable, device-agnostic key of a spec — rules that agree share a window. */
 function audioSpecKey(spec) {
-	return spec.mode === "label" ? `label|${spec.labels.join(",")}` : `level|${String(spec.dbThreshold)}|h${String(spec.hitPercent)}|s${String(spec.samplingSeconds)}`;
+	return spec.mode === "label" ? `label|${spec.labels.join(",")}|c${String(spec.confirmHits)}|w${String(spec.confirmWindowSec)}` : `level|${String(spec.dbThreshold)}|h${String(spec.hitPercent)}|s${String(spec.samplingSeconds)}`;
 }
 /**
 * The watched labels this sample carries, normalized and sorted. Empty = no
@@ -5472,6 +5467,8 @@ var AudioWatcher = class {
 	watched = /* @__PURE__ */ new Map();
 	/** LEVEL windows, keyed `${deviceId}|${specKey}`. */
 	windows = /* @__PURE__ */ new Map();
+	/** LABEL pending hits, keyed `${deviceId}|${specKey}` — timestamps only. */
+	labelHits = /* @__PURE__ */ new Map();
 	/**
 	* Replace the watched spec set (rule-driven — recomputed on every rule
 	* reload). Windows whose spec is no longer watched are DROPPED: a rule
@@ -5482,9 +5479,9 @@ var AudioWatcher = class {
 	setWatchedSpecs(specs) {
 		this.watched.clear();
 		for (const spec of specs) this.watched.set(audioSpecKey(spec), spec);
-		for (const key of [...this.windows.keys()]) {
+		for (const store of [this.windows, this.labelHits]) for (const key of [...store.keys()]) {
 			const specKey = key.slice(key.indexOf("|") + 1);
-			if (!this.watched.has(specKey)) this.windows.delete(key);
+			if (!this.watched.has(specKey)) store.delete(key);
 		}
 	}
 	/** True when at least one spec is watched — the caller's cheap no-op gate. */
@@ -5500,7 +5497,7 @@ var AudioWatcher = class {
 		if (this.watched.size === 0) return [];
 		const confirmed = [];
 		for (const [specKey, spec] of this.watched) {
-			const hit = spec.mode === "label" ? observeLabel(deviceId, spec, sample, now) : this.observeLevel(deviceId, specKey, spec, sample, now);
+			const hit = spec.mode === "label" ? this.observeLabel(deviceId, specKey, spec, sample, now) : this.observeLevel(deviceId, specKey, spec, sample, now);
 			if (hit !== null) confirmed.push(hit);
 		}
 		return confirmed;
@@ -5508,7 +5505,7 @@ var AudioWatcher = class {
 	/** Drop every window of a camera (unbound, removed, audio switched off). */
 	forgetDevice(deviceId) {
 		const prefix = `${deviceId}|`;
-		for (const key of [...this.windows.keys()]) if (key.startsWith(prefix)) this.windows.delete(key);
+		for (const store of [this.windows, this.labelHits]) for (const key of [...store.keys()]) if (key.startsWith(prefix)) store.delete(key);
 	}
 	observeLevel(deviceId, specKey, spec, sample, now) {
 		const key = `${deviceId}|${specKey}`;
@@ -5557,23 +5554,34 @@ var AudioWatcher = class {
 			spec
 		};
 	}
+	/**
+	* LABEL mode: confirm when `confirmHits` labelled frames land inside
+	* `confirmWindowSec`. `confirmHits <= 1` is first-frame fire (stateless).
+	* Confirming re-arms — the next episode needs a fresh count.
+	*/
+	observeLabel(deviceId, specKey, spec, sample, now) {
+		const matched = matchedAudioLabels(sample, spec.labels);
+		if (matched.length === 0) return null;
+		const hit = {
+			deviceId,
+			timestamp: now,
+			labels: matched,
+			...sample.dbfs !== void 0 && Number.isFinite(sample.dbfs) ? { peakDbfs: sample.dbfs } : {},
+			spec
+		};
+		if (spec.confirmHits <= 1) return hit;
+		const key = `${deviceId}|${specKey}`;
+		const cutoff = now - spec.confirmWindowSec * 1e3;
+		const kept = (this.labelHits.get(key) ?? []).filter((at) => at > cutoff);
+		kept.push(now);
+		if (kept.length < spec.confirmHits) {
+			this.labelHits.set(key, kept);
+			return null;
+		}
+		this.labelHits.delete(key);
+		return hit;
+	}
 };
-/**
-* LABEL mode: confirm on the first frame carrying a watched label. Stateless
-* by construction — nothing is remembered between frames, so there is no
-* window to be not-full and no percentage to fall short of.
-*/
-function observeLabel(deviceId, spec, sample, now) {
-	const matched = matchedAudioLabels(sample, spec.labels);
-	if (matched.length === 0) return null;
-	return {
-		deviceId,
-		timestamp: now,
-		labels: matched,
-		...sample.dbfs !== void 0 && Number.isFinite(sample.dbfs) ? { peakDbfs: sample.dbfs } : {},
-		spec
-	};
-}
 //#endregion
 //#region src/shared/llm-vision/prompt-hygiene.ts
 /**
@@ -7920,7 +7928,10 @@ function attachmentKindPreference(policy, ownerKind) {
 	if (policy === "keyFrame") return ownerKind === "track" ? [
 		"keyFrameSmall",
 		"keyFrame",
-		"fullFrameBoxed"
+		"fullFrameBoxed",
+		"firstFrame",
+		"lastFrame",
+		"snapshot"
 	] : [
 		"fullFrameBoxed",
 		"fullFrame",
@@ -9455,8 +9466,8 @@ var NcDispatcher = class {
 		try {
 			const points = (await this.deps.getZonePolygons?.(deviceId, zoneIds) ?? []).flat();
 			if (points.length === 0) return null;
-			const { default: sharp$14 } = await import("sharp");
-			const img = sharp$14(Buffer.from(jpeg));
+			const { default: sharp$15 } = await import("sharp");
+			const img = sharp$15(Buffer.from(jpeg));
 			const meta = await img.metadata();
 			const W = meta.width ?? 0;
 			const H = meta.height ?? 0;
@@ -15130,14 +15141,13 @@ function selectSummaryTiles(candidates, opts) {
 /**
 * The media a tile is drawn from, best first.
 *
-* `keyFrameSmall` heads the ladder because it is the CLEAN best-shot frame at
-* 960 px — the whole scene, legible on a phone, cheap. `fullFrameBoxed` and
-* `firstFrame` are deliberately absent: a drawn rectangle is a permanent lie in
-* a digest tile, the operator asked for a mosaic that is ALWAYS CLEAN, and (for
-* P2) a box burnt into a pixel is text inside an image — an injection channel
-* and a source of hallucination. Boxes stay data.
+* `groupCrop` heads the ladder: it is the group's own clean wide-central-square
+* over the union bbox, and a drawn rectangle is a permanent lie in a digest
+* tile. Singletons have no groupCrop and fall through to the member ladder.
+* `fullFrameBoxed` and `firstFrame` stay absent for the same reason.
 */
 var SUMMARY_MEDIA_LADDER = [
+	"groupCrop",
 	"keyFrameSmall",
 	"keyFrame",
 	"snapshot",
@@ -15219,7 +15229,7 @@ var SUMMARY_TRACK_QUERY_LIMIT = 2e3;
 function summaryMediaOwnerId(ruleId, windowEndMs) {
 	return `summary-${ruleId}-${windowEndMs}`;
 }
-var EMPTY_REPORT = {
+var EMPTY_REPORT$1 = {
 	produced: 0,
 	collecting: 0,
 	barrier: 0,
@@ -15283,9 +15293,9 @@ var NcSummaryProducer = class {
 	* must not open ten simultaneous render/publish sequences.
 	*/
 	async tick() {
-		if (this.tickInFlight) return EMPTY_REPORT;
+		if (this.tickInFlight) return EMPTY_REPORT$1;
 		this.tickInFlight = true;
-		const report = { ...EMPTY_REPORT };
+		const report = { ...EMPTY_REPORT$1 };
 		try {
 			const now = this.deps.now();
 			const rules = this.deps.store.listEnabled();
@@ -15996,7 +16006,7 @@ var NcSummaryRuleInputSchema = require_dist.object({
 	deviceIds: DeviceIdsField,
 	window: NcSummaryWindowSchema,
 	filters: NcSummaryFiltersSchema.optional(),
-	maxTiles: MaxTilesField.default(9),
+	maxTiles: MaxTilesField.default(12),
 	maxAiImages: MaxAiImagesField.default(6),
 	rank: NcSummaryRankSchema.default("importance"),
 	barrierSeconds: BarrierSecondsField.default(120),
@@ -16714,8 +16724,8 @@ async function deriveSyntheticMedia(jpeg, bbox, timestamp) {
 	];
 	if (bbox === void 0) return files;
 	try {
-		const { default: sharp$13 } = await import("sharp");
-		const meta = await sharp$13(Buffer.from(jpeg)).metadata();
+		const { default: sharp$14 } = await import("sharp");
+		const meta = await sharp$14(Buffer.from(jpeg)).metadata();
 		const W = meta.width ?? 0;
 		const H = meta.height ?? 0;
 		if (W === 0 || H === 0) return files;
@@ -16723,7 +16733,7 @@ async function deriveSyntheticMedia(jpeg, bbox, timestamp) {
 		const top = Math.max(0, Math.min(H - 1, Math.floor(bbox.y * H)));
 		const width = Math.max(1, Math.min(W - left, Math.ceil(bbox.w * W)));
 		const height = Math.max(1, Math.min(H - top, Math.ceil(bbox.h * H)));
-		const cropBuf = await sharp$13(Buffer.from(jpeg)).extract({
+		const cropBuf = await sharp$14(Buffer.from(jpeg)).extract({
 			left,
 			top,
 			width,
@@ -16745,7 +16755,7 @@ async function deriveSyntheticMedia(jpeg, bbox, timestamp) {
 		});
 		const stroke = Math.max(2, Math.round(Math.min(W, H) / 240));
 		const overlay = Buffer.from(`<svg width="${W}" height="${H}"><rect x="${left}" y="${top}" width="${width}" height="${height}" fill="none" stroke="#22d3ee" stroke-width="${stroke}"/></svg>`);
-		const boxedBuf = await sharp$13(Buffer.from(jpeg)).composite([{
+		const boxedBuf = await sharp$14(Buffer.from(jpeg)).composite([{
 			input: overlay,
 			top: 0,
 			left: 0
@@ -18362,6 +18372,15 @@ var TIMELAPSE_LOOKBACK_MS = 8 * 864e5;
 function timelapseEligibilityFloor(rule, deviceId) {
 	return Math.max(require_dist.readTimelapseGeneratedAt(rule, deviceId), rule.createdAt);
 }
+var EMPTY_REPORT = {
+	produced: 0,
+	waiting: 0,
+	alreadyDone: 0,
+	beforeFloor: 0,
+	failed: 0,
+	idle: 0,
+	skippedInFlight: 0
+};
 /** The in-flight map's key. One render per (rule, camera) pair by construction. */
 function renderFlightKey(ruleId, deviceId) {
 	return `${ruleId}:${String(deviceId)}`;
@@ -18369,7 +18388,8 @@ function renderFlightKey(ruleId, deviceId) {
 var TimelapseScheduler = class {
 	deps;
 	timer = null;
-	tickInFlight = false;
+	/** True only while this tick is scanning eligibility — not while ffmpeg runs. */
+	scanning = false;
 	inFlight = /* @__PURE__ */ new Map();
 	settleMs;
 	lookbackMs;
@@ -18416,25 +18436,29 @@ var TimelapseScheduler = class {
 			this.timer = null;
 		}
 	}
-	/** One pass over every enabled rule × camera. Single-flight. */
+	/**
+	* One pass over every enabled rule × camera.
+	*
+	* Eligibility is scanned under a short `scanning` lock so two ticks do not
+	* double-launch the same pair. Renders themselves are started together —
+	* awaiting them one-by-one made camera B wait for camera A's ffmpeg
+	* (live: 1441 until 08:39, 615 until 08:46, both windows closed at 07:00).
+	* A later tick that meets a pair already in `inFlight` counts it and
+	* moves on, so a 30-minute render does not make the producer go deaf.
+	*/
 	async tick() {
-		if (this.tickInFlight) return {
-			produced: 0,
-			waiting: 0,
-			alreadyDone: 0,
-			beforeFloor: 0,
-			failed: 0,
-			idle: 0
-		};
-		this.tickInFlight = true;
+		if (this.scanning) return { ...EMPTY_REPORT };
+		this.scanning = true;
 		const report = {
 			produced: 0,
 			waiting: 0,
 			alreadyDone: 0,
 			beforeFloor: 0,
 			failed: 0,
-			idle: 0
+			idle: 0,
+			skippedInFlight: 0
 		};
+		const jobs = [];
 		try {
 			const now = this.deps.now();
 			for (const rule of this.deps.store.listEnabled()) {
@@ -18469,13 +18493,20 @@ var TimelapseScheduler = class {
 						});
 						continue;
 					}
-					if ((await this.produce(rule, deviceId, window, { stamp: true })).produced > 0) report.produced += 1;
-					else report.failed += 1;
+					if (this.inFlight.has(renderFlightKey(rule.id, deviceId))) {
+						report.skippedInFlight += 1;
+						continue;
+					}
+					jobs.push(this.produce(rule, deviceId, window, { stamp: true }).then((ok) => {
+						if (ok.produced > 0) report.produced += 1;
+						else report.failed += 1;
+					}));
 				}
 			}
 		} finally {
-			this.tickInFlight = false;
+			this.scanning = false;
 		}
+		await Promise.all(jobs);
 		return report;
 	}
 	/**
@@ -27631,6 +27662,35 @@ function pairRiders(detections) {
 	return pairs;
 }
 //#endregion
+//#region src/pipeline-analytics/pipeline/tracker/rescue-growth.ts
+/** How far the grown box's centroid may sit, as a multiple of the LARGER
+*  diagonal. 1.35 covers the live 4285605a bird→dog jump (~75px / 59px). */
+var GROWTH_CENTROID_FACTOR = 1.35;
+function intersectionArea(a, b) {
+	const x1 = Math.max(a.x, b.x);
+	const y1 = Math.max(a.y, b.y);
+	const x2 = Math.min(a.x + a.w, b.x + b.w);
+	const y2 = Math.min(a.y + a.h, b.y + b.h);
+	if (x2 <= x1 || y2 <= y1) return 0;
+	return (x2 - x1) * (y2 - y1);
+}
+/** Same-class partial crop growing into (or collapsing from) a full-body box
+*  with IoU 0. Used by rescue and spawn-dedup so we do not mint a second id.
+*  A SMALL box nested inside a LARGE one is occlusion, not growth — those
+*  stay two tracks (sort-tracker occlusion suite). */
+function growthAdjacentMatch(track, det) {
+	const trackArea = track.w * track.h;
+	const detArea = det.w * det.h;
+	if (trackArea <= 0 || detArea <= 0) return false;
+	const larger = Math.max(trackArea, detArea);
+	const smaller = Math.min(trackArea, detArea);
+	if (larger / smaller < 1.5) return false;
+	if (intersectionArea(track, det) / smaller >= .5) return false;
+	const tc = bboxCentroid(track);
+	const dc = bboxCentroid(det);
+	return Math.hypot(tc.x - dc.x, tc.y - dc.y) <= GROWTH_CENTROID_FACTOR * Math.max(Math.hypot(track.w, track.h), Math.hypot(det.w, det.h));
+}
+//#endregion
 //#region src/pipeline-analytics/pipeline/tracker/sort-tracker.ts
 var DEFAULT_TRACKER_CONFIG = {
 	iouThreshold: .3,
@@ -27758,7 +27818,7 @@ var SortTracker = class SortTracker {
 	* and earlier same-frame spawns).
 	*/
 	isDuplicateSpawn(det, live) {
-		for (const t of live) if (this.dedupCompatible(t.class, det.class) && iou$2(det.bbox, t.bbox) >= this.config.dedupSpawnIou) return true;
+		for (const t of live) if (this.dedupCompatible(t.class, det.class) && (iou$2(det.bbox, t.bbox) >= this.config.dedupSpawnIou || growthAdjacentMatch(t.bbox, det.bbox))) return true;
 		if (this.config.personAnimalDedup && det.class === ANIMAL_CLASS && det.score < this.config.animalOverPersonMaxScore) {
 			for (const t of live) if (t.class === PERSON_CLASS && iou$2(det.bbox, t.bbox) >= this.config.animalOverPersonIou) return true;
 		}
@@ -27852,7 +27912,8 @@ var SortTracker = class SortTracker {
 		const dc = bboxCentroid(det.bbox);
 		const dist = Math.hypot(tc.x - dc.x, tc.y - dc.y);
 		const diag = Math.hypot(track.bbox.w, track.bbox.h);
-		return dist <= this.config.rescueCentroidFactor * diag;
+		if (dist <= this.config.rescueCentroidFactor * diag) return true;
+		return growthAdjacentMatch(track.bbox, det.bbox);
 	}
 	/** Fold a matched detection's class + score into a track's lifetime vote
 	*  tally. A non-positive score still counts as an infinitesimal vote so a
@@ -28177,6 +28238,7 @@ var StateAnalyzer = class {
 					enteredAt: timestamp,
 					stationarySince: void 0,
 					totalDistancePx: 0,
+					startPosition: center,
 					lastPosition: center,
 					frameCount: 1
 				};
@@ -28196,8 +28258,9 @@ var StateAnalyzer = class {
 			else if (velocity <= this.config.velocityThreshold) {
 				if (!ts.stationarySince) ts.stationarySince = timestamp;
 				const stationaryDurationSec = (timestamp - ts.stationarySince) / 1e3;
+				const neverMoved = Math.hypot(ts.lastPosition.x - ts.startPosition.x, ts.lastPosition.y - ts.startPosition.y) <= this.config.velocityThreshold;
 				if (stationaryDurationSec >= this.config.loiteringThresholdSec) state = "loitering";
-				else if (stationaryDurationSec >= this.config.stationaryThresholdSec) state = "stationary";
+				else if (neverMoved || stationaryDurationSec >= this.config.stationaryThresholdSec) state = "stationary";
 				else state = "moving";
 			} else {
 				ts.stationarySince = void 0;
@@ -29030,6 +29093,22 @@ function promoteSemanticBestFrame(deps, input) {
 	};
 }
 //#endregion
+//#region src/pipeline-analytics/pipeline/semantic-detail-bbox.ts
+/** Which box the semantic best-shot should crop: a plate/face DETAIL box
+*  when we have one, otherwise the subject box. */
+function bboxForSemanticPromotion(className, detailBbox, subjectBbox) {
+	if ((className === "plate" || className === "face") && detailBbox !== void 0 && detailBbox.w > 0 && detailBbox.h > 0) return detailBbox;
+	return subjectBbox;
+}
+//#endregion
+//#region src/pipeline-analytics/pipeline/first-frame-retry-bbox.ts
+/** Crop box for a late firstFrame retry: the BIRTH geometry, not the
+*  later frozen/coasted box (track 1b659d56). */
+function firstFrameRetryBbox(current, birth) {
+	if (birth !== void 0 && birth.w > 0 && birth.h > 0) return { ...birth };
+	return { ...current };
+}
+//#endregion
 //#region src/pipeline-analytics/store/zone-geometry.ts
 /**
 * Normalized min/max envelope over every position's bbox. Returns `null`
@@ -29244,6 +29323,7 @@ var EMPTY_CASCADE_TALLY = {
 	faces: 0,
 	plates: 0,
 	embeddings: 0,
+	groups: 0,
 	bytesReclaimed: 0
 };
 /** Fold a leaf store's receipts into a running tally. */
@@ -29287,6 +29367,13 @@ function addLeafCounts(tally, counts) {
 					bytesReclaimed
 				};
 				break;
+			case "groups":
+				next = {
+					...next,
+					groups: next.groups + c.rows,
+					bytesReclaimed
+				};
+				break;
 		}
 	}
 	return next;
@@ -29300,6 +29387,7 @@ function mergeCascadeTallies(a, b) {
 		faces: a.faces + b.faces,
 		plates: a.plates + b.plates,
 		embeddings: a.embeddings + b.embeddings,
+		groups: a.groups + b.groups,
 		bytesReclaimed: a.bytesReclaimed + b.bytesReclaimed
 	};
 }
@@ -29348,6 +29436,7 @@ function buildAnalyticsCascadeRegistry(stores) {
 	if (stores.faceStore) registry.push(stores.faceStore);
 	if (stores.plateStore) registry.push(stores.plateStore);
 	if (stores.objectEmbeddingStore) registry.push(stores.objectEmbeddingStore);
+	if (stores.groupStore) registry.push(stores.groupStore);
 	return registry;
 }
 /**
@@ -31058,7 +31147,8 @@ var OWNER_KINDS = [
 	"identity",
 	"plate",
 	"vehicle",
-	"scene"
+	"scene",
+	"group"
 ];
 /**
 * Narrow an arbitrary string to an `OwnerKind`.
@@ -31807,6 +31897,10 @@ var MediaStore = class {
 	async deleteForTracks(trackIds) {
 		return this.deleteForOwner("track", trackIds);
 	}
+	/** Delete the group's OWN crop. The native frame is a pointer and is not here. */
+	async deleteByGroups(groupIds) {
+		return this.deleteForOwnerCounted("group", groupIds);
+	}
 	/**
 	* `TrackScopedStore` contract for the retention cascade: delete all media
 	* owned by the given tracks — the tracks' OWN media (`ownerKind:'track'`) plus
@@ -39898,7 +39992,9 @@ function resolvePackageDropSettings(raw) {
 function planPeriodicMedia(input) {
 	const appendSnapshot = input.dueSnapshot;
 	const lastFrameInterval = input.lastFrameIntervalMs ?? input.intervalMs;
-	const rollingLastFrame = input.saveThumbnails && Math.floor(input.now / lastFrameInterval) > Math.floor(input.lastFrameAt / lastFrameInterval) && !appendSnapshot;
+	const lastFrameElapsed = input.saveThumbnails && Math.floor(input.now / lastFrameInterval) > Math.floor(input.lastFrameAt / lastFrameInterval);
+	const firstFrameLanded = input.firstFrameLanded ?? true;
+	const rollingLastFrame = lastFrameElapsed && !appendSnapshot && firstFrameLanded;
 	const thumbnailLanded = input.thumbnailLanded ?? true;
 	return {
 		appendSnapshot,
@@ -40131,6 +40227,1171 @@ var DeferredBirthRegistry = class {
 		this.byDevice.delete(deviceKey);
 	}
 };
+var AnalyticsGroupRecordSchema = require_dist.object({
+	id: require_dist.string(),
+	deviceId: require_dist.number().int(),
+	openedAt: require_dist.number().int(),
+	closedAt: require_dist.number().int(),
+	timestamp: require_dist.number().int(),
+	memberCount: require_dist.number().int(),
+	memberTrackIds: require_dist.array(require_dist.string()).readonly(),
+	className: require_dist.string(),
+	classes: require_dist.array(require_dist.string()).readonly(),
+	/** Relative event-media path, or null when the group has no picture yet. */
+	mediaUrl: require_dist.string().nullable(),
+	singleton: require_dist.boolean()
+});
+var AnalyticsGroupMemberSchema = require_dist.object({
+	trackId: require_dist.string(),
+	deviceId: require_dist.number().int(),
+	className: require_dist.string(),
+	firstSeen: require_dist.number().int(),
+	lastSeen: require_dist.number().int(),
+	mediaUrl: require_dist.string().nullable()
+});
+var AnalyticsGroupDetailSchema = AnalyticsGroupRecordSchema.extend({ members: require_dist.array(AnalyticsGroupMemberSchema).readonly() });
+var ListGroupsInputSchema = require_dist.object({
+	deviceId: require_dist.number().int().optional(),
+	sinceMs: require_dist.number().int().optional(),
+	untilMs: require_dist.number().int().optional(),
+	limit: require_dist.number().int().min(1).max(100).optional(),
+	offset: require_dist.number().int().min(0).optional()
+});
+var groupActions = require_dist.defineCustomActions({
+	"analytics.listGroups": require_dist.customAction(ListGroupsInputSchema, require_dist.object({
+		groups: require_dist.array(AnalyticsGroupRecordSchema).readonly(),
+		hasMore: require_dist.boolean()
+	})),
+	"analytics.getGroup": require_dist.customAction(require_dist.object({ groupId: require_dist.string().min(1) }), require_dist.object({ group: AnalyticsGroupDetailSchema.nullable() }))
+});
+//#endregion
+//#region src/pipeline-analytics/group/group-query.ts
+/**
+* Stamp a relative event-media URL.
+*
+* Media keys contain `:` and the data-plane serves them by key. Track ids are
+* bare and fall through to the existing event/track thumbnail resolver. Never
+* percent-encode: the handler does not URL-decode the path.
+*/
+function stampEventMediaUrl(baseUrl, id) {
+	if (baseUrl === null || baseUrl.length === 0) return null;
+	if (id === null || id === void 0 || id.length === 0) return null;
+	return `${baseUrl}/${id}`;
+}
+/** Union of every class on the members; `className` is the first, stable order. */
+function aggregateGroupClasses(tracks) {
+	const seen = /* @__PURE__ */ new Set();
+	const classes = [];
+	for (const track of tracks) for (const name of [track.className, ...track.classes ?? []]) {
+		if (name.length === 0 || seen.has(name)) continue;
+		seen.add(name);
+		classes.push(name);
+	}
+	return {
+		className: classes[0] ?? "unknown",
+		classes
+	};
+}
+function toGroupRecord(input) {
+	const { className, classes } = aggregateGroupClasses(input.tracks);
+	const mediaId = input.group.mediaKey ?? (input.group.memberCount === 1 ? input.memberTrackIds[0] : null);
+	return {
+		id: input.group.id,
+		deviceId: input.group.deviceId,
+		openedAt: input.group.openedAt,
+		closedAt: input.group.closedAt,
+		timestamp: input.group.timestamp,
+		memberCount: input.memberTrackIds.length > 0 ? input.memberTrackIds.length : input.group.memberCount,
+		memberTrackIds: [...input.memberTrackIds],
+		className,
+		classes: [...classes],
+		mediaUrl: stampEventMediaUrl(input.eventMediaBaseUrl, mediaId),
+		singleton: input.memberTrackIds.length <= 1
+	};
+}
+function toGroupMember(member, track, eventMediaBaseUrl) {
+	return {
+		trackId: member.trackId,
+		deviceId: member.deviceId,
+		className: track?.className ?? "unknown",
+		firstSeen: track?.firstSeen ?? member.timestamp,
+		lastSeen: track?.lastSeen ?? member.timestamp,
+		mediaUrl: stampEventMediaUrl(eventMediaBaseUrl, member.trackId)
+	};
+}
+function trackToLite(track) {
+	return {
+		trackId: track.trackId,
+		className: track.className,
+		classes: track.classes,
+		firstSeen: track.firstSeen,
+		lastSeen: track.lastSeen
+	};
+}
+async function listGroupRecords(ports, input) {
+	const page = await ports.groupStore.listRecent(input);
+	const groups = [];
+	for (const group of page.groups) groups.push(await buildGroupRecord(ports, group));
+	return {
+		groups,
+		hasMore: page.hasMore
+	};
+}
+async function getGroupDetail(ports, groupId) {
+	const group = await ports.groupStore.get(groupId);
+	if (group === null) return null;
+	const members = await ports.groupStore.listMembers(groupId);
+	const lites = [];
+	const rows = [];
+	for (const member of members) {
+		const track = await ports.loadTrack(member.trackId);
+		const lite = track === null ? null : trackToLite(track);
+		if (lite !== null) lites.push(lite);
+		rows.push(toGroupMember(member, lite, ports.eventMediaBaseUrl()));
+	}
+	return {
+		...toGroupRecord({
+			group,
+			memberTrackIds: members.map((m) => m.trackId),
+			tracks: lites,
+			eventMediaBaseUrl: ports.eventMediaBaseUrl()
+		}),
+		members: rows
+	};
+}
+async function buildGroupRecord(ports, group) {
+	const members = await ports.groupStore.listMembers(group.id);
+	const lites = [];
+	for (const member of members) {
+		const track = await ports.loadTrack(member.trackId);
+		if (track !== null) lites.push(trackToLite(track));
+	}
+	return toGroupRecord({
+		group,
+		memberTrackIds: members.map((m) => m.trackId),
+		tracks: lites,
+		eventMediaBaseUrl: ports.eventMediaBaseUrl()
+	});
+}
+//#endregion
+//#region src/pipeline-analytics/group/group-crop.ts
+/** Always containSubject: true. Never the 0.5 delivered threshold. */
+function groupWideCentralSquareLayout(unionBbox, frame) {
+	return wideCentralSquareLayout(unionBbox, frame, { containSubject: true });
+}
+async function cropGroupFromRgb(rgb, frameWidth, frameHeight, unionBbox) {
+	const layout = groupWideCentralSquareLayout(unionBbox, {
+		W: frameWidth,
+		H: frameHeight
+	});
+	const { crop: slab } = await extractCrop(rgb, frameWidth, frameHeight, layout.fetch);
+	return composeWideCentralSquareThumbnail(slab, layout);
+}
+var MATCH_WINDOW_MS = 1e3;
+var MOVE_EPS = .35;
+/** Registry stationary is out; audio has no bbox and is never a member or a singleton. */
+function isEligibleMember(track) {
+	if (track.closedReason === "stationary-promotion") return false;
+	if (track.className === "audio") return false;
+	return true;
+}
+function temporallyOverlap(a, b, slackMs) {
+	return a.firstSeen <= b.lastSeen + slackMs && b.firstSeen <= a.lastSeen + slackMs;
+}
+/** Connected components of temporal overlap (+ slack) per camera. */
+function sessionsOf(tracks) {
+	const byDevice = /* @__PURE__ */ new Map();
+	for (const t of tracks) {
+		const list = byDevice.get(t.deviceId);
+		if (list) list.push(t);
+		else byDevice.set(t.deviceId, [t]);
+	}
+	const sessions = [];
+	for (const deviceTracks of byDevice.values()) {
+		const n = deviceTracks.length;
+		const parent = deviceTracks.map((_, i) => i);
+		const find = (i) => {
+			let cur = i;
+			while (parent[cur] !== cur) cur = parent[cur];
+			let walk = i;
+			while (parent[walk] !== cur) {
+				const next = parent[walk];
+				parent[walk] = cur;
+				walk = next;
+			}
+			return cur;
+		};
+		const union = (i, j) => {
+			const ri = find(i);
+			const rj = find(j);
+			if (ri !== rj) parent[ri] = rj;
+		};
+		for (let i = 0; i < n; i++) for (let j = i + 1; j < n; j++) if (temporallyOverlap(deviceTracks[i], deviceTracks[j], 3e3)) union(i, j);
+		const buckets = /* @__PURE__ */ new Map();
+		for (let i = 0; i < n; i++) {
+			const root = find(i);
+			const bucket = buckets.get(root);
+			if (bucket) bucket.push(deviceTracks[i]);
+			else buckets.set(root, [deviceTracks[i]]);
+		}
+		sessions.push(...buckets.values());
+	}
+	return sessions;
+}
+function diag(bbox) {
+	return Math.hypot(bbox.w, bbox.h);
+}
+function nearestPosition(positions, t) {
+	let best;
+	let bestDt = 1001;
+	for (const p of positions) {
+		const dt = Math.abs(p.timestamp - t);
+		if (dt <= 1e3 && dt < bestDt) {
+			best = p;
+			bestDt = dt;
+		}
+	}
+	return best;
+}
+function meanDiag(positions) {
+	if (positions.length === 0) return 0;
+	let sum = 0;
+	for (const p of positions) sum += diag(p.bbox);
+	return sum / positions.length;
+}
+function netDisplacement(track) {
+	const first = track.positions[0];
+	const last = track.positions[track.positions.length - 1];
+	if (!first || !last) return {
+		x: 0,
+		y: 0
+	};
+	const a = bboxCentroid(first.bbox);
+	const b = bboxCentroid(last.bbox);
+	return {
+		x: b.x - a.x,
+		y: b.y - a.y
+	};
+}
+function vecLen(v) {
+	return Math.hypot(v.x, v.y);
+}
+function cosine(a, b) {
+	const la = vecLen(a);
+	const lb = vecLen(b);
+	if (la === 0 || lb === 0) return 1;
+	return (a.x * b.x + a.y * b.y) / (la * lb);
+}
+function relativeMotion(track) {
+	const mean = meanDiag(track.positions);
+	if (mean <= 0) return 0;
+	return vecLen(netDisplacement(track)) / mean;
+}
+/** A ~ B iff cohesion ≥ 0.5 AND NOT (both move AND cos < 0.3). */
+function pairTogether(a, b) {
+	const overlapStart = Math.max(a.firstSeen, b.firstSeen);
+	const overlapEnd = Math.min(a.lastSeen, b.lastSeen);
+	if (overlapEnd < overlapStart) return false;
+	let joint = 0;
+	let close = 0;
+	for (let t = overlapStart; t <= overlapEnd; t += 500) {
+		const pa = nearestPosition(a.positions, t);
+		const pb = nearestPosition(b.positions, t);
+		if (!pa || !pb) continue;
+		joint++;
+		const ca = bboxCentroid(pa.bbox);
+		const cb = bboxCentroid(pb.bbox);
+		const gap = Math.hypot(ca.x - cb.x, ca.y - cb.y);
+		const scale = (diag(pa.bbox) + diag(pb.bbox)) / 2;
+		if ((scale > 0 ? gap / scale : Number.POSITIVE_INFINITY) <= 1.5) close++;
+	}
+	if (joint === 0) return false;
+	if (close / joint < .5) return false;
+	const aMoves = relativeMotion(a) >= MOVE_EPS;
+	const bMoves = relativeMotion(b) >= MOVE_EPS;
+	if (aMoves && bMoves && cosine(netDisplacement(a), netDisplacement(b)) < .3) return false;
+	return true;
+}
+function clusterGroups(tracks) {
+	const eligible = tracks.filter(isEligibleMember);
+	const out = [];
+	for (const session of sessionsOf(eligible)) {
+		const pairable = [];
+		for (const t of session) if (t.positions.length < 2) out.push({
+			deviceId: t.deviceId,
+			memberTrackIds: [t.trackId]
+		});
+		else pairable.push(t);
+		if (pairable.length === 0) continue;
+		const parent = pairable.map((_, i) => i);
+		const find = (i) => {
+			let cur = i;
+			while (parent[cur] !== cur) cur = parent[cur];
+			let walk = i;
+			while (parent[walk] !== cur) {
+				const next = parent[walk];
+				parent[walk] = cur;
+				walk = next;
+			}
+			return cur;
+		};
+		const union = (i, j) => {
+			const ri = find(i);
+			const rj = find(j);
+			if (ri !== rj) parent[ri] = rj;
+		};
+		for (let i = 0; i < pairable.length; i++) for (let j = i + 1; j < pairable.length; j++) if (pairTogether(pairable[i], pairable[j])) union(i, j);
+		const buckets = /* @__PURE__ */ new Map();
+		for (let i = 0; i < pairable.length; i++) {
+			const root = find(i);
+			const bucket = buckets.get(root);
+			const id = pairable[i].trackId;
+			if (bucket) bucket.push(id);
+			else buckets.set(root, [id]);
+		}
+		const deviceId = pairable[0].deviceId;
+		for (const memberTrackIds of buckets.values()) out.push({
+			deviceId,
+			memberTrackIds
+		});
+	}
+	return out;
+}
+//#endregion
+//#region src/pipeline-analytics/group/group-instant.ts
+/**
+* Chosen instant + union bbox for a group, at close, over stored positions[]
+* (`docs/design/2026-08-21-group-entity-and-group-media.md` §4.1).
+*
+* Tier order — the first that separates two candidates decides:
+*   1. completeness (members with a position within ±1 s)
+*   2. square containment of the union (D212)
+*   3. semantic (a member's confirmed recognition)
+*   4. edge-clear (union touches no frame border)
+*   5. effective score = mean(confidence) × containment × sizeFactor
+*
+* Retrospective. No new capture path.
+*/
+function nearest(positions, t, windowMs) {
+	let best;
+	let bestDt = windowMs + 1;
+	for (const p of positions) {
+		const dt = Math.abs(p.timestamp - t);
+		if (dt <= windowMs && dt < bestDt) {
+			best = p;
+			bestDt = dt;
+		}
+	}
+	return best;
+}
+function unionOf(boxes) {
+	if (boxes.length === 0) return null;
+	let x0 = Infinity;
+	let y0 = Infinity;
+	let x1 = -Infinity;
+	let y1 = -Infinity;
+	for (const b of boxes) {
+		x0 = Math.min(x0, b.x);
+		y0 = Math.min(y0, b.y);
+		x1 = Math.max(x1, b.x + b.w);
+		y1 = Math.max(y1, b.y + b.h);
+	}
+	return {
+		x: x0,
+		y: y0,
+		w: x1 - x0,
+		h: y1 - y0
+	};
+}
+function touchesBorder(box, frame, tol = 1) {
+	return box.x <= tol || box.y <= tol || box.x + box.w >= frame.width - tol || box.y + box.h >= frame.height - tol;
+}
+function scoreInstant(members, t, frame) {
+	const boxes = [];
+	let semantic = false;
+	let confSum = 0;
+	let confN = 0;
+	for (const m of members) {
+		const p = nearest(m.positions, t, MATCH_WINDOW_MS);
+		if (!p) continue;
+		boxes.push(p.bbox);
+		if (m.semantic === true) semantic = true;
+		if (m.confidence !== void 0) {
+			confSum += m.confidence;
+			confN += 1;
+		}
+	}
+	const union = unionOf(boxes);
+	if (!union) return null;
+	const square = centralSquareContainmentFraction(union, {
+		W: frame.width,
+		H: frame.height
+	});
+	const containment = bboxContainment(union, frame.width, frame.height);
+	const size = bboxSizeScore(union, frame.width, frame.height);
+	const meanConf = confN > 0 ? confSum / confN : 1;
+	return {
+		timestamp: t,
+		union,
+		visibleCount: boxes.length,
+		square,
+		semantic,
+		edgeClear: !touchesBorder(union, frame),
+		effective: meanConf * containment * size
+	};
+}
+function better(a, b) {
+	if (a.visibleCount !== b.visibleCount) return a.visibleCount > b.visibleCount ? a : b;
+	if (a.square !== b.square) return a.square > b.square ? a : b;
+	if (a.semantic !== b.semantic) return a.semantic ? a : b;
+	if (a.edgeClear !== b.edgeClear) return a.edgeClear ? a : b;
+	if (a.effective !== b.effective) return a.effective > b.effective ? a : b;
+	return a.timestamp <= b.timestamp ? a : b;
+}
+function chooseGroupInstant(members, frame) {
+	if (members.length === 0) return null;
+	const candidates = /* @__PURE__ */ new Set();
+	for (const m of members) for (const p of m.positions) candidates.add(p.timestamp);
+	let best = null;
+	for (const t of candidates) {
+		const scored = scoreInstant(members, t, frame);
+		if (!scored) continue;
+		best = best === null ? scored : better(scored, best);
+	}
+	if (!best) return null;
+	const w = Math.max(frame.width, 1);
+	const h = Math.max(frame.height, 1);
+	return {
+		timestamp: best.timestamp,
+		union: best.union,
+		ux: best.union.x / w,
+		uy: best.union.y / h,
+		uw: best.union.w / w,
+		uh: best.union.h / h,
+		visibleCount: best.visibleCount
+	};
+}
+/** Longest-lived member that owns a clean full frame; ties break on trackId. */
+function chooseAnchorTrackId(members, ownsCleanFrame) {
+	const eligible = members.filter((m) => ownsCleanFrame(m.trackId));
+	if (eligible.length === 0) return null;
+	return eligible.toSorted((a, b) => {
+		const life = b.lastSeen - b.firstSeen - (a.lastSeen - a.firstSeen);
+		return life !== 0 ? life : a.trackId.localeCompare(b.trackId);
+	})[0].trackId;
+}
+//#endregion
+//#region src/pipeline-analytics/group/group-session.ts
+/**
+* Session close → sealed groups. A group is born here, never live.
+*
+* Session = temporal chain + 3 s slack, per camera. Close = every overlapping
+* track is persisted AND the newest lastSeen is older than the idle cutoff
+* (the Phase-1 burst's 30 s, reused — not a second clock).
+*
+* Merge and split cannot occur: connected components of a closed session is a
+* partition. Say it out loud so a later live-group attempt does not reach
+* for them here.
+*/
+/** Same idle as the notification burst (`NC_GROUP_DEFAULT_IDLE_SEC`). */
+var GROUP_SESSION_IDLE_MS = 3e4;
+function overlaps(a, b) {
+	return a.firstSeen <= b.lastSeen + 3e3 && b.firstSeen <= a.lastSeen + 3e3;
+}
+function sessionSpan(tracks) {
+	return {
+		firstSeen: Math.min(...tracks.map((t) => t.firstSeen)),
+		lastSeen: Math.max(...tracks.map((t) => t.lastSeen))
+	};
+}
+/**
+* Sessions whose members are all in `closed` and whose newest lastSeen is
+* older than `idleMs`. An overlapping ACTIVE track keeps the session open.
+*/
+function sessionsReadyToSeal(closed, active, now, idleMs = GROUP_SESSION_IDLE_MS) {
+	const byDevice = /* @__PURE__ */ new Map();
+	for (const t of closed) {
+		const list = byDevice.get(t.deviceId);
+		if (list) list.push(t);
+		else byDevice.set(t.deviceId, [t]);
+	}
+	const ready = [];
+	for (const [deviceId, tracks] of byDevice) {
+		const deviceActive = active.filter((a) => a.deviceId === deviceId);
+		for (const session of sessionsOf(tracks)) {
+			const span = sessionSpan(session);
+			if (now < span.lastSeen + idleMs) continue;
+			if (deviceActive.some((a) => overlaps(span, a))) continue;
+			ready.push(session);
+		}
+	}
+	return ready;
+}
+function partitionsForSealedSessions(closed, active, now, idleMs = GROUP_SESSION_IDLE_MS) {
+	return clusterGroups(sessionsReadyToSeal(closed, active, now, idleMs).flat());
+}
+//#endregion
+//#region src/pipeline-analytics/group/group-sealer.ts
+var DEFAULT_FRAME = {
+	width: 640,
+	height: 360
+};
+var SEAL_LOOKBACK_MS = 10 * 6e4;
+var BACKFILL_LOOKBACK_MS = 2880 * 6e4;
+var QUERY_LIMIT = 2e3;
+function toInstant(t) {
+	return {
+		trackId: t.trackId,
+		deviceId: t.deviceId,
+		className: t.className,
+		firstSeen: t.firstSeen,
+		lastSeen: t.lastSeen,
+		positions: t.positions,
+		...t.closedReason !== void 0 ? { closedReason: t.closedReason } : {},
+		semantic: t.hasFace === true || t.hasPlate === true,
+		confidence: t.importance
+	};
+}
+var GroupSealer = class {
+	deps;
+	constructor(deps) {
+		this.deps = deps;
+	}
+	async sealRecent() {
+		const now = this.deps.now();
+		return this.sealSince(now - SEAL_LOOKBACK_MS, now);
+	}
+	async backfill() {
+		const now = this.deps.now();
+		return this.sealSince(now - BACKFILL_LOOKBACK_MS, now);
+	}
+	async sealSince(since, now) {
+		let written = 0;
+		let devices;
+		try {
+			devices = await this.deps.trackStore.listDeviceIds();
+		} catch (err) {
+			this.deps.logger.warn("group sealer: listDeviceIds failed", { meta: { error: String(err) } });
+			return 0;
+		}
+		for (const deviceId of devices) try {
+			written += await this.sealDevice(deviceId, since, now);
+		} catch (err) {
+			this.deps.logger.warn("group sealer: device failed", {
+				tags: { deviceId },
+				meta: { error: String(err) }
+			});
+		}
+		return written;
+	}
+	async sealDevice(deviceId, since, now) {
+		const closed = await this.deps.trackStore.queryHistorical({
+			deviceId,
+			since,
+			until: now,
+			limit: QUERY_LIMIT,
+			projection: "full"
+		});
+		if (closed.length === 0) return 0;
+		const already = new Set((await this.deps.groupStore.membersOfTracks(closed.map((t) => t.trackId))).map((m) => m.trackId));
+		const pending = closed.filter((t) => !already.has(t.trackId));
+		if (pending.length === 0) return 0;
+		const active = this.deps.trackStore.getActive(deviceId).map((t) => ({
+			deviceId,
+			firstSeen: t.firstSeen,
+			lastSeen: t.lastSeen
+		}));
+		const partitions = partitionsForSealedSessions(pending.map(toInstant), active, now, GROUP_SESSION_IDLE_MS);
+		if (partitions.length === 0) {
+			if (pending.filter((t) => t.closedReason !== "stationary-promotion" && t.className !== "audio").length === 0 && pending.length > 0) this.deps.logger.info("group session produced no groups", {
+				tags: { deviceId },
+				meta: {
+					dropped: pending.length,
+					reason: "no-eligible-members"
+				}
+			});
+			return 0;
+		}
+		const byId = new Map(pending.map((t) => [t.trackId, t]));
+		let written = 0;
+		for (const part of partitions) {
+			const members = part.memberTrackIds.map((id) => byId.get(id)).filter((t) => t !== void 0);
+			if (members.length === 0) continue;
+			if (members.every((m) => already.has(m.trackId))) continue;
+			try {
+				await this.persistPartition(members);
+				written += 1;
+			} catch (err) {
+				this.deps.logger.warn("group sealer: persist failed", {
+					tags: { deviceId },
+					meta: {
+						members: members.map((m) => m.trackId),
+						error: String(err)
+					}
+				});
+			}
+		}
+		return written;
+	}
+	async persistPartition(members) {
+		const deviceId = members[0].deviceId;
+		const frame = this.deps.frameDims(deviceId) ?? DEFAULT_FRAME;
+		const instantMembers = members.map(toInstant);
+		const instant = chooseGroupInstant(instantMembers, frame);
+		const openedAt = Math.min(...members.map((m) => m.firstSeen));
+		const closedAt = Math.max(...members.map((m) => m.lastSeen));
+		const timestamp = instant?.timestamp ?? closedAt;
+		const mediaInfos = await Promise.all(members.map(async (m) => ({
+			trackId: m.trackId,
+			rows: await this.deps.mediaStore.listInfoByOwner("track", m.trackId)
+		})));
+		const ownsClean = (trackId) => {
+			return mediaInfos.find((m) => m.trackId === trackId)?.rows.some((r) => r.kind === "keyFrame" || r.kind === "keyFrameSmall") ?? false;
+		};
+		const anchorTrackId = members.length >= 2 ? chooseAnchorTrackId(instantMembers, ownsClean) : null;
+		let nativeKey = null;
+		if (anchorTrackId !== null) {
+			const rows = mediaInfos.find((m) => m.trackId === anchorTrackId)?.rows ?? [];
+			nativeKey = (rows.find((r) => r.kind === "keyFrame") ?? rows.find((r) => r.kind === "keyFrameSmall"))?.key ?? null;
+		}
+		const draft = await this.deps.groupStore.insert({
+			deviceId,
+			timestamp,
+			openedAt,
+			closedAt,
+			members: members.map((m) => ({
+				trackId: m.trackId,
+				firstSeen: m.firstSeen
+			})),
+			anchorTrackId,
+			ux: instant?.ux ?? 0,
+			uy: instant?.uy ?? 0,
+			uw: instant?.uw ?? 0,
+			uh: instant?.uh ?? 0,
+			frameWidth: frame.width,
+			frameHeight: frame.height,
+			mediaKey: null,
+			nativeKey
+		});
+		if (members.length < 2 || instant === null) return;
+		const source = await this.pickCleanPixels(mediaInfos, timestamp);
+		if (source === null) return;
+		try {
+			const raw = await (0, sharp.default)(source.jpeg).removeAlpha().raw().toBuffer({ resolveWithObject: true });
+			if (raw.info.channels !== 3) return;
+			const union = {
+				x: instant.ux * raw.info.width,
+				y: instant.uy * raw.info.height,
+				w: instant.uw * raw.info.width,
+				h: instant.uh * raw.info.height
+			};
+			const crop = await cropGroupFromRgb(raw.data, raw.info.width, raw.info.height, union);
+			const mediaKey = await this.deps.mediaStore.put({
+				deviceId,
+				ownerKind: "group",
+				ownerId: draft.id,
+				kind: "thumbnail",
+				timestamp,
+				data: crop
+			});
+			await this.deps.groupStore.setMediaKey(draft.id, mediaKey);
+		} catch (err) {
+			this.deps.logger.warn("group sealer: crop failed", {
+				tags: { deviceId },
+				meta: {
+					groupId: draft.id,
+					error: String(err)
+				}
+			});
+		}
+	}
+	async pickCleanPixels(mediaInfos, instantMs) {
+		const candidates = [];
+		for (const info of mediaInfos) for (const row of info.rows) {
+			const rank = row.kind === "keyFrame" ? 0 : row.kind === "keyFrameSmall" ? 1 : -1;
+			if (rank < 0) continue;
+			const dt = Math.abs(row.timestamp - instantMs);
+			if (dt > 2e3) continue;
+			candidates.push({
+				key: row.key,
+				dt,
+				rank
+			});
+		}
+		const chosen = candidates.toSorted((a, b) => a.rank - b.rank || a.dt - b.dt)[0];
+		if (chosen === void 0) return null;
+		const file = await this.deps.mediaStore.getByKey(chosen.key);
+		if (file === null) return null;
+		return { jpeg: Buffer.from(file.base64, "base64") };
+	}
+};
+//#endregion
+//#region src/pipeline-analytics/group/group-store.ts
+/**
+* The group ENTITY store — a co-moving partition of one session, with one
+* picture of its own (`docs/design/2026-08-21-group-entity-and-group-media.md`).
+*
+* Two tables, two questions:
+*
+* - `pipeline-analytics:track-groups` is the group row. It has N members and
+*   no `trackId` column; it is owned by its members (owner-indirection).
+* - `pipeline-analytics:track-group-members` is one row per member. The column
+*   is named exactly `trackId` so the classification derives `track-owned`.
+*
+* `anchorTrackId` and `nativeKey` are the only fields mutable after birth:
+* they are nulled when the anchor member is deleted alone. Everything else is
+* written once. Re-anchoring is deliberately not done.
+*
+* No age clock. A group dies when its last member does; a group with one live
+* member does not, and it never keeps a dead link.
+*/
+/**
+* @durable class=ledger owner=pipeline-analytics
+*   write="one row per co-moving group at session close — sealed, never live.
+*     Membership is a partition of one camera's eligible tracks. mediaKey is
+*     the group's own crop; nativeKey is a POINTER to the anchor member's
+*     keyFrame, nulled if that member is deleted alone. anchorTrackId and
+*     nativeKey are the only fields rewritten after birth."
+*   retention="NO age clock (D61). Rows leave with their last member through
+*     TrackGroupStore.deleteByTracks: memberships first; zero survivors
+*     deletes the group's media then the row; survivors plus a lost anchor
+*     null the pointer. The orphan audit verifies the same via a second
+*     resolver (groupId → any member still present)."
+*/
+var TRACK_GROUPS_COLLECTION = "pipeline-analytics:track-groups";
+/**
+* @durable class=ledger owner=pipeline-analytics
+*   write="one row per member at group birth — id is '<groupId>:<trackId>'.
+*     timestamp is the member's firstSeen so the orphan audit has a clock
+*     column. Never rewritten."
+*   retention="TRACK-OWNED and clockless (D61): the column is named exactly
+*     trackId, so classification derives ownership and the cascade deletes
+*     the row with its track. A group with surviving members stays."
+*/
+var TRACK_GROUP_MEMBERS_COLLECTION = "pipeline-analytics:track-group-members";
+var TRACK_GROUPS_COLUMNS = [
+	{
+		name: "id",
+		type: "TEXT",
+		primaryKey: true,
+		notNull: true
+	},
+	{
+		name: "deviceId",
+		type: "INTEGER",
+		notNull: true
+	},
+	{
+		name: "timestamp",
+		type: "INTEGER",
+		notNull: true
+	},
+	{
+		name: "openedAt",
+		type: "INTEGER",
+		notNull: true
+	},
+	{
+		name: "closedAt",
+		type: "INTEGER",
+		notNull: true
+	},
+	{
+		name: "memberCount",
+		type: "INTEGER",
+		notNull: true
+	},
+	{
+		name: "anchorTrackId",
+		type: "TEXT"
+	},
+	{
+		name: "ux",
+		type: "REAL",
+		notNull: true
+	},
+	{
+		name: "uy",
+		type: "REAL",
+		notNull: true
+	},
+	{
+		name: "uw",
+		type: "REAL",
+		notNull: true
+	},
+	{
+		name: "uh",
+		type: "REAL",
+		notNull: true
+	},
+	{
+		name: "frameWidth",
+		type: "INTEGER",
+		notNull: true
+	},
+	{
+		name: "frameHeight",
+		type: "INTEGER",
+		notNull: true
+	},
+	{
+		name: "mediaKey",
+		type: "TEXT"
+	},
+	{
+		name: "nativeKey",
+		type: "TEXT"
+	},
+	{
+		name: "sealed",
+		type: "BOOLEAN",
+		notNull: true
+	}
+];
+var TRACK_GROUP_MEMBERS_COLUMNS = [
+	{
+		name: "id",
+		type: "TEXT",
+		primaryKey: true,
+		notNull: true
+	},
+	{
+		name: "groupId",
+		type: "TEXT",
+		notNull: true
+	},
+	{
+		name: "trackId",
+		type: "TEXT",
+		notNull: true
+	},
+	{
+		name: "deviceId",
+		type: "INTEGER",
+		notNull: true
+	},
+	{
+		name: "timestamp",
+		type: "INTEGER",
+		notNull: true
+	}
+];
+var TRACK_GROUPS_INDEXES = [{
+	name: "idx_track_groups_device_closed",
+	columns: ["deviceId", "closedAt"]
+}, {
+	name: "idx_track_groups_device_opened",
+	columns: ["deviceId", "openedAt"]
+}];
+var TRACK_GROUP_MEMBERS_INDEXES = [{
+	name: "idx_track_group_members_track",
+	columns: ["trackId"]
+}, {
+	name: "idx_track_group_members_group",
+	columns: ["groupId"]
+}];
+function newGroupId() {
+	return `grp-${(0, node_crypto.randomUUID)()}`;
+}
+function memberRowId(groupId, trackId) {
+	return `${groupId}:${trackId}`;
+}
+var TrackGroupStore = class {
+	store;
+	logger;
+	media;
+	constructor(deps) {
+		this.store = deps.store;
+		this.logger = deps.logger;
+		this.media = deps.media ?? null;
+	}
+	static async declare(store) {
+		await Promise.all([store.declareCollection.mutate({
+			collection: TRACK_GROUPS_COLLECTION,
+			columns: [...TRACK_GROUPS_COLUMNS],
+			indexes: [...TRACK_GROUPS_INDEXES]
+		}), store.declareCollection.mutate({
+			collection: TRACK_GROUP_MEMBERS_COLLECTION,
+			columns: [...TRACK_GROUP_MEMBERS_COLUMNS],
+			indexes: [...TRACK_GROUP_MEMBERS_INDEXES]
+		})]);
+	}
+	async insert(input) {
+		const id = newGroupId();
+		const group = {
+			id,
+			deviceId: input.deviceId,
+			timestamp: input.timestamp,
+			openedAt: input.openedAt,
+			closedAt: input.closedAt,
+			memberCount: input.members.length,
+			anchorTrackId: input.anchorTrackId,
+			ux: input.ux,
+			uy: input.uy,
+			uw: input.uw,
+			uh: input.uh,
+			frameWidth: input.frameWidth,
+			frameHeight: input.frameHeight,
+			mediaKey: input.mediaKey,
+			nativeKey: input.nativeKey,
+			sealed: true
+		};
+		await this.store.set.mutate({
+			collection: TRACK_GROUPS_COLLECTION,
+			key: id,
+			value: this.toRow(group)
+		});
+		for (const member of input.members) await this.store.set.mutate({
+			collection: TRACK_GROUP_MEMBERS_COLLECTION,
+			key: memberRowId(id, member.trackId),
+			value: {
+				groupId: id,
+				trackId: member.trackId,
+				deviceId: input.deviceId,
+				timestamp: member.firstSeen
+			}
+		});
+		return group;
+	}
+	/** The crop is written after birth; this is the only post-birth write besides the pointer null. */
+	async setMediaKey(groupId, mediaKey) {
+		const current = await this.get(groupId);
+		if (current === null) return;
+		await this.store.set.mutate({
+			collection: TRACK_GROUPS_COLLECTION,
+			key: groupId,
+			value: this.toRow({
+				...current,
+				mediaKey
+			})
+		});
+	}
+	async get(groupId) {
+		const raw = await this.store.get.query({
+			collection: TRACK_GROUPS_COLLECTION,
+			key: groupId
+		});
+		if (!raw) return null;
+		return this.normalizeGroup({
+			id: groupId,
+			data: raw
+		});
+	}
+	async listMembers(groupId) {
+		return (await this.store.query.query({
+			collection: TRACK_GROUP_MEMBERS_COLLECTION,
+			filter: { where: { groupId } }
+		})).map((r) => this.normalizeMember({
+			id: r.id,
+			data: r.data
+		}));
+	}
+	async membersOfTracks(trackIds) {
+		const out = [];
+		for (const trackId of trackIds) {
+			const rows = await this.store.query.query({
+				collection: TRACK_GROUP_MEMBERS_COLLECTION,
+				filter: { where: { trackId } }
+			});
+			for (const r of rows) out.push(this.normalizeMember({
+				id: r.id,
+				data: r.data
+			}));
+		}
+		return out;
+	}
+	/**
+	* Newest-closed page for the Library Groups tab.
+	*
+	* Time filter is overlap (`closedAt >= since` and `openedAt <= until`),
+	* same as {@link listOverlapping}. Pagination is applied AFTER the window
+	* so a day cursor is honest rather than a raw-row offset that skips live
+	* groups on a busy camera.
+	*/
+	async listRecent(input) {
+		const limit = Math.min(Math.max(input.limit ?? 40, 1), 100);
+		const offset = Math.max(input.offset ?? 0, 0);
+		const slice = (await this.store.query.query({
+			collection: TRACK_GROUPS_COLLECTION,
+			filter: {
+				...input.deviceId !== void 0 ? { where: { deviceId: input.deviceId } } : {},
+				orderBy: {
+					field: "closedAt",
+					direction: "desc"
+				},
+				limit: 2e3
+			}
+		})).map((r) => this.normalizeGroup({
+			id: r.id,
+			data: r.data
+		})).filter((g) => {
+			if (input.sinceMs !== void 0 && g.closedAt < input.sinceMs) return false;
+			if (input.untilMs !== void 0 && g.openedAt > input.untilMs) return false;
+			return true;
+		}).slice(offset, offset + limit + 1);
+		return {
+			groups: slice.slice(0, limit),
+			hasMore: slice.length > limit
+		};
+	}
+	/** Groups whose life overlaps `[since, until]` on one camera. */
+	async listOverlapping(input) {
+		return (await this.store.query.query({
+			collection: TRACK_GROUPS_COLLECTION,
+			filter: {
+				where: { deviceId: input.deviceId },
+				orderBy: {
+					field: "closedAt",
+					direction: "desc"
+				},
+				limit: input.limit ?? 2e3
+			}
+		})).map((r) => this.normalizeGroup({
+			id: r.id,
+			data: r.data
+		})).filter((g) => g.closedAt >= input.sinceMs && g.openedAt <= input.untilMs);
+	}
+	async existingGroupIds(ids) {
+		const live = /* @__PURE__ */ new Set();
+		for (const id of ids) if (await this.store.get.query({
+			collection: "pipeline-analytics:track-groups",
+			key: id
+		})) live.add(id);
+		return live;
+	}
+	/** Group ids that still have at least one membership row. */
+	async groupsWithMembers(ids) {
+		const live = /* @__PURE__ */ new Set();
+		for (const groupId of ids) if ((await this.store.query.query({
+			collection: "pipeline-analytics:track-group-members",
+			filter: {
+				where: { groupId },
+				limit: 1
+			}
+		})).length > 0) live.add(groupId);
+		return live;
+	}
+	/**
+	* Cascade leaf: delete memberships for the batch; a group with zero survivors
+	* dies (media then row); a group that lost only its anchor nulls the pointer.
+	*/
+	async deleteByTracks(trackIds) {
+		const batch = new Set(trackIds);
+		let memberRows = 0;
+		let groupRows = 0;
+		let mediaRows = 0;
+		let mediaBytes = 0;
+		const affected = /* @__PURE__ */ new Set();
+		try {
+			const memberships = await this.membersOfTracks(trackIds);
+			for (const member of memberships) try {
+				await this.store.delete.mutate({
+					collection: TRACK_GROUP_MEMBERS_COLLECTION,
+					key: member.id
+				});
+				memberRows += 1;
+				affected.add(member.groupId);
+			} catch (err) {
+				this.logger.warn("TrackGroupStore.deleteByTracks member delete failed", { meta: {
+					memberId: member.id,
+					error: String(err)
+				} });
+			}
+			for (const groupId of affected) try {
+				if ((await this.listMembers(groupId)).length === 0) {
+					if (this.media) {
+						const gone = await this.media.deleteByGroups([groupId]);
+						mediaRows += gone.rows;
+						mediaBytes += gone.bytes;
+					}
+					await this.store.delete.mutate({
+						collection: TRACK_GROUPS_COLLECTION,
+						key: groupId
+					});
+					groupRows += 1;
+					continue;
+				}
+				const group = await this.get(groupId);
+				if (group?.anchorTrackId && batch.has(group.anchorTrackId)) await this.store.set.mutate({
+					collection: TRACK_GROUPS_COLLECTION,
+					key: groupId,
+					value: this.toRow({
+						...group,
+						anchorTrackId: null,
+						nativeKey: null
+					})
+				});
+			} catch (err) {
+				this.logger.warn("TrackGroupStore.deleteByTracks group update failed", { meta: {
+					groupId,
+					error: String(err)
+				} });
+			}
+		} catch (err) {
+			this.logger.warn("TrackGroupStore.deleteByTracks failed", { meta: { error: String(err) } });
+		}
+		return [{
+			family: "groups",
+			rows: memberRows + groupRows,
+			bytes: 0
+		}, {
+			family: "media",
+			rows: mediaRows,
+			bytes: mediaBytes
+		}];
+	}
+	toRow(group) {
+		return {
+			deviceId: group.deviceId,
+			timestamp: group.timestamp,
+			openedAt: group.openedAt,
+			closedAt: group.closedAt,
+			memberCount: group.memberCount,
+			anchorTrackId: group.anchorTrackId,
+			ux: group.ux,
+			uy: group.uy,
+			uw: group.uw,
+			uh: group.uh,
+			frameWidth: group.frameWidth,
+			frameHeight: group.frameHeight,
+			mediaKey: group.mediaKey,
+			nativeKey: group.nativeKey,
+			sealed: group.sealed
+		};
+	}
+	normalizeGroup(r) {
+		const data = r.data;
+		return {
+			id: r.id,
+			deviceId: Number(data["deviceId"]),
+			timestamp: Number(data["timestamp"]),
+			openedAt: Number(data["openedAt"]),
+			closedAt: Number(data["closedAt"]),
+			memberCount: Number(data["memberCount"]),
+			anchorTrackId: typeof data["anchorTrackId"] === "string" ? data["anchorTrackId"] : null,
+			ux: Number(data["ux"]),
+			uy: Number(data["uy"]),
+			uw: Number(data["uw"]),
+			uh: Number(data["uh"]),
+			frameWidth: Number(data["frameWidth"]),
+			frameHeight: Number(data["frameHeight"]),
+			mediaKey: typeof data["mediaKey"] === "string" ? data["mediaKey"] : null,
+			nativeKey: typeof data["nativeKey"] === "string" ? data["nativeKey"] : null,
+			sealed: Boolean(data["sealed"])
+		};
+	}
+	normalizeMember(r) {
+		const data = r.data;
+		return {
+			id: r.id,
+			groupId: String(data["groupId"]),
+			trackId: String(data["trackId"]),
+			deviceId: Number(data["deviceId"]),
+			timestamp: Number(data["timestamp"])
+		};
+	}
+};
 //#endregion
 //#region src/pipeline-analytics/pipeline/dropout-skip.ts
 function shouldSkipDropoutFrame(activeTrackCount, detectionCount, consecutiveSkips, cfg) {
@@ -46748,6 +48009,15 @@ function isAfterCursor(row, cursor) {
 	if (row.lastSeen < cursor.lastSeen) return true;
 	return row.lastSeen === cursor.lastSeen && row.id < cursor.trackId;
 }
+function netDisplacementPx(positions) {
+	const first = positions[0];
+	const last = positions[positions.length - 1];
+	if (!first || !last) return 0;
+	return Math.hypot(last.x - first.x, last.y - first.y);
+}
+function isShortMotionlessTrack(lifeMs, movedPx) {
+	return lifeMs <= 25e3 && movedPx <= 8;
+}
 //#endregion
 //#region src/pipeline-analytics/store/track-store.ts
 /**
@@ -47330,6 +48600,7 @@ var TrackStore = class {
 		for (const [trackId, t] of this.active) {
 			if (nowMs - t.lastSeen < this.config.ttlMs) continue;
 			t.active = false;
+			if (t.positions.length > 0 && isShortMotionlessTrack(t.lastSeen - t.firstSeen, netDisplacementPx(t.positions))) t.closedReason = "stationary-promotion";
 			const record = cloneTrack(t);
 			try {
 				await this.persistCompleted(record);
@@ -48878,12 +50149,24 @@ var ANALYTICS_COLLECTIONS = [
 		collection: PLATES_COLLECTION,
 		classification: derived(PLATE_COLUMNS)
 	},
+	{
+		collection: TRACK_GROUP_MEMBERS_COLLECTION,
+		classification: derived(TRACK_GROUP_MEMBERS_COLUMNS)
+	},
 	{
 		collection: MEDIA_COLLECTION,
 		classification: {
 			kind: "owner-indirection",
 			derivation: "explicit",
-			why: "(ownerKind, ownerId) means a different entity per kind — a trackId for 'track', a PREFIXED trackId for 'face'/'plate', an eventId for 'event', and an enrolled gallery row for 'identity'/'vehicle' that retention must never touch. The mapping is `resolveMediaOwner` in orphan-audit.ts."
+			why: "(ownerKind, ownerId) means a different entity per kind — a trackId for 'track', a PREFIXED trackId for 'face'/'plate', an eventId for 'event', a groupId for 'group', and an enrolled gallery row for 'identity'/'vehicle' that retention must never touch. The mapping is `resolveMediaOwner` in orphan-audit.ts."
+		}
+	},
+	{
+		collection: TRACK_GROUPS_COLLECTION,
+		classification: {
+			kind: "owner-indirection",
+			derivation: "explicit",
+			why: "a group has N members and no trackId column; it is owned by its membership rows. The mapping is `resolveGroupOwner` in orphan-audit.ts (groupId → any member still present). Do not classify never-orphaned — that would make the last-member guarantee unverifiable."
 		}
 	},
 	{
@@ -48995,7 +50278,7 @@ var ANALYTICS_COLLECTIONS = [
 		collection: SCENE_LATCH_COLLECTION,
 		classification: {
 			kind: "never-orphaned",
-			why: "it IS owned — by the scene set — but the owner-cleanup is self-contained: `pruneExcept(the scene set)` runs on every scene reload, so a latch whose scene is gone is collected there and never by retention. Deliberately NOT `owner-indirection`: that kind puts a collection into `auditableCollections()`, and the orphan audit resolves exactly one indirection, that of `pipeline-analytics:media`."
+			why: "it IS owned — by the scene set — but the owner-cleanup is self-contained: `pruneExcept(the scene set)` runs on every scene reload, so a latch whose scene is gone is collected there and never by retention. Deliberately NOT `owner-indirection`: that kind puts a collection into `auditableCollections()`, and the orphan audit resolves only the indirections it has a resolver for (`pipeline-analytics:media` and `pipeline-analytics:track-groups`)."
 		}
 	},
 	{
@@ -49083,6 +50366,10 @@ function resolveMediaOwner(row) {
 			kind: "unresolvable",
 			why: `plate-owned media whose ownerId does not carry the '${PLATE_MEDIA_OWNER_PREFIX}' prefix`
 		};
+		case "group": return {
+			kind: "group",
+			groupId: ownerId
+		};
 		default: return {
 			kind: "unresolvable",
 			why: `unknown ownerKind '${kindRaw}'`
@@ -49094,6 +50381,13 @@ function resolveMediaOwner(row) {
 * is derived the same way the classification is — an enrolled row is out of
 * reach regardless of what happened to the track that produced it.
 */
+/** A group row lives iff any membership row still names it. */
+function resolveGroupOwner(row) {
+	return {
+		kind: "group-members",
+		groupId: row.key
+	};
+}
 function resolveDeclaredTrackOwner(row, enrolmentExempt) {
 	if (enrolmentExempt && row.data["assigned"] === true) return {
 		kind: "exempt",
@@ -49113,15 +50407,28 @@ function buildOrphanScopes(collections = auditableCollections()) {
 	const scopes = [];
 	for (const entry of collections) {
 		if (entry.classification.kind === "owner-indirection") {
-			if (entry.collection !== "pipeline-analytics:media") continue;
-			scopes.push({
-				id: entry.collection,
-				collection: entry.collection,
-				resolve: resolveMediaOwner,
-				timestampField: "timestamp",
-				sizeField: "sizeBytes",
-				deviceIdField: "deviceId"
-			});
+			if (entry.collection === "pipeline-analytics:media") {
+				scopes.push({
+					id: entry.collection,
+					collection: entry.collection,
+					resolve: resolveMediaOwner,
+					timestampField: "timestamp",
+					sizeField: "sizeBytes",
+					deviceIdField: "deviceId"
+				});
+				continue;
+			}
+			if (entry.collection === "pipeline-analytics:track-groups") {
+				scopes.push({
+					id: entry.collection,
+					collection: entry.collection,
+					resolve: resolveGroupOwner,
+					timestampField: "timestamp",
+					sizeField: null,
+					deviceIdField: "deviceId"
+				});
+				continue;
+			}
 			continue;
 		}
 		if (entry.classification.kind !== "track-owned") continue;
@@ -49153,11 +50460,17 @@ var DEFAULT_ORPHAN_LIMITS = {
 function questionsFor(refs) {
 	const trackIds = /* @__PURE__ */ new Set();
 	const eventIds = /* @__PURE__ */ new Set();
+	const groupIds = /* @__PURE__ */ new Set();
+	const groupMemberIds = /* @__PURE__ */ new Set();
 	for (const ref of refs) if (ref.kind === "track") trackIds.add(ref.trackId);
 	else if (ref.kind === "event") eventIds.add(ref.eventId);
+	else if (ref.kind === "group") groupIds.add(ref.groupId);
+	else if (ref.kind === "group-members") groupMemberIds.add(ref.groupId);
 	return {
 		trackIds: [...trackIds],
-		eventIds: [...eventIds]
+		eventIds: [...eventIds],
+		groupIds: [...groupIds],
+		groupMemberIds: [...groupMemberIds]
 	};
 }
 /**
@@ -49189,12 +50502,16 @@ async function auditScope(scope, deps, limits, cursor) {
 			break;
 		}
 		const refs = rows.map((row) => scope.resolve(row));
-		const { trackIds, eventIds } = questionsFor(refs);
+		const { trackIds, eventIds, groupIds, groupMemberIds } = questionsFor(refs);
 		let liveTracks;
 		let liveEvents;
+		let liveGroups;
+		let liveGroupsWithMembers;
 		try {
 			liveTracks = trackIds.length > 0 ? await deps.liveTrackIds(trackIds) : /* @__PURE__ */ new Set();
 			liveEvents = eventIds.length > 0 ? await deps.liveEventIds(eventIds) : /* @__PURE__ */ new Set();
+			liveGroups = groupIds.length > 0 && deps.liveGroupIds ? await deps.liveGroupIds(groupIds) : /* @__PURE__ */ new Set();
+			liveGroupsWithMembers = groupMemberIds.length > 0 && deps.liveGroupsWithMembers ? await deps.liveGroupsWithMembers(groupMemberIds) : /* @__PURE__ */ new Set();
 		} catch (err) {
 			deps.logger.warn("orphan audit: liveness probe failed — scope abandoned for this run", { meta: {
 				collection: scope.collection,
@@ -49218,7 +50535,7 @@ async function auditScope(scope, deps, limits, cursor) {
 				tally.unresolvable += 1;
 				continue;
 			}
-			if (ref.kind === "track" ? liveTracks.has(ref.trackId) : liveEvents.has(ref.eventId)) continue;
+			if (ref.kind === "track" ? liveTracks.has(ref.trackId) : ref.kind === "event" ? liveEvents.has(ref.eventId) : ref.kind === "group" ? liveGroups.has(ref.groupId) : liveGroupsWithMembers.has(ref.groupId)) continue;
 			const ts = num(row.data, scope.timestampField);
 			if (ts !== null && ts > graceFloor) {
 				tally.withinGrace += 1;
@@ -51310,6 +52627,13 @@ function squareSafeCropRegionNormalized(bbox, frame, padding) {
 	};
 }
 //#endregion
+//#region src/pipeline-analytics/pipeline/usable-bbox.ts
+/** A box that can legally drive a crop. The leaving-event fallback
+*  `{0,0,0,0}` must never become a face/plate JPEG. */
+function isUsableBbox(bbox) {
+	return bbox.w > 0 && bbox.h > 0;
+}
+//#endregion
 //#region src/pipeline-analytics/services/event-media-dispatcher.ts
 /**
 * Long-side cap (px) for the boxed timeline tiles — `firstFrame`, `snapshot`,
@@ -51888,26 +53212,29 @@ var EventMediaDispatcher = class {
 		}
 	}
 	async writeEventMedia(deviceId, frameHandle, frameData, fw, fh, ev, cropPadding) {
-		if (ev.childCrops) for (const child of ev.childCrops) try {
-			const childCropData = await this.cropSubjectRegion(deviceId, frameHandle, frameData, fw, fh, child.bbox, cropPadding, `${ev.eventId}:${child.kind}`);
-			if (!childCropData) continue;
-			await this.deps.mediaStore.put({
-				deviceId,
-				ownerKind: "event",
-				ownerId: ev.eventId,
-				kind: child.kind,
-				timestamp: ev.timestamp,
-				data: childCropData
-			});
-		} catch (err) {
-			this.deps.logger.warn(`event media: ${child.kind} failed`, {
-				tags: { deviceId },
-				meta: {
+		if (ev.childCrops) for (const child of ev.childCrops) {
+			if (!isUsableBbox(child.bbox)) continue;
+			try {
+				const childCropData = await this.cropSubjectRegion(deviceId, frameHandle, frameData, fw, fh, child.bbox, cropPadding, `${ev.eventId}:${child.kind}`);
+				if (!childCropData) continue;
+				await this.deps.mediaStore.put({
 					deviceId,
-					eventId: ev.eventId,
-					error: err instanceof Error ? err.message : String(err)
-				}
-			});
+					ownerKind: "event",
+					ownerId: ev.eventId,
+					kind: child.kind,
+					timestamp: ev.timestamp,
+					data: childCropData
+				});
+			} catch (err) {
+				this.deps.logger.warn(`event media: ${child.kind} failed`, {
+					tags: { deviceId },
+					meta: {
+						deviceId,
+						eventId: ev.eventId,
+						error: err instanceof Error ? err.message : String(err)
+					}
+				});
+			}
 		}
 	}
 	async writeTrackFrame(deviceId, frameHandle, frameData, fw, fh, tf) {
@@ -55168,7 +56495,8 @@ var customActions = {
 	...orphanAuditActions,
 	...viewerSettingsActions,
 	...photoEnrollActions,
-	...faceRescoreActions
+	...faceRescoreActions,
+	...groupActions
 };
 /**
 * Assist threshold when the caller does not pin one. Packages have their own
@@ -55347,11 +56675,6 @@ function decodeEmbeddingBase64(base64) {
 	const view = new Float32Array(bytes.buffer, bytes.byteOffset, Math.floor(bytes.byteLength / 4));
 	return Array.from(view);
 }
-/** A track shorter than this is a candidate phantom, not a subject that came
-*  and went. Brackets the observed plant tracks (3.8-19.0 s). */
-var SHORT_TRACK_MAX_MS = 25e3;
-/** Total displacement under this is "did not move at all" (observed: 0-2.5 px). */
-var MOTIONLESS_MAX_PX = 8;
 /** Grid the spawn point is quantised to, so respawns whose boxes never repeat
 *  to the pixel still land in one cell. */
 var PHANTOM_CELL_PX = 32;
@@ -55415,6 +56738,8 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_dist.B
 	faceStore = null;
 	faceRecognizer = null;
 	plateStore = null;
+	groupStore = null;
+	groupSealer = null;
 	plateRecognizer = null;
 	objectEmbeddingStore = null;
 	/** Live state of the detached embedding rebuild — see `rebuildObjectEmbeddings`. */
@@ -56232,7 +57557,8 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_dist.B
 					...orphanAuditActions,
 					...viewerSettingsActions,
 					...photoEnrollActions,
-					...faceRescoreActions
+					...faceRescoreActions,
+					...groupActions
 				},
 				actionHandlers: {
 					...ncHandlers,
@@ -56240,6 +57566,7 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_dist.B
 					...this.buildDebugActionHandlers(),
 					...this.buildPhotoEnrollActionHandlers(),
 					...this.buildFaceRescoreActionHandlers(),
+					...this.buildGroupActionHandlers(),
 					...this.viewerSettingsSnapshots ? makeViewerSettingsActionHandlers(this.viewerSettingsSnapshots) : {}
 				}
 			} : {}
@@ -56442,6 +57769,7 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_dist.B
 			SceneStore.declare(api.settingsStore),
 			NotificationCenter.declare(api.settingsStore),
 			ViewerSettingsSnapshotStore.declare(api.settingsStore),
+			TrackGroupStore.declare(api.settingsStore),
 			declareMigrationMarkers(api.settingsStore)
 		]);
 		this.viewerSettingsSnapshots = new ViewerSettingsSnapshotStore(api.settingsStore);
@@ -56726,6 +58054,33 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_dist.B
 			logger: logger.child("PlateStore")
 		});
 		this.plateStore = plateStore;
+		const vehicleStore = new VehicleStore({
+			store: api.settingsStore,
+			logger: logger.child("VehicleStore")
+		});
+		const groupStore = new TrackGroupStore({
+			store: api.settingsStore,
+			logger: logger.child("TrackGroupStore"),
+			media: mediaStore
+		});
+		this.groupStore = groupStore;
+		this.groupSealer = new GroupSealer({
+			trackStore,
+			groupStore,
+			mediaStore,
+			logger: logger.child("GroupSealer"),
+			frameDims: (deviceId) => {
+				const dims = this.lastFrameDimsByDevice.get(deviceId);
+				return dims ? {
+					width: dims.w,
+					height: dims.h
+				} : void 0;
+			},
+			now: () => Date.now()
+		});
+		this.groupSealer.backfill().catch((err) => {
+			logger.warn("group sealer backfill failed", { meta: { error: require_dist.errMsg(err) } });
+		});
 		return {
 			trackStore,
 			mediaStore,
@@ -56733,10 +58088,8 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_dist.B
 			identityStore,
 			faceStore,
 			plateStore,
-			vehicleStore: new VehicleStore({
-				store: api.settingsStore,
-				logger: logger.child("VehicleStore")
-			})
+			vehicleStore,
+			groupStore
 		};
 	}
 	/** Face + plate recognizers, the durable keyFrame-derived plate crop and the
@@ -57170,29 +58523,65 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_dist.B
 	buildSummaryPorts(stores) {
 		return {
 			listTracks: async ({ deviceId, sinceMs, untilMs, limit }) => {
-				const tracks = await stores.trackStore.queryHistorical({
+				const groups = await stores.groupStore.listOverlapping({
+					deviceId,
+					sinceMs,
+					untilMs,
+					limit
+				});
+				const windowTracks = await stores.trackStore.queryHistorical({
 					deviceId,
 					since: sinceMs,
 					until: untilMs,
 					projection: "slim",
-					limit
+					limit: Math.max(limit, 2e3)
 				});
+				const trackById = new Map(windowTracks.map((t) => [t.trackId, t]));
 				const { minHits } = await this.resolveDeviceDetectionSensitivitySettings(deviceId);
-				return tracks.map((t) => ({
-					trackId: t.trackId,
-					deviceId: t.deviceId,
-					className: t.className,
-					firstSeen: t.firstSeen,
-					lastSeen: t.lastSeen,
-					...t.importance !== void 0 ? { importance: t.importance } : {},
-					zones: [...t.zonesVisited],
-					...t.classes !== void 0 ? { classes: [...t.classes] } : {},
-					...t.closedReason === "stationary-promotion" ? { stationary: true } : {},
-					...t.observations !== void 0 ? { confirmed: t.observations >= minHits } : {}
-				}));
+				const out = [];
+				for (const group of groups) {
+					const members = await stores.groupStore.listMembers(group.id);
+					const tracks = members.map((m) => trackById.get(m.trackId)).filter((t) => t !== void 0);
+					if (tracks.length === 0) continue;
+					const classes = [...new Set(tracks.flatMap((t) => [t.className, ...t.classes ?? []]))];
+					const zones = [...new Set(tracks.flatMap((t) => [...t.zonesVisited]))];
+					const importance = Math.max(0, ...tracks.map((t) => t.importance ?? 0));
+					const primary = tracks.reduce((best, t) => (t.importance ?? 0) > (best.importance ?? 0) ? t : best);
+					out.push({
+						trackId: group.id,
+						groupId: group.id,
+						memberTrackIds: members.map((m) => m.trackId),
+						deviceId,
+						className: primary.className,
+						firstSeen: group.openedAt,
+						lastSeen: group.closedAt,
+						importance,
+						zones,
+						classes,
+						...tracks.every((t) => t.closedReason === "stationary-promotion") ? { stationary: true } : {},
+						confirmed: tracks.some((t) => t.observations !== void 0 && t.observations >= minHits)
+					});
+				}
+				return out;
 			},
-			listMediaInfo: async (trackId) => {
-				return (await stores.mediaStore.listInfoByOwner("track", trackId)).map((r) => ({
+			listMediaInfo: async (id) => {
+				const group = await stores.groupStore.get(id);
+				if (group?.mediaKey) return [{
+					key: group.mediaKey,
+					kind: "groupCrop",
+					timestamp: group.timestamp
+				}];
+				if (group && group.memberCount === 1) {
+					const memberId = (await stores.groupStore.listMembers(group.id))[0]?.trackId;
+					if (!memberId) return [];
+					return (await stores.mediaStore.listInfoByOwner("track", memberId)).map((r) => ({
+						key: r.key,
+						kind: r.kind,
+						timestamp: r.timestamp
+					}));
+				}
+				if (group) return [];
+				return (await stores.mediaStore.listInfoByOwner("track", id)).map((r) => ({
 					key: r.key,
 					kind: r.kind,
 					timestamp: r.timestamp
@@ -59216,8 +60605,8 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_dist.B
 		const first = track.positions?.[0];
 		if (!first) return;
 		const lifeMs = track.lastSeen - track.firstSeen;
-		const moved = track.totalDistance ?? 0;
-		if (!(lifeMs <= SHORT_TRACK_MAX_MS && moved <= MOTIONLESS_MAX_PX)) {
+		const moved = netDisplacementPx(track.positions ?? []);
+		if (!isShortMotionlessTrack(lifeMs, moved)) {
 			this.phantomCells?.noteMovingClose({
 				deviceId: track.deviceId,
 				className: track.className,
@@ -59360,7 +60749,7 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_dist.B
 						deviceId,
 						trackId,
 						timestamp: frame.timestamp,
-						bbox: { ...frame.bbox },
+						bbox: { ...bboxForSemanticPromotion(d.className, d.bbox, frame.bbox) },
 						frameWidth: frame.frameWidth,
 						frameHeight: frame.frameHeight,
 						kind: d.className === "plate" ? "plate" : "classification",
@@ -59793,7 +61182,7 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_dist.B
 			retries.push({
 				trackId: t.trackId,
 				timestamp,
-				bbox: { ...t.bbox },
+				bbox: firstFrameRetryBbox(t.bbox, this.trackStore?.peekActive(t.trackId)?.positions[0]?.bbox),
 				...patchDisplayLabel(t.labelPatch) !== void 0 ? { label: patchDisplayLabel(t.labelPatch) } : {}
 			});
 		}
@@ -59850,7 +61239,8 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_dist.B
 				lastFrameAt: this.residents.lastFrameAt(t.trackId) ?? 0,
 				now: timestamp,
 				intervalMs: media.snapshotIntervalMs,
-				lastFrameIntervalMs: Math.min(LAST_FRAME_INTERVAL_MS, media.snapshotIntervalMs)
+				lastFrameIntervalMs: Math.min(LAST_FRAME_INTERVAL_MS, media.snapshotIntervalMs),
+				firstFrameLanded: this.residents.isFirstFrameLanded(t.trackId)
 			});
 			const rollingLastFrame = plan.rollingLastFrame && !this.captureScheduler.isKeyActive(captureCoalesceKey(deviceId, "lastFrame", t.trackId));
 			if (plan.appendSnapshot) this.trackStore.markSnapshotPending(t.trackId, timestamp, t.bbox);
@@ -60359,6 +61749,7 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_dist.B
 	async sweepExpiredTracks() {
 		if (this.shuttingDown || !this.trackStore) return;
 		await this.trackCloser.sweep();
+		this.groupSealer?.sealRecent();
 	}
 	/** Unified retention (Phase 1): earliest retained footage per device — the
 	*  follow-recordings cutoff source. Cached 10 min: availability answers in
@@ -61637,6 +63028,8 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_dist.B
 				},
 				liveTrackIds: (ids) => trackStore.existingTrackIds(ids),
 				liveEventIds: (ids) => eventStore.existingEventIds(ids),
+				liveGroupIds: (ids) => this.groupStore?.existingGroupIds(ids) ?? Promise.resolve(/* @__PURE__ */ new Set()),
+				liveGroupsWithMembers: (ids) => this.groupStore?.groupsWithMembers(ids) ?? Promise.resolve(/* @__PURE__ */ new Set()),
 				reclaim: async (collection, key) => {
 					if (collection === "pipeline-analytics:media") {
 						await mediaStore.deleteByKey(key);
@@ -62360,6 +63753,36 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_dist.B
 	buildFaceRescoreActionHandlers() {
 		return { "face.rescoreTrack": (input) => this.rescoreFaceForTrack(input) };
 	}
+	buildGroupActionHandlers() {
+		const ports = () => {
+			const groupStore = this.groupStore;
+			if (groupStore === null) return null;
+			return {
+				groupStore,
+				loadTrack: async (trackId) => {
+					const tracks = this.trackStore;
+					if (!tracks) return null;
+					return tracks.getActiveByTrack(trackId) ?? await tracks.getPersistedByTrackId(trackId);
+				},
+				eventMediaBaseUrl: () => this.eventMediaBaseUrl
+			};
+		};
+		return {
+			"analytics.listGroups": async (input) => {
+				const ready = ports();
+				if (ready === null) return {
+					groups: [],
+					hasMore: false
+				};
+				return listGroupRecords(ready, input);
+			},
+			"analytics.getGroup": async (input) => {
+				const ready = ports();
+				if (ready === null) return { group: null };
+				return { group: await getGroupDetail(ready, input.groupId) };
+			}
+		};
+	}
 	buildPhotoEnrollActionHandlers() {
 		return {
 			"photo.analyze": async (input) => {
@@ -62590,7 +64013,8 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_dist.B
 				mediaStore,
 				faceStore: this.faceStore,
 				plateStore: this.plateStore,
-				objectEmbeddingStore: this.objectEmbeddingStore
+				objectEmbeddingStore: this.objectEmbeddingStore,
+				groupStore: this.groupStore
 			}),
 			trackStore
 		};
@@ -62739,7 +64163,8 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_dist.B
 			media: 0,
 			faces: 0,
 			plates: 0,
-			embeddings: 0
+			embeddings: 0,
+			groups: 0
 		};
 		this.lastPruneBytes = 0;
 		const cascade = this.buildTrackCascadeRegistry();
@@ -62799,7 +64224,8 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_dist.B
 			media: tally.media,
 			faces: tally.faces,
 			plates: tally.plates,
-			embeddings: tally.embeddings
+			embeddings: tally.embeddings,
+			groups: tally.groups
 		};
 	}
 	/**