@camstack/addon-pipeline 1.1.56 → 1.1.57

package/dist/stream-broker/index.mjs

@@ -1,10 +1,8 @@
 import { t as __require } from "../chunk-BdkLduGY.mjs";
-import { $ as boolean, B as DeviceType, D as nodePin, F as webrtcSessionCapability, G as makeProfileBrokerId, H as createEvent, I as errMsg, J as parseProfileBrokerId, K as makeSourceBrokerId, L as BaseAddon, N as streamBrokerCapability, Q as array, R as CAM_PROFILE_ORDER, V as EventCategory, W as isEvent, Z as _enum, at as record, c as EncodeProfileSchema, d as RingBuffer, et as discriminatedUnion, g as cameraStreamsCapability, it as object, nt as literal, ot as string, p as addonWidgetsSourceCapability, rt as number, st as union, w as maskUrlCredentials, z as DeviceFeature } from "../dist-CrjLGrkj.mjs";
-import { a as DecoderSessionProxy, i as FrameHandlePlane, r as profileForStreamId } from "../remote-source-plane-B28iGi7h.mjs";
-import { t as createFileDataPlaneHandler } from "../model-download-service-C-IHWnXx-BPy6aoAx.mjs";
+import { $ as boolean, B as DeviceType, D as nodePin, F as webrtcSessionCapability, G as makeProfileBrokerId, H as createEvent, I as errMsg, J as parseProfileBrokerId, K as makeSourceBrokerId, L as BaseAddon, N as streamBrokerCapability, Q as array, R as CAM_PROFILE_ORDER, V as EventCategory, W as isEvent, Z as _enum, at as record, c as EncodeProfileSchema, d as RingBuffer, et as discriminatedUnion, g as cameraStreamsCapability, it as object, nt as literal, ot as string, p as addonWidgetsSourceCapability, rt as number, st as union, w as maskUrlCredentials, z as DeviceFeature } from "../dist-CL531uVA.mjs";
+import { n as profileForStreamId } from "../remote-restream-BeHi78PZ.mjs";
+import { t as createFileDataPlaneHandler } from "../model-download-service-C-IHWnXx-3Mmeob3l.mjs";
 import { createRequire } from "node:module";
-import * as crypto$1 from "node:crypto";
-import crypto, { createHash, randomBytes, randomUUID } from "node:crypto";
 import { spawn } from "node:child_process";
 import { pathToFileURL } from "node:url";
 import * as fs from "node:fs";
@@ -12,6 +10,8 @@ import * as path$1 from "node:path";
 import path, { join } from "node:path";
 import * as os from "node:os";
 import { networkInterfaces, tmpdir } from "node:os";
+import * as crypto$1 from "node:crypto";
+import crypto, { createHash, randomBytes, randomUUID } from "node:crypto";
 import { lookup } from "node:dns/promises";
 import * as net$1 from "node:net";
 import net from "node:net";
@@ -9070,6 +9070,787 @@ var EncodedRingBuffer = class {
 	}
 };
 //#endregion
