@camstack/addon-pipeline 1.1.26 → 1.1.28

package/dist/frame-ring-sink-Cs9vby6v.mjs

@@ -0,0 +1,409 @@
+import { p as RingBuffer } from "./dist-C6_wgXqF.mjs";
+import { FrameRingWriter, MIN_RING_SLOTS, computeSegmentSize, computeSlotByteLength, createSegment, deriveSlotCount } from "@camstack/shm-ring";
+//#region src/shared/decoder-backend-keys.ts
+/** Built-in default when a node has no selection — the subprocess decoder. */
+var DEFAULT_DECODER_BACKEND = "ffmpeg";
+/** Narrow an unknown settings value to a {@link DecoderBackend}, else `null`. */
+function parseDecoderBackend(value) {
+	return value === "ffmpeg" || value === "nodeav" ? value : null;
+}
+/**
+* Normalise a raw kernel node id to the bare node id used for scoping.
+* `localNodeId` can carry a `<node>/<addon>` suffix; the decoder selection is
+* per-NODE, so strip the addon segment. Falls back to `hub`.
+*/
+function normalizeDecoderNodeId(rawNodeId) {
+	const raw = rawNodeId ?? "hub";
+	return raw.includes("/") ? raw.split("/")[0] ?? "hub" : raw;
+}
+//#endregion
+//#region src/shared/decoder-backend.ts
+/** The addon whose global settings OWN the per-node `backend` field. */
+var DECODER_OWNER_ADDON_ID = "decoder-ffmpeg";
+function isHydratedField(entry) {
+	return typeof entry === "object" && entry !== null && "key" in entry;
+}
+/**
+* Pure selection from an already-read hydrated settings payload: extract the
+* owner's `backend` field value (which the owner projected per-node from its
+* scoped store key) and narrow it. A missing/invalid field or a null payload
+* resolves to {@link DEFAULT_DECODER_BACKEND} — never a bare store key.
+*/
+function pickDecoderBackendFromSettings(view) {
+	if (view === null) return DEFAULT_DECODER_BACKEND;
+	for (const section of view.sections) for (const entry of section.fields) {
+		if (!isHydratedField(entry) || entry.key !== "backend") continue;
+		return parseDecoderBackend(entry.value) ?? "ffmpeg";
+	}
+	return DEFAULT_DECODER_BACKEND;
+}
+/**
+* Resolve the decoder backend this node should run. Called by BOTH decoder
+* addons at the start of `onInitialize`; the addon whose backend is NOT
+* selected registers nothing.
+*
+* Fails safe: no api surface, a read error, or a null payload (owner not
+* answering yet) resolves to {@link DEFAULT_DECODER_BACKEND} — the default
+* backend still registers, and the non-default one stands down (never both).
+*/
+async function resolveDecoderBackend(api, nodeId, logger) {
+	if (!api) {
+		logger.warn("decoder-backend: no api surface — using default backend", { meta: { default: DEFAULT_DECODER_BACKEND } });
+		return DEFAULT_DECODER_BACKEND;
+	}
+	try {
+		const view = await api.addonSettings.getGlobalSettings.query({
+			addonId: DECODER_OWNER_ADDON_ID,
+			nodeId: normalizeDecoderNodeId(nodeId)
+		});
+		if (view === null) {
+			logger.warn("decoder-backend: owner settings unavailable — using default backend", { meta: {
+				default: DEFAULT_DECODER_BACKEND,
+				owner: DECODER_OWNER_ADDON_ID
+			} });
+			return DEFAULT_DECODER_BACKEND;
+		}
+		return pickDecoderBackendFromSettings(view);
+	} catch (err) {
+		logger.warn("decoder-backend: settings read failed — using default backend", { meta: {
+			default: DEFAULT_DECODER_BACKEND,
+			error: err instanceof Error ? err.message : String(err)
+		} });
+		return DEFAULT_DECODER_BACKEND;
+	}
+}
+//#endregion
+//#region src/shared/notifying-ring-buffer.ts
+/**
+* A {@link RingBuffer} that can notify a single blocked consumer the moment an
+* item commits — the server side of the `pullFrames`/`pullHandles` long-poll.
+*
+* The decoder's `onFrame`/`onFrameHandle` callback drives `push()`; a consumer
+* that finds the ring momentarily empty calls {@link waitForItem} and is woken
+* on the very next `push()` (a real commit signal) rather than spinning at
+* ~1kHz on `setTimeout(…,1)`. If nothing commits it resolves after `waitMs`,
+* and {@link cancel} (session teardown) resolves any in-flight wait promptly so
+* a blocked long-poll never waits out `waitMs` on destroy.
+*
+* Semantics are otherwise identical to `RingBuffer`: fixed capacity,
+* latest-wins overwrite when full, FIFO `drain`.
+*/
+var NotifyingRingBuffer = class {
+	ring;
+	waiters = /* @__PURE__ */ new Set();
+	constructor(capacity) {
+		this.ring = new RingBuffer(capacity);
+	}
+	get size() {
+		return this.ring.size;
+	}
+	push(item) {
+		this.ring.push(item);
+		this.wakeAll();
+	}
+	drain(maxCount) {
+		return this.ring.drain(maxCount);
+	}
+	/**
+	* Resolve as soon as an item commits to the ring, or after `waitMs`,
+	* whichever comes first. Returns immediately when items are already present
+	* or `waitMs <= 0` (legacy immediate-return). {@link cancel} also resolves an
+	* in-flight wait.
+	*/
+	async waitForItem(waitMs) {
+		if (this.ring.size > 0 || waitMs <= 0) return;
+		await new Promise((resolve) => {
+			let settled = false;
+			const finish = () => {
+				if (settled) return;
+				settled = true;
+				this.waiters.delete(wake);
+				clearTimeout(timer);
+				resolve();
+			};
+			const wake = () => finish();
+			const timer = setTimeout(finish, waitMs);
+			if (typeof timer.unref === "function") timer.unref();
+			this.waiters.add(wake);
+		});
+	}
+	/**
+	* Cancel every in-flight {@link waitForItem} — called on session teardown so
+	* a blocked long-poll returns promptly instead of waiting out `waitMs`.
+	*/
+	cancel() {
+		this.wakeAll();
+	}
+	wakeAll() {
+		if (this.waiters.size === 0) return;
+		const pending = [...this.waiters];
+		this.waiters.clear();
+		for (const wake of pending) wake();
+	}
+};
+//#endregion
+//#region src/decoder-ffmpeg/frame-ring-sink.ts
+/**
+* `DecoderFrameRingSink` — the decoder's shared-memory write side (Phase 5 / D9).
+*
+* When a decoder session is configured with `frameSink: 'shm'`, the decoder
+* **owns** the shared-memory ring segment for that stream: it creates the
+* segment on the first decoded frame (when the output geometry is known),
+* writes every subsequent decoded frame into the ring via a `FrameRingWriter`,
+* and closes + unlinks the segment when the session is destroyed.
+*
+* What leaves the decoder is no longer the pixel `Buffer` — it is a tiny,
+* serialisable `FrameHandle` (`FrameRingWriter.writeFrame`'s return value).
+* Same-host consumers (motion, detection, the WebRTC encoder) open the same
+* segment with a `FrameRingReader` and read the pixels zero-copy.
+*
+* ## Lazy segment creation
+*
+* The segment cannot be sized until the first frame: `slotByteLength` is
+* `width × height × bytesPerPixel`, and the output dimensions are only known
+* once the scaler has produced its first `dstFrame`. So `writeFrame` is a
+* no-op-until-armed: the first call sizes + creates the segment, every later
+* call writes into it.
+*
+* ## Resolution-change decision
+*
+* A live camera stream can change resolution mid-stream (the decoder's scaler
+* is rebuilt on a config toggle, or the source renegotiates). The slot is
+* sized for the **first** frame's geometry. A later frame that no longer fits
+* the slot triggers a **segment re-create**: the old segment is closed +
+* unlinked and a fresh, larger segment is created under a new generation-tagged
+* name. This is simpler and leak-free versus over-allocating slots for a
+* worst-case 4K frame on every stream; resolution changes on a live camera are
+* rare, and a brief gap while consumers re-open the segment is acceptable
+* (latest-wins — a missed frame is correct behaviour).
+*/
+/**
+* Per-ring shared-memory budget (MB) — the slot count is derived per-resolution
+* from this budget via {@link deriveSlotCount}, so a 360p stream gets many
+* slots and a 4K stream a few, both inside the same memory footprint.
+*
+* Read ONCE at module load from `CAMSTACK_SHM_RING_BUDGET_MB`; a non-finite or
+* non-positive value falls back to the 16 MB default.
+*
+* The default is deliberately small (16 MB) so many concurrent per-camera rings
+* fit inside a bounded `/dev/shm`. The decoder output is capped at 640px wide, so
+* a slot is ≤ ~920 KB and 16 MB still yields ~17–70 latest-wins slots. A ring
+* segment larger than the container's `/dev/shm` tmpfs backing (Docker default is
+* only 64 MB) faults an **uncatchable SIGBUS** on write past `st_size` — the old
+* 128 MB default overflowed a 64 MB `/dev/shm` and crashed the decoder on 8MP
+* streams. Pair this with a `--shm-size` that scales with concurrent-decode load.
+*/
+var RING_BUDGET_MB = (() => {
+	const raw = Number(process.env["CAMSTACK_SHM_RING_BUDGET_MB"]);
+	return Number.isFinite(raw) && raw > 0 ? Math.floor(raw) : 16;
+})();
+/** {@link RING_BUDGET_MB} in bytes — the budget passed to `deriveSlotCount`. */
+var RING_BUDGET_BYTES = RING_BUDGET_MB * 1024 * 1024;
+/** A unique, stable shared-memory segment name for a decoder stream.
+*
+* macOS POSIX shm names are capped at ~31 characters (`PSHMNAMLEN`). A
+* `camstack.frames.<deviceId>.<streamId>` scheme overflows that for realistic
+* ids, so the sink uses a short, collision-resistant scheme instead:
+* `csf.<base36 hash>.<gen>`. The hash folds the device id, the session tag
+* and a per-process random salt; the generation suffix makes a re-created
+* segment (resolution change) a distinct name so a stale consumer mapping is
+* never silently reused.
+*/
+function makeSegmentName(seed, generation) {
+	let hash = 5381;
+	for (let i = 0; i < seed.length; i += 1) hash = (hash << 5) + hash + seed.charCodeAt(i) | 0;
+	return `csf.${(hash >>> 0).toString(36)}.${generation}`;
+}
+/**
+* The decoder-side owner of one stream's shared-memory frame ring.
+*
+* Not constructed until a session actually uses the shm sink; the segment
+* itself is created lazily on the first `writeFrame`.
+*/
+var DecoderFrameRingSink = class {
+	seed;
+	logger;
+	nodeId;
+	segment = null;
+	writer = null;
+	segmentName = null;
+	slotByteLength = 0;
+	generation = 0;
+	destroyed = false;
+	/** Frames committed into the ring across this sink's lifetime (all generations). */
+	framesWritten = 0;
+	constructor(options) {
+		const salt = Math.random().toString(36).slice(2, 8);
+		this.seed = `${options.seed}.${salt}`;
+		this.logger = options.logger;
+		this.nodeId = options.nodeId;
+	}
+	/** Whether a segment has been created (i.e. at least one frame written). */
+	get isArmed() {
+		return this.writer !== null;
+	}
+	/** The current segment name, or `null` before the first frame. */
+	get currentSegmentName() {
+		return this.segmentName;
+	}
+	/**
+	* Write one decoded frame into the ring and return its `FrameHandle`.
+	*
+	* On the first call (or after a geometry change that overflows the current
+	* slot) the segment is created / re-created sized for this frame. Returns
+	* `null` only when the sink has been destroyed.
+	*
+	* This is the copy-in convenience form (it copies `pixels` into the slot).
+	* The decoder's hot path uses the zero-copy {@link beginFrame} /
+	* {@link commitFrame} scatter-write pair instead — the scaler produces its
+	* packed output directly into the slot, eliminating the write-side memcpy.
+	*/
+	writeFrame(pixels, meta) {
+		if (this.destroyed) return null;
+		if (this.writer === null || computeSlotByteLength(meta.width, meta.height, meta.format) > this.slotByteLength) this.recreateSegment(computeSlotByteLength(meta.width, meta.height, meta.format));
+		const writer = this.writer;
+		if (writer === null) return null;
+		const handle = writer.writeFrame(pixels, meta);
+		this.framesWritten += 1;
+		return handle;
+	}
+	/**
+	* Reserve a ring slot for a frame of the given geometry — the **zero-copy**
+	* scatter-write entry point (Phase 5 / D9 Task 7c).
+	*
+	* The segment is created / re-created here if this is the first frame or the
+	* geometry overflows the current slot capacity, so the slot is correctly
+	* sized before the caller fills it. The returned `buffer` is a writable view
+	* **directly over the mapped segment** — the node-av scaler scatters its
+	* packed output straight into it, with no intermediate copy. The caller MUST
+	* call {@link commitFrame} with the returned `slot` once the slot is filled.
+	*
+	* Returns `null` when the sink is destroyed or the segment cannot be created.
+	*/
+	beginFrame(width, height, format) {
+		if (this.destroyed) return null;
+		const requiredSlotBytes = computeSlotByteLength(width, height, format);
+		if (this.writer === null || requiredSlotBytes > this.slotByteLength) this.recreateSegment(requiredSlotBytes);
+		const writer = this.writer;
+		if (writer === null) return null;
+		const { slot, buffer } = writer.beginFrame();
+		return {
+			slot,
+			buffer
+		};
+	}
+	/**
+	* Publish the frame whose slot was reserved by {@link beginFrame} and filled
+	* in place by the caller. `slot` MUST be the value from the matching
+	* `beginFrame`. Returns the published `FrameHandle`, or `null` if the sink
+	* was destroyed (or the segment lost) between begin and commit.
+	*/
+	commitFrame(slot, meta) {
+		if (this.destroyed) return null;
+		const writer = this.writer;
+		if (writer === null) return null;
+		const handle = writer.commitFrame(slot, meta);
+		this.framesWritten += 1;
+		return handle;
+	}
+	/**
+	* Current shm ring usage — `null` until the first frame arms the segment.
+	* Surfaced through `decoder.getShmStats` so a downstream consumer can
+	* observe ring pressure (slot depth, byte budget, frames written).
+	*/
+	getShmStats() {
+		if (this.writer === null) return null;
+		return {
+			slotCount: this.writer.slotCount,
+			slotByteLength: this.slotByteLength,
+			segmentBytes: computeSegmentSize(this.writer.slotCount, this.slotByteLength),
+			framesWritten: this.framesWritten
+		};
+	}
+	/**
+	* Abandon a slot reserved by {@link beginFrame} **without publishing it** —
+	* the degenerate-path counterpart of {@link commitFrame}.
+	*
+	* A caller that reserved a slot but then could not produce valid pixels (no
+	* decoded source planes, or the scaler threw) MUST call this instead of
+	* `commitFrame`: it closes the open seqlock without advancing `writeIndex`,
+	* so no reader ever sees the slot's uninitialised bytes as a real frame, and
+	* no `FrameHandle` is handed downstream. `slot` MUST be the value from the
+	* matching `beginFrame`. A no-op if the sink was destroyed (or the segment
+	* lost) between begin and abort.
+	*/
+	abortFrame(slot) {
+		if (this.destroyed) return;
+		const writer = this.writer;
+		if (writer === null) return;
+		writer.abortFrame(slot);
+	}
+	/** Close + unlink the segment. Idempotent. */
+	destroy() {
+		if (this.destroyed) return;
+		this.destroyed = true;
+		this.releaseSegment();
+	}
+	/**
+	* Create a fresh segment sized for at least `slotByteLength` bytes per slot,
+	* replacing any prior one. A re-create bumps the generation so the new
+	* segment has a distinct name — a consumer holding the old mapping is never
+	* silently handed a resized segment.
+	*/
+	recreateSegment(slotByteLength) {
+		this.releaseSegment();
+		this.generation += 1;
+		const name = makeSegmentName(this.seed, this.generation);
+		const slotCount = deriveSlotCount(RING_BUDGET_BYTES, slotByteLength);
+		if (slotCount === MIN_RING_SLOTS && MIN_RING_SLOTS * slotByteLength > RING_BUDGET_BYTES) this.logger.warn("decoder shm ring: budget too small for resolution — using MIN slots", { meta: {
+			slotByteLength,
+			budgetMb: RING_BUDGET_MB
+		} });
+		const totalBytes = computeSegmentSize(slotCount, slotByteLength);
+		try {
+			const segment = createSegment(name, totalBytes);
+			this.segment = segment;
+			this.segmentName = name;
+			this.slotByteLength = slotByteLength;
+			this.writer = new FrameRingWriter(segment.buffer, name, slotCount, slotByteLength, this.nodeId);
+			this.logger.info("decoder shm ring: segment created", { meta: {
+				segment: name,
+				slotCount,
+				slotByteLength,
+				totalBytes,
+				generation: this.generation
+			} });
+		} catch (err) {
+			this.segment = null;
+			this.writer = null;
+			this.segmentName = null;
+			this.slotByteLength = 0;
+			this.logger.error("decoder shm ring: segment create failed", { meta: {
+				segment: name,
+				slotByteLength,
+				error: err instanceof Error ? err.message : String(err)
+			} });
+		}
+	}
+	/** Unmap + unlink the current segment, if any. */
+	releaseSegment() {
+		const segment = this.segment;
+		if (segment === null) return;
+		this.segment = null;
+		this.writer = null;
+		const name = this.segmentName;
+		this.segmentName = null;
+		try {
+			segment.close();
+			segment.unlink();
+			this.logger.info("decoder shm ring: segment released", { meta: { segment: name } });
+		} catch (err) {
+			this.logger.warn("decoder shm ring: segment release failed", { meta: {
+				segment: name,
+				error: err instanceof Error ? err.message : String(err)
+			} });
+		}
+	}
+};
+//#endregion
+export { resolveDecoderBackend as a, NotifyingRingBuffer as i, RING_BUDGET_MB as n, DEFAULT_DECODER_BACKEND as o, makeSegmentName as r, DecoderFrameRingSink as t };

