@camstack/addon-pipeline 1.1.65 → 1.1.67

package/dist/recorder/index.js

@@ -1,5 +1,5 @@
 const require_chunk = require("../chunk-D6vf50IK.js");
-const require_dist = require("../dist-WW3gH8hF.js");
+const require_dist = require("../dist-BxxVKcnw.js");
 const require_sheet_geometry = require("../sheet-geometry-BR-ip0CP.js");
 const require_model_download_service_Cp9f4dk6 = require("../model-download-service-Cp9f4dk6-Dv-oFwjN.js");
 let node_child_process = require("node:child_process");
@@ -2593,6 +2593,122 @@ function makeBrokerCall(handle) {
 	return (fn) => handle.call(fn, BROKER_READY_TIMEOUT_MS);
 }
 //#endregion
+//#region src/recorder/addon/retention-sweep.ts
+/**
+* Periodic footage-retention sweep (recording-spec §6).
+*
+* The disk-pressure eviction path only fires when a volume is TOO FULL
+* (`shouldSaveDiskSpace` + `minFreePercent`); it never enforces a camera's
+* age/size policy. This sweeper closes that gap: on an hourly cadence it prunes
+* footage for every device whose operator set an actionable `retention` policy,
+* delegating the actual selection + delete to the `recording` cap's
+* `pruneFootage` (which owns the retention FLOOR via `selectEvictions` — this
+* sweeper only decides WHICH devices to prune and WHEN).
+*
+* Owns its own timer + single-flight guard so a slow sweep is never overlapped
+* by the next tick — the same subsystem-owns-its-timer shape as
+* `ThumbnailService`. Pure over injected deps (config read + prune + logger +
+* clock via `setInterval`), so it is unit-testable with fake timers and a mock
+* `prune`. Every pass is best-effort: a per-device prune failure is logged and
+* never aborts the rest, and the sweep never throws.
+*/
+/**
+* True when the operator set an ACTIONABLE retention policy on a device — at
+* least one of `maxAgeDays` / `maxSizeGb` is present and positive. Mirrors the
+* `> 0` guards `selectEvictions` itself applies, so a `0`/absent limit (which
+* inherits the node default = "keep forever") is treated as NO policy and the
+* device is skipped. NEVER prune a device without an explicit policy — that
+* would delete footage the operator never asked to age out.
+*/
+function hasRetentionPolicy(config) {
+	const retention = config.retention;
+	if (!retention) return false;
+	const byAge = retention.maxAgeDays != null && retention.maxAgeDays > 0;
+	const bySize = retention.maxSizeGb != null && retention.maxSizeGb > 0;
+	return byAge || bySize;
+}
+var RetentionSweeper = class {
+	deps;
+	timer = null;
+	/** Single-flight guard: true while a sweep is in flight. */
+	sweeping = false;
+	constructor(deps) {
+		this.deps = deps;
+	}
+	/**
+	* Arm the sweep: run immediately, then on the interval. Idempotent — a second
+	* `start()` while already armed is a no-op. The timer is `unref`'d so it never
+	* keeps the process alive.
+	*/
+	start() {
+		if (this.timer !== null) return;
+		const tick = () => {
+			this.sweep();
+		};
+		tick();
+		this.timer = setInterval(tick, this.deps.intervalMs);
+		this.timer.unref?.();
+	}
+	/** Stop the sweep timer. Idempotent. An in-flight sweep still completes. */
+	stop() {
+		if (this.timer !== null) {
+			clearInterval(this.timer);
+			this.timer = null;
+		}
+	}
+	/**
+	* One retention pass. Single-flighted: a call that fires while a previous
+	* sweep is still running is a no-op. Never throws — a config-read failure
+	* aborts THIS pass (logged); a per-device prune failure is logged and the
+	* sweep continues with the remaining devices.
+	*/
+	async sweep() {
+		if (this.sweeping) {
+			this.deps.logger.debug("recorder: retention sweep already running — skipping this tick");
+			return;
+		}
+		this.sweeping = true;
+		try {
+			let configs;
+			try {
+				configs = await this.deps.readConfigs();
+			} catch (err) {
+				this.deps.logger.warn("recorder: retention sweep could not read device configs", { meta: { error: require_dist.errMsg(err) } });
+				return;
+			}
+			let devicesSwept = 0;
+			let devicesSkipped = 0;
+			let bucketsPruned = 0;
+			let bytesReclaimed = 0;
+			for (const [deviceId, config] of configs) {
+				if (!hasRetentionPolicy(config)) {
+					devicesSkipped += 1;
+					continue;
+				}
+				try {
+					const result = await this.deps.prune(deviceId);
+					devicesSwept += 1;
+					bucketsPruned += result.deletedBuckets;
+					bytesReclaimed += result.reclaimedBytes;
+				} catch (err) {
+					this.deps.logger.warn("recorder: retention prune failed for device", {
+						tags: { deviceId },
+						meta: { error: require_dist.errMsg(err) }
+					});
+				}
+			}
+			this.deps.logger.info("recorder: retention sweep complete", { meta: {
+				devicesSwept,
+				devicesSkipped,
+				bucketsPruned,
+				bytesReclaimed
+			} });
+		} finally {
+			this.sweeping = false;
+		}
+	}
+};
+//#endregion
 //#region src/recorder/addon/recording-hub-host.ts
 /**
 * Resolve the host a REMOTE recording node should use to dial the hub-only
@@ -3599,6 +3715,12 @@ var PLAYBACK_PREFIX = "playback";
 var EXPORTS_PREFIX = "exports";
 /** How often the export janitor sweeps expired exports. */
 var EXPORT_SWEEP_INTERVAL_MS = 5 * 6e4;
