@camstack/addon-pipeline 0.1.13 → 0.1.15

package/dist/decoder-nodeav/index.mjs

@@ -1,5 +1,227 @@
 import { randomUUID } from "node:crypto";
-import { e as errMsg, B as BaseAddon, u as DEFAULT_DECODER_HWACCEL_CONFIG, H as HWACCEL_OPTIONS, v as decoderCapability, R as RingBuffer } from "../index-BwLnHesq.mjs";
+import { e as errMsg, B as BaseAddon, u as DEFAULT_DECODER_HWACCEL_CONFIG, H as HWACCEL_OPTIONS, v as decoderCapability, R as RingBuffer } from "../index-CVzLrojg.mjs";
+import { computeSlotByteLength, computeSegmentSize, deriveSlotCount, MIN_RING_SLOTS, createSegment, FrameRingWriter, FrameRingReaderCache } from "@camstack/shm-ring";
+const RING_BUDGET_MB = (() => {
+  const raw = Number(process.env["CAMSTACK_SHM_RING_BUDGET_MB"]);
+  return Number.isFinite(raw) && raw > 0 ? Math.floor(raw) : 128;
+})();
+const RING_BUDGET_BYTES = RING_BUDGET_MB * 1024 * 1024;
+function makeSegmentName(seed, generation) {
+  let hash = 5381;
+  for (let i = 0; i < seed.length; i += 1) {
+    hash = (hash << 5) + hash + seed.charCodeAt(i) | 0;
+  }
+  const tag = (hash >>> 0).toString(36);
+  return `csf.${tag}.${generation}`;
+}
+class DecoderFrameRingSink {
+  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)
+        }
+      });
+    }
+  }
+}
 function backendToHwDeviceConst(backend, consts) {
   switch (backend) {
     case "videotoolbox":
@@ -91,7 +313,19 @@ class NodeAvDecoderSession {
   config;
   logger;
   frameCallbacks = /* @__PURE__ */ new Set();
+  handleCallbacks = /* @__PURE__ */ new Set();
   destroyed = false;
+  /**
+   * Frame delivery mode (see {@link DecoderFrameSink}). `'shm'` lazily
+   * constructs `frameRingSink` and routes every decoded frame through it.
+   */
+  frameSink;
+  /**
+   * The shared-memory ring writer for this stream. Created lazily on the
+   * first decoded frame in `'shm'` mode (the segment cannot be sized until
+   * the output geometry is known) and torn down in `destroy`.
+   */
+  frameRingSink = null;
   // Low-level node-av objects (initialized on first keyframe)
   parser = null;
   codecCtx = null;
@@ -183,6 +417,8 @@ class NodeAvDecoderSession {
   startTime = Date.now();
   hwaccelPref;
   hwaccelResolver;
+  /** Cluster node id stamped into every `FrameHandle` the `'shm'` sink emits. */
+  nodeId;
   /** The backend that actually initialised successfully — `'none'` = software fallback. */
   activeHwAccel = "none";
   hwDevice = null;
@@ -197,6 +433,39 @@ class NodeAvDecoderSession {
     this.outputMode = NodeAvDecoderSession.resolveOutputMode(config.outputFormat);
     this.hwaccelPref = options?.hwaccel ?? "auto";
     this.hwaccelResolver = options?.hwaccelResolver ?? null;
+    this.frameSink = options?.frameSink ?? "callback";
+    this.nodeId = options?.nodeId ?? "local";
+  }
+  /**
+   * The shared-memory ring sink for this stream, or `null` before the first
+   * `'shm'`-mode frame lazily creates it. Exposed so the owning addon can
+   * surface ring stats via `decoder.getShmStats`.
+   */
+  get frameRingSinkOrNull() {
+    return this.frameRingSink;
+  }
+  /**
+   * Lazily build the shared-memory ring sink for this stream. The segment
+   * itself is still created lazily by the sink on its first `writeFrame`,
+   * once the decoded geometry is known.
+   */
+  ensureFrameRingSink() {
+    if (this.frameRingSink === null) {
+      const seedParts = [];
+      if (typeof this.config.deviceId === "number") {
+        seedParts.push(String(this.config.deviceId));
+      }
+      if (typeof this.config.tag === "string" && this.config.tag.length > 0) {
+        seedParts.push(this.config.tag);
+      }
+      const seed = seedParts.length > 0 ? seedParts.join(":") : "anon";
+      this.frameRingSink = new DecoderFrameRingSink({
+        seed,
+        logger: this.logger,
+        nodeId: this.nodeId
+      });
+    }
+    return this.frameRingSink;
   }
   /**
    * Resolve the backend preference list and try each one against
@@ -497,6 +766,10 @@ class NodeAvDecoderSession {
     }
     if (!this.dstFrame || !this.scaler) return;
     const decodeStart = performance.now();
+    if (this.frameSink === "shm" && this.outputMode !== "jpeg") {
+      this.scaleIntoRingSlot(frame, decodeStart);
+      return;
+    }
     try {
       this.dstFrame.makeWritable();
       this.scaler.scaleFrameSync(this.dstFrame, frame);
@@ -542,6 +815,104 @@ class NodeAvDecoderSession {
       this.emitRawFrame(rawBuf, "gray", decodeStart);
     }
   }
+  /**
+   * Scale a decoded frame **directly into a shared-memory ring slot** — the
+   * zero write-side copy path (Phase 5 / D9 Task 7c).
+   *
+   * `beginFrame` reserves the slot (its seqlock open / odd — readers skip it);
+   * `SoftwareScaleContext.scaleSync` (the low-level `sws_scale` mapping) writes
+   * the packed pixels straight into the slot buffer with `linesize = width ×
+   * bpp` — no linesize padding, so there is nothing to strip and nothing to
+   * memcpy; `commitFrame` writes the metadata, closes the seqlock and publishes
+   * the slot. The decoded source planes feed `scaleSync` as `srcSlice` +
+   * `srcStride` (`frame.data` / `frame.linesize`).
+   *
+   * Used only for raw output formats (rgb/bgr/gray). The jpeg path keeps the
+   * `dstFrame` + sharp encode route because sharp must consume an RGB buffer
+   * before the final (variable-length) jpeg bytes exist.
+   */
+  scaleIntoRingSlot(frame, decodeStart) {
+    if (!this.scaler) return;
+    const format = this.outputMode === "gray" ? "gray" : "rgb";
+    const channels = this.outputMode === "gray" ? 1 : 3;
+    const sink = this.ensureFrameRingSink();
+    const reserved = sink.beginFrame(this.outWidth, this.outHeight, format);
+    if (reserved === null) {
+      this.droppedFrames++;
+      return;
+    }
+    const srcPlanes = frame.data;
+    if (!srcPlanes || srcPlanes.length === 0) {
+      sink.abortFrame(reserved.slot);
+      this.droppedFrames++;
+      return;
+    }
+    const dstStride = this.outWidth * channels;
+    try {
+      const srcStrides = Array.from(frame.linesize).slice(0, srcPlanes.length);
+      this.scaler.scaleSync(
+        Array.from(srcPlanes),
+        srcStrides,
+        0,
+        frame.height,
+        [reserved.buffer],
+        [dstStride]
+      );
+    } catch (err) {
+      this.logger.warn("node-av scale-into-slot error", {
+        meta: { error: errMsg(err) }
+      });
+      sink.abortFrame(reserved.slot);
+      this.droppedFrames++;
+      return;
+    }
+    const decodeMs = performance.now() - decodeStart;
+    this.totalDecodeTimeMs += decodeMs;
+    this.outputFrames++;
+    this.lastEmitTime = performance.now();
+    if (!this.firstFrameLogged) {
+      this.firstFrameLogged = true;
+      this.logger.info("node-av: scaled directly into shm ring slot", {
+        meta: {
+          phase: "frame-debug",
+          width: this.outWidth,
+          height: this.outHeight,
+          dstStride,
+          format
+        }
+      });
+    }
+    if (this.outputFrames === 1 || this.outputFrames % 500 === 0) {
+      this.logger.info("node-av frame emitted", {
+        meta: {
+          frameNumber: this.outputFrames,
+          width: this.outWidth,
+          height: this.outHeight,
+          format,
+          decodeMs,
+          sink: "shm",
+          subs: this.handleCallbacks.size
+        }
+      });
+    }
+    const handle = sink.commitFrame(reserved.slot, {
+      width: this.outWidth,
+      height: this.outHeight,
+      format,
+      // pts uses performance.now() (monotonic, process-relative) for
+      // ring-ordering; DecodedFrameHandle.timestamp carries the wall clock.
+      pts: performance.now(),
+      byteLength: dstStride * this.outHeight
+    });
+    if (handle === null) {
+      this.droppedFrames++;
+      return;
+    }
+    const delivered = { handle, timestamp: Date.now() };
+    for (const cb of this.handleCallbacks) {
+      cb(delivered);
+    }
+  }
   /**
    * Extract packed pixel buffer from a decoded frame.
    * FFmpeg's av_frame_get_buffer() may pad each row to alignment (32/64 bytes).
@@ -604,10 +975,15 @@ class NodeAvDecoderSession {
           height: this.outHeight,
           format,
           decodeMs,
-          subs: this.frameCallbacks.size
+          sink: this.frameSink,
+          subs: this.frameSink === "shm" ? this.handleCallbacks.size : this.frameCallbacks.size
         }
       });
     }
+    if (this.frameSink === "shm") {
+      this.emitShmFrame(data, format);
+      return;
+    }
     const decodedFrame = {
       data,
       width: this.outWidth,
@@ -619,12 +995,53 @@ class NodeAvDecoderSession {
       cb(decodedFrame);
     }
   }
+  /**
+   * Write a decoded frame into this stream's shared-memory ring and deliver
+   * the resulting `FrameHandle` to `onFrameHandle` subscribers. No pixel
+   * `Buffer` is handed to callbacks — consumers open the segment and read the
+   * pixels zero-copy via a `FrameRingReader`.
+   */
+  emitShmFrame(data, format) {
+    const sink = this.ensureFrameRingSink();
+    const handle = sink.writeFrame(data, {
+      width: this.outWidth,
+      height: this.outHeight,
+      format,
+      // The decoder does not carry a source PTS down to this point; use a
+      // monotone-ish wall clock so a consumer can still order frames.
+      // NOTE: pts uses performance.now() (monotonic, process-relative) while
+      // DecodedFrameHandle.timestamp uses Date.now() (wall-clock epoch).
+      // The two clocks are intentionally distinct — pts is for ring-ordering,
+      // timestamp is for wall-clock correlation — and must not be compared.
+      pts: performance.now(),
+      byteLength: data.byteLength
+    });
+    if (handle === null) {
+      this.droppedFrames++;
+      return;
+    }
+    const frame = { handle, timestamp: Date.now() };
+    for (const cb of this.handleCallbacks) {
+      cb(frame);
+    }
+  }
   onFrame(callback) {
     this.frameCallbacks.add(callback);
     return () => {
       this.frameCallbacks.delete(callback);
     };
   }
+  /**
+   * Subscribe to shared-memory frame handles. Fires only when the session was
+   * created with `frameSink: 'shm'`; in the legacy `'callback'` mode no
+   * handles are produced and this subscription never fires.
+   */
+  onFrameHandle(callback) {
+    this.handleCallbacks.add(callback);
+    return () => {
+      this.handleCallbacks.delete(callback);
+    };
+  }
   updateConfig(update) {
     const prevFormat = this.config.outputFormat;
     this.config = { ...this.config, ...update };
@@ -659,6 +1076,9 @@ class NodeAvDecoderSession {
     if (this.destroyed) return;
     this.destroyed = true;
     this.frameCallbacks.clear();
+    this.handleCallbacks.clear();
+    this.frameRingSink?.destroy();
+    this.frameRingSink = null;
     this.dstFrame?.[Symbol.dispose]?.();
     this.avFrame?.[Symbol.dispose]?.();
     this.avPacket?.[Symbol.dispose]?.();
@@ -691,10 +1111,28 @@ class NodeAvDecoderSession {
 }
 const FRAME_BUFFER_CAPACITY = 32;
 class DecoderNodeAvAddon extends BaseAddon {
+  /**
+   * Sessions are stored as the concrete `NodeAvDecoderSession` (the only type
+   * this addon ever creates) so `getShmStats` can reach the per-session shm
+   * ring sink — `IDecoderSession` does not expose it.
+   */
   sessions = /* @__PURE__ */ new Map();
+  /** Pixel-frame buffers — populated only for `frameSink: 'callback'` sessions. */
   frameBuffers = /* @__PURE__ */ new Map();
+  /** `FrameHandle` buffers — populated only for `frameSink: 'shm'` sessions. */
+  handleBuffers = /* @__PURE__ */ new Map();
   unsubscribers = /* @__PURE__ */ new Map();
   sessionMeta = /* @__PURE__ */ new Map();
+  /**
+   * Per-shm-segment `FrameRingReader` cache backing `getFrame`. Opens each
+   * named segment once and reuses the reader for every later handle on it;
+   * built in `onInitialize` (it needs the scoped logger) and closed in
+   * `onShutdown`.
+   */
+  frameReaders = null;
+  /** Running `getFrame` hit/miss counters surfaced via `getShmStats`. */
+  getFrameHits = 0;
+  getFrameMisses = 0;
   constructor() {
     super(DEFAULT_DECODER_HWACCEL_CONFIG);
   }
@@ -731,6 +1169,7 @@ class DecoderNodeAvAddon extends BaseAddon {
   }
   async onInitialize() {
     this.ctx.logger.info("node-av decoder addon initialized");
+    this.frameReaders = new FrameRingReaderCache(this.ctx.logger);
     if (!this.config.probedBestHwaccel) {
       this.reprobeHwaccel().catch((err) => {
         this.ctx.logger.warn("nodeav: auto-reprobe hwaccel failed", {
@@ -789,15 +1228,48 @@ class DecoderNodeAvAddon extends BaseAddon {
       priority: 10
     };
   }
+  /**
+   * The cluster node id of this decoder — the Moleculer nodeID (`hub`,
+   * `dev-agent-0`, …), not the addon id. Stamped into session-owned
+   * `FrameHandle`s so a downstream consumer routes `getFrame` to the node
+   * that holds the shm ring. A hierarchical broker nodeID (`hub/...`) is
+   * collapsed to the cluster-visible parent; in-process boot is left as-is.
+   * Mirrors the resolution `PipelineRunnerAddon.onInitialize` performs.
+   */
+  resolveLocalNodeId() {
+    const raw = this.ctx.kernel.localNodeId ?? this.ctx.id;
+    return raw.includes("/") ? raw.split("/")[0] : raw;
+  }
   async createSession(config) {
     const sessionId = randomUUID();
     const hwaccel = this.resolveHwAccelPref();
+    const { frameSink } = config;
+    const nodeId = this.resolveLocalNodeId();
     const session = new NodeAvDecoderSession(config, this.ctx.logger, {
       hwaccel,
-      hwaccelResolver: this.ctx.kernel.hwaccel
+      hwaccelResolver: this.ctx.kernel.hwaccel,
+      frameSink,
+      nodeId
     });
+    const unsub = frameSink === "shm" ? this.wireShmSink(sessionId, session) : this.wireCallbackSink(sessionId, session);
+    this.sessions.set(sessionId, session);
+    this.unsubscribers.set(sessionId, unsub);
+    this.sessionMeta.set(sessionId, {
+      codec: config.codec,
+      outputFormat: config.outputFormat,
+      createdAtMs: Date.now()
+    });
+    this.ctx.logger.info("node-av: created session", { meta: { sessionId, codec: config.codec, hwaccelPref: hwaccel, frameSink, nodeId } });
+    return { sessionId, nodeId };
+  }
+  /**
+   * Subscribe a `'callback'` session's pixel frames into a per-session
+   * ring buffer drained by `pullFrames`.
+   */
+  wireCallbackSink(sessionId, session) {
     const ringBuffer = new RingBuffer(FRAME_BUFFER_CAPACITY);
-    const unsub = session.onFrame((frame) => {
+    this.frameBuffers.set(sessionId, ringBuffer);
+    return session.onFrame((frame) => {
       const { format } = frame;
       if (format !== "jpeg" && format !== "rgb" && format !== "bgr" && format !== "yuv420" && format !== "gray") return;
       const arrayBuf = new ArrayBuffer(frame.data.byteLength);
@@ -812,16 +1284,18 @@ class DecoderNodeAvAddon extends BaseAddon {
       };
       ringBuffer.push(capFrame);
     });
-    this.sessions.set(sessionId, session);
-    this.frameBuffers.set(sessionId, ringBuffer);
-    this.unsubscribers.set(sessionId, unsub);
-    this.sessionMeta.set(sessionId, {
-      codec: config.codec,
-      outputFormat: config.outputFormat,
-      createdAtMs: Date.now()
+  }
+  /**
+   * Subscribe a `'shm'` session's `FrameHandle`s into a per-session ring
+   * buffer drained by `pullHandles`. No pixel bytes cross the cap boundary
+   * — the broker opens the named segment and reads the pixels zero-copy.
+   */
+  wireShmSink(sessionId, session) {
+    const handleRing = new RingBuffer(FRAME_BUFFER_CAPACITY);
+    this.handleBuffers.set(sessionId, handleRing);
+    return session.onFrameHandle((frame) => {
+      handleRing.push(frame.handle);
     });
-    this.ctx.logger.info("node-av: created session", { meta: { sessionId, codec: config.codec, hwaccelPref: hwaccel } });
-    return { sessionId, nodeId: this.ctx.kernel.localNodeId ?? "local" };
   }
   async destroySession(input) {
     const { sessionId } = input;
@@ -834,6 +1308,7 @@ class DecoderNodeAvAddon extends BaseAddon {
     await session.destroy();
     this.sessions.delete(sessionId);
     this.frameBuffers.delete(sessionId);
+    this.handleBuffers.delete(sessionId);
     this.unsubscribers.delete(sessionId);
     this.sessionMeta.delete(sessionId);
     this.ctx.logger.info("node-av: destroyed session", { meta: { sessionId } });
@@ -859,17 +1334,24 @@ class DecoderNodeAvAddon extends BaseAddon {
     if (!session) {
       throw new Error(`decoder-nodeav: unknown sessionId ${input.sessionId}`);
     }
-    if (session.openStream) {
-      await session.openStream(input.url);
-    }
+    void input.url;
   }
   async pullFrames(input) {
-    const ringBuffer = this.frameBuffers.get(input.sessionId);
-    if (!ringBuffer) {
+    if (!this.sessions.has(input.sessionId)) {
       throw new Error(`decoder-nodeav: unknown sessionId ${input.sessionId}`);
     }
+    const ringBuffer = this.frameBuffers.get(input.sessionId);
+    if (!ringBuffer) return [];
     return ringBuffer.drain(input.maxCount);
   }
+  async pullHandles(input) {
+    if (!this.sessions.has(input.sessionId)) {
+      throw new Error(`decoder-nodeav: unknown sessionId ${input.sessionId}`);
+    }
+    const handleRing = this.handleBuffers.get(input.sessionId);
+    if (!handleRing) return [];
+    return handleRing.drain(input.maxCount);
+  }
   async updateConfig(input) {
     const session = this.sessions.get(input.sessionId);
     if (!session) {
@@ -884,6 +1366,53 @@ class DecoderNodeAvAddon extends BaseAddon {
     }
     return session.getStats();
   }
+  /**
+   * Read back the pixels a `FrameHandle` refers to from this node's shm ring
+   * (Phase 5 / D9 downstream access). Returns `null` when the slot was
+   * already recycled (latest-wins drop) or the segment could not be opened.
+   * The reader cache opens each named segment once and reuses the reader.
+   *
+   * The reader hands back a `Buffer` view over its **reusable scratch
+   * buffer**, only valid until the next `read` on the same reader; the
+   * cap caller may keep the frame across reads, so the pixels are copied
+   * into a fresh detached `ArrayBuffer` here. This matches the existing
+   * callback-path copy in `wireCallbackSink`.
+   */
+  async getFrame(input) {
+    const frame = this.frameReaders?.read(input.handle) ?? null;
+    if (!frame) {
+      this.getFrameMisses += 1;
+      return null;
+    }
+    this.getFrameHits += 1;
+    const arrayBuf = new ArrayBuffer(frame.data.byteLength);
+    new Uint8Array(arrayBuf).set(frame.data);
+    return {
+      data: new Uint8Array(arrayBuf),
+      width: frame.width,
+      height: frame.height,
+      format: frame.format,
+      timestamp: frame.timestamp
+    };
+  }
+  /**
+   * shm ring usage stats for a `frameSink: 'shm'` session — slot geometry,
+   * frames written, byte budget, plus this addon's running `getFrame`
+   * hit/miss counters. Returns `null` for an unknown session or one whose
+   * shm ring has not yet been armed by a first decoded frame.
+   */
+  async getShmStats(input) {
+    const session = this.sessions.get(input.sessionId);
+    const stats = session?.frameRingSinkOrNull?.getShmStats() ?? null;
+    if (!stats) return null;
+    return {
+      sessionId: input.sessionId,
+      ...stats,
+      budgetMb: RING_BUDGET_MB,
+      getFrameHits: this.getFrameHits,
+      getFrameMisses: this.getFrameMisses
+    };
+  }
   async onShutdown() {
     this.ctx.logger.info("node-av decoder addon shutdown — destroying all sessions");
     const destroyPromises = [];
@@ -895,13 +1424,18 @@ class DecoderNodeAvAddon extends BaseAddon {
     await Promise.all(destroyPromises);
     this.sessions.clear();
     this.frameBuffers.clear();
+    this.handleBuffers.clear();
     this.unsubscribers.clear();
     this.sessionMeta.clear();
+    this.frameReaders?.close();
+    this.frameReaders = null;
   }
 }
 export {
+  DecoderFrameRingSink,
   DecoderNodeAvAddon,
   NodeAvDecoderSession,
-  DecoderNodeAvAddon as default
+  DecoderNodeAvAddon as default,
+  makeSegmentName
 };
 //# sourceMappingURL=index.mjs.map