package/dist/motion-wasm/index.js

@@ -2,7 +2,8 @@ Object.defineProperties(exports, {
 	__esModule: { value: true },
 	[Symbol.toStringTag]: { value: "Module" }
 });
-const require_dist = require("../dist-DAIlCdAx.js");
+const require_dist = require("../dist-Biq62zt4.js");
+let _camstack_shm_ring = require("@camstack/shm-ring");
 let node_fs = require("node:fs");
 let node_path = require("node:path");
 //#region src/motion-wasm/wasm-motion-detector.ts
@@ -135,6 +136,13 @@ var DEFAULT_CONFIG = {
 };
 var MotionWasmAddon = class MotionWasmAddon extends require_dist.BaseAddon {
 	detector = null;
+	/**
+	* CB5 shm passthrough — process-local, long-lived reader cache for
+	* `analyze({ frameHandle })`. Opens each named shm segment once and reuses
+	* the mapping; lazily created on first LOCAL handle, unmapped in
+	* {@link onShutdown}. Never opened/closed per-call.
+	*/
+	frameHandleReaders = null;
 	cameras = /* @__PURE__ */ new Map();
 	deviceConfigCache = /* @__PURE__ */ new Map();
 	static DEVICE_CONFIG_TTL_MS = 6e4;
@@ -187,9 +195,51 @@ var MotionWasmAddon = class MotionWasmAddon extends require_dist.BaseAddon {
 	* motion-detection cap: analyze a frame, return regions + stats.
 	* Per-device state keyed by the numeric deviceId (stringified internally
 	* so the pipeline-step sentinel shares the same Map).
+	*
+	* CB5: pixels arrive either inline (`frame`) or as a zero-pixel shm
+	* `FrameHandle`. A LOCAL handle is read back zero-copy here; a foreign /
+	* recycled / unmappable handle yields a null read and an empty result (the
+	* runner ships `frame` as the fallback, queue-depth gated).
 	*/
-	async analyze({ deviceId, frame }) {
-		return this.analyzeInternal(String(deviceId), frame);
+	async analyze({ deviceId, frame, frameHandle }) {
+		const resolved = frame ?? (frameHandle ? this.resolveFrameHandle(frameHandle) : null);
+		if (!resolved) return this.emptyMotionResult(frameHandle);
+		return this.analyzeInternal(String(deviceId), resolved);
+	}
+	/** This node's cluster id (suffix-stripped), for local-vs-foreign gating. */
+	ownNodeId() {
+		const raw = this.ctx.kernel?.localNodeId ?? "hub";
+		return raw.includes("/") ? raw.split("/")[0] : raw;
+	}
+	/**
+	* CB5 — resolve a shm `FrameHandle` to gray pixels zero-copy. Returns null
+	* for a FOREIGN handle (segment on another node — the runner only sends
+	* local handles), a recycled ring slot, or an unmappable segment.
+	*/
+	resolveFrameHandle(handle) {
+		if (handle.nodeId !== this.ownNodeId()) return null;
+		if (!this.frameHandleReaders) this.frameHandleReaders = new _camstack_shm_ring.FrameRingReaderCache(this.ctx.logger);
+		const decoded = this.frameHandleReaders.read(handle);
+		if (!decoded) return null;
+		return {
+			data: decoded.data,
+			width: decoded.width,
+			height: decoded.height,
+			format: decoded.format,
+			timestamp: decoded.timestamp
+		};
+	}
+	/** Zeroed motion result for a missed `frameHandle` read (dropped frame). */
+	emptyMotionResult(handle) {
+		return {
+			detected: false,
+			regionCount: 0,
+			regions: [],
+			rawRegions: [],
+			frameWidth: handle?.width ?? 0,
+			frameHeight: handle?.height ?? 0,
+			analysisMs: 0
+		};
 	}
 	async analyzeInternal(cameraId, frame) {
 		if (!this.detector) return {
@@ -351,6 +401,8 @@ var MotionWasmAddon = class MotionWasmAddon extends require_dist.BaseAddon {
 		this.deviceConfigCache.clear();
 		for (const id of this.proxies.keys()) this.releaseProxy(id);
 		this.detector = null;
+		this.frameHandleReaders?.close();
+		this.frameHandleReaders = null;
 	}
 	deviceSettingsSchema() {
 		return this.schema({ sections: [{

package/dist/motion-wasm/index.mjs

@@ -1,4 +1,5 @@
-import { A as motionDetectionCapability, T as evaluateZoneRules, V as BaseAddon, W as DeviceType, Y as hydrateSchema } from "../dist-CgEP_0OL.mjs";
+import { A as motionDetectionCapability, T as evaluateZoneRules, V as BaseAddon, W as DeviceType, q as hydrateSchema } from "../dist-C6_wgXqF.mjs";
+import { FrameRingReaderCache } from "@camstack/shm-ring";
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 //#region src/motion-wasm/wasm-motion-detector.ts
@@ -131,6 +132,13 @@ var DEFAULT_CONFIG = {
 };
 var MotionWasmAddon = class MotionWasmAddon extends BaseAddon {
 	detector = null;
+	/**
+	* CB5 shm passthrough — process-local, long-lived reader cache for
+	* `analyze({ frameHandle })`. Opens each named shm segment once and reuses
+	* the mapping; lazily created on first LOCAL handle, unmapped in
+	* {@link onShutdown}. Never opened/closed per-call.
+	*/
+	frameHandleReaders = null;
 	cameras = /* @__PURE__ */ new Map();
 	deviceConfigCache = /* @__PURE__ */ new Map();
 	static DEVICE_CONFIG_TTL_MS = 6e4;
@@ -183,9 +191,51 @@ var MotionWasmAddon = class MotionWasmAddon extends BaseAddon {
 	* motion-detection cap: analyze a frame, return regions + stats.
 	* Per-device state keyed by the numeric deviceId (stringified internally
 	* so the pipeline-step sentinel shares the same Map).
+	*
+	* CB5: pixels arrive either inline (`frame`) or as a zero-pixel shm
+	* `FrameHandle`. A LOCAL handle is read back zero-copy here; a foreign /
+	* recycled / unmappable handle yields a null read and an empty result (the
+	* runner ships `frame` as the fallback, queue-depth gated).
 	*/
-	async analyze({ deviceId, frame }) {
-		return this.analyzeInternal(String(deviceId), frame);
+	async analyze({ deviceId, frame, frameHandle }) {
+		const resolved = frame ?? (frameHandle ? this.resolveFrameHandle(frameHandle) : null);
+		if (!resolved) return this.emptyMotionResult(frameHandle);
+		return this.analyzeInternal(String(deviceId), resolved);
+	}
+	/** This node's cluster id (suffix-stripped), for local-vs-foreign gating. */
+	ownNodeId() {
+		const raw = this.ctx.kernel?.localNodeId ?? "hub";
+		return raw.includes("/") ? raw.split("/")[0] : raw;
+	}
+	/**
+	* CB5 — resolve a shm `FrameHandle` to gray pixels zero-copy. Returns null
+	* for a FOREIGN handle (segment on another node — the runner only sends
+	* local handles), a recycled ring slot, or an unmappable segment.
+	*/
+	resolveFrameHandle(handle) {
+		if (handle.nodeId !== this.ownNodeId()) return null;
+		if (!this.frameHandleReaders) this.frameHandleReaders = new FrameRingReaderCache(this.ctx.logger);
+		const decoded = this.frameHandleReaders.read(handle);
+		if (!decoded) return null;
+		return {
+			data: decoded.data,
+			width: decoded.width,
+			height: decoded.height,
+			format: decoded.format,
+			timestamp: decoded.timestamp
+		};
+	}
+	/** Zeroed motion result for a missed `frameHandle` read (dropped frame). */
+	emptyMotionResult(handle) {
+		return {
+			detected: false,
+			regionCount: 0,
+			regions: [],
+			rawRegions: [],
+			frameWidth: handle?.width ?? 0,
+			frameHeight: handle?.height ?? 0,
+			analysisMs: 0
+		};
 	}
 	async analyzeInternal(cameraId, frame) {
 		if (!this.detector) return {
@@ -347,6 +397,8 @@ var MotionWasmAddon = class MotionWasmAddon extends BaseAddon {
 		this.deviceConfigCache.clear();
 		for (const id of this.proxies.keys()) this.releaseProxy(id);
 		this.detector = null;
+		this.frameHandleReaders?.close();
+		this.frameHandleReaders = null;
 	}
 	deviceSettingsSchema() {
 		return this.schema({ sections: [{

package/dist/node-topology-platform-BkR_k6WT.mjs

@@ -0,0 +1,15 @@
+//#region src/shared/node-topology-platform.ts
+/**
+* Pick a node's `{ platform, arch }` from the cluster topology. Returns an empty
+* object when the topology is missing or the node is absent (caller falls back).
+*/
+function pickNodePlatformArch(topology, nodeId) {
+	const entry = topology?.find((n) => n.id === nodeId);
+	if (!entry) return {};
+	return {
+		platform: entry.platform,
+		arch: entry.arch
+	};
+}
+//#endregion
+export { pickNodePlatformArch as t };

package/dist/node-topology-platform-CFZ7F4xW.js

@@ -0,0 +1,20 @@
+//#region src/shared/node-topology-platform.ts
+/**
+* Pick a node's `{ platform, arch }` from the cluster topology. Returns an empty
+* object when the topology is missing or the node is absent (caller falls back).
+*/
+function pickNodePlatformArch(topology, nodeId) {
+	const entry = topology?.find((n) => n.id === nodeId);
+	if (!entry) return {};
+	return {
+		platform: entry.platform,
+		arch: entry.arch
+	};
+}
+//#endregion
+Object.defineProperty(exports, "pickNodePlatformArch", {
+	enumerable: true,
+	get: function() {
+		return pickNodePlatformArch;
+	}
+});