+/** How often the retention sweep prunes footage past each camera's per-device
+*  age/size policy. Retention is NOT time-critical (footage ages out over days,
+*  and the disk-pressure eviction path already bounds the worst case), so an
+*  hourly cadence keeps the storage.list/evict cost negligible while honouring
+*  the recording-spec §6 periodic retention. */
+var RETENTION_SWEEP_INTERVAL_MS = 60 * 6e4;
 /** Grace after a completed download before a `deleteAfterDownload` file is removed. */
 var EXPORT_DELETE_GRACE_MS = 6e4;
 /** Only `.mp4` export ids matching this shape are servable (traversal guard). */
@@ -3634,6 +3756,12 @@ var RecorderV2Addon = class extends require_dist.BaseAddon {
 	exportEngine = null;
 	/** Periodic export-expiry sweep timer. Cleared on shutdown. */
 	exportSweepTimer = null;
+	/** The `recording` cap provider — retained so the periodic retention sweep can
+	*  call its `pruneFootage`. Null until built in `onInitialize`. */
+	recordingProvider = null;
+	/** Periodic footage-retention sweep (owns its timer + single-flight guard).
+	*  Constructed + started in `onHubReachable`, stopped on shutdown. */
+	retentionSweeper = null;
 	constructor() {
 		super({ ...DEFAULT_CONFIG });
 	}
@@ -3742,6 +3870,7 @@ var RecorderV2Addon = class extends require_dist.BaseAddon {
 			}
 		};
 		const recordingProvider = buildRecordingProvider(recordingDeps);
