@camstack/addon-pipeline 1.1.24 → 1.1.26

package/dist/frame-handle-plane-Dq20KtKL.mjs

@@ -0,0 +1,636 @@
+import { B as errMsg, p as RingBuffer } from "./dist-CgEP_0OL.mjs";
+import { randomUUID } from "node:crypto";
+//#region src/stream-broker/stream-broker/decoder-session-proxy.ts
+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
+			});
+			for (const frame of frames) onFrame(frame);
+			if (frames.length === 0) await new Promise((r) => setTimeout(r, 1));
+		}
+	}
+	/**
+	* 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
+			});
+			for (const handle of handles) onHandle(handle);
+			if (handles.length === 0) await new Promise((r) => setTimeout(r, 1));
+		} 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;
+/**
+* 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;
+	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;
+	/** 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;
+	}
+	/** 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.logger?.info("frame-handle subscription added", { meta: {
+			subscriptionId,
+			format: input.format,
+			tag: subscription.tag,
+			maxFps
+		} });
+		return {
+			subscriptionId,
+			maxFps
+		};
+	}
+	/**
+	* 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);
+		}
+		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 timer = setTimeout(() => {
+			session.lingerTimer = null;
+			if (session.subscriberIds.size > 0) return;
+			this.sessions.delete(session.format);
+			this.destroySession(session).catch(() => {});
+		}, SESSION_LINGER_MS);
+		timer.unref?.();
+		session.lingerTimer = timer;
+	}
+	/** 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 shm decoder session. */
+	feedSessions(packet) {
+		for (const session of this.sessions.values()) {
+			if (!session.proxy) continue;
+			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 this method feeds
+	* the triggering packet to each session it just created, otherwise that
+	* first (keyframe-carrying) packet would be lost and a push-mode H264/H265
+	* decoder would stall waiting for SPS/PPS.
+	*/
+	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.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);
+			return;
+		}
+		const inflight = this.sessionCreating.get(format);
+		if (inflight) {
+			await inflight;
+			this.sessions.get(format)?.subscriberIds.add(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,
+				lingerTimer: null
+			};
+			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 { sessionId, nodeId } = await this.decoderApi.createSession({
+			codec: info.codec,
+			maxFps: 0,
+			outputFormat: format,
+			scale: 1,
+			frameSink: "shm",
+			...info.numericDeviceId !== void 0 ? { deviceId: info.numericDeviceId } : {},
+			tag: `${info.tag}:shm:${format}`
+		});
+		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;
+		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) 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", { 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
+export { DecoderSessionProxy as n, FrameHandlePlane as t };