@camstack/addon-post-analysis 1.2.298 → 1.2.299

package/dist/pipeline-analytics/index.js

@@ -2,7 +2,7 @@ Object.defineProperties(exports, {
 	__esModule: { value: true },
 	[Symbol.toStringTag]: { value: "Module" }
 });
-const require_clip_model_registry = require("../clip-model-registry-olxNKN7T.js");
+const require_clip_model_registry = require("../clip-model-registry-hTbsQ-z7.js");
 let node_fs = require("node:fs");
 node_fs = require_clip_model_registry.__toESM(node_fs, 1);
 let node_path = require("node:path");
@@ -12,6 +12,8 @@ let node_crypto = require("node:crypto");
 let node_child_process = require("node:child_process");
 let _camstack_system_addon_utils = require("@camstack/system/addon-utils");
 let node_stream_promises = require("node:stream/promises");
+let node_fs_promises = require("node:fs/promises");
+node_fs_promises = require_clip_model_registry.__toESM(node_fs_promises, 1);
 let sharp = require("sharp");
 sharp = require_clip_model_registry.__toESM(sharp);
 let node_os = require("node:os");
@@ -9980,14 +9982,25 @@ function occupancySubjectFromEdge(edge) {
 		threshold: edge.threshold
 	};
 }
-/** Build the subject for a `package-event` evaluation (a persisted `package`
-*  object-event; `phase` derives from the event `state` at the call site). */
+/**
+* Build the subject for a `package-event` evaluation (a persisted `package`
+* object-event; `phase` derives from the event `state` at the call site).
+*
+* `observedAt` (D682, D684): a pick-up row's `timestamp` is when the departure
+* was CONCLUDED — five minutes of unseen observed time after the parcel went —
+* so the detector STORES the instant it happened on the row, and the footage is
+* cut around that (`media-anchor.ts`). Read from the row HERE, the one place
+* every path builds a package subject (live hook, boot reconcile, dry-run), so
+* none of them can anchor differently. `timestamp` keeps its meaning; a row
+* written before D684 has none, which the anchor reads as unknown, out loud.
+*/
 function subjectFromPackageEvent(ev, phase) {
 	return {
 		kind: "package-event",
 		recordId: String(ev.id),
 		deviceId: ev.deviceId,
 		timestamp: ev.timestamp,
+		...ev.observedAt !== void 0 ? { observedAt: ev.observedAt } : {},
 		classNames: [ev.className],
 		...displayLabel(ev) !== void 0 ? { label: displayLabel(ev) } : {},
 		...recognitionPatch(ev.subLabelMeta),
@@ -10918,7 +10931,11 @@ function incomingFromAudioEvent(event, stillOwnerId) {
 		})
 	};
 }
-/** Package object-event persist (delivered / picked-up). */
+/**
+* Package object-event persist (delivered / picked-up) — the live hook and the
+* boot reconcile alike. A pick-up's instant is read from the row
+* (`event.observedAt`, D684) inside `subjectFromPackageEvent`.
+*/
 function incomingFromPackageEvent(event, phase) {
 	return {
 		subject: subjectFromPackageEvent(event, phase),
@@ -10928,7 +10945,8 @@ function incomingFromPackageEvent(event, phase) {
 			tags: { deviceId: event.deviceId },
 			meta: {
 				eventId: event.id,
-				phase
+				phase,
+				...event.observedAt !== void 0 ? { observedAt: event.observedAt } : {}
 			}
 		})
 	};
@@ -19336,9 +19354,14 @@ function mediaAnchor(subject) {
 		lagMs: subject.timestamp - observedAt
 	};
 }
