@camstack/addon-post-analysis 1.2.228 → 1.2.229

package/dist/pipeline-analytics/index.js

@@ -35511,6 +35511,71 @@ function pairRiders(detections) {
 	}
 	return pairs;
 }
+//#endregion
+//#region src/pipeline-analytics/pipeline/track-id.ts
+/**
+* A track's identity: short, random, and mintable inside a frame.
+*
+* ## Why not a counter, and why not the database
+*
+* The operator asked for an incremental id. It cannot be a database
+* auto-increment: the id is minted by the tracker MID-FRAME and is used
+* immediately — in the event, in the media key, as the `object-clip` vector's
+* row id — long before anything is written, so there is no rowid to wait for
+* and no await to spend on the hot path (D49: a one-shot never gates on a
+* fallible read).
+*
+* A local counter was already tried and reverted. `sort-tracker.ts` still
+* records what it did: "A bare per-process counter (`track-${n++}`) reset to 1
+* on every runner restart and collided across restarts AND devices — a
+* post-reboot track reused an old id and UPSERT-clobbered the old persisted row
+* (wrong 'now' dates, stale bestEventId thumbnails, cross-session media in the
+* detail view)."
+*
+* A durable counter is possible — the hub hands each node a BLOCK of ids ahead
+* of need, and the bookmark advances before they are used, so a crash leaves a
+* gap and never a duplicate. It was designed and NOT built: agents hold no
+* sqlite of their own (the hub is the only store), so the whole mechanism is a
+* cluster allocator with a degrade path, for a property nobody reads. The
+* operator chose the smaller thing.
+*
+* So: still random, and only shorter. 36 characters become 10.
+*
+* ## Is 10 enough
+*
+* Arithmetic, not optimism. The alphabet is 32 characters, so an id is 50 bits
+* and the space is 32^10 ≈ 1.13e15. The live table held 17 870 track rows under
+* a 7-day window (measured, `piano-riduzione-database`), so call the population
+* 20 000 ids that must not collide with each other. Birthday:
+*
+*     p ≈ n² / 2N = 4e8 / 2.25e15 ≈ 1.8e-7 per retention window
+*
+* ~1e-5 per year at the current fleet. A collision is not cosmetic — two tracks
+* sharing an id UPSERT over each other, which is precisely the old counter's
+* failure — so the margin is deliberately three orders of magnitude wider than
+* "probably fine", and it is the reason this is 10 characters and not 6.
+*
+* ## The alphabet
+*
+* Crockford-style base32, lower case: the digits plus the letters, minus
+* `i`, `l`, `o` and `u`. The first three are misread as `1`/`1`/`0` by a human
+* copying an id out of a log; `u` goes with them so the set is exactly 32,
+* which is what lets five raw bits map to one character with NO modulo bias.
+* A `% 36` over a byte would make the first 16 characters ~1.5× more likely and
+* silently shrink the space the arithmetic above depends on.
+*/
+/** 32 characters: `0-9a-z` minus `i`, `l`, `o`, `u`. A power of two, on purpose. */
+var TRACK_ID_ALPHABET = "0123456789abcdefghjkmnpqrstvwxyz";
+/**
+* A fresh track id. Synchronous, no I/O, no shared state — safe to call from
+* inside the tracker's per-frame loop, which is the only place that calls it.
+*/
+function newTrackId() {
+	const bytes = (0, node_crypto.randomBytes)(10);
+	let out = "";
+	for (let i = 0; i < 10; i += 1) out += TRACK_ID_ALPHABET[(bytes[i] ?? 0) & 31];
+	return out;
+}
 /** Per-(stage, gate) counter + sampling decision. One instance per tracker, so
 *  the counts are per camera and per detection source. */
 var LooseBindSampler = class {
@@ -36789,7 +36854,7 @@ var SortTracker = class SortTracker {
 				used.add(di);
 				continue;
 			}
-			const spawnedId = (0, node_crypto.randomUUID)();
+			const spawnedId = newTrackId();
 			this.reportSpawnBesideCoasting(spawnedId, det, surviving.filter((t) => t.lastSeen !== timestamp), detections, frameArea, timestamp);
 			surviving.push({
 				id: spawnedId,
@@ -60826,6 +60891,95 @@ async function reconcileGallerySamples(deps, options) {
 	};
 }
 //#endregion
+//#region src/pipeline-analytics/summary/summary-membership.ts
+/**
+* Who belongs to a summary, and which member is its primary.
+*
+* ## What this corrects
+*
+* `openOrAbsorb` absorbed ANY track born while a summary was open on the
+* camera, and `primary` went to whoever opened it. Both were measured wrong on
+* the live hub on 2026-09-13: synthetic sensor tracks (`pa-synth-…`) sat inside
+* summaries describing "who was here together", and a dog that walked in ahead
+* of its owner outranked the person behind it.
+*
+* The operator's rule: "persona animale veicolo la priorità. Gli eventi extra
+* sono sempre separati come eventi sintetici di sensori e pacchi."
+*
+* ## Why exclusion and priority live together
+*
+* They are the same question asked twice — "what is a subject in a group" —
+* and answering it in two files is how the two drift. A class that stops being
+* a member must not keep a rank, and a class that gains a rank must be a
+* member.
+*
+* Pure, so the surprising cases are pinned rather than discovered: the dog that
+* arrives first, the tie between two people, and the member whose class is not
+* known yet.
+*/
+/** The synthetic marker. `synthetic-track.ts` mints these and nothing parses it
+*  except this — which is the one place it must be parsed. */
+var SYNTHETIC_TRACK_PREFIX = "pa-synth-";
+/**
+* Classes the operator keeps OUT of a group, by name.
+*
+* A delivered package is an event about a PLACE, not a member of something that
+* arrived together — the operator named it alongside the sensors.
+*/
+var NON_MEMBER_CLASSES = new Set(["package"]);
+/**
+* Is this track a member of a group at all?
+*
+* An unknown class is NOT a reason to refuse. The grouping is the point and the
+* label is decoration, and nothing revisits this decision — a member dropped
+* here is dropped for the life of the summary.
+*/
+function isSummaryEligible(trackId, className) {
+	if (trackId.startsWith(SYNTHETIC_TRACK_PREFIX)) return false;
+	return className === null || className === void 0 || !NON_MEMBER_CLASSES.has(className);
+}
+/**
+* The operator's order: person › animal › vehicle › everything else.
+*
+* Higher is more important. Everything unnamed — including a class that has not
+* resolved yet — sits below all three rather than above them: promoting an
+* unknown would let a momentary mis-read take the group's identity, and the
+* group shot with it.
+*/
+var CLASS_RANK = new Map([
+	["person", 3],
+	["animal", 2],
+	["vehicle", 1]
+]);
+function classPriority(className) {
+	if (className === null || className === void 0) return 0;
+	return CLASS_RANK.get(className) ?? 0;
+}
+/**
+* Which member is the primary: highest class rank, ties broken by EARLIEST
+* arrival.
+*
+* The tie-break matters more than it looks. Two people are equal, so without it
+* the primary would flip on every join between equals — and the primary is what
+* a consumer reads to name the group, so it would rename itself for no reason
+* an operator could see.
+*
+* `null` for no members, never a fabricated id.
+*/
+function primaryTrackId(members) {
+	let best = null;
+	for (const m of members) {
+		if (best === null) {
+			best = m;
+			continue;
+		}
+		const rank = classPriority(m.className);
+		const bestRank = classPriority(best.className);
+		if (rank > bestRank || rank === bestRank && m.joinedAt < best.joinedAt) best = m;
+	}
+	return best?.trackId ?? null;
+}
+//#endregion
 //#region src/pipeline-analytics/summary/summary-store.ts
 /**
 * @durable class=ledger owner=pipeline-analytics
@@ -61090,7 +61244,18 @@ var SummaryStore = class {
 	async absorb(summary, input) {
 		const members = await this.membersOf(summary.id);
 		if (members.some((m) => m.trackId === input.trackId)) return summary;
-		await this.addMember(summary.id, input, "sibling");
+		const joined = {
+			trackId: input.trackId,
+			className: input.className ?? null,
+			joinedAt: input.at
+		};
+		const primary = primaryTrackId([...members.map((m) => ({
+			trackId: m.trackId,
+			className: m.className,
+			joinedAt: m.joinedAt
+		})), joined]);
+		await this.addMember(summary.id, input, primary === input.trackId ? "primary" : "sibling");
+		if (primary === input.trackId) await this.demoteOtherPrimaries(summary.id, input.trackId, members);
 		const memberCount = members.length + 1;
 		const lastActiveAt = Math.max(summary.lastActiveAt, input.at);
 		await this.store.updateWhere.mutate({
@@ -61110,6 +61275,31 @@ var SummaryStore = class {
 			lastActiveAt
 		};
 	}
+	/**
+	* Put every OTHER member back to `sibling` after a new primary took the role.
+	*
+	* Best-effort per row and loud about a row it could not move: two primaries
+	* is a wrong a consumer can see, but it is smaller than a lost member, so a
+	* failure here never propagates to the join.
+	*/
+	async demoteOtherPrimaries(summaryIdValue, primaryTrack, previous) {
+		for (const m of previous) {
+			if (m.trackId === primaryTrack || m.role !== "primary") continue;
+			try {
+				await this.store.update.mutate({
+					collection: SUMMARY_MEMBERS_COLLECTION,
+					id: memberRowId(summaryIdValue, m.trackId),
+					data: { role: "sibling" }
+				});
+			} catch (err) {
+				this.logger.warn("summary: could not demote the previous primary — two remain", { meta: {
+					summaryId: summaryIdValue,
+					trackId: m.trackId,
+					error: String(err)
+				} });
+			}
+		}
+	}
 	async addMember(summaryIdValue, input, role) {
 		await this.store.insertMany.mutate({
 			collection: SUMMARY_MEMBERS_COLLECTION,
@@ -68454,7 +68644,7 @@ var SyntheticTrackMaterializer = class {
 		this.deps = deps;
 		this.debounceMs = deps.debounceMs ?? DEFAULT_DEBOUNCE_MS;
 		this.snapshotTimeoutMs = deps.snapshotTimeoutMs ?? DEFAULT_SNAPSHOT_TIMEOUT_MS;
-		this.makeId = deps.makeId ?? (() => `pa-synth-${(0, node_crypto.randomUUID)()}`);
+		this.makeId = deps.makeId ?? (() => `pa-synth-${newTrackId()}`);
 		this.now = deps.now ?? Date.now;
 	}
 	/**
@@ -71436,6 +71626,16 @@ var SummarySealer = class {
 	}
 	async onTrackOpened(input) {
 		try {
+			if (!isSummaryEligible(input.trackId, input.className)) {
+				this.deps.logger.debug("summary: track is not a group member — left standalone", {
+					tags: { deviceId: input.deviceId },
+					meta: {
+						trackId: input.trackId,
+						className: input.className ?? null
+					}
+				});
+				return;
+			}
 			const row = await this.deps.summaries.openOrAbsorb({
 				deviceId: input.deviceId,
 				trackId: input.trackId,

package/dist/pipeline-analytics/index.mjs

@@ -4,7 +4,7 @@ import * as fs from "node:fs";
 import { promises } from "node:fs";
 import * as path$1 from "node:path";
 import path from "node:path";
-import { createHash, createHmac, randomUUID, timingSafeEqual } from "node:crypto";
+import { createHash, createHmac, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
 import { execFile } from "node:child_process";
 import { startEventLoopStallMonitor } from "@camstack/system/addon-utils";
 import sharp from "sharp";
@@ -35486,6 +35486,71 @@ function pairRiders(detections) {
 	}
 	return pairs;
 }
+//#endregion
+//#region src/pipeline-analytics/pipeline/track-id.ts
+/**
+* A track's identity: short, random, and mintable inside a frame.
+*
+* ## Why not a counter, and why not the database
+*
+* The operator asked for an incremental id. It cannot be a database
+* auto-increment: the id is minted by the tracker MID-FRAME and is used
+* immediately — in the event, in the media key, as the `object-clip` vector's
+* row id — long before anything is written, so there is no rowid to wait for
+* and no await to spend on the hot path (D49: a one-shot never gates on a
+* fallible read).
+*
+* A local counter was already tried and reverted. `sort-tracker.ts` still
+* records what it did: "A bare per-process counter (`track-${n++}`) reset to 1
+* on every runner restart and collided across restarts AND devices — a
+* post-reboot track reused an old id and UPSERT-clobbered the old persisted row
+* (wrong 'now' dates, stale bestEventId thumbnails, cross-session media in the
+* detail view)."
+*
+* A durable counter is possible — the hub hands each node a BLOCK of ids ahead
+* of need, and the bookmark advances before they are used, so a crash leaves a
+* gap and never a duplicate. It was designed and NOT built: agents hold no
+* sqlite of their own (the hub is the only store), so the whole mechanism is a
+* cluster allocator with a degrade path, for a property nobody reads. The
+* operator chose the smaller thing.
+*
+* So: still random, and only shorter. 36 characters become 10.
+*
+* ## Is 10 enough
+*
+* Arithmetic, not optimism. The alphabet is 32 characters, so an id is 50 bits
+* and the space is 32^10 ≈ 1.13e15. The live table held 17 870 track rows under
+* a 7-day window (measured, `piano-riduzione-database`), so call the population
+* 20 000 ids that must not collide with each other. Birthday:
+*
+*     p ≈ n² / 2N = 4e8 / 2.25e15 ≈ 1.8e-7 per retention window
+*
+* ~1e-5 per year at the current fleet. A collision is not cosmetic — two tracks
+* sharing an id UPSERT over each other, which is precisely the old counter's
+* failure — so the margin is deliberately three orders of magnitude wider than
+* "probably fine", and it is the reason this is 10 characters and not 6.
+*
+* ## The alphabet
+*
+* Crockford-style base32, lower case: the digits plus the letters, minus
+* `i`, `l`, `o` and `u`. The first three are misread as `1`/`1`/`0` by a human
+* copying an id out of a log; `u` goes with them so the set is exactly 32,
+* which is what lets five raw bits map to one character with NO modulo bias.
+* A `% 36` over a byte would make the first 16 characters ~1.5× more likely and
+* silently shrink the space the arithmetic above depends on.
+*/
+/** 32 characters: `0-9a-z` minus `i`, `l`, `o`, `u`. A power of two, on purpose. */
+var TRACK_ID_ALPHABET = "0123456789abcdefghjkmnpqrstvwxyz";
+/**
+* A fresh track id. Synchronous, no I/O, no shared state — safe to call from
+* inside the tracker's per-frame loop, which is the only place that calls it.
+*/
+function newTrackId() {
+	const bytes = randomBytes(10);
+	let out = "";
+	for (let i = 0; i < 10; i += 1) out += TRACK_ID_ALPHABET[(bytes[i] ?? 0) & 31];
+	return out;
+}
 /** Per-(stage, gate) counter + sampling decision. One instance per tracker, so
 *  the counts are per camera and per detection source. */
 var LooseBindSampler = class {
@@ -36764,7 +36829,7 @@ var SortTracker = class SortTracker {
 				used.add(di);
 				continue;
 			}
-			const spawnedId = randomUUID();
+			const spawnedId = newTrackId();
 			this.reportSpawnBesideCoasting(spawnedId, det, surviving.filter((t) => t.lastSeen !== timestamp), detections, frameArea, timestamp);
 			surviving.push({
 				id: spawnedId,
@@ -60752,6 +60817,95 @@ async function reconcileGallerySamples(deps, options) {
 	};
 }
 //#endregion
+//#region src/pipeline-analytics/summary/summary-membership.ts
+/**
+* Who belongs to a summary, and which member is its primary.
+*
+* ## What this corrects
+*
+* `openOrAbsorb` absorbed ANY track born while a summary was open on the
+* camera, and `primary` went to whoever opened it. Both were measured wrong on
+* the live hub on 2026-09-13: synthetic sensor tracks (`pa-synth-…`) sat inside
+* summaries describing "who was here together", and a dog that walked in ahead
+* of its owner outranked the person behind it.
+*
+* The operator's rule: "persona animale veicolo la priorità. Gli eventi extra
+* sono sempre separati come eventi sintetici di sensori e pacchi."
+*
+* ## Why exclusion and priority live together
+*
+* They are the same question asked twice — "what is a subject in a group" —
+* and answering it in two files is how the two drift. A class that stops being
+* a member must not keep a rank, and a class that gains a rank must be a
+* member.
+*
+* Pure, so the surprising cases are pinned rather than discovered: the dog that
+* arrives first, the tie between two people, and the member whose class is not
+* known yet.
+*/
+/** The synthetic marker. `synthetic-track.ts` mints these and nothing parses it
+*  except this — which is the one place it must be parsed. */
+var SYNTHETIC_TRACK_PREFIX = "pa-synth-";
+/**
+* Classes the operator keeps OUT of a group, by name.
+*
+* A delivered package is an event about a PLACE, not a member of something that
+* arrived together — the operator named it alongside the sensors.
+*/
+var NON_MEMBER_CLASSES = new Set(["package"]);
+/**
+* Is this track a member of a group at all?
+*
+* An unknown class is NOT a reason to refuse. The grouping is the point and the
+* label is decoration, and nothing revisits this decision — a member dropped
+* here is dropped for the life of the summary.
+*/
+function isSummaryEligible(trackId, className) {
+	if (trackId.startsWith(SYNTHETIC_TRACK_PREFIX)) return false;
+	return className === null || className === void 0 || !NON_MEMBER_CLASSES.has(className);
+}
+/**
+* The operator's order: person › animal › vehicle › everything else.
+*
+* Higher is more important. Everything unnamed — including a class that has not
+* resolved yet — sits below all three rather than above them: promoting an
+* unknown would let a momentary mis-read take the group's identity, and the
+* group shot with it.
+*/
+var CLASS_RANK = new Map([
+	["person", 3],
+	["animal", 2],
+	["vehicle", 1]
+]);
+function classPriority(className) {
+	if (className === null || className === void 0) return 0;
+	return CLASS_RANK.get(className) ?? 0;
+}
+/**
+* Which member is the primary: highest class rank, ties broken by EARLIEST
+* arrival.
+*
+* The tie-break matters more than it looks. Two people are equal, so without it
+* the primary would flip on every join between equals — and the primary is what
+* a consumer reads to name the group, so it would rename itself for no reason
+* an operator could see.
+*
+* `null` for no members, never a fabricated id.
+*/
+function primaryTrackId(members) {
+	let best = null;
+	for (const m of members) {
+		if (best === null) {
+			best = m;
+			continue;
+		}
+		const rank = classPriority(m.className);
+		const bestRank = classPriority(best.className);
+		if (rank > bestRank || rank === bestRank && m.joinedAt < best.joinedAt) best = m;
+	}
+	return best?.trackId ?? null;
+}
+//#endregion
 //#region src/pipeline-analytics/summary/summary-store.ts
 /**
 * @durable class=ledger owner=pipeline-analytics
@@ -61016,7 +61170,18 @@ var SummaryStore = class {
 	async absorb(summary, input) {
 		const members = await this.membersOf(summary.id);
 		if (members.some((m) => m.trackId === input.trackId)) return summary;
-		await this.addMember(summary.id, input, "sibling");
+		const joined = {
+			trackId: input.trackId,
+			className: input.className ?? null,
+			joinedAt: input.at
+		};
+		const primary = primaryTrackId([...members.map((m) => ({
+			trackId: m.trackId,
+			className: m.className,
+			joinedAt: m.joinedAt
+		})), joined]);
+		await this.addMember(summary.id, input, primary === input.trackId ? "primary" : "sibling");
+		if (primary === input.trackId) await this.demoteOtherPrimaries(summary.id, input.trackId, members);
 		const memberCount = members.length + 1;
 		const lastActiveAt = Math.max(summary.lastActiveAt, input.at);
 		await this.store.updateWhere.mutate({
@@ -61036,6 +61201,31 @@ var SummaryStore = class {
 			lastActiveAt
 		};
 	}
+	/**
+	* Put every OTHER member back to `sibling` after a new primary took the role.
+	*
+	* Best-effort per row and loud about a row it could not move: two primaries
+	* is a wrong a consumer can see, but it is smaller than a lost member, so a
+	* failure here never propagates to the join.
+	*/
+	async demoteOtherPrimaries(summaryIdValue, primaryTrack, previous) {
+		for (const m of previous) {
+			if (m.trackId === primaryTrack || m.role !== "primary") continue;
+			try {
+				await this.store.update.mutate({
+					collection: SUMMARY_MEMBERS_COLLECTION,
+					id: memberRowId(summaryIdValue, m.trackId),
+					data: { role: "sibling" }
+				});
+			} catch (err) {
+				this.logger.warn("summary: could not demote the previous primary — two remain", { meta: {
+					summaryId: summaryIdValue,
+					trackId: m.trackId,
+					error: String(err)
+				} });
+			}
+		}
+	}
 	async addMember(summaryIdValue, input, role) {
 		await this.store.insertMany.mutate({
 			collection: SUMMARY_MEMBERS_COLLECTION,
@@ -68380,7 +68570,7 @@ var SyntheticTrackMaterializer = class {
 		this.deps = deps;
 		this.debounceMs = deps.debounceMs ?? DEFAULT_DEBOUNCE_MS;
 		this.snapshotTimeoutMs = deps.snapshotTimeoutMs ?? DEFAULT_SNAPSHOT_TIMEOUT_MS;
-		this.makeId = deps.makeId ?? (() => `pa-synth-${randomUUID()}`);
+		this.makeId = deps.makeId ?? (() => `pa-synth-${newTrackId()}`);
 		this.now = deps.now ?? Date.now;
 	}
 	/**
@@ -71362,6 +71552,16 @@ var SummarySealer = class {
 	}
 	async onTrackOpened(input) {
 		try {
+			if (!isSummaryEligible(input.trackId, input.className)) {
+				this.deps.logger.debug("summary: track is not a group member — left standalone", {
+					tags: { deviceId: input.deviceId },
+					meta: {
+						trackId: input.trackId,
+						className: input.className ?? null
+					}
+				});
+				return;
+			}
 			const row = await this.deps.summaries.openOrAbsorb({
 				deviceId: input.deviceId,
 				trackId: input.trackId,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/addon-post-analysis",
-  "version": "1.2.228",
+  "version": "1.2.229",
   "description": "Post-Analysis bundle — enrichment, embedding-encoder, pipeline-analytics. Multi-entry npm package shipping addons that consume pipeline output.",
   "keywords": [
     "camstack",