@camstack/shm-ring 1.0.18 → 1.0.20

package/dist/decoder-frame-ring-sink.d.ts

@@ -0,0 +1,181 @@
+import { FrameMeta } from './frame-ring.js';
+import { IScopedLogger, FrameHandle } from '@camstack/types';
+/**
+ * A reserved ring slot handed back by {@link DecoderFrameRingSink.beginFrame}.
+ *
+ * The slot's seqlock is open (odd) — a reader skips it. The caller fills
+ * `buffer` (a writable view directly over the mapped segment — the node-av
+ * scaler scatters its packed output straight into it, zero write-side copy)
+ * then publishes the frame via {@link DecoderFrameRingSink.commitFrame}.
+ */
+export interface DecoderFrameSlot {
+    /** The ring slot index — pass it back to `commitFrame`. */
+    readonly slot: number;
+    /** A writable view directly over the slot's pixel region in shared memory. */
+    readonly buffer: Buffer;
+}
+/**
+ * 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.
+ */
+export declare const RING_BUDGET_MB: number;
+/** {@link RING_BUDGET_MB} in bytes — the budget passed to `deriveSlotCount`. */
+export declare const RING_BUDGET_BYTES: number;
+/**
+ * Shared prefix for every decoder shm segment name. Startup orphan reclamation
+ * (`purgeOrphanSegments`) keys off this to find segments left behind by a
+ * crashed prior instance.
+ *
+ * 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.
+ */
+export declare const SEGMENT_NAME_PREFIX: "csf.";
+/**
+ * Build a stable, short shm segment name from a seed + generation, under a
+ * segment prefix. `prefix` defaults to {@link SEGMENT_NAME_PREFIX}; a distinct
+ * writer (e.g. the session-decode retention ring) passes its own prefix so its
+ * segments are never reclaimed by another writer's orphan-purge sweep.
+ */
+export declare function makeSegmentName(seed: string, generation: number, prefix?: string): string;
+/** Options for a `DecoderFrameRingSink`. */
+export interface DecoderFrameRingSinkOptions {
+    /**
+     * Stable seed identifying this stream — folded into the segment name. The
+     * decoder passes `deviceId:tag` (or a random fallback); the sink adds a
+     * per-instance random salt so concurrent sessions never collide.
+     */
+    readonly seed: string;
+    readonly logger: IScopedLogger;
+    /**
+     * Cluster node id of the decoder that owns this ring. Stamped into every
+     * `FrameHandle` the writer produces so a downstream consumer knows which
+     * node's `decoder.getFrame` to route a read through.
+     */
+    readonly nodeId: string;
+    /**
+     * Segment name prefix. Defaults to {@link SEGMENT_NAME_PREFIX} (`csf.`). A
+     * non-decoder writer (session-decode retention ring) passes a distinct prefix
+     * (e.g. `csr.`) so its segments are isolated from the decoder's orphan-purge.
+     */
+    readonly segmentPrefix?: string;
+    /**
+     * Per-ring shared-memory budget in bytes. Defaults to {@link RING_BUDGET_BYTES}
+     * (`CAMSTACK_SHM_RING_BUDGET_MB`). A larger budget yields more latest-wins
+     * slots (deeper retention) for the same per-slot geometry.
+     */
+    readonly budgetBytes?: number;
+}
+/** shm ring usage snapshot — see {@link DecoderFrameRingSink.getShmStats}. */
+export interface DecoderShmStats {
+    readonly slotCount: number;
+    readonly slotByteLength: number;
+    readonly segmentBytes: number;
+    readonly framesWritten: number;
+}
+/**
+ * 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`.
+ */
+export declare class DecoderFrameRingSink {
+    private readonly seed;
+    private readonly logger;
+    private readonly nodeId;
+    private readonly segmentPrefix;
+    private readonly budgetBytes;
+    private segment;
+    private writer;
+    private segmentName;
+    private slotByteLength;
+    private generation;
+    private destroyed;
+    /** Frames committed into the ring across this sink's lifetime (all generations). */
+    private framesWritten;
+    constructor(options: DecoderFrameRingSinkOptions);
+    /** Whether a segment has been created (i.e. at least one frame written). */
+    get isArmed(): boolean;
+    /** The current segment name, or `null` before the first frame. */
+    get currentSegmentName(): string | null;
+    /**
+     * 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: Buffer, meta: FrameMeta): FrameHandle | null;
+    /**
+     * 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: number, height: number, format: FrameMeta['format']): DecoderFrameSlot | null;
+    /**
+     * 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: number, meta: FrameMeta): FrameHandle | null;
+    /**
+     * 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(): DecoderShmStats | null;
+    /**
+     * 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: number): void;
+    /** Close + unlink the segment. Idempotent. */
+    destroy(): void;
+    /**
+     * 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.
+     */
+    private recreateSegment;
+    /** Unmap + unlink the current segment, if any. */
+    private releaseSegment;
+}