+		this.recordingProvider = recordingProvider;
 		const evictableProvider = new StorageEvictableProvider({
 			index: this.index,
 			store: this.segmentStore
@@ -3839,7 +3968,10 @@ var RecorderV2Addon = class extends require_dist.BaseAddon {
 			clearInterval(this.exportSweepTimer);
 			this.exportSweepTimer = null;
 		}
+		this.retentionSweeper?.stop();
+		this.retentionSweeper = null;
 		this.exportEngine = null;
+		this.recordingProvider = null;
 	}
 	/**
 	* Boot hydrate: once the hub is reachable (`ctx.api.*` safe), resolve the
@@ -3898,6 +4030,14 @@ var RecorderV2Addon = class extends require_dist.BaseAddon {
 			this.ctx.logger.warn("recorder: thumbnail service start failed", { meta: { error: require_dist.errMsg(err) } });
 		}
 		await this.bootstrapExports();
+		const provider = this.recordingProvider;
+		if (provider && this.retentionSweeper === null) this.retentionSweeper = new RetentionSweeper({
+			prune: (deviceId) => provider.pruneFootage({ deviceId }),
+			readConfigs: () => readDeviceConfigs(this.configStore()),
+			logger: this.ctx.logger,
+			intervalMs: RETENTION_SWEEP_INTERVAL_MS
+		});
+		this.retentionSweeper?.start();
 	}
 	/**
 	* Resume interrupted exports and arm the expiry sweep. A row left `rendering`

package/dist/recorder/index.mjs

@@ -1,4 +1,4 @@
-import { B as errMsg, D as migrateConfigToBands, I as storageEvictableCapability, K as hydrateSchema, M as recordingCapability, N as recordingExportCapability, P as resolveScrubThumbnailGeometry, Q as selectAssignedProfileSlots, V as BaseAddon, W as DeviceType, ct as record, d as OpsLogEntrySchema, dt as EventCategory, f as RecordingConfigSchema, k as nodePin, l as ExportRecordSchema, lt as string, q as isEvent, s as EVENT_PAD_MS, tt as array } from "../dist-D6tHM9GA.mjs";
+import { B as errMsg, D as migrateConfigToBands, I as storageEvictableCapability, K as hydrateSchema, M as recordingCapability, N as recordingExportCapability, P as resolveScrubThumbnailGeometry, Q as selectAssignedProfileSlots, V as BaseAddon, W as DeviceType, ct as record, d as OpsLogEntrySchema, dt as EventCategory, f as RecordingConfigSchema, k as nodePin, l as ExportRecordSchema, lt as string, q as isEvent, s as EVENT_PAD_MS, tt as array } from "../dist-DkGHtAaK.mjs";
 import { n as computeSheetGeometry, r as resolveHubHostname, t as allTilePlacements } from "../sheet-geometry-DcpuGTCm.mjs";
 import { n as createFileDataPlaneHandler, s as parseRangeHeader, t as contentTypeFor } from "../model-download-service-Cp9f4dk6-CwUb5v3Y.mjs";
 import { spawn } from "node:child_process";
@@ -2590,6 +2590,122 @@ function makeBrokerCall(handle) {
 	return (fn) => handle.call(fn, BROKER_READY_TIMEOUT_MS);
 }
 //#endregion
+//#region src/recorder/addon/retention-sweep.ts
+/**
+* Periodic footage-retention sweep (recording-spec §6).
+*
+* The disk-pressure eviction path only fires when a volume is TOO FULL
+* (`shouldSaveDiskSpace` + `minFreePercent`); it never enforces a camera's
+* age/size policy. This sweeper closes that gap: on an hourly cadence it prunes
+* footage for every device whose operator set an actionable `retention` policy,
+* delegating the actual selection + delete to the `recording` cap's
+* `pruneFootage` (which owns the retention FLOOR via `selectEvictions` — this
+* sweeper only decides WHICH devices to prune and WHEN).
+*
+* Owns its own timer + single-flight guard so a slow sweep is never overlapped
+* by the next tick — the same subsystem-owns-its-timer shape as
+* `ThumbnailService`. Pure over injected deps (config read + prune + logger +
+* clock via `setInterval`), so it is unit-testable with fake timers and a mock
+* `prune`. Every pass is best-effort: a per-device prune failure is logged and
+* never aborts the rest, and the sweep never throws.
+*/
+/**
+* True when the operator set an ACTIONABLE retention policy on a device — at
+* least one of `maxAgeDays` / `maxSizeGb` is present and positive. Mirrors the
+* `> 0` guards `selectEvictions` itself applies, so a `0`/absent limit (which
+* inherits the node default = "keep forever") is treated as NO policy and the
+* device is skipped. NEVER prune a device without an explicit policy — that
+* would delete footage the operator never asked to age out.
+*/
+function hasRetentionPolicy(config) {
+	const retention = config.retention;
+	if (!retention) return false;
+	const byAge = retention.maxAgeDays != null && retention.maxAgeDays > 0;
+	const bySize = retention.maxSizeGb != null && retention.maxSizeGb > 0;
+	return byAge || bySize;
+}
+var RetentionSweeper = class {
+	deps;
+	timer = null;
+	/** Single-flight guard: true while a sweep is in flight. */
+	sweeping = false;
+	constructor(deps) {
+		this.deps = deps;
+	}
+	/**
+	* Arm the sweep: run immediately, then on the interval. Idempotent — a second
+	* `start()` while already armed is a no-op. The timer is `unref`'d so it never
+	* keeps the process alive.
+	*/
+	start() {
+		if (this.timer !== null) return;
+		const tick = () => {
+			this.sweep();
+		};
+		tick();
+		this.timer = setInterval(tick, this.deps.intervalMs);
+		this.timer.unref?.();
+	}
+	/** Stop the sweep timer. Idempotent. An in-flight sweep still completes. */
+	stop() {
+		if (this.timer !== null) {
+			clearInterval(this.timer);
+			this.timer = null;
+		}
+	}
+	/**
+	* One retention pass. Single-flighted: a call that fires while a previous
+	* sweep is still running is a no-op. Never throws — a config-read failure
+	* aborts THIS pass (logged); a per-device prune failure is logged and the
+	* sweep continues with the remaining devices.
+	*/
+	async sweep() {
+		if (this.sweeping) {
+			this.deps.logger.debug("recorder: retention sweep already running — skipping this tick");
+			return;
+		}
+		this.sweeping = true;
+		try {
+			let configs;
+			try {
+				configs = await this.deps.readConfigs();
+			} catch (err) {
+				this.deps.logger.warn("recorder: retention sweep could not read device configs", { meta: { error: errMsg(err) } });
+				return;
+			}
+			let devicesSwept = 0;
+			let devicesSkipped = 0;
+			let bucketsPruned = 0;
+			let bytesReclaimed = 0;
+			for (const [deviceId, config] of configs) {
+				if (!hasRetentionPolicy(config)) {
+					devicesSkipped += 1;
+					continue;
+				}
+				try {
+					const result = await this.deps.prune(deviceId);
+					devicesSwept += 1;
+					bucketsPruned += result.deletedBuckets;
+					bytesReclaimed += result.reclaimedBytes;
+				} catch (err) {
+					this.deps.logger.warn("recorder: retention prune failed for device", {
+						tags: { deviceId },
+						meta: { error: errMsg(err) }
+					});
+				}
+			}
+			this.deps.logger.info("recorder: retention sweep complete", { meta: {
+				devicesSwept,
+				devicesSkipped,
+				bucketsPruned,
+				bytesReclaimed
+			} });
+		} finally {
+			this.sweeping = false;
+		}
+	}
+};
+//#endregion
 //#region src/recorder/addon/recording-hub-host.ts
 /**
 * Resolve the host a REMOTE recording node should use to dial the hub-only
@@ -3596,6 +3712,12 @@ var PLAYBACK_PREFIX = "playback";
 var EXPORTS_PREFIX = "exports";
 /** How often the export janitor sweeps expired exports. */
 var EXPORT_SWEEP_INTERVAL_MS = 5 * 6e4;
+/** How often the retention sweep prunes footage past each camera's per-device
+*  age/size policy. Retention is NOT time-critical (footage ages out over days,
+*  and the disk-pressure eviction path already bounds the worst case), so an
+*  hourly cadence keeps the storage.list/evict cost negligible while honouring
+*  the recording-spec §6 periodic retention. */
+var RETENTION_SWEEP_INTERVAL_MS = 60 * 6e4;
 /** Grace after a completed download before a `deleteAfterDownload` file is removed. */
 var EXPORT_DELETE_GRACE_MS = 6e4;
 /** Only `.mp4` export ids matching this shape are servable (traversal guard). */
@@ -3631,6 +3753,12 @@ var RecorderV2Addon = class extends BaseAddon {
 	exportEngine = null;
 	/** Periodic export-expiry sweep timer. Cleared on shutdown. */
 	exportSweepTimer = null;
+	/** The `recording` cap provider — retained so the periodic retention sweep can
+	*  call its `pruneFootage`. Null until built in `onInitialize`. */
+	recordingProvider = null;
+	/** Periodic footage-retention sweep (owns its timer + single-flight guard).
+	*  Constructed + started in `onHubReachable`, stopped on shutdown. */
+	retentionSweeper = null;
 	constructor() {
 		super({ ...DEFAULT_CONFIG });
 	}
@@ -3739,6 +3867,7 @@ var RecorderV2Addon = class extends BaseAddon {
 			}
 		};
 		const recordingProvider = buildRecordingProvider(recordingDeps);
+		this.recordingProvider = recordingProvider;
 		const evictableProvider = new StorageEvictableProvider({
 			index: this.index,
 			store: this.segmentStore
@@ -3836,7 +3965,10 @@ var RecorderV2Addon = class extends BaseAddon {
 			clearInterval(this.exportSweepTimer);
 			this.exportSweepTimer = null;
 		}
+		this.retentionSweeper?.stop();
+		this.retentionSweeper = null;
 		this.exportEngine = null;
+		this.recordingProvider = null;
 	}
 	/**
 	* Boot hydrate: once the hub is reachable (`ctx.api.*` safe), resolve the
@@ -3895,6 +4027,14 @@ var RecorderV2Addon = class extends BaseAddon {
 			this.ctx.logger.warn("recorder: thumbnail service start failed", { meta: { error: errMsg(err) } });
 		}
 		await this.bootstrapExports();
+		const provider = this.recordingProvider;
+		if (provider && this.retentionSweeper === null) this.retentionSweeper = new RetentionSweeper({
+			prune: (deviceId) => provider.pruneFootage({ deviceId }),
+			readConfigs: () => readDeviceConfigs(this.configStore()),
+			logger: this.ctx.logger,
+			intervalMs: RETENTION_SWEEP_INTERVAL_MS
+		});
+		this.retentionSweeper?.start();
 	}
 	/**
 	* Resume interrupted exports and arm the expiry sweep. A row left `rendering`

package/dist/session-decode/decode-worker-child.js

@@ -6,6 +6,133 @@ let node_fs = require("node:fs");
 node_fs = require_chunk.__toESM(node_fs);
 let node_path = require("node:path");
 node_path = require_chunk.__toESM(node_path);
+//#region src/session-decode/color-conversion.ts
+/**
+* Explicit YUV→RGB colorspace/range resolution for the session-decode worker.
+*
+* WHY THIS EXISTS (RC-5, `docs/superpowers/specs/2026-07-19-track-media-bugs-analysis.md`):
+* an intermittent ~one-GOP DESATURATED stretch was measured on cam 615 — the
+* classic "limited-range YUV interpreted as full-range" signature (lifted
+* blacks, washed color, JPEG size collapse). Root cause: NONE of the decode
+* worker's YUV→RGB conversion sites pinned an explicit colorspace/range, so the
+* conversion depended on whatever `colorspace`/`color_range` metadata each
+* decoded frame happened to carry. A GOP replayed/decoded by a DIFFERENT path
+* (hwaccel-cascade / keyframe-seed fallback, see `docs/design/decode-path.md`)
+* can carry UNSPECIFIED (or a different) range, which the libav auto-inserted
+* converter then guesses differently than its neighbours → one washed-out GOP,
+* then a snap back.
+*
+* The fix is to resolve every frame's source color to an EXPLICIT
+* `(matrix, range)` — using the frame's own tags when present, and a STABLE
+* default (bt709 / limited, the typical H.264/H.265 HD signalling) when they
+* are unspecified — and to pin the conversion to that + full-range RGB output
+* IDENTICALLY at every site. An unspecified/fallback GOP then converts exactly
+* like its neighbours instead of being auto-guessed, so the desaturation cannot
+* recur regardless of which decode path produced the GOP.
+*
+* These functions operate on the raw FFmpeg `AVColorSpace` / `AVColorRange`
+* enum integers (stable ABI values) so they are unit-testable without loading
+* node-av. node-av's branded `AVColorSpace`/`AVColorRange` are `number`
+* subtypes and pass through directly.
+*/
+/**
+* FFmpeg `AVColorSpace` enum values we map to a libswscale/`scale`-filter
+* `in_color_matrix` token. Stable ABI integers (libavutil `pixfmt.h`).
+*/
+var AVCOL_SPC_BT709 = 1;
+var AVCOL_SPC_FCC = 4;
+var AVCOL_SPC_BT470BG = 5;
+var AVCOL_SPC_SMPTE170M = 6;
+var AVCOL_SPC_SMPTE240M = 7;
+var AVCOL_SPC_BT2020_NCL = 9;
+var AVCOL_SPC_BT2020_CL = 10;
+/** FFmpeg `AVColorRange` enum values. Stable ABI integers. */
+var AVCOL_RANGE_MPEG = 1;
+var AVCOL_RANGE_JPEG = 2;
+/**
+* Default source matrix when the frame carries no (or an unusable) colorspace
+* tag — bt709, the near-universal signalling for HD H.264/H.265 IP cameras.
+*/
+var DEFAULT_COLOR_MATRIX = "bt709";
+/**
+* Default source range when the frame carries no (or an unspecified) range tag
+* — limited/mpeg, the near-universal signalling for camera video. Guessing
+* full here is the exact mistake that produced the desaturated GOP.
+*/
+var DEFAULT_COLOR_RANGE = "limited";
+/**
+* Output RGB range — always FULL (0-255). Every RGB conversion site converges
+* on this so downstream media/inference sees a single, path-independent RGB
+* contract.
+*/
+var OUTPUT_RGB_RANGE = "full";
+/** Map an `AVColorSpace` enum integer to a `scale`-filter matrix token. */
+function resolveColorMatrix(colorSpace) {
+	switch (colorSpace) {
+		case AVCOL_SPC_BT709: return "bt709";
+		case AVCOL_SPC_BT470BG:
+		case AVCOL_SPC_SMPTE170M: return "bt601";
+		case AVCOL_SPC_FCC: return "fcc";
+		case AVCOL_SPC_SMPTE240M: return "smpte240m";
+		case AVCOL_SPC_BT2020_NCL:
+		case AVCOL_SPC_BT2020_CL: return "bt2020nc";
+		default: return DEFAULT_COLOR_MATRIX;
+	}
+}
+/** Map an `AVColorRange` enum integer to a `scale`-filter range token. */
+function resolveColorRange(colorRange) {
+	switch (colorRange) {
+		case AVCOL_RANGE_JPEG: return "full";
+		case AVCOL_RANGE_MPEG: return "limited";
+		default: return DEFAULT_COLOR_RANGE;
+	}
+}
+/**
+* Resolve a frame's `(colorSpace, colorRange)` tags to the explicit
+* `(matrix, range)` every conversion site pins — applying the stable defaults
+* when a tag is unspecified/unusable.
+*/
+function resolveSourceColor(colorSpace, colorRange) {
+	return {
+		inColorMatrix: resolveColorMatrix(colorSpace),
+		inRange: resolveColorRange(colorRange),
+		colorSpaceDefaulted: !(colorSpace === AVCOL_SPC_BT709 || colorSpace === AVCOL_SPC_BT470BG || colorSpace === AVCOL_SPC_SMPTE170M || colorSpace === AVCOL_SPC_FCC || colorSpace === AVCOL_SPC_SMPTE240M || colorSpace === AVCOL_SPC_BT2020_NCL || colorSpace === AVCOL_SPC_BT2020_CL),
+		colorRangeDefaulted: !(colorRange === AVCOL_RANGE_JPEG || colorRange === AVCOL_RANGE_MPEG),
+		rawColorSpace: colorSpace,
+		rawColorRange: colorRange
+	};
+}
+/**
+* The `scale`-filter option fragment that pins the explicit YUV→(full)RGB
+* conversion — appended to a `scale=...` filter in the GPU/CPU filtergraph
+* (`scale=W:H:<fragment>` or `scale=<fragment>` for an identity-size convert).
+* Always converges output on full-range RGB; `out_color_matrix` is intentionally
+* omitted (irrelevant for an RGB/gray packed output).
+*/
+function colorConvertFilterOptions(resolved) {
+	return `in_color_matrix=${resolved.inColorMatrix}:in_range=${resolved.inRange}:out_range=${OUTPUT_RGB_RANGE}`;
+}
+/**
+* A stable cache key for the resolved source color — folded into the GPU
+* filtergraph key so a mid-session colorspace/range change rebuilds the graph
+* (and re-emits the provenance transition marker) instead of reusing a graph
+* pinned to the old color.
+*/
+function sourceColorKey(resolved) {
+	return `${resolved.inColorMatrix}:${resolved.inRange}`;
+}
+/**
+* One-line provenance marker: which decode/scale path produced a frame + the
+* (raw and resolved) source color it was converted with. Emitted on a color
+* TRANSITION (rare, diagnostic-gold: pinpoints an intermittent recurrence) and,
+* behind the debug flag, per frame. Includes a trailing newline for `emitStderr`.
+*/
+function colorProvenanceLine(path, resolved, transition) {
+	const spaceTag = resolved.colorSpaceDefaulted ? `${resolved.rawColorSpace}->${resolved.inColorMatrix}(default)` : `${resolved.rawColorSpace}->${resolved.inColorMatrix}`;
+	const rangeTag = resolved.colorRangeDefaulted ? `${resolved.rawColorRange}->${resolved.inRange}(default)` : `${resolved.rawColorRange}->${resolved.inRange}`;
+	return `session-decode color${transition ? " TRANSITION" : ""} {path:${path}, colorSpace:${spaceTag}, colorRange:${rangeTag}, out:rgb-${OUTPUT_RGB_RANGE}}\n`;
+}
+//#endregion
 //#region src/session-decode/crop-geometry.ts
 /** Clamp to [min,max] then floor to the nearest even number (YUV420P chroma is 2x2 subsampled). */
 function clampEven(value, min, max) {
@@ -460,12 +587,18 @@ var NATIVE_LEASE_BUDGET_BYTES = (() => {
 /**
 * TTL (ms) after which a native-frame lease is treated as a miss and reclaimed.
 * The backstop that bounds in-flight RAM even if the explicit `releaseNativeLease`
-* is dropped — comfortably longer than the detection inference + crop round-trip
-* (~40-200ms). `CAMSTACK_SESSION_NATIVE_LEASE_TTL_MS` (default 500).
+* is dropped. Must comfortably exceed the FULL late-crop horizon: detection
+* inference + the cross-process inference-result hop to hub post-analysis +
+* tracking + the tRPC crop round-trip back — on a busy camera with many
+* concurrent tracks that is well past the old 500 ms (which the busiest cameras'
+* subject crops outran, missing to the ≤640 fallback). Raised to 1200 ms; still
+* bounded by the per-session {@link NATIVE_LEASE_BUDGET_BYTES} ceiling and the
+* {@link NATIVE_LEASE_ACTIVITY_WINDOW_MS} demand gate, so idle cameras retain
+* nothing. `CAMSTACK_SESSION_NATIVE_LEASE_TTL_MS` (default 1200).
 */
 var NATIVE_LEASE_TTL_MS = (() => {
 	const raw = Number(process.env["CAMSTACK_SESSION_NATIVE_LEASE_TTL_MS"]);
-	return Number.isFinite(raw) && raw > 0 ? Math.floor(raw) : 500;
+	return Number.isFinite(raw) && raw > 0 ? Math.floor(raw) : 1200;
 })();
 /**
 * Demand window (ms) for the lease-capture {@link LeaseActivityGate}: eager
@@ -632,9 +765,10 @@ function backendToHwDeviceConst(backend, consts) {
 * It is correct and never crashes; it just forgoes the GPU win for that rare
 * call — exactly the safety/behaviour trade-off the task calls for.
 */
-function buildGpuFilterDescription(scaleFilter, region, target, fullFrame, pixel) {
-	if (fullFrame) return `${scaleFilter}=w=${target.width}:h=${target.height},hwdownload,format=nv12,format=${pixel}`;
-	return `hwdownload,format=nv12,crop=${region.width}:${region.height}:${region.left}:${region.top},scale=${target.width}:${target.height},format=${pixel}`;
+function buildGpuFilterDescription(scaleFilter, region, target, fullFrame, pixel, color) {
+	const convert = `scale=${colorConvertFilterOptions(color)}`;
+	if (fullFrame) return `${scaleFilter}=w=${target.width}:h=${target.height},hwdownload,format=nv12,${convert},format=${pixel}`;
+	return `hwdownload,format=nv12,crop=${region.width}:${region.height}:${region.left}:${region.top},scale=${target.width}:${target.height}:${colorConvertFilterOptions(color)},format=${pixel}`;
 }
 /**
 * Copy a single-plane packed frame (rgb24 / gray8 out of the filtergraph) into
@@ -765,6 +899,15 @@ var DecodeWorkerChild = class {
 	/** Throttled native-crop hit/miss counters, emitted with the throughput line. */
 	nativeCropHits = 0;
 	nativeCropMisses = 0;
+	/**
+	* Last `(path, rawColorSpace, rawColorRange)` provenance key emitted — a
+	* change re-emits a one-line TRANSITION marker (RC-5 diagnostic: pinpoints an
+	* intermittent desaturation recurrence by showing the exact GOP whose color
+	* tags drifted). See {@link logColorProvenance}.
+	*/
+	lastColorProvenanceKey = "";
+	/** Per-frame color provenance logging (opt-in; the transition marker is always on). */
+	colorDebug = process.env["CAMSTACK_DECODE_COLOR_DEBUG"] === "1";
 	/** Scrypted-style throughput counters (plain integers, no per-frame allocation). */
 	framesDecoded = 0;
 	/** Child-side skips only (HW-guard drops + probe/degrade frees); slot drops add {@link FrameSlot.droppedCount}. */
@@ -965,6 +1108,28 @@ var DecodeWorkerChild = class {
 		return this.nativeRing.get(frameId) ?? this.frames.toBuffer(frameId);
 	}
 	/**
+	* Resolve a decoded frame's `(colorSpace, colorRange)` tags to the EXPLICIT
+	* `(matrix, range)` every RGB conversion site pins — the RC-5 fix. `colorSpace`
+	* / `colorRange` are node-av branded `number` subtypes, so they pass to the
+	* plain-number helper directly.
+	*/
+	resolveFrameColor(frame) {
+		return resolveSourceColor(frame.colorSpace, frame.colorRange);
+	}
+	/**
+	* Emit the color-provenance marker: which decode/scale path produced this
+	* frame + its raw and resolved source color. Always logs on a TRANSITION (the
+	* path or the frame's raw color tags changed vs the last emit — rare, and the
+	* exact signal a desaturation recurrence leaves); logs every frame only under
+	* the `CAMSTACK_DECODE_COLOR_DEBUG` flag.
+	*/
+	logColorProvenance(path, color) {
+		const key = `${path}|${color.rawColorSpace}|${color.rawColorRange}`;
+		const transition = key !== this.lastColorProvenanceKey;
+		if (transition) this.lastColorProvenanceKey = key;
+		if (transition || this.colorDebug) this.emitStderr(colorProvenanceLine(path, color, transition));
+	}
+	/**
 	* Retain a just-superseded DELIVERED frame for later native crops. Transfers
 	* ownership from the {@link FrameSlot} (the caller MUST NOT free when this
 	* returns `true`).
@@ -1047,6 +1212,7 @@ var DecodeWorkerChild = class {
 		const nav = this.nav;
 		const C = this.consts;
 		if (!nav || !C) throw new Error("node-av not initialized");
+		this.logColorProvenance("sw-crop", this.resolveFrameColor(frame));
 		const { region, target } = resolved;
 		const planes = frame.data;
 		const strides = frame.linesize;
@@ -1085,7 +1251,9 @@ var DecodeWorkerChild = class {
 	*/
 	nativeHwCropToBuffer(frame, resolved) {
 		const { region, target } = resolved;
-		const outputs = this.ensureNativeCropHwFilter(region, target).processAllSync(frame);
+		const color = this.resolveFrameColor(frame);
+		this.logColorProvenance("hw-crop", color);
+		const outputs = this.ensureNativeCropHwFilter(region, target, color).processAllSync(frame);
 		const first = outputs[0];
 		if (!first) {
 			for (const out of outputs) out.free();
@@ -1119,17 +1287,17 @@ var DecodeWorkerChild = class {
 		return scaler;
 	}
 	/** Build-once / reuse the dedicated native-crop GPU filtergraph (rgb out). */
-	ensureNativeCropHwFilter(region, target) {
+	ensureNativeCropHwFilter(region, target, color) {
 		const nav = this.nav;
 		const scaleFilter = this.gpuScaleFilter;
 		if (!nav || !scaleFilter || !this.hwContext) throw new Error("decode-worker-child: native GPU crop requested without a HW context");
-		const key = `${region.left},${region.top},${region.width},${region.height}->${target.width}x${target.height}`;
+		const key = `${region.left},${region.top},${region.width},${region.height}->${target.width}x${target.height}:${sourceColorKey(color)}`;
 		const cached = this.nativeCropHwFilter;
 		if (cached && key === this.nativeCropHwFilterKey) return cached;
 		this.nativeCropHwFilter?.close();
 		this.nativeCropHwFilter = null;
 		this.nativeCropHwFilterKey = "";
-		const description = buildGpuFilterDescription(scaleFilter, region, target, false, "rgb24");
+		const description = buildGpuFilterDescription(scaleFilter, region, target, false, "rgb24", color);
 		const filter = nav.FilterAPI.create(description, { hardware: this.hwContext });
 		this.nativeCropHwFilter = filter;
 		this.nativeCropHwFilterKey = key;
@@ -1338,6 +1506,7 @@ var DecodeWorkerChild = class {
 		const format = opts?.format ?? this.sessionFormat;
 		const dstFmt = format === "gray" ? C.AV_PIX_FMT_GRAY8 : C.AV_PIX_FMT_RGB24;
 		const channels = format === "gray" ? 1 : 3;
+		this.logColorProvenance(isFullFrameRegion(region, frame.width, frame.height) ? "sw-fullframe" : "sw-crop", this.resolveFrameColor(frame));
 		const planes = frame.data;
 		const strides = frame.linesize;
 		const yPlane = planes?.[0];
@@ -1409,7 +1578,9 @@ var DecodeWorkerChild = class {
 			const target = resolveResizeTarget(region.width, region.height, opts?.resize);
 			const format = opts?.format ?? this.sessionFormat;
 			const channels = format === "gray" ? 1 : 3;
-			const outputs = this.ensureHwFilter(region, target, frame.width, frame.height, format).processAllSync(frame);
+			const color = this.resolveFrameColor(frame);
+			this.logColorProvenance(isFullFrameRegion(region, frame.width, frame.height) ? "hw-fullframe" : "hw-crop", color);
+			const outputs = this.ensureHwFilter(region, target, frame.width, frame.height, format, color).processAllSync(frame);
 			const first = outputs[0];
 			if (!first) throw new Error("GPU filtergraph produced no frame");
 			try {
@@ -1431,19 +1602,19 @@ var DecodeWorkerChild = class {
 	* only when the key changes; detection's ROI + resize target are stable, so
 	* this is a per-worker singleton in the steady state.
 	*/
-	ensureHwFilter(region, target, srcW, srcH, format) {
+	ensureHwFilter(region, target, srcW, srcH, format, color) {
 		const nav = this.nav;
 		const scaleFilter = this.gpuScaleFilter;
 		if (!nav || !scaleFilter || !this.hwContext) throw new Error("decode-worker-child: GPU filter requested without a HW context");
 		const fullFrame = isFullFrameRegion(region, srcW, srcH);
 		const pixel = pixelFilterName(format);
-		const key = `${region.left},${region.top},${region.width},${region.height}->${target.width}x${target.height}:${pixel}`;
+		const key = `${region.left},${region.top},${region.width},${region.height}->${target.width}x${target.height}:${pixel}:${sourceColorKey(color)}`;
 		const cached = this.hwFilter;
 		if (cached && key === this.hwFilterKey) return cached;
 		this.hwFilter?.close();
 		this.hwFilter = null;
 		this.hwFilterKey = "";
-		const description = buildGpuFilterDescription(scaleFilter, region, target, fullFrame, pixel);
+		const description = buildGpuFilterDescription(scaleFilter, region, target, fullFrame, pixel, color);
 		const filter = nav.FilterAPI.create(description, { hardware: this.hwContext });
 		this.hwFilter = filter;
 		this.hwFilterKey = key;