+//#region src/stream-broker/stream-broker/decoder-session-proxy.ts
+/**
+* Long-poll window handed to `pullFrames`/`pullHandles`: an empty drain blocks
+* decoder-side until a frame commits or this elapses, replacing the old ~1kHz
+* `setTimeout(…,1)` busy-spin with a single await-notify round-trip. Kept
+* modest so a hung UDS/Moleculer transport can't pin the call; the decoder
+* cancels the waiter on `destroySession` so teardown never waits it out.
+*/
+var POLL_WAIT_MS = 50;
+var DecoderSessionProxy = class {
+	api;
+	sessionId;
+	polling = false;
+	constructor(api, sessionId) {
+		this.api = api;
+		this.sessionId = sessionId;
+	}
+	async pushPacket(packet) {
+		await this.api.pushPacket({
+			sessionId: this.sessionId,
+			packet
+		});
+	}
+	async openStream(url) {
+		await this.api.openStream({
+			sessionId: this.sessionId,
+			url
+		});
+	}
+	async startPolling(onFrame) {
+		this.polling = true;
+		while (this.polling) {
+			const frames = await this.api.pullFrames({
+				sessionId: this.sessionId,
+				maxCount: 4,
+				waitMs: POLL_WAIT_MS
+			});
+			for (const frame of frames) onFrame(frame);
+		}
+	}
+	/**
+	* Poll a `frameSink: 'shm'` session for `FrameHandle`s (Phase 5 / D9).
+	* Mirrors `startPolling` but drains `pullHandles` — the decoder has
+	* already written the pixels into a shared-memory ring, so what crosses
+	* the cap boundary is the tiny serialisable handle. Runs until
+	* `stopPolling`, `destroy`, or the session is destroyed externally.
+	*
+	* When the decoder reports the session is gone (`unknown sessionId` /
+	* `Service … not found`) the loop exits gracefully — those errors are
+	* expected during decoder restart/shutdown and must not be re-thrown to
+	* the caller's `.catch()` handler, which would otherwise spin forever.
+	*/
+	async startHandlePolling(onHandle) {
+		this.polling = true;
+		while (this.polling) try {
+			const handles = await this.api.pullHandles({
+				sessionId: this.sessionId,
+				maxCount: 4,
+				waitMs: POLL_WAIT_MS
+			});
+			for (const handle of handles) onHandle(handle);
+		} catch (err) {
+			this.polling = false;
+			const msg = err instanceof Error ? err.message : String(err);
+			if (!msg.includes("unknown sessionId") && !msg.includes("Service") && !msg.includes("not found")) throw err;
+			return;
+		}
+	}
+	stopPolling() {
+		this.polling = false;
+	}
+	async updateConfig(config) {
+		await this.api.updateConfig({
+			sessionId: this.sessionId,
+			config
+		});
+	}
+	async getStats() {
+		return this.api.getStats({ sessionId: this.sessionId });
+	}
+	async destroy() {
+		this.stopPolling();
+		await this.api.destroySession({ sessionId: this.sessionId });
+	}
+};
+//#endregion
+//#region src/stream-broker/stream-broker/frame-handle-plane.ts
+/**
+* `FrameHandlePlane` — the broker's shared-memory frame-handle surface
+* (Phase 5 / D9).
+*
+* This is the handle-based replacement for `StreamBroker.onDecodedFrame`'s
+* live-object callback path. Instead of fanning pixel `DecodedFrame`s out to
+* in-process callbacks (which cannot cross a process boundary), the broker
+* publishes zero-pixel, serialisable `FrameHandle`s a consumer drains over
+* tRPC and reads back from a shared-memory ring with a `FrameRingReader`.
+*
+* ## Ring-per-format model
+*
+* A `frameSink: 'shm'` decoder session produces exactly ONE pixel format
+* (the decoder's scaler is configured for it). The broker therefore keeps
+* one decoder session — hence one shm ring — per `(brokerId, format)` that a
+* consumer actually subscribes to:
+*
+*   - motion subscribes `gray`  → one `gray` decoder session + ring
+*   - detection subscribes `rgb` → one `rgb` decoder session + ring
+*
+* Only the formats consumers ask for are materialised. There is NO
+* broker-side `sharp` conversion any more — each consumer reads the exact
+* format it requested. A session is reference-counted by its subscriber set
+* and torn down when the last subscriber of that format leaves.
+*
+* ## fps throttling
+*
+* Throttling is implicit: the ring is latest-wins, so a slow consumer that
+* polls `pullFrameHandles` infrequently simply receives the newest handles
+* and the intervening frames are dropped at the ring (a recycled slot the
+* consumer never read). The optional `maxFps` from `subscribeFrames` is NOT
+* enforced here — it is echoed back to the consumer as a reader-side polling
+* cadence hint.
+*
+* ## Packet feed
+*
+* The plane's decoder sessions are push-mode by default: the broker forwards
+* every video `EncodedPacket` to `pushPacket`. For a pull-mode decoder the
+* broker supplies a `pullModeUrl` and the plane calls `openStream` once the
+* session exists.
+*/
+/**
+* Collapse a hierarchical Moleculer nodeID (`hub/child-abc`) to its owning
+* node (`hub`). Frame-plane co-location only cares about the physical node, not
+* which forked child within it hosts the session.
+*/
+function collapseNodeId(nodeId) {
+	const slash = nodeId.indexOf("/");
+	return slash >= 0 ? nodeId.slice(0, slash) : nodeId;
+}
+/**
+* Decide whether a decoder session created on `decoderNodeId` is co-located
+* with the broker whose local node is `brokerNodeId`.
+*
+* The broker's shm frame ring is NODE-LOCAL: a decoder session on any other
+* node can never deliver frame handles to this broker's consumers, so a
+* mis-placed session must be rejected. Both ids are collapsed (`hub/child`→
+* `hub`) before comparison.
+*
+* A `null` `brokerNodeId` means the broker's own node is unknown — enforcement
+* is skipped (legacy behavior, accept any placement).
+*/
+function isDecoderNodeColocated(brokerNodeId, decoderNodeId) {
+	if (brokerNodeId === null) return true;
+	return collapseNodeId(brokerNodeId) === collapseNodeId(decoderNodeId);
+}
+/** Per-subscription handle-queue capacity. A handle is tiny; 64 absorbs a
+*  burst between two `pullFrameHandles` polls without unbounded growth. */
+var HANDLE_QUEUE_CAPACITY = 64;
+/** Default reader-side cadence hint when a subscriber omits `maxFps`. */
+var DEFAULT_HINT_FPS = 5;
+/** Rolling window for the aggregate `decodeFps` rate, ms. Mirrors the
+*  broker's 2s `inputFps` window so the two stats are comparable. */
+var DECODE_FPS_WINDOW_MS = 2e3;
+/**
+* Keep-warm grace before a decoder session with no subscribers is torn down.
+*
+* Subscribers flap on ~30s cadences (occupancy recheck bursts, detection
+* motion-gating watch↔active, onboard gray gating). Destroying the
+* ffmpeg/VAAPI decode session the instant the last subscriber leaves spawns +
+* destroys a full session every cycle — wasted setup/teardown. Chosen >30s so
+* consecutive bursts and watch↔active flips reuse the warm session, yet a
+* genuinely idle session still frees its ffmpeg within ~a minute.
+*/
+var SESSION_LINGER_MS = 45e3;
+/**
+* Short keep-warm grace for a PURE-OCCUPANCY session (every remaining
+* subscriber is a periodic on-motion occupancy recheck, tag `'occupancy'`).
+*
+* Occupancy rechecks subscribe to decoded frames for ~1s every ~30s. The
+* normal `SESSION_LINGER_MS` (45s) EXCEEDS that ~30s interval, so the linger
+* timer is perpetually cancelled by the next recheck before it can fire — the
+* decoder never tears down and decodes continuously at source-rate to serve a
+* 1s/30s consumer (~30x wasted decode; multiplied across cameras this is the
+* iGPU baseline that saturated the decoder). A pure-occupancy session instead
+* tears down between polls: short enough to fire well before the next ~30s
+* recheck, long enough to absorb the ~1s poll plus minor jitter. Re-dial is
+* cheap on GPU-scale decode and the restream burst re-primes the live edge
+* fast, so on-demand re-arm on the next recheck is fine.
+*/
+var OCCUPANCY_LINGER_MS = 5e3;
+/** Subscription tag emitted by the periodic on-motion occupancy recheck. A
+*  session whose subscribers have only ever carried this tag gets the short
+*  `OCCUPANCY_LINGER_MS` teardown; any other subscriber biases to the long
+*  `SESSION_LINGER_MS` warm linger (interactive viewers, detection, motion). */
+var OCCUPANCY_TAG = "occupancy";
+/**
+* Default retry cooldown after a decoder session lands on a NON-LOCAL node
+* (see `FrameHandlePlaneOptions.sessionRetryCooldownMs`). Long enough to
+* turn a per-packet storm into a slow probe; short enough that the plane
+* recovers within seconds once the local decoder respawns.
+*/
+var SESSION_RETRY_COOLDOWN_MS = 1e4;
+/**
+* Owns the broker's shared-memory frame-handle subscriptions and the
+* per-format `frameSink: 'shm'` decoder sessions that feed them.
+*/
+var FrameHandlePlane = class {
+	decoderApi;
+	logger;
+	resolveStreamInfo;
+	localNodeId;
+	sessionRetryCooldownMs;
+	getSeedPackets;
+	isDebugEnabled;
+	subscriptions = /* @__PURE__ */ new Map();
+	sessions = /* @__PURE__ */ new Map();
+	/** Per-format retry gate set when a session lands on a non-local node:
+	*  `ensureSession` skips creation until the epoch-ms deadline passes. */
+	sessionRetryCooldownUntil = /* @__PURE__ */ new Map();
+	/** In-flight `ensureSession` creation per format. Coalesces concurrent
+	*  same-format callers onto ONE decoder session — without it two callers
+	*  both pass the `sessions.get` check, both `createSession` (two ffmpeg),
+	*  and the second registration orphans the first with no `destroySession`. */
+	sessionCreating = /* @__PURE__ */ new Map();
+	disposed = false;
+	/** Re-entrancy guard for `armPendingSessions` — collapses the per-packet
+	*  `pushPacket` calls into a single in-flight deferred-arm pass. */
+	armInFlight = false;
+	/** DIAG(592): P-frames skipped on an un-bootstrapped session before its
+	*  first live keyframe. Reset when a keyframe bootstraps the session. */
+	unbootstrappedSkips = 0;
+	/** Aggregate decoded-frame rate state — frames fanned out in the current
+	*  rolling window, the window's start epoch, and the last computed fps. */
+	framesInWindow = 0;
+	windowStartMs = Date.now();
+	decodedFps = 0;
+	constructor(options) {
+		this.decoderApi = options.decoderApi;
+		this.logger = options.logger;
+		this.resolveStreamInfo = options.resolveStreamInfo;
+		this.localNodeId = options.localNodeId;
+		this.sessionRetryCooldownMs = options.sessionRetryCooldownMs ?? SESSION_RETRY_COOLDOWN_MS;
+		this.getSeedPackets = options.getSeedPackets;
+		this.isDebugEnabled = options.isDebugEnabled;
+	}
+	/** Number of active handle subscriptions — surfaced for diagnostics. */
+	get subscriberCount() {
+		return this.subscriptions.size;
+	}
+	/**
+	* Moleculer nodeIDs of the decoder providers currently hosting this plane's
+	* `frameSink: 'shm'` sessions. Used by the broker-manager's per-agent
+	* hwaccel-change handler to decide which brokers need a decoder rotation.
+	*/
+	decoderNodeIds() {
+		const ids = [];
+		for (const session of this.sessions.values()) if (session.nodeId) ids.push(session.nodeId);
+		return ids;
+	}
+	/**
+	* Rotate every shm decoder session hosted on `agentNodeId` — destroy and
+	* rebuild it so the new session re-pulls the latest per-agent decoder
+	* preferences (hwaccel backend, …). Subscriptions are preserved: the same
+	* `subscriptionId`s read from the rebuilt session's fresh ring. A no-op for
+	* sessions on other nodes. Returns the number of sessions rotated.
+	*/
+	async rotate(agentNodeId, reason) {
+		if (this.disposed) return 0;
+		let rotated = 0;
+		for (const session of this.sessions.values()) {
+			if ((session.nodeId && session.nodeId.includes("/") ? session.nodeId.split("/")[0] : session.nodeId) !== agentNodeId) continue;
+			this.logger?.info("frame-handle plane: rotating shm decoder session", { meta: {
+				format: session.format,
+				reason,
+				nodeId: session.nodeId
+			} });
+			await this.destroySession(session);
+			let restarted = false;
+			try {
+				restarted = await this.startSessionDecoder(session);
+			} finally {
+				if (!restarted) this.sessions.delete(session.format);
+			}
+			if (restarted) rotated += 1;
+		}
+		return rotated;
+	}
+	/**
+	* Register a frame-handle subscription. Spins up (or reuses) a
+	* `frameSink: 'shm'` decoder session producing `format`. The returned
+	* `subscriptionId` is the handle the consumer passes to
+	* `pullFrameHandles` / `unsubscribe`.
+	*/
+	async subscribe(input) {
+		if (this.disposed) throw new Error("FrameHandlePlane: subscribe after dispose");
+		const subscriptionId = `fh-${randomUUID()}`;
+		const maxFps = input.maxFps !== void 0 && input.maxFps > 0 ? input.maxFps : DEFAULT_HINT_FPS;
+		const subscription = {
+			id: subscriptionId,
+			format: input.format,
+			maxFps,
+			tag: input.tag ?? "unknown",
+			subscribedAt: Date.now(),
+			queue: new RingBuffer(HANDLE_QUEUE_CAPACITY),
+			framesDelivered: 0
+		};
+		this.subscriptions.set(subscriptionId, subscription);
+		await this.ensureSession(input.format, subscriptionId);
+		this.reconcileSessionFps(input.format);
+		this.logger?.info("frame-handle subscription added", { meta: {
+			subscriptionId,
+			format: input.format,
+			tag: subscription.tag,
+			maxFps
+		} });
+		return {
+			subscriptionId,
+			maxFps
+		};
+	}
+	/**
+	* The emit `maxFps` a format's decoder session should run at — the MAX of all
+	* current subscribers' `maxFps` for that format (fallback `DEFAULT_HINT_FPS`
+	* when none, e.g. mid-teardown). The decoder emits at this rate; each
+	* subscriber then down-samples to its own `maxFps` on read (latest-wins).
+	*/
+	computeFormatFps(format) {
+		let max = 0;
+		for (const sub of this.subscriptions.values()) if (sub.format === format && sub.maxFps > max) max = sub.maxFps;
+		return max > 0 ? max : DEFAULT_HINT_FPS;
+	}
+	/**
+	* Recompute a format session's emit `maxFps` after a subscriber joins/leaves
+	* and push it to the live decoder via `updateConfig` when it changed — so the
+	* decoder emits only as fast as the busiest reader needs (saving the
+	* scale+convert+shm-write for frames nobody reads).
+	*/
+	reconcileSessionFps(format) {
+		const session = this.sessions.get(format);
+		if (!session || !session.proxy) return;
+		const target = this.computeFormatFps(format);
+		if (target === session.targetFps) return;
+		session.targetFps = target;
+		session.proxy.updateConfig({ maxFps: target }).catch((err) => {
+			this.logger?.warn("frame-handle plane: updateConfig(maxFps) failed", { meta: {
+				format,
+				maxFps: target,
+				error: errMsg(err)
+			} });
+		});
+	}
+	/**
+	* Drain up to `maxCount` `FrameHandle`s for a subscription, latest-wins.
+	* An unknown subscription id returns `[]` (the consumer may have been
+	* torn down concurrently).
+	*/
+	pullHandles(subscriptionId, maxCount) {
+		const subscription = this.subscriptions.get(subscriptionId);
+		if (!subscription) return [];
+		const stale = subscription.queue.size - maxCount;
+		if (stale > 0) subscription.queue.drain(stale);
+		const handles = subscription.queue.drain(maxCount);
+		subscription.framesDelivered += handles.length;
+		return handles;
+	}
+	/**
+	* Release a subscription. When it was the last reader of its format the
+	* underlying decoder session is destroyed (and its shm segment unlinked
+	* by the decoder). Returns `true` when a known subscription was released.
+	*/
+	async unsubscribe(subscriptionId, immediate = false) {
+		const subscription = this.subscriptions.get(subscriptionId);
+		if (!subscription) return false;
+		this.subscriptions.delete(subscriptionId);
+		const session = this.sessions.get(subscription.format);
+		if (session) {
+			session.subscriberIds.delete(subscriptionId);
+			if (session.subscriberIds.size === 0) if (immediate) {
+				this.clearLinger(session);
+				this.sessions.delete(subscription.format);
+				await this.destroySession(session);
+			} else this.scheduleLinger(session);
+			else this.reconcileSessionFps(subscription.format);
+		}
+		this.logger?.info("frame-handle subscription removed", { meta: {
+			subscriptionId,
+			format: subscription.format
+		} });
+		return true;
+	}
+	/**
+	* Arm the keep-warm teardown timer for a session whose last subscriber just
+	* left. Clears any existing timer first (idempotent). On fire it re-checks
+	* `subscriberIds.size === 0` — a subscriber may have returned in the interim,
+	* in which case the timer is a no-op — and only then removes the session and
+	* destroys the decoder. The timer is `unref`'d so a lingering warm session
+	* never keeps the process alive.
+	*/
+	scheduleLinger(session) {
+		this.clearLinger(session);
+		const occupancyOnly = !session.hasNonOccupancySubscriberEver;
+		const lingerMs = occupancyOnly ? OCCUPANCY_LINGER_MS : SESSION_LINGER_MS;
+		this.logger?.debug(occupancyOnly ? "frame-handle plane: short occupancy linger scheduled" : "frame-handle plane: keep-warm linger scheduled", { meta: {
+			format: session.format,
+			lingerMs,
+			occupancyOnly
+		} });
+		const timer = setTimeout(() => {
+			session.lingerTimer = null;
+			if (session.subscriberIds.size > 0) return;
+			this.sessions.delete(session.format);
+			this.destroySession(session).catch(() => {});
+		}, lingerMs);
+		timer.unref?.();
+		session.lingerTimer = timer;
+	}
+	/**
+	* Latch `session.hasNonOccupancySubscriberEver` when the subscription
+	* `subscriptionId` carries any tag other than `OCCUPANCY_TAG`. Called at
+	* every point a subscription is attached to a session so the keep-warm
+	* decision only fast-tears-down sessions that have been PURELY on-demand
+	* occupancy rechecks. Unknown ids (mid-teardown) are ignored.
+	*/
+	noteSessionSubscriberTag(session, subscriptionId) {
+		const subscription = this.subscriptions.get(subscriptionId);
+		if (subscription && subscription.tag !== OCCUPANCY_TAG) session.hasNonOccupancySubscriberEver = true;
+	}
+	/** Cancel a session's pending keep-warm teardown timer, if any. */
+	clearLinger(session) {
+		if (session.lingerTimer) {
+			clearTimeout(session.lingerTimer);
+			session.lingerTimer = null;
+		}
+	}
+	/**
+	* Forward a video `EncodedPacket` to every active shm decoder session.
+	* Push-mode decoders consume this; a pull-mode decoder ignores it (it
+	* reads its own pipe via `openStream`). Audio packets are not forwarded.
+	*
+	* The packet feed doubles as the plane's stream-ready signal: the broker
+	* only calls `pushPacket` once it has a source and the first keyframe has
+	* landed — exactly the point `resolveStreamInfo` starts returning a
+	* descriptor. Each packet therefore triggers `armPendingSessions`, which
+	* re-attempts session creation for any deferred subscription so a lone
+	* first subscriber on a not-yet-started broker self-arms without a
+	* redundant re-`subscribe`.
+	*/
+	pushPacket(packet) {
+		if (this.disposed || packet.type !== "video") return;
+		this.armPendingSessions(packet).catch((err) => {
+			this.logger?.warn("frame-handle plane: arm pending sessions error", { meta: { error: errMsg(err) } });
+		});
+		this.feedSessions(packet);
+	}
+	/** Forward a video `EncodedPacket` to every live PUSH-mode shm decoder session. */
+	feedSessions(packet) {
+		for (const session of this.sessions.values()) {
+			if (!session.proxy) continue;
+			if (session.pullMode) continue;
+			if (!session.bootstrapped) {
+				if (!packet.keyframe) {
+					this.unbootstrappedSkips = (this.unbootstrappedSkips ?? 0) + 1;
+					continue;
+				}
+				this.logger?.debug("frame-handle plane: session bootstrapped from live keyframe", { meta: {
+					format: session.format,
+					pFramesSkippedBefore: this.unbootstrappedSkips ?? 0
+				} });
+				this.unbootstrappedSkips = 0;
+				session.bootstrapped = true;
+			}
+			session.proxy.pushPacket(packet).catch((err) => {
+				const msg = errMsg(err);
+				this.logger?.warn("frame-handle plane: decoder push error", { meta: {
+					format: session.format,
+					error: msg
+				} });
+				if (msg.includes("unknown sessionId") || msg.includes("Service") || msg.includes("not found")) {
+					this.logger?.info("frame-handle plane: invalidating stale proxy", { meta: { format: session.format } });
+					this.destroySession(session).catch(() => {});
+					this.sessions.delete(session.format);
+				}
+			});
+		}
+	}
+	/**
+	* Re-attempt session creation for every subscription whose format has no
+	* live `FormatSession` yet — the subscriptions whose `startSessionDecoder`
+	* was deferred because the broker had no stream at `subscribe` time. Driven
+	* off the `pushPacket` feed (event-driven, no polling timer); a no-op once
+	* every subscribed format already owns a session.
+	*
+	* `armInFlight` collapses re-entrant calls: `pushPacket` fires per packet,
+	* but `ensureSession` is async — without the guard a burst of packets would
+	* launch overlapping decoder-creation round-trips for the same format.
+	*
+	* `triggerPacket` is the packet whose arrival armed the pass. Because
+	* `ensureSession` is async, the synchronous `feedSessions` in `pushPacket`
+	* runs before the session lands in `this.sessions`, so the triggering packet
+	* would be lost to the new session. `startSessionDecoder` normally bootstraps
+	* it by replaying the broker's keyframe-aligned seed GOP; only when NO seed
+	* was available (no `getSeedPackets`, or the ring held no keyframe yet) is the
+	* session left un-bootstrapped — and then this method hands it the triggering
+	* packet, but ONLY if that packet is a keyframe. A P-frame trigger is left for
+	* `feedSessions` to skip until the first live keyframe, so a push-mode decoder
+	* never sees a slice referencing an unseen param set.
+	*/
+	async armPendingSessions(triggerPacket) {
+		if (this.disposed || this.armInFlight) return;
+		const pending = /* @__PURE__ */ new Map();
+		for (const subscription of this.subscriptions.values()) {
+			if (this.sessions.has(subscription.format)) continue;
+			if (!pending.has(subscription.format)) pending.set(subscription.format, subscription.id);
+		}
+		if (pending.size === 0) return;
+		this.armInFlight = true;
+		try {
+			for (const [format, subscriptionId] of pending) {
+				if (this.disposed) return;
+				await this.ensureSession(format, subscriptionId);
+				const armed = this.sessions.get(format);
+				if (armed?.proxy && !armed.bootstrapped && triggerPacket.keyframe) {
+					armed.bootstrapped = true;
+					armed.proxy.pushPacket(triggerPacket).catch((err) => {
+						this.logger?.warn("frame-handle plane: decoder push error", { meta: {
+							format,
+							error: errMsg(err)
+						} });
+					});
+				}
+			}
+		} finally {
+			this.armInFlight = false;
+		}
+	}
+	/**
+	* Aggregate decoded-frame rate across every `frameSink: 'shm'` session in
+	* this plane, frames/s. Each `fanoutHandle` call is one decoded frame
+	* delivered into the plane; the rate is recomputed over a rolling
+	* `DECODE_FPS_WINDOW_MS` window. Returns the last computed value between
+	* window rolls, and `0` while no session is producing.
+	*/
+	decodeFps() {
+		this.rollDecodeFpsWindow();
+		return this.decodedFps;
+	}
+	/**
+	* Roll the decoded-fps window when it has elapsed: convert frames seen in
+	* the window into a per-second rate, then reset the counter. Called both
+	* on every fanout and on every `decodeFps()` read so a stalled session
+	* (no fanout) decays its rate to `0` rather than reporting a stale value.
+	*/
+	rollDecodeFpsWindow() {
+		const now = Date.now();
+		const windowMs = now - this.windowStartMs;
+		if (windowMs < DECODE_FPS_WINDOW_MS) return;
+		this.decodedFps = this.framesInWindow / windowMs * 1e3;
+		this.framesInWindow = 0;
+		this.windowStartMs = now;
+	}
+	/** Diagnostic snapshot of every active frame-handle subscription. */
+	listSubscribers() {
+		return [...this.subscriptions.values()].map((s) => ({
+			tag: s.tag,
+			subscribedAt: s.subscribedAt,
+			maxFps: s.maxFps,
+			framesDelivered: s.framesDelivered
+		}));
+	}
+	/**
+	* Force-release every subscription whose tag matches `tag`. Returns the
+	* number released. Decoder sessions wind down when their last subscriber
+	* leaves, same as a normal `unsubscribe`.
+	*/
+	async killByTag(tag) {
+		const victims = [...this.subscriptions.values()].filter((s) => s.tag === tag).map((s) => s.id);
+		for (const id of victims) await this.unsubscribe(id, true);
+		return victims.length;
+	}
+	/** Tear down every subscription + decoder session. Idempotent. */
+	async dispose() {
+		if (this.disposed) return;
+		this.disposed = true;
+		this.subscriptions.clear();
+		const sessions = [...this.sessions.values()];
+		this.sessions.clear();
+		await Promise.all(sessions.map((s) => this.destroySession(s)));
+	}
+	/**
+	* Ensure a `frameSink: 'shm'` decoder session for `format` exists and add
+	* `subscriptionId` to its reader set. Reuses the session when one already
+	* runs for that format.
+	*
+	* When a session is created fresh, its reader set is seeded with EVERY
+	* subscription currently reading `format`, not just `subscriptionId` — a
+	* deferred-arm pass (`armPendingSessions`) may create the session long
+	* after several subscriptions of that format have registered, and the
+	* session is reference-counted by `subscriberIds`. Seeding only the one id
+	* would let an `unsubscribe` of that id tear the session down while its
+	* sibling subscriptions still read it.
+	*/
+	async ensureSession(format, subscriptionId) {
+		const existing = this.sessions.get(format);
+		if (existing) {
+			this.clearLinger(existing);
+			existing.subscriberIds.add(subscriptionId);
+			this.noteSessionSubscriberTag(existing, subscriptionId);
+			return;
+		}
+		const inflight = this.sessionCreating.get(format);
+		if (inflight) {
+			await inflight;
+			const session = this.sessions.get(format);
+			if (session) {
+				session.subscriberIds.add(subscriptionId);
+				this.noteSessionSubscriberTag(session, subscriptionId);
+			}
+			return;
+		}
+		if (Date.now() < (this.sessionRetryCooldownUntil.get(format) ?? 0)) return;
+		const creation = (async () => {
+			const subscriberIds = new Set([subscriptionId]);
+			for (const subscription of this.subscriptions.values()) if (subscription.format === format) subscriberIds.add(subscription.id);
+			const session = {
+				format,
+				proxy: null,
+				nodeId: null,
+				subscriberIds,
+				bootstrapped: false,
+				pullMode: false,
+				targetFps: this.computeFormatFps(format),
+				lingerTimer: null,
+				hasNonOccupancySubscriberEver: false
+			};
+			for (const id of subscriberIds) this.noteSessionSubscriberTag(session, id);
+			let started = false;
+			try {
+				started = await this.startSessionDecoder(session);
+			} catch (err) {
+				this.sessionRetryCooldownUntil.set(format, Date.now() + this.sessionRetryCooldownMs);
+				throw err;
+			}
+			if (started) this.sessions.set(format, session);
+		})();
+		this.sessionCreating.set(format, creation);
+		try {
+			await creation;
+		} finally {
+			this.sessionCreating.delete(format);
+		}
+	}
+	/**
+	* Create the `frameSink: 'shm'` decoder for a `FormatSession` and start
+	* draining its handle queue. Mutates `session.proxy` / `session.nodeId` in
+	* place so a `rotate()` can rebuild a registered session without disturbing
+	* its `subscriberIds`. Returns `false` when no stream / unsupported codec
+	* means no decoder could be created.
+	*/
+	async startSessionDecoder(session) {
+		const { format } = session;
+		const info = this.resolveStreamInfo();
+		if (!info) {
+			this.logger?.info("frame-handle plane: no stream — session deferred", { meta: { format } });
+			return false;
+		}
+		if (!await this.decoderApi.supportsCodec({ codec: info.codec })) {
+			this.logger?.warn("frame-handle plane: codec unsupported — session skipped", { meta: {
+				format,
+				codec: info.codec
+			} });
+			return false;
+		}
+		const targetFps = this.computeFormatFps(format);
+		session.targetFps = targetFps;
+		const { sessionId, nodeId } = await this.decoderApi.createSession({
+			codec: info.codec,
+			maxFps: targetFps,
+			outputFormat: format,
+			scale: 1,
+			frameSink: "shm",
+			...info.numericDeviceId !== void 0 ? { deviceId: info.numericDeviceId } : {},
+			tag: `${info.tag}:shm:${format}`,
+			...this.isDebugEnabled?.() ? { debug: true } : {}
+		});
+		if (!isDecoderNodeColocated(this.localNodeId, nodeId)) {
+			this.sessionRetryCooldownUntil.set(format, Date.now() + this.sessionRetryCooldownMs);
+			this.logger?.warn("frame-handle plane: decoder session landed on a non-local node — destroying (shm ring is node-local)", { meta: {
+				format,
+				requestedNode: this.localNodeId,
+				gotNode: nodeId,
+				sessionId,
+				retryInMs: this.sessionRetryCooldownMs
+			} });
+			await this.decoderApi.destroySession({ sessionId }).catch((err) => {
+				this.logger?.warn("frame-handle plane: failed to destroy mis-placed decoder session", { meta: {
+					format,
+					sessionId,
+					error: errMsg(err)
+				} });
+			});
+			return false;
+		}
+		this.sessionRetryCooldownUntil.delete(format);
+		const proxy = new DecoderSessionProxy(this.decoderApi, sessionId);
+		session.proxy = proxy;
+		session.nodeId = nodeId;
+		session.bootstrapped = false;
+		session.pullMode = false;
+		proxy.startHandlePolling((handle) => {
+			this.fanoutHandle(format, handle);
+		}).catch((err) => {
+			this.logger?.warn("frame-handle plane: handle polling error", { meta: {
+				format,
+				error: errMsg(err)
+			} });
+		});
+		if (info.pullModeUrl) {
+			session.pullMode = true;
+			session.bootstrapped = true;
+			proxy.openStream(info.pullModeUrl).catch((err) => {
+				this.logger?.error("frame-handle plane: pull-mode openStream failed", { meta: {
+					format,
+					error: errMsg(err)
+				} });
+			});
+			this.logger?.info("frame-handle plane: shm decoder session created (pull-mode RTSP)", { meta: {
+				format,
+				codec: info.codec,
+				sessionId,
+				nodeId,
+				pullModeUrl: info.pullModeUrl
+			} });
+			return true;
+		}
+		const seed = this.getSeedPackets?.() ?? [];
+		if (seed.length > 0) {
+			for (const seedPacket of seed) await proxy.pushPacket(seedPacket).catch((err) => {
+				this.logger?.warn("frame-handle plane: seed-replay push error", { meta: {
+					format,
+					error: errMsg(err)
+				} });
+			});
+			session.bootstrapped = true;
+			this.logger?.debug("frame-handle plane: session bootstrapped from seed GOP", { meta: {
+				format,
+				seedPackets: seed.length
+			} });
+		}
+		this.logger?.info("frame-handle plane: shm decoder session created", { meta: {
+			format,
+			codec: info.codec,
+			sessionId,
+			nodeId
+		} });
+		return true;
+	}
+	/** Push one decoded `FrameHandle` to every subscription of `format`. */
+	fanoutHandle(format, handle) {
+		this.rollDecodeFpsWindow();
+		this.framesInWindow += 1;
+		for (const subscription of this.subscriptions.values()) {
+			if (subscription.format !== format) continue;
+			subscription.queue.push(handle);
+		}
+	}
+	/** Destroy a decoder session, swallowing teardown errors. */
+	async destroySession(session) {
+		this.clearLinger(session);
+		const proxy = session.proxy;
+		session.proxy = null;
+		session.nodeId = null;
+		if (!proxy) return;
+		try {
+			await proxy.destroy();
+		} catch (err) {
+			this.logger?.warn("frame-handle plane: session destroy failed", { meta: {
+				format: session.format,
+				error: errMsg(err)
+			} });
+		}
+	}
+};
+//#endregion
 //#region src/stream-broker/stream-broker/annexb-param-sets.ts
 /**
 * Annex-B parameter-set detection for the decoder-priming path.
@@ -14409,7 +15190,7 @@ var StreamBrokerManager = class StreamBrokerManager {
 			value: setting,
 			label: hwAccelOptionLabel(setting)
 		}));
-		const streamTabs = streams.map((stream) => {
+		const streamTabs = streams.filter((s) => !s.camStreamId.startsWith("derived:")).map((stream) => {
 			const camStreamId = stream.camStreamId;
 			const brokerId = brokerIdFor(deviceId, camStreamId);
 			const profile = findProfileForStream(assignment.map, camStreamId);
@@ -14713,7 +15494,9 @@ var StreamBrokerManager = class StreamBrokerManager {
 			return { success: true };
 		}
 		let overrideDirty = false;
+		let derivedDirty = false;
 		const nextOverride = { ...this.deviceOverrides.get(deviceId) };
+		const priorDerivedDefs = new Map(Object.entries(this.deviceOverrides.get(deviceId)?.derivedStreams ?? {}));
 		for (const [fieldKey, value] of Object.entries(input.patch)) {
 			if (fieldKey.startsWith("streamProfile:")) {
 				const profile = fieldKey.slice(14);
@@ -14820,6 +15603,7 @@ var StreamBrokerManager = class StreamBrokerManager {
 			}
 			if (fieldKey === "derivedStreamNames" && Array.isArray(value)) {
 				overrideDirty = true;
+				derivedDirty = true;
 				const names = value.filter((v) => typeof v === "string" && v.length > 0);
 				const next = { ...nextOverride.derivedStreams };
 				for (const n of names) if (!next[n]) next[n] = { encodeProfile: {
@@ -14828,37 +15612,12 @@ var StreamBrokerManager = class StreamBrokerManager {
 				} };
 				for (const existing of Object.keys(next)) if (!names.includes(existing)) delete next[existing];
 				nextOverride.derivedStreams = next;
-				for (const existing of Object.keys(nextOverride.derivedStreams === next ? {} : nextOverride.derivedStreams ?? {})) if (!names.includes(existing)) this.retractCameraStream({
-					deviceId,
-					camStreamId: `derived:${existing}`
-				});
-				for (const n of names) {
-					const def = next[n];
-					if (!def?.source) continue;
-					const pinnedCamStreamId = derivedSourceCamStreamId(def.source);
-					if (pinnedCamStreamId && !this.brokers.has(brokerIdFor(deviceId, pinnedCamStreamId))) continue;
-					this.publishCameraStream({
-						deviceId,
-						camStreamId: `derived:${n}`,
-						kind: "derived",
-						source: def.source,
-						encodeProfile: def.encodeProfile
-					}).catch((err) => {
-						if (err instanceof Error && err.message.includes("SOURCE_NOT_FOUND")) return;
-						this.logger.warn("applyDeviceSettingsPatch: derivedStreamNames materialise failed", {
-							tags: { deviceId },
-							meta: {
-								name: n,
-								error: err instanceof Error ? err.message : String(err)
-							}
-						});
-					});
-				}
 				continue;
 			}
 			if (fieldKey.startsWith("derivedSource:")) {
 				const name = fieldKey.slice(14);
 				overrideDirty = true;
+				derivedDirty = true;
 				const next = { ...nextOverride.derivedStreams };
 				if (!next[name]) next[name] = { encodeProfile: {
 					video: { codec: "h264" },
@@ -14879,6 +15638,7 @@ var StreamBrokerManager = class StreamBrokerManager {
 			if (fieldKey.startsWith("derivedProfile:")) {
 				const name = fieldKey.slice(15);
 				overrideDirty = true;
+				derivedDirty = true;
 				const next = { ...nextOverride.derivedStreams };
 				if (!next[name]) next[name] = { encodeProfile: {
 					video: { codec: "h264" },
@@ -14894,6 +15654,7 @@ var StreamBrokerManager = class StreamBrokerManager {
 			if (fieldKey.startsWith("derivedPrebufferEnabled:")) {
 				const name = fieldKey.slice(24);
 				overrideDirty = true;
+				derivedDirty = true;
 				const next = { ...nextOverride.derivedStreams };
 				if (next[name]) {
 					next[name] = {
@@ -14913,6 +15674,7 @@ var StreamBrokerManager = class StreamBrokerManager {
 			if (fieldKey.startsWith("derivedPrebufferSec:")) {
 				const name = fieldKey.slice(20);
 				overrideDirty = true;
+				derivedDirty = true;
 				const next = { ...nextOverride.derivedStreams };
 				if (next[name] && typeof value === "number") {
 					next[name] = {
@@ -14932,6 +15694,7 @@ var StreamBrokerManager = class StreamBrokerManager {
 			if (fieldKey.startsWith("derivedRtspEnabled:")) {
 				const name = fieldKey.slice(19);
 				overrideDirty = true;
+				derivedDirty = true;
 				const next = { ...nextOverride.derivedStreams };
 				if (next[name]) {
 					next[name] = {
@@ -14948,8 +15711,81 @@ var StreamBrokerManager = class StreamBrokerManager {
 			else this.deviceOverrides.set(deviceId, nextOverride);
 			this.deviceOverridePersister?.(this.deviceOverrides);
 		}
+		if (derivedDirty) await this.reconcileDerivedStreams(deviceId, priorDerivedDefs);
 		return { success: true };
 	}
+	/**
+	* Materialize / rebind / tear down the live `derived:*` brokers of a device
+	* so they match the persisted `derivedStreams` overrides. Idempotent:
+	*
+	*   - a derived WITH a source that isn't live yet → publish (materialize);
+	*   - a materialized derived whose SOURCE changed → retract + republish so
+	*     its feeder rebinds to the new source;
+	*   - a materialized derived whose source is unchanged → left running (an
+	*     encode-only edit must NOT tear down a live stream on every keystroke —
+	*     the new encode params apply on the next feeder respawn, matching the
+	*     `publishCameraStream` single-flight contract);
+	*   - a derived removed from the list (present in `prior`, absent now) →
+	*     retract.
+	*
+	* A PROFILE source resolves its physical stream dynamically (no
+	* precondition); a pinned CAMSTREAM source needs its broker up first — when
+	* absent the def is queued in `pendingDerivedStreams` so a later source
+	* publish drains it.
+	*/
+	async reconcileDerivedStreams(deviceId, prior) {
+		const current = this.deviceOverrides.get(deviceId)?.derivedStreams ?? {};
+		for (const name of prior.keys()) if (!(name in current)) await this.retractCameraStream({
+			deviceId,
+			camStreamId: `derived:${name}`
+		}).catch(() => {});
+		for (const [name, def] of Object.entries(current)) {
+			const camStreamId = `derived:${name}`;
+			const materialized = this.cameraStreams.get(deviceId)?.has(camStreamId) ?? false;
+			if (!def.source) {
+				if (materialized) await this.retractCameraStream({
+					deviceId,
+					camStreamId
+				}).catch(() => {});
+				continue;
+			}
+			const priorSource = prior.get(name)?.source;
+			const sourceChanged = priorSource === void 0 || encodeDerivedSourceValue(priorSource) !== encodeDerivedSourceValue(def.source);
+			if (materialized && !sourceChanged) continue;
+			if (materialized && sourceChanged) await this.retractCameraStream({
+				deviceId,
+				camStreamId
+			}).catch(() => {});
+			const pinned = derivedSourceCamStreamId(def.source);
+			if (pinned && !this.brokers.has(brokerIdFor(deviceId, pinned))) {
+				const sourceBrokerId = brokerIdFor(deviceId, pinned);
+				const list = this.pendingDerivedStreams.get(sourceBrokerId) ?? [];
+				if (!list.some((p) => p.name === name)) list.push({
+					deviceId,
+					name,
+					def
+				});
+				this.pendingDerivedStreams.set(sourceBrokerId, list);
+				continue;
+			}
+			await this.publishCameraStream({
+				deviceId,
+				camStreamId,
+				kind: "derived",
+				source: def.source,
+				encodeProfile: def.encodeProfile
+			}).catch((err) => {
+				if (err instanceof Error && err.message.includes("SOURCE_NOT_FOUND")) return;
+				this.logger.warn("reconcileDerivedStreams: materialize failed", {
+					tags: { deviceId },
+					meta: {
+						name,
+						error: err instanceof Error ? err.message : String(err)
+					}
+				});
+			});
+		}
+	}
 	nextOrder(deviceId) {
 		const next = (this.streamOrderSeq.get(deviceId) ?? 0) + 1;
 		this.streamOrderSeq.set(deviceId, next);
@@ -14966,7 +15802,7 @@ var StreamBrokerManager = class StreamBrokerManager {
 		return false;
 	}
 	labelForDropdown(s) {
-		const base = s.label ?? s.camStreamId;
+		const base = s.label ?? (s.kind === "derived" && s.camStreamId.startsWith("derived:") ? `Derived · ${s.camStreamId.slice(8)}` : s.camStreamId);
 		if (s.resolution) return `${base} (${s.resolution.width}×${s.resolution.height})`;
 		return base;
 	}
@@ -18235,9 +19071,13 @@ var WebrtcSessionProvider = class WebrtcSessionProvider {
 		for (const cam of camStreams) {
 			const camStreamId = cam.camStreamId;
 			const stats = (await this.manager.getBroker({ brokerId: makeSourceBrokerId(deviceId, camStreamId) }))?.getStats();
+			const isDerived = camStreamId.startsWith("derived:");
+			const derivedName = isDerived ? camStreamId.slice(8) : camStreamId;
+			const res = cam.resolution ? ` (${cam.resolution.width}×${cam.resolution.height})` : "";
+			const label = cam.label ?? (isDerived ? `Derived · ${derivedName}${res}` : camStreamId);
 			choices.push({
 				id: `stream:${camStreamId}`,
-				label: cam.label ?? camStreamId,
+				label,
 				target: {
 					kind: "cam-stream",
 					camStreamId