+function selfDatingKindOf(subject) {
+	if (subject.occupancy !== void 0) return "occupancy";
+	if (subject.packagePhase === "picked-up") return "package pick-up";
+	return null;
+}
 /**
 * True when this anchor is the conclusion instant AND the subject was one that
-* should have been able to date itself — today, an occupancy row.
+* should have been able to date itself — see {@link selfDatingKindOf}.
 *
 * Split from {@link mediaAnchor} because the anchor must stay pure of any
 * notion of subject KIND, while the log line that matters is exactly the one
@@ -20442,7 +20465,8 @@ var NcDispatcher = class {
 		};
 		const preRollSec = entry.payload.mediaClipPreRollSec ?? 4;
 		const anchor = mediaAnchor(entry.payload.subject);
-		if (anchorFellBack(anchor, entry.payload.subject.occupancy !== void 0)) this.deps.logger.warn("occupancy footage anchored on the conclusion — moment unknown", {
+		const selfDating = selfDatingKindOf(entry.payload.subject);
+		if (anchorFellBack(anchor, selfDating !== null)) this.deps.logger.warn(`${selfDating ?? "occupancy"} footage anchored on the conclusion — moment unknown`, {
 			tags: { deviceId: entry.payload.subject.deviceId },
 			meta: {
 				ruleId: entry.ruleId,
@@ -20470,7 +20494,7 @@ var NcDispatcher = class {
 					preRollSec,
 					retentionSec: this.ringRetentionSec(entry.payload.subject.deviceId),
 					wanted: [...wantGif ? ["gif"] : [], ...wantMp4 ? ["video"] : []],
-					next: this.deps.cutRecordedClip !== void 0 ? "recorded-clip-follow-up" : "no-clip"
+					next: this.recordedFollowUp(entry).kinds.length > 0 ? "recorded-clip-follow-up" : "no-clip"
 				}
 			});
 			return {
@@ -20524,6 +20548,13 @@ var NcDispatcher = class {
 	* alert for a complete one, which is precisely the wrong trade for the
 	* notification that tells an operator someone is at the door.
 	*
+	* A GIF rule is served here too (D682): a package pick-up is concluded five
+	* minutes after it happened, so a gif anchored on the pick-up is always
+	* outside the ring. The gif is derived from THIS cut's bytes
+	* (`deriveGifFromClip`) — one cut, never a second renderer — and a moment the
+	* recordings cannot serve ships NO gif, by named reason, rather than a gif of
+	* the wrong time.
+	*
 	* So the alert's latency is UNCHANGED, and **the clip is attached later**, as
 	* a follow-up send to the same target carrying the same `tag` — a phone
 	* collapses the two, so what the operator sees is the notification gaining
@@ -20546,7 +20577,9 @@ var NcDispatcher = class {
 	*/
 	startRecordedFootage(entry, target, notification) {
 		const cut = this.deps.cutRecordedClip;
-		if (cut === void 0 || entry.payload.mediaClip !== true) return;
+		const plan = this.recordedFollowUp(entry);
+		const wanted = plan.kinds;
+		if (cut === void 0 || wanted.length === 0 && plan.gifRefused === void 0 && plan.videoRefused === void 0) return;
 		const preRollSec = entry.payload.mediaClipPreRollSec ?? 4;
 		const anchor = mediaAnchor(entry.payload.subject);
 		if (footageSourceFor({
@@ -20556,34 +20589,70 @@ var NcDispatcher = class {
 			ringRetentionSec: this.ringRetentionSec(entry.payload.subject.deviceId)
 		}) !== "recordings") return;
 		const deviceId = entry.payload.subject.deviceId;
+		if (plan.gifRefused !== void 0) this.deps.logger.info("recorded gif follow-up: none — the gif is not cut from the recordings", {
+			tags: { deviceId },
+			meta: {
+				ruleId: entry.ruleId,
+				eventId: entry.recordId,
+				targetId: target.id,
+				reason: plan.gifRefused,
+				anchoredOn: anchor.source,
+				...anchor.fallback !== void 0 ? { anchorFallback: anchor.fallback } : {},
+				next: wanted
+			}
+		});
+		if (plan.videoRefused !== void 0) this.deps.logger.info("recorded video follow-up: none — the video is not cut from the recordings", {
+			tags: { deviceId },
+			meta: {
+				ruleId: entry.ruleId,
+				eventId: entry.recordId,
+				targetId: target.id,
+				reason: plan.videoRefused,
+				anchoredOn: anchor.source,
+				...anchor.fallback !== void 0 ? { anchorFallback: anchor.fallback } : {},
+				next: wanted
+			}
+		});
+		if (wanted.length === 0) return;
+		const videoSpeed = entry.payload.mediaClipSpeed;
 		const pending = (async () => {
 			const result = await cut({
 				deviceId,
 				aroundMs: anchor.atMs,
 				preRollSec,
 				postRollSec: entry.payload.mediaClipPostRollSec ?? 6,
-				...entry.payload.mediaClipSpeed !== void 0 ? { speed: entry.payload.mediaClipSpeed } : {},
+				...videoSpeed !== void 0 ? { speed: videoSpeed } : {},
 				ruleId: entry.ruleId,
 				recordId: entry.recordId
 			});
 			if (!result.ok) {
-				this.deps.logger.info("recorded clip follow-up: none — this delivery keeps no clip", {
+				this.deps.logger.info("recorded footage follow-up: none — the recorded cut failed", {
 					tags: { deviceId },
 					meta: {
 						ruleId: entry.ruleId,
 						eventId: entry.recordId,
 						targetId: target.id,
-						reason: result.reason
+						reason: result.reason,
+						wanted
 					}
 				});
 				return;
 			}
-			const withUrls = await this.withArtifactUrls(entry, [{
-				mediaType: "video",
-				bytes: result.mp4,
-				mime: "video/mp4",
-				name: "event.mp4"
-			}]);
+			const attachments = await this.recordedAttachments(entry, wanted, result.mp4);
+			if (attachments.length === 0) {
+				this.deps.logger.info("recorded clip follow-up: none — the gif could not be derived", {
+					tags: { deviceId },
+					meta: {
+						ruleId: entry.ruleId,
+						eventId: entry.recordId,
+						targetId: target.id,
+						reason: "gif-derive-failed",
+						wanted
+					}
+				});
+				return;
+			}
+			const withUrls = await this.withArtifactUrls(entry, attachments);
 			const sent = await this.deps.send({
 				addonId: target.addonId,
 				targetId: target.id,
@@ -20612,6 +20681,8 @@ var NcDispatcher = class {
 					target: target.name,
 					profile: result.profile,
 					bytes: result.mp4.byteLength,
+					attachments: attachments.map((a) => a.mediaType),
+					anchoredOn: anchor.source,
 					lagMs: this.now() - entry.updatedAt
 				}
 			});
@@ -20631,6 +20702,84 @@ var NcDispatcher = class {
 		});
 	}
 	/**
+	* What a recorded follow-up for this row would CARRY — the one answer both
+	* the refusal line (`next`) and the follow-up read, so the log cannot promise
+	* a follow-up the dispatcher will not send.
+	*
+	* A video when the rule asked for one. A gif only for a package PICK-UP
+	* whose moment is KNOWN (D682): the gif is derived from the recorded cut's
+	* own bytes, the same way the broker derives it from a ring cut — one cut,
+	* two containers, never a second renderer.
+	*
+	* Narrow on purpose. A pick-up is the one kind whose moment is ALWAYS outside
+	* the ring; every other kind keeps the gif behaviour it had (the ring's, or
+	* none) rather than silently gaining a recorder export per notification. And
+	* a pick-up that fell back to its conclusion gets no recorded footage at all,
+	* gif OR video — cutting the recordings there is exactly the doormat D682
+	* removed (see {@link NcRecordedGifRefusal}, {@link NcRecordedVideoRefusal}).
+	*/
+	recordedFollowUp(entry) {
+		if (this.deps.cutRecordedClip === void 0) return { kinds: [] };
+		const gifRefused = this.recordedGifRefusal(entry);
+		const videoRefused = this.recordedVideoRefusal(entry);
+		const kinds = [];
+		if (entry.payload.mediaGif === true && gifRefused === void 0) kinds.push("gif");
+		if (entry.payload.mediaClip === true && videoRefused === void 0) kinds.push("video");
+		return {
+			kinds,
+			...gifRefused !== void 0 ? { gifRefused } : {},
+			...videoRefused !== void 0 ? { videoRefused } : {}
+		};
+	}
+	/** Why this row's video is not cut from the recordings, or `undefined` when
+	*  it is (or when the rule asked for no video). */
+	recordedVideoRefusal(entry) {
+		if (entry.payload.mediaClip !== true) return void 0;
+		const subject = entry.payload.subject;
+		if (selfDatingKindOf(subject) !== "package pick-up") return void 0;
+		if (anchorFellBack(mediaAnchor(subject), true)) return "moment-unknown";
+	}
+	/** Why this row's gif is not cut from the recordings, or `undefined` when it
+	*  is (or when the rule asked for no gif). */
+	recordedGifRefusal(entry) {
+		if (entry.payload.mediaGif !== true) return void 0;
+		if (this.deps.deriveGifFromClip === void 0) return "no-derive";
+		const subject = entry.payload.subject;
+		if (selfDatingKindOf(subject) !== "package pick-up") return "not-a-pick-up";
+		if (anchorFellBack(mediaAnchor(subject), true)) return "moment-unknown";
+	}
+	/**
+	* The follow-up's attachments, gif first and video second — the order the
+	* ring path ships them in. A gif that could not be derived is left out (its
+	* reason already logged); the video, when asked for, still ships.
+	*/
+	async recordedAttachments(entry, wanted, mp4) {
+		const out = [];
+		const derive = this.deps.deriveGifFromClip;
+		if (wanted.includes("gif") && derive !== void 0) {
+			const gif = await derive({
+				deviceId: entry.payload.subject.deviceId,
+				mp4,
+				...entry.payload.mediaClipSpeed !== void 0 ? { videoSpeed: entry.payload.mediaClipSpeed } : {},
+				ruleId: entry.ruleId,
+				recordId: entry.recordId
+			});
+			if (gif.ok) out.push({
+				mediaType: "gif",
+				bytes: gif.gif,
+				mime: "image/gif",
+				name: "event.gif"
+			});
+		}
+		if (wanted.includes("video")) out.push({
+			mediaType: "video",
+			bytes: mp4,
+			mime: "video/mp4",
+			name: "event.mp4"
+		});
+		return out;
+	}
+	/**
 	* Settle every recorded-clip follow-up this dispatcher has in flight.
 	*
 	* A TEST SEAM, and the honest kind: the follow-up is detached by design, so
@@ -32558,6 +32707,9 @@ var NotificationCenter = class NotificationCenter {
 	* delivered/picked-up), in the SAME moment as the durable insert. Feeds the
 	* `package-event` trigger. Package events ARE object-event rows, so the boot
 	* crash-gap reconcile re-covers them (routed by className in {@link reconcile}).
+	*
+	* When a pick-up HAPPENED is on the row (`event.observedAt`, D684), so this
+	* hook and the reconcile read it from the same place.
 	*/
 	onPackageEventPersisted(event, phase) {
 		this.consumeEvent(incomingFromPackageEvent(event, phase));
@@ -53055,7 +53207,9 @@ var MOTION_EVENTS_COLLECTION = "pipeline-analytics:motion-events";
 * @durable class=ledger owner=pipeline-analytics
 *   write="one row per detected object per processed frame — every tracked
 *     detection the frame processor emits, plus the appearance events and the
-*     synthetic package-drop events. Every row carries the trackId it belongs to."
+*     synthetic package-drop events. Every row carries the trackId it belongs to.
+*     A package PICK-UP row also carries observedAt, when the parcel went,
+*     beside its timestamp, when the departure was concluded (D684)."
 *   retention="TRACK-OWNED: it has no clock of its own. Rows go only when their
 *     track goes, through EventStore.deleteByTracks — which folds in the deletion
 *     of the event's child crops so a caller cannot take the events and leave the
@@ -53262,7 +53416,21 @@ var OBJECT_COLUMNS = [
 	{
 		name: "importance",
 		type: "REAL"
-	}
+	},
+	(
+	/**
+	* When a package PICK-UP happened, beside `timestamp` (when it was
+	* CONCLUDED, five minutes later) — see `ObjectEvent.observedAt` (D684).
+	*
+	* DECLARED, or the backend drops it on write (see `frameId`). Additive: the
+	* collection gains the column in place (`ALTER TABLE … ADD COLUMN`), and every
+	* row written before it reads SQL NULL → absent after `stripNulls`, which is
+	* the truth about it: the moment is unknown. Only the package detector sets it.
+	*/
+	{
+		name: "observedAt",
+		type: "INTEGER"
+	})
 ];
 var AUDIO_COLUMNS = [
 	...COMMON_BASE_COLUMNS,
@@ -59101,6 +59269,180 @@ function decodeBase64(base64) {
 	}
 }
 //#endregion
+//#region src/notification-center/recorded-gif.ts
+/**
+* The notification GIF for a moment only the RECORDINGS still hold — derived
+* from the recorded clip's own bytes (D682).
+*
+* ## Why this exists
+*
+* A package pick-up is concluded five minutes after the parcel went
+* (`PACKAGE_STILLNESS_TTL_MS`). Once its footage is anchored on the pick-up
+* itself rather than on the conclusion (`media-anchor.ts`), the window is far
+* older than any clip ring (≤ 60 s, `NC_CLIP_RETENTION_MAX_SEC`), so the ring
+* refuses it. A gif-only rule then had NOTHING: the recorded follow-up served
+* only a rule that asked for a video. The honest fix for "the gif shows the
+* empty doormat" is not "no gif" — it is the gif of the pick-up, from the
+* recordings.
+*
+* ## One cut, and the gif is DERIVED from it
+*
+* The recorded clip (`recorded-clip.ts`, one `recordingExport` render) is the
+* only cut. The gif is derived from ITS bytes with the SAME filter chain the
+* broker uses on a ring cut (`gifFromMp4Args` in `@camstack/types`), so a gif
+* of an old moment and a gif of a live one look the same, and a rule that asks
+* for both a gif and a video gets two containers of ONE window — the guarantee
+* `NcEventMediaRequest` exists for.
+*
+* ## Never throws, every miss named
+*
+* `derive-failed` (ffmpeg could not produce it) and `stage-failed` (the clip
+* could not be written where ffmpeg can read it) are logged with
+* `tags: { deviceId }` (D400: a missing attachment names its reason).
+*/
+/** Bound on one derive: a ~10 s window encodes in well under a second; a
+*  derive that has not finished in 20 s is wedged. Same bound as the broker's. */
+var NC_RECORDED_GIF_TIMEOUT_MS = 2e4;
+/** A notification gif is a few hundred KB; this is headroom, not a budget. */
+var RECORDED_GIF_MAX_BUFFER = 32 * 1024 * 1024;
+/**
+* Derive the gif. Never throws; every `ok: false` has logged its reason.
+*/
+async function deriveRecordedGif(ports, req) {
+	const tags = { deviceId: req.deviceId };
+	const common = {
+		ruleId: req.ruleId,
+		eventId: req.recordId,
+		sourceBytes: req.mp4.byteLength
+	};
+	let file;
+	try {
+		file = await ports.writeTemp(req.mp4);
+	} catch (err) {
+		ports.logger.warn("recorded gif: could not stage the recorded clip — no gif", {
+			tags,
+			meta: {
+				...common,
+				reason: "stage-failed",
+				error: String(err)
+			}
+		});
+		return {
+			ok: false,
+			reason: "stage-failed"
+		};
+	}
+	try {
+		const speed = require_clip_model_registry.gifDeriveSpeed(4, req.videoSpeed ?? 1);
+		const args = require_clip_model_registry.gifFromMp4Args({
+			maxWidth: 640,
+			fps: 12,
+			speed,
+			input: file
+		});
+		const startedAt = Date.now();
+		let ran;
+		try {
+			ran = await ports.run(await ports.resolveFfmpeg(), args);
+		} catch (err) {
+			ran = {
+				ok: false,
+				error: String(err)
+			};
+		}
+		const out = ran.ok ? ran.stdout : null;
+		if (out === null || out.byteLength === 0) {
+			ports.logger.warn("recorded gif: the derive failed — the follow-up carries no gif", {
+				tags,
+				meta: {
+					...common,
+					reason: "derive-failed",
+					error: ran.ok ? "ffmpeg produced no bytes" : ran.error.slice(-400)
+				}
+			});
+			return {
+				ok: false,
+				reason: "derive-failed"
+			};
+		}
+		const gif = new Uint8Array(new ArrayBuffer(out.byteLength));
+		gif.set(out);
+		ports.logger.info("recorded gif: derived from the recorded clip", {
+			tags,
+			meta: {
+				...common,
+				gifBytes: gif.byteLength,
+				width: 640,
+				fps: 12,
+				speed,
+				encodeMs: Date.now() - startedAt
+			}
+		});
+		return {
+			ok: true,
+			gif
+		};
+	} finally {
+		await ports.removeTemp(file).catch((err) => {
+			ports.logger.warn("recorded gif: could not remove the staged clip", {
+				tags,
+				meta: {
+					...common,
+					file,
+					error: String(err)
+				}
+			});
+		});
+	}
+}
+/** The production ports: the pinned ffmpeg, a temp file, a bounded child. */
+function buildRecordedGifPorts(input) {
+	return {
+		logger: input.logger,
+		resolveFfmpeg: input.resolveFfmpeg,
+		run: (cmd, args) => new Promise((resolve) => {
+			(0, node_child_process.execFile)(cmd, [...args], {
+				encoding: "buffer",
+				maxBuffer: RECORDED_GIF_MAX_BUFFER,
+				timeout: NC_RECORDED_GIF_TIMEOUT_MS,
+				killSignal: "SIGKILL"
+			}, (err, stdout) => resolve(err !== null ? {
+				ok: false,
+				error: String(err)
+			} : {
+				ok: true,
+				stdout
+			}));
+		}),
+		writeTemp: (bytes) => stageTempClip(node_path.default.join(node_os.default.tmpdir(), `camstack-nc-gif-${(0, node_crypto.randomUUID)()}.mp4`), bytes, {
+			write: (file, data) => node_fs_promises.default.writeFile(file, data),
+			remove: (file) => node_fs_promises.default.rm(file, { force: true })
+		}),
+		removeTemp: (file) => node_fs_promises.default.rm(file, { force: true })
+	};
+}
+/**
+* Write the clip to `file`, and on a failed write remove whatever landed.
+*
+* The path is named BEFORE the write, because a write can create the file and
+* then fail (ENOSPC half-way): the caller's `finally` only knows a path the
+* write RETURNED, so a partial `camstack-nc-gif-*.mp4` used to stay in the temp
+* directory for good. The write's error is re-thrown — the caller names it
+* (`stage-failed`, tagged per camera). A removal that ALSO fails is a real leak
+* and rides in that same error's message, so it reaches that one line rather
+* than a second, untagged one.
+*/
+async function stageTempClip(file, bytes, io) {
+	try {
+		await io.write(file, bytes);
+		return file;
+	} catch (err) {
+		const leaked = await io.remove(file).then(() => null, (removeErr) => String(removeErr));
+		if (leaked === null) throw err;
+		throw new Error(`${String(err)}; the partial file ${file} was NOT removed: ${leaked}`);
+	}
+}
+//#endregion
 //#region src/shared/frame/crop-extractor.ts
 /**
 * The ONE reading of a normalized box against a frame: round, then clamp so
@@ -70574,10 +70916,12 @@ var PackageDropDetector = class {
 				pickupAt: entry.lastConfirmedAt
 			}
 		});
+		const observedAt = collector?.observedAt ?? pickupInstantOf(entry);
 		const draft = {
 			kind: "object",
 			deviceId: entry.deviceId,
 			timestamp,
+			observedAt,
 			source: "pipeline",
 			idempotencyKey: pickedUpKey,
 			trackId: mediaTrackId,
@@ -70629,6 +70973,8 @@ var PackageDropDetector = class {
 				idempotencyKey: pickedUpKey,
 				deliveredEventId: delivered.id,
 				mediaTrackId,
+				observedAt,
+				concludedLagMs: timestamp - observedAt,
 				...collector !== void 0 ? {
 					collectorTrackId: collector.trackId,
 					collectorClassName: collector.className,
@@ -89143,6 +89489,10 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_clip_m
 					readExportBytes: (input) => api.recordingExport.readExportBytes.query(input),
 					deleteExport: (input) => api.recordingExport.deleteExport.mutate(input)
 				}, req),
+				deriveGifFromClip: (req) => deriveRecordedGif(buildRecordedGifPorts({
+					logger: logger.child("RecordedGif"),
+					resolveFfmpeg: () => this.ctx.deps.ensureFfmpeg()
+				}), req),
 				publishArtifact: async (bytes, mime, deviceId) => await this.ncArtifactPlane?.publish(bytes, mime, deviceId) ?? null,
 				viewerUrlBase: async () => pickArtifactBaseUrl(await this.ncEndpoints()),
 				indexArtifact: async (bytes, mime, meta) => await this.ncArtifactPlane?.publishIndexed(bytes, mime, meta) ?? {