@camstack/addon-pipeline 1.1.43 → 1.1.44

package/dist/recorder/index.mjs

@@ -1,4 +1,4 @@
-import { A as recordingCapability, B as DeviceType, I as errMsg, J as selectAssignedProfileSlots, L as BaseAddon, M as storageEvictableCapability, T as migrateConfigToBands, U as hydrateSchema, V as EventCategory, at as string, it as record, s as EVENT_PAD_MS, u as RecordingConfigSchema } from "../dist-GFd8M6KO.mjs";
+import { A as recordingCapability, B as DeviceType, D as nodePin, I as errMsg, L as BaseAddon, M as storageEvictableCapability, T as migrateConfigToBands, U as hydrateSchema, V as EventCategory, Y as selectAssignedProfileSlots, at as record, ot as string, s as EVENT_PAD_MS, u as RecordingConfigSchema } from "../dist-CgBGV988.mjs";
 import { t as resolveHubHostname } from "../hub-hostname-cCknRYKj.mjs";
 import { t as createFileDataPlaneHandler } from "../model-download-service-C-IHWnXx-BPy6aoAx.mjs";
 import { spawn } from "node:child_process";
@@ -223,7 +223,10 @@ var SegmentStore = class SegmentStore {
 		try {
 			bytes = await this.deps.statBytes(input.flatAbsPath);
 		} catch (err) {
-			this.deps.logger.warn("segment stat failed", err);
+			this.deps.logger.warn("segment stat failed", {
+				tags: { deviceId: input.deviceId },
+				error: err
+			});
 			return null;
 		}
 		if (bytes <= 0) return null;
@@ -232,7 +235,10 @@ var SegmentStore = class SegmentStore {
 		try {
 			await this.deps.moveFile(input.flatAbsPath, toAbs);
 		} catch (err) {
-			this.deps.logger.warn("segment relocate failed", err);
+			this.deps.logger.warn("segment relocate failed", {
+				tags: { deviceId: input.deviceId },
+				error: err
+			});
 			return null;
 		}
 		const row = {
@@ -282,7 +288,10 @@ var SegmentStore = class SegmentStore {
 				}
 				continue;
 			} catch (err) {
-				this.deps.logger.warn("bucket removeDir failed — falling back to per-file deletes", err);
+				this.deps.logger.warn("bucket removeDir failed — falling back to per-file deletes", {
+					tags: { deviceId: bucketRows[0]?.deviceId },
+					error: err
+				});
 			}
 			for (const r of bucketRows) try {
 				await this.deps.deletePath({
@@ -292,7 +301,10 @@ var SegmentStore = class SegmentStore {
 				removed.push(r.path);
 				reclaimed += r.bytes;
 			} catch (err) {
-				this.deps.logger.warn("segment delete failed", err);
+				this.deps.logger.warn("segment delete failed", {
+					tags: { deviceId: r.deviceId },
+					error: err
+				});
 			}
 		}
 		if (removed.length > 0) this.deps.index.removeSegments(removed);
@@ -1862,7 +1874,7 @@ var RecordingController = class {
 	* assigned sources is ignored (record every assigned source — minimum of 1).
 	*/
 	async resolveProfiles(deviceId, override) {
-		const assigned = selectAssignedProfileSlots(await this.deps.brokerCall(() => this.deps.api.streamBroker.listAllProfileSlots.query()), deviceId).map((slot) => slot.profile);
+		const assigned = selectAssignedProfileSlots(await this.deps.brokerCall(() => this.deps.api.streamBroker.listAllProfileSlots.query(void 0, nodePin(this.deps.ownerNodeId))), deviceId).map((slot) => slot.profile);
 		if (!override || override.length === 0) return assigned;
 		const selected = assigned.filter((p) => override.includes(p));
 		return selected.length > 0 ? selected : assigned;
@@ -1882,7 +1894,7 @@ var RecordingController = class {
 			profile,
 			...this.deps.consumerHostname !== void 0 ? { hostname: this.deps.consumerHostname } : {},
 			tag: `recorder:${deviceId}/${profile}`
-		}));
+		}, nodePin(this.deps.ownerNodeId)));
 		const outDir = path.join(placement.root, STAGING_DIR_NAME, String(deviceId), profile);
 		await promises.mkdir(outDir, { recursive: true });
 		const deviceLog = this.deps.logger.withTags({ deviceId });
@@ -1968,7 +1980,7 @@ var RecordingController = class {
 			r.writer.stop();
 		} catch {}
 		try {
-			await this.deps.api.streamBroker.releaseStreamWithCodec.mutate({ pipelineKey: r.pipelineKey });
+			await this.deps.api.streamBroker.releaseStreamWithCodec.mutate({ pipelineKey: r.pipelineKey }, nodePin(this.deps.ownerNodeId));
 		} catch (err) {
 			this.deps.logger.warn("recorder: releaseStreamWithCodec failed", {
 				tags: { deviceId },
@@ -2079,9 +2091,13 @@ var MARKER_PAD_POST_MS = EVENT_PAD_MS.postMs;
 *  form the hub reverse-proxy client path `/addon/recorder/playback`. */
 var RECORDER_ADDON_ID = "recorder";
 var PLAYBACK_PREFIX = "playback";
-/** Node the hub-only `stream-broker` runs on. Every recorder — on the hub or on
-*  a designated agent — gates on, and pulls from, THIS node's broker. */
-var BROKER_HOST_NODE_ID = "hub";
+/** Narrows the `unknown` extras `SegmentStore`'s logger contract accepts down
+*  to the structured `{ tags, error }` shape the device-scoped call sites
+*  (stat/relocate failures) pass — as opposed to the raw caught error most
+*  other call sites still pass directly. */
+function isSegmentStoreLogExtras(extras) {
+	return typeof extras === "object" && extras !== null && ("tags" in extras || "error" in extras);
+}
 var RecorderV2Addon = class extends BaseAddon {
 	nodeId = "hub";
 	/** True when THIS node is the designated recording node (`recordingNodeId`).
@@ -2116,14 +2132,15 @@ var RecorderV2Addon = class extends BaseAddon {
 			} });
 			return { providers: [] };
 		}
-		const consumerHostname = this.nodeId === BROKER_HOST_NODE_ID ? void 0 : resolveRecordingHubHostname(this.config.recordingHubHostname, process.env["CAMSTACK_HUB_URL"]);
-		if (this.nodeId !== BROKER_HOST_NODE_ID) {
+		const ingestOwner = await this.resolveIngestOwner();
+		const consumerHostname = this.nodeId === ingestOwner.ownerNodeId ? void 0 : ingestOwner.reachableHost ?? resolveRecordingHubHostname(this.config.recordingHubHostname, process.env["CAMSTACK_HUB_URL"]);
+		if (this.nodeId !== ingestOwner.ownerNodeId) {
 			this.ctx.logger.info("recorder is a REMOTE recording node — pulling broker streams cross-node", { meta: {
 				ownNodeId: this.nodeId,
-				brokerHost: BROKER_HOST_NODE_ID,
+				brokerHost: ingestOwner.ownerNodeId,
 				consumerHostname: consumerHostname ?? "(unresolved)"
 			} });
-			if (consumerHostname === void 0) this.ctx.logger.warn("recorder: could not resolve the hub host for cross-node pull — set the `recordingHubHostname` global setting or CAMSTACK_HUB_URL; recording will not reach this node", { meta: { ownNodeId: this.nodeId } });
+			if (consumerHostname === void 0) this.ctx.logger.warn("recorder: could not resolve the ingest owner host for cross-node pull — set the `recordingHubHostname` global setting or CAMSTACK_HUB_URL; recording will not reach this node", { meta: { ownNodeId: this.nodeId } });
 		}
 		const segmentStoreDeps = {
 			index: this.index,
@@ -2148,14 +2165,21 @@ var RecorderV2Addon = class extends BaseAddon {
 					force: true
 				});
 			},
-			logger: { warn: (message, extras) => this.ctx.logger.warn(message, { meta: { extras } }) }
+			logger: { warn: (message, extras) => {
+				if (isSegmentStoreLogExtras(extras)) this.ctx.logger.warn(message, {
+					tags: extras.tags,
+					meta: { error: extras.error }
+				});
+				else this.ctx.logger.warn(message, { meta: { extras } });
+			} }
 		};
 		this.segmentStore = new SegmentStore(segmentStoreDeps);
-		const brokerHandle = this.ctx.useCapability("stream-broker", brokerScope(BROKER_HOST_NODE_ID));
+		const brokerHandle = this.ctx.useCapability("stream-broker", brokerScope(ingestOwner.ownerNodeId));
 		this.controller = new RecordingController({
 			api: this.ctx.api,
 			logger: this.ctx.logger,
 			nodeId: this.nodeId,
+			ownerNodeId: ingestOwner.ownerNodeId,
 			segmentStore: this.segmentStore,
 			loadConfig: (deviceId) => loadDeviceConfig(this.configStore(), deviceId),
 			enabledDeviceIds: async () => [...(await readDeviceConfigs(this.configStore())).keys()],
@@ -2164,7 +2188,7 @@ var RecorderV2Addon = class extends BaseAddon {
 			segmentSeconds: this.config.segmentSeconds,
 			watchIntervalMs: this.config.watchIntervalMs,
 			...consumerHostname !== void 0 ? { consumerHostname } : {},
-			onBrokerReady: (handler) => this.ctx.onCapabilityStateChange("stream-broker", brokerScope(BROKER_HOST_NODE_ID), (state) => {
+			onBrokerReady: (handler) => this.ctx.onCapabilityStateChange("stream-broker", brokerScope(ingestOwner.ownerNodeId), (state) => {
 				if (state === "ready") handler();
 			}),
 			brokerCall: makeBrokerCall(brokerHandle)
@@ -2290,6 +2314,21 @@ var RecorderV2Addon = class extends BaseAddon {
 		return this.resolvedLocations;
 	}
 	/**
+	* Resolve the cluster's camera-source owner. Graceful degrade: the
+	* `pipeline-orchestrator` cap may not be mounted yet (pre-image-release),
+	* in which case we fall back to `{ ownerNodeId: 'hub' }` — the same default
+	* `getIngestOwner` itself returns absent an explicit `clusterRoles.ingestNode`,
+	* so an unresolved owner is byte-identical to today's hub-only behaviour.
+	*/
+	async resolveIngestOwner() {
+		try {
+			return await this.ctx.api.pipelineOrchestrator.getIngestOwner.query();
+		} catch (err) {
+			this.ctx.logger.warn("recorder: getIngestOwner unavailable — defaulting to hub (cap not mounted yet?)", { meta: { error: errMsg(err) } });
+			return { ownerNodeId: "hub" };
+		}
+	}
+	/**
 	* Roots the playback data-plane handler searches, IN ORDER: `<dataDir>/playback`
 	* FIRST (the freshly-written master/variant `.m3u8` playlists), then every
 	* recordings location root (the segment `.m4s` files at

package/dist/{frame-handle-plane-E_AsR77T.mjs → remote-source-plane-B4hRwchu.mjs}

@@ -1,4 +1,4 @@
-import { I as errMsg, d as RingBuffer } from "./dist-GFd8M6KO.mjs";
+import { D as nodePin, I as errMsg, d as RingBuffer } from "./dist-CgBGV988.mjs";
 import { randomUUID } from "node:crypto";
 //#region src/stream-broker/stream-broker/decoder-session-proxy.ts
 /**
@@ -781,4 +781,221 @@ var FrameHandlePlane = class {
 	}
 };
 //#endregion
-export { DecoderSessionProxy as n, FrameHandlePlane as t };
+//#region src/pipeline-runner/remote-source-plane.ts
+/**
+* Runner-side mode selection (pure): whether an attach payload routes this
+* camera through the remote-source leg. Absent `frameSource` (a pre-P2c
+* payload) and `local-broker` both take today's co-located broker path —
+* the rollout-OFF safety invariant.
+*/
+function isRemoteRestream(frameSource) {
+	return frameSource !== void 0 && frameSource.kind === "remote-restream";
+}
+/**
+* Resolve WHICH broker profile a camStream id feeds for a device (pure).
+*
+* `getStreamWithCodec` targets a PROFILE (its assigned camStream), while the
+* runner is dispatched with camStream ids (`motionStreamId` /
+* `detectionStreamId`). The broker's profile slots carry the mapping
+* (`sourceCamStreamId`); a stream no slot feeds returns `null` — the acquire
+* fails fast and the poller's backoff retries (the assignment may still be
+* propagating).
+*/
+function profileForStreamId(slots, deviceId, streamId) {
+	for (const slot of slots) if (slot.deviceId === deviceId && slot.sourceCamStreamId === streamId) return slot.profile;
+	return null;
+}
+var RemoteSourcePlane = class {
+	api;
+	logger;
+	deviceId;
+	ownNodeId;
+	ownerNodeId;
+	hostname;
+	/** Single-flight entry creation per camStream id. */
+	entries = /* @__PURE__ */ new Map();
+	disposed = false;
+	constructor(options) {
+		this.api = options.api;
+		this.logger = options.logger.withTags({ deviceId: options.deviceId });
+		this.deviceId = options.deviceId;
+		this.ownNodeId = options.ownNodeId;
+		this.ownerNodeId = options.ownerNodeId;
+		this.hostname = options.hostname;
+	}
+	/**
+	* A {@link FrameHandleSource} for one camStream id, pluggable into
+	* `startFrameHandlePoller`. Motion (`gray`) and detection (`rgb`)
+	* subscriptions of the same stream share ONE acquired restream and ONE
+	* satellite plane (per-format decoder sessions inside it — hub parity).
+	*/
+	makeSource(streamId) {
+		return {
+			subscribe: async (input) => {
+				if (this.disposed) throw new Error("RemoteSourcePlane: subscribe after dispose");
+				const entry = await this.ensureEntry(streamId);
+				const result = await entry.plane.subscribe({
+					format: input.format,
+					maxFps: input.maxFps,
+					tag: input.tag
+				});
+				entry.subscriptionIds.add(result.subscriptionId);
+				return result;
+			},
+			pullHandles: async (input) => {
+				const entry = await this.peekEntry(streamId);
+				if (!entry) return [];
+				return entry.plane.pullHandles(input.subscriptionId, input.maxCount);
+			},
+			unsubscribe: async (input) => {
+				const entry = await this.peekEntry(streamId);
+				if (!entry) return;
+				entry.subscriptionIds.delete(input.subscriptionId);
+				await entry.plane.unsubscribe(input.subscriptionId).catch(() => {});
+				if (entry.subscriptionIds.size === 0) {
+					this.entries.delete(streamId);
+					await this.teardownEntry(entry, streamId);
+				}
+			}
+		};
+	}
+	/** Dispose every entry: satellite planes destroyed, restreams released. Idempotent. */
+	async dispose() {
+		if (this.disposed) return;
+		this.disposed = true;
+		const pending = [...this.entries.entries()];
+		this.entries.clear();
+		for (const [streamId, entryPromise] of pending) try {
+			const entry = await entryPromise;
+			await this.teardownEntry(entry, streamId);
+		} catch {}
+	}
+	/** The live entry for a stream, or `null` (never creates one). */
+	async peekEntry(streamId) {
+		const pending = this.entries.get(streamId);
+		if (!pending) return null;
+		try {
+			return await pending;
+		} catch {
+			return null;
+		}
+	}
+	/** Single-flight: acquire the restream + build the satellite plane once per stream. */
+	ensureEntry(streamId) {
+		const existing = this.entries.get(streamId);
+		if (existing) return existing;
+		const creation = this.createEntry(streamId);
+		this.entries.set(streamId, creation);
+		creation.catch(() => {
+			if (this.entries.get(streamId) === creation) this.entries.delete(streamId);
+		});
+		return creation;
+	}
+	async createEntry(streamId) {
+		const { api, deviceId, ownNodeId, ownerNodeId } = this;
+		if (this.hostname === void 0) throw new Error("RemoteSourcePlane: owner hostname unresolvable — set frameSource.hubHostnameOverride or CAMSTACK_HUB_URL (a 127.0.0.1 restream URL would dial the wrong box)");
+		const profile = profileForStreamId(await api.streamBroker.listAllProfileSlots.query(void 0, nodePin(ownerNodeId)), deviceId, streamId);
+		if (profile === null) throw new Error(`RemoteSourcePlane: no broker profile is fed by camStream '${streamId}' of device ${deviceId} — cannot acquire the owner restream`);
+		const rtpSource = await api.streamBroker.getStreamWithCodec.mutate({
+			deviceId,
+			video: "copy",
+			audio: "none",
+			profile,
+			hostname: this.hostname,
+			tag: `runner:${ownNodeId}:remote-src:${deviceId}/${streamId}`
+		}, nodePin(ownerNodeId));
+		const codec = rtpSource.videoCodec === "H265" ? "h265" : "h264";
+		const plane = new FrameHandlePlane({
+			decoderApi: this.buildPinnedDecoderCapApi(),
+			logger: this.logger,
+			localNodeId: ownNodeId,
+			resolveStreamInfo: () => ({
+				codec,
+				numericDeviceId: deviceId,
+				tag: `runner-remote:${deviceId}/${streamId}`,
+				pullModeUrl: rtpSource.url
+			})
+		});
+		this.logger.info("remote-source plane: owner restream acquired", { meta: {
+			streamId,
+			profile,
+			codec,
+			pipelineKey: rtpSource.pipelineKey,
+			hostname: this.hostname
+		} });
+		return {
+			plane,
+			pipelineKey: rtpSource.pipelineKey,
+			subscriptionIds: /* @__PURE__ */ new Set(),
+			released: false
+		};
+	}
+	/** Destroy an entry's satellite plane and release its restream refcount once. */
+	async teardownEntry(entry, streamId) {
+		await entry.plane.dispose().catch((err) => {
+			this.logger.warn("remote-source plane: satellite plane dispose failed", { meta: {
+				streamId,
+				error: errMsg(err)
+			} });
+		});
+		if (entry.released) return;
+		entry.released = true;
+		await this.api.streamBroker.releaseStreamWithCodec.mutate({ pipelineKey: entry.pipelineKey }, nodePin(this.ownerNodeId)).catch((err) => {
+			this.logger.debug("remote-source plane: releaseStreamWithCodec failed (benign on hub restart)", { meta: {
+				streamId,
+				pipelineKey: entry.pipelineKey,
+				error: errMsg(err)
+			} });
+		});
+	}
+	/**
+	* Every decoder call pinned to THIS runner's node — mirror of the hub
+	* broker's wrapper (`stream-broker-manager.buildDecoderCapApi`): the
+	* `decoder` cap is a singleton whose UNPINNED calls resolve to the
+	* cluster-elected node, which is generally NOT this agent. Pinning create
+	* AND every session op to the same local node keeps the session + its shm
+	* ring here, where this plane's readers live.
+	*/
+	buildPinnedDecoderCapApi() {
+		const api = this.api;
+		const pin = nodePin(this.ownNodeId);
+		const toWireBytes = (bytes) => {
+			const copy = new Uint8Array(new ArrayBuffer(bytes.byteLength));
+			copy.set(bytes);
+			return copy;
+		};
+		return {
+			supportsCodec: async (input) => api.decoder.supportsCodec.query({ ...input }, pin),
+			getInfo: async () => api.decoder.getInfo.query(void 0, pin),
+			createSession: async (config) => api.decoder.createSession.query({ ...config }, pin),
+			pushPacket: async (input) => {
+				await api.decoder.pushPacket.query({
+					sessionId: input.sessionId,
+					packet: {
+						...input.packet,
+						data: toWireBytes(input.packet.data)
+					}
+				}, pin);
+			},
+			pullFrames: async (input) => {
+				return (await api.decoder.pullFrames.query({ ...input }, pin)).map((frame) => ({
+					...frame,
+					data: Buffer.from(frame.data)
+				}));
+			},
+			pullHandles: async (input) => api.decoder.pullHandles.query({ ...input }, pin),
+			destroySession: async (input) => {
+				await api.decoder.destroySession.query({ ...input }, pin);
+			},
+			openStream: async (input) => {
+				await api.decoder.openStream.query({ ...input }, pin);
+			},
+			updateConfig: async (input) => {
+				await api.decoder.updateConfig.query({ ...input }, pin);
+			},
+			getStats: async (input) => api.decoder.getStats.query({ ...input }, pin)
+		};
+	}
+};
+//#endregion
+export { DecoderSessionProxy as a, FrameHandlePlane as i, isRemoteRestream as n, profileForStreamId as r, RemoteSourcePlane as t };

package/dist/{frame-handle-plane-B3Fxww8H.js → remote-source-plane-D9m0z1N9.js}

@@ -1,4 +1,4 @@
-const require_dist = require("./dist-NvwN60Fq.js");
+const require_dist = require("./dist-CySHUkXY.js");
 let node_crypto = require("node:crypto");
 //#region src/stream-broker/stream-broker/decoder-session-proxy.ts
 /**
@@ -781,6 +781,223 @@ var FrameHandlePlane = class {
 	}
 };
 //#endregion
+//#region src/pipeline-runner/remote-source-plane.ts
+/**
+* Runner-side mode selection (pure): whether an attach payload routes this
+* camera through the remote-source leg. Absent `frameSource` (a pre-P2c
+* payload) and `local-broker` both take today's co-located broker path —
+* the rollout-OFF safety invariant.
+*/
+function isRemoteRestream(frameSource) {
+	return frameSource !== void 0 && frameSource.kind === "remote-restream";
+}
+/**
+* Resolve WHICH broker profile a camStream id feeds for a device (pure).
+*
+* `getStreamWithCodec` targets a PROFILE (its assigned camStream), while the
+* runner is dispatched with camStream ids (`motionStreamId` /
+* `detectionStreamId`). The broker's profile slots carry the mapping
+* (`sourceCamStreamId`); a stream no slot feeds returns `null` — the acquire
+* fails fast and the poller's backoff retries (the assignment may still be
+* propagating).
+*/
+function profileForStreamId(slots, deviceId, streamId) {
+	for (const slot of slots) if (slot.deviceId === deviceId && slot.sourceCamStreamId === streamId) return slot.profile;
+	return null;
+}
+var RemoteSourcePlane = class {
+	api;
+	logger;
+	deviceId;
+	ownNodeId;
+	ownerNodeId;
+	hostname;
+	/** Single-flight entry creation per camStream id. */
+	entries = /* @__PURE__ */ new Map();
+	disposed = false;
+	constructor(options) {
+		this.api = options.api;
+		this.logger = options.logger.withTags({ deviceId: options.deviceId });
+		this.deviceId = options.deviceId;
+		this.ownNodeId = options.ownNodeId;
+		this.ownerNodeId = options.ownerNodeId;
+		this.hostname = options.hostname;
+	}
+	/**
+	* A {@link FrameHandleSource} for one camStream id, pluggable into
+	* `startFrameHandlePoller`. Motion (`gray`) and detection (`rgb`)
+	* subscriptions of the same stream share ONE acquired restream and ONE
+	* satellite plane (per-format decoder sessions inside it — hub parity).
+	*/
+	makeSource(streamId) {
+		return {
+			subscribe: async (input) => {
+				if (this.disposed) throw new Error("RemoteSourcePlane: subscribe after dispose");
+				const entry = await this.ensureEntry(streamId);
+				const result = await entry.plane.subscribe({
+					format: input.format,
+					maxFps: input.maxFps,
+					tag: input.tag
+				});
+				entry.subscriptionIds.add(result.subscriptionId);
+				return result;
+			},
+			pullHandles: async (input) => {
+				const entry = await this.peekEntry(streamId);
+				if (!entry) return [];
+				return entry.plane.pullHandles(input.subscriptionId, input.maxCount);
+			},
+			unsubscribe: async (input) => {
+				const entry = await this.peekEntry(streamId);
+				if (!entry) return;
+				entry.subscriptionIds.delete(input.subscriptionId);
+				await entry.plane.unsubscribe(input.subscriptionId).catch(() => {});
+				if (entry.subscriptionIds.size === 0) {
+					this.entries.delete(streamId);
+					await this.teardownEntry(entry, streamId);
+				}
+			}
+		};
+	}
+	/** Dispose every entry: satellite planes destroyed, restreams released. Idempotent. */
+	async dispose() {
+		if (this.disposed) return;
+		this.disposed = true;
+		const pending = [...this.entries.entries()];
+		this.entries.clear();
+		for (const [streamId, entryPromise] of pending) try {
+			const entry = await entryPromise;
+			await this.teardownEntry(entry, streamId);
+		} catch {}
+	}
+	/** The live entry for a stream, or `null` (never creates one). */
+	async peekEntry(streamId) {
+		const pending = this.entries.get(streamId);
+		if (!pending) return null;
+		try {
+			return await pending;
+		} catch {
+			return null;
+		}
+	}
+	/** Single-flight: acquire the restream + build the satellite plane once per stream. */
+	ensureEntry(streamId) {
+		const existing = this.entries.get(streamId);
+		if (existing) return existing;
+		const creation = this.createEntry(streamId);
+		this.entries.set(streamId, creation);
+		creation.catch(() => {
+			if (this.entries.get(streamId) === creation) this.entries.delete(streamId);
+		});
+		return creation;
+	}
+	async createEntry(streamId) {
+		const { api, deviceId, ownNodeId, ownerNodeId } = this;
+		if (this.hostname === void 0) throw new Error("RemoteSourcePlane: owner hostname unresolvable — set frameSource.hubHostnameOverride or CAMSTACK_HUB_URL (a 127.0.0.1 restream URL would dial the wrong box)");
+		const profile = profileForStreamId(await api.streamBroker.listAllProfileSlots.query(void 0, require_dist.nodePin(ownerNodeId)), deviceId, streamId);
+		if (profile === null) throw new Error(`RemoteSourcePlane: no broker profile is fed by camStream '${streamId}' of device ${deviceId} — cannot acquire the owner restream`);
+		const rtpSource = await api.streamBroker.getStreamWithCodec.mutate({
+			deviceId,
+			video: "copy",
+			audio: "none",
+			profile,
+			hostname: this.hostname,
+			tag: `runner:${ownNodeId}:remote-src:${deviceId}/${streamId}`
+		}, require_dist.nodePin(ownerNodeId));
+		const codec = rtpSource.videoCodec === "H265" ? "h265" : "h264";
+		const plane = new FrameHandlePlane({
+			decoderApi: this.buildPinnedDecoderCapApi(),
+			logger: this.logger,
+			localNodeId: ownNodeId,
+			resolveStreamInfo: () => ({
+				codec,
+				numericDeviceId: deviceId,
+				tag: `runner-remote:${deviceId}/${streamId}`,
+				pullModeUrl: rtpSource.url
+			})
+		});
+		this.logger.info("remote-source plane: owner restream acquired", { meta: {
+			streamId,
+			profile,
+			codec,
+			pipelineKey: rtpSource.pipelineKey,
+			hostname: this.hostname
+		} });
+		return {
+			plane,
+			pipelineKey: rtpSource.pipelineKey,
+			subscriptionIds: /* @__PURE__ */ new Set(),
+			released: false
+		};
+	}
+	/** Destroy an entry's satellite plane and release its restream refcount once. */
+	async teardownEntry(entry, streamId) {
+		await entry.plane.dispose().catch((err) => {
+			this.logger.warn("remote-source plane: satellite plane dispose failed", { meta: {
+				streamId,
+				error: require_dist.errMsg(err)
+			} });
+		});
+		if (entry.released) return;
+		entry.released = true;
+		await this.api.streamBroker.releaseStreamWithCodec.mutate({ pipelineKey: entry.pipelineKey }, require_dist.nodePin(this.ownerNodeId)).catch((err) => {
+			this.logger.debug("remote-source plane: releaseStreamWithCodec failed (benign on hub restart)", { meta: {
+				streamId,
+				pipelineKey: entry.pipelineKey,
+				error: require_dist.errMsg(err)
+			} });
+		});
+	}
+	/**
+	* Every decoder call pinned to THIS runner's node — mirror of the hub
+	* broker's wrapper (`stream-broker-manager.buildDecoderCapApi`): the
+	* `decoder` cap is a singleton whose UNPINNED calls resolve to the
+	* cluster-elected node, which is generally NOT this agent. Pinning create
+	* AND every session op to the same local node keeps the session + its shm
+	* ring here, where this plane's readers live.
+	*/
+	buildPinnedDecoderCapApi() {
+		const api = this.api;
+		const pin = require_dist.nodePin(this.ownNodeId);
+		const toWireBytes = (bytes) => {
+			const copy = new Uint8Array(new ArrayBuffer(bytes.byteLength));
+			copy.set(bytes);
+			return copy;
+		};
+		return {
+			supportsCodec: async (input) => api.decoder.supportsCodec.query({ ...input }, pin),
+			getInfo: async () => api.decoder.getInfo.query(void 0, pin),
+			createSession: async (config) => api.decoder.createSession.query({ ...config }, pin),
+			pushPacket: async (input) => {
+				await api.decoder.pushPacket.query({
+					sessionId: input.sessionId,
+					packet: {
+						...input.packet,
+						data: toWireBytes(input.packet.data)
+					}
+				}, pin);
+			},
+			pullFrames: async (input) => {
+				return (await api.decoder.pullFrames.query({ ...input }, pin)).map((frame) => ({
+					...frame,
+					data: Buffer.from(frame.data)
+				}));
+			},
+			pullHandles: async (input) => api.decoder.pullHandles.query({ ...input }, pin),
+			destroySession: async (input) => {
+				await api.decoder.destroySession.query({ ...input }, pin);
+			},
+			openStream: async (input) => {
+				await api.decoder.openStream.query({ ...input }, pin);
+			},
+			updateConfig: async (input) => {
+				await api.decoder.updateConfig.query({ ...input }, pin);
+			},
+			getStats: async (input) => api.decoder.getStats.query({ ...input }, pin)
+		};
+	}
+};
+//#endregion
 Object.defineProperty(exports, "DecoderSessionProxy", {
 	enumerable: true,
 	get: function() {
@@ -793,3 +1010,21 @@ Object.defineProperty(exports, "FrameHandlePlane", {
 		return FrameHandlePlane;
 	}
 });
+Object.defineProperty(exports, "RemoteSourcePlane", {
+	enumerable: true,
+	get: function() {
+		return RemoteSourcePlane;
+	}
+});
+Object.defineProperty(exports, "isRemoteRestream", {
+	enumerable: true,
+	get: function() {
+		return isRemoteRestream;
+	}
+});
+Object.defineProperty(exports, "profileForStreamId", {
+	enumerable: true,
+	get: function() {
+		return profileForStreamId;
+	}
+});