package/dist/index.d.ts

@@ -10,3 +10,5 @@ export type { ShmSegment, NativeSegmentHandle } from './native.js';
 export { FrameRingWriter, FrameRingReader, computeSegmentSize, bytesPerPixel, computeSlotByteLength, deriveSlotCount, MIN_RING_SLOTS, MAX_RING_SLOTS, } from './frame-ring.js';
 export type { FrameMeta, FrameRead, FrameView, FrameSlotWrite } from './frame-ring.js';
 export { FrameRingReaderCache } from './frame-ring-reader-cache.js';
+export { DecoderFrameRingSink, makeSegmentName, RING_BUDGET_MB, RING_BUDGET_BYTES, SEGMENT_NAME_PREFIX, } from './decoder-frame-ring-sink.js';
+export type { DecoderFrameRingSinkOptions, DecoderFrameSlot, DecoderShmStats, } from './decoder-frame-ring-sink.js';

package/dist/index.js

@@ -694,15 +694,307 @@ var FrameRingReaderCache = class {
 	}
 };
 //#endregion
+//#region src/decoder-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).
+*
+* ## Reuse note
+*
+* This lives in `@camstack/shm-ring` (a host-provided framework package) so both
+* decoder addons (`addon-decoder-nodeav`, `addon-decoder-ffmpeg`) and the
+* session-decode retention ring in `addon-pipeline` share one implementation.
+* The `segmentPrefix` / `budgetBytes` options let a non-decoder writer (e.g. the
+* session-decode retention ring) pick a distinct segment prefix and memory
+* budget without forking the class.
+*/
+/**
+* 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;
+/**
+* Shared prefix for every decoder shm segment name. Startup orphan reclamation
+* (`purgeOrphanSegments`) keys off this to find segments left behind by a
+* crashed prior instance.
+*
+* 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.
+*/
+var SEGMENT_NAME_PREFIX = "csf.";
+/**
+* Build a stable, short shm segment name from a seed + generation, under a
+* segment prefix. `prefix` defaults to {@link SEGMENT_NAME_PREFIX}; a distinct
+* writer (e.g. the session-decode retention ring) passes its own prefix so its
+* segments are never reclaimed by another writer's orphan-purge sweep.
+*/
+function makeSegmentName(seed, generation, prefix = SEGMENT_NAME_PREFIX) {
+	let hash = 5381;
+	for (let i = 0; i < seed.length; i += 1) hash = (hash << 5) + hash + seed.charCodeAt(i) | 0;
+	return `${prefix}${(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;
+	segmentPrefix;
+	budgetBytes;
+	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;
+		this.segmentPrefix = options.segmentPrefix ?? "csf.";
+		this.budgetBytes = options.budgetBytes !== void 0 && Number.isFinite(options.budgetBytes) && options.budgetBytes > 0 ? Math.floor(options.budgetBytes) : RING_BUDGET_BYTES;
+	}
+	/** 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, this.segmentPrefix);
+		const slotCount = deriveSlotCount(this.budgetBytes, slotByteLength);
+		if (slotCount === 6 && 6 * slotByteLength > this.budgetBytes) this.logger.warn("decoder shm ring: budget too small for resolution — using MIN slots", { meta: {
+			slotByteLength,
+			budgetBytes: this.budgetBytes
+		} });
+		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
+exports.DecoderFrameRingSink = DecoderFrameRingSink;
 exports.FrameRingReader = FrameRingReader;
 exports.FrameRingReaderCache = FrameRingReaderCache;
 exports.FrameRingWriter = FrameRingWriter;
 exports.MAX_RING_SLOTS = MAX_RING_SLOTS;
 exports.MIN_RING_SLOTS = MIN_RING_SLOTS;
+exports.RING_BUDGET_BYTES = RING_BUDGET_BYTES;
+exports.RING_BUDGET_MB = RING_BUDGET_MB;
+exports.SEGMENT_NAME_PREFIX = SEGMENT_NAME_PREFIX;
 exports.bytesPerPixel = bytesPerPixel;
 exports.computeSegmentSize = computeSegmentSize;
 exports.computeSlotByteLength = computeSlotByteLength;
 exports.createSegment = createSegment;
 exports.deriveSlotCount = deriveSlotCount;
+exports.makeSegmentName = makeSegmentName;
 exports.openSegment = openSegment;
 exports.unlinkSegment = unlinkSegment;

package/dist/index.mjs

@@ -693,4 +693,291 @@ var FrameRingReaderCache = class {
 	}
 };
 //#endregion
-export { FrameRingReader, FrameRingReaderCache, FrameRingWriter, MAX_RING_SLOTS, MIN_RING_SLOTS, bytesPerPixel, computeSegmentSize, computeSlotByteLength, createSegment, deriveSlotCount, openSegment, unlinkSegment };
+//#region src/decoder-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).
+*
+* ## Reuse note
+*
+* This lives in `@camstack/shm-ring` (a host-provided framework package) so both
+* decoder addons (`addon-decoder-nodeav`, `addon-decoder-ffmpeg`) and the
+* session-decode retention ring in `addon-pipeline` share one implementation.
+* The `segmentPrefix` / `budgetBytes` options let a non-decoder writer (e.g. the
+* session-decode retention ring) pick a distinct segment prefix and memory
+* budget without forking the class.
+*/
+/**
+* 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;
+/**
+* Shared prefix for every decoder shm segment name. Startup orphan reclamation
+* (`purgeOrphanSegments`) keys off this to find segments left behind by a
+* crashed prior instance.
+*
+* 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.
+*/
+var SEGMENT_NAME_PREFIX = "csf.";
+/**
+* Build a stable, short shm segment name from a seed + generation, under a
+* segment prefix. `prefix` defaults to {@link SEGMENT_NAME_PREFIX}; a distinct
+* writer (e.g. the session-decode retention ring) passes its own prefix so its
+* segments are never reclaimed by another writer's orphan-purge sweep.
+*/
+function makeSegmentName(seed, generation, prefix = SEGMENT_NAME_PREFIX) {
+	let hash = 5381;
+	for (let i = 0; i < seed.length; i += 1) hash = (hash << 5) + hash + seed.charCodeAt(i) | 0;
+	return `${prefix}${(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;
+	segmentPrefix;
+	budgetBytes;
+	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;
+		this.segmentPrefix = options.segmentPrefix ?? "csf.";
+		this.budgetBytes = options.budgetBytes !== void 0 && Number.isFinite(options.budgetBytes) && options.budgetBytes > 0 ? Math.floor(options.budgetBytes) : RING_BUDGET_BYTES;
+	}
+	/** 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, this.segmentPrefix);
+		const slotCount = deriveSlotCount(this.budgetBytes, slotByteLength);
+		if (slotCount === 6 && 6 * slotByteLength > this.budgetBytes) this.logger.warn("decoder shm ring: budget too small for resolution — using MIN slots", { meta: {
+			slotByteLength,
+			budgetBytes: this.budgetBytes
+		} });
+		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 { DecoderFrameRingSink, FrameRingReader, FrameRingReaderCache, FrameRingWriter, MAX_RING_SLOTS, MIN_RING_SLOTS, RING_BUDGET_BYTES, RING_BUDGET_MB, SEGMENT_NAME_PREFIX, bytesPerPixel, computeSegmentSize, computeSlotByteLength, createSegment, deriveSlotCount, makeSegmentName, openSegment, unlinkSegment };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/shm-ring",
-  "version": "1.0.18",
+  "version": "1.0.20",
   "description": "CamStack shared-memory frame ring — cross-platform N-API segment mapping + seqlock ring",
   "keywords": [
     "camstack",