@camstack/addon-decoder-ffmpeg 1.1.9 → 1.1.10

package/dist/index.mjs

@@ -1,5 +1,5 @@
 import { randomUUID } from "node:crypto";
-import { FrameRingReaderCache, FrameRingWriter, MIN_RING_SLOTS, computeSegmentSize, computeSlotByteLength, createSegment, deriveSlotCount, unlinkSegment } from "@camstack/shm-ring";
+import { DecoderFrameRingSink, FrameRingReaderCache, RING_BUDGET_MB, SEGMENT_NAME_PREFIX, unlinkSegment } from "@camstack/shm-ring";
 import { spawn } from "node:child_process";
 import { readdirSync } from "node:fs";
 //#region ../../node_modules/zod/v4/core/core.js
@@ -4631,7 +4631,7 @@ function _instanceof(cls, params = {}) {
 	return inst;
 }
 //#endregion
-//#region ../types/dist/sleep-CZDdRBua.mjs
+//#region ../types/dist/sleep-DJaTV2D7.mjs
 var EventCategory = /* @__PURE__ */ function(EventCategory) {
 	EventCategory["SystemBoot"] = "system.boot";
 	EventCategory["SystemAddonsReady"] = "system.addons-ready";
@@ -4817,6 +4817,18 @@ var EventCategory = /* @__PURE__ */ function(EventCategory) {
 	*/
 	EventCategory["PipelineCameraUpdated"] = "pipeline.camera-updated";
 	/**
+	* The cluster camera-source OWNER changed (`clusterRoles.ingestNode`).
+	* Emitted by addon-pipeline-orchestrator whenever it (re)derives node
+	* capabilities — at boot, on agent online/offline, and on an ingest-node
+	* flip. Carries the resolved `ownerNodeId`. The stream-broker consumes it to
+	* keep its ingest-owner-gate decision current WITHOUT a per-`ensureBroker`
+	* cross-process `getIngestOwner` query (push the authority's decision instead
+	* of polling it on the hot path). Idempotent state — re-emitted on every
+	* topology change, so a dropped event self-heals on the next one (plus the
+	* broker's long backstop reconcile query).
+	*/
+	EventCategory["PipelineIngestOwnerChanged"] = "pipeline.ingest-owner-changed";
+	/**
 	* Periodic snapshot of per-node pipeline-runner load
 	* (`RunnerLocalLoad`). Emitted ~1Hz by every runner so UI dashboards
 	* subscribe instead of polling `pipelineRunner.getLocalLoad`.
@@ -5340,10 +5352,6 @@ function hydrateField(field, values) {
 		};
 	}
 	const rawValue = storedValue !== void 0 ? storedValue : defaultValue !== void 0 ? defaultValue : null;
-	if (field.type === "password") return {
-		...field,
-		value: ""
-	};
 	const value = field.type === "textarea" && field.isJson && rawValue !== null && typeof rawValue === "object" ? JSON.stringify(rawValue, null, 2) : rawValue;
 	return {
 		...field,
@@ -6727,6 +6735,9 @@ function method(input, output, options) {
 		timeoutMs: options?.timeoutMs
 	};
 }
+var StaticDirOutputSchema$1 = object({ staticDir: string() });
+var VersionOutputSchema$1 = object({ version: string() });
+method(_void(), StaticDirOutputSchema$1), method(_void(), VersionOutputSchema$1);
 var StaticDirOutputSchema = object({ staticDir: string() });
 var VersionOutputSchema = object({ version: string() });
 method(_void(), StaticDirOutputSchema), method(_void(), VersionOutputSchema);
@@ -6908,6 +6919,36 @@ var ModelFormatsSchema = object({
 	tflite: ModelFormatEntrySchema.optional(),
 	pt: ModelFormatEntrySchema.optional()
 });
+/**
+* Variant-selector grouping axes. Shared by the full `ModelCatalogEntry` and by
+* the reduced `PipelineModelOption` returned in `pipeline.getSchema()` so the
+* grouped Family→Tier→Variant picker renders identically in the config UI and
+* in the pipeline/device steppers. The flat `id` stays the source of truth for
+* resolution/download/persistence; this is a presentation overlay resolved back
+* to an `id`.
+*/
+var ModelVariantGroupSchema = object({
+	/** Top-level family, e.g. `yolo26` (later `d-fine`, `rf-detr`). */
+	family: string(),
+	/** Size within the family, e.g. `n` | `s` | `m` | `l`. */
+	tier: string(),
+	/** Quantization axis. Omit ⇒ the fp32 base build. */
+	precision: _enum(["fp32", "int8"]).optional(),
+	/**
+	* Speed-optimization axis. Omit ⇒ the standard build. `fast` marks a
+	* latency-optimized export (e.g. ReLU-activation variant) — the slot the
+	* future performance variants plug into.
+	*/
+	optimization: _enum(["standard", "fast"]).optional(),
+	/**
+	* Input-resolution axis (square input side, px). Omit ⇒ the family's native
+	* resolution (640 for yolo26). Reduced-input builds (320 / 256) are a big,
+	* cheap latency lever — especially on Apple ANE and the Intel N100 — at a
+	* small-object accuracy cost. Mirrors the model's `inputSize` but lifted onto
+	* the group so the selector can offer it as a variant axis.
+	*/
+	resolution: number().int().positive().optional()
+});
 var ModelCatalogEntrySchema = object({
 	id: string(),
 	name: string(),
@@ -6937,7 +6978,43 @@ var ModelCatalogEntrySchema = object({
 	* Auxiliary files required at runtime (labels JSON, charset dict, etc.).
 	* Downloaded into the same modelsDir alongside the model file.
 	*/
-	extraFiles: array(ModelExtraFileSchema).readonly().optional()
+	extraFiles: array(ModelExtraFileSchema).readonly().optional(),
+	/**
+	* LEGACY entry — retained in the catalog so a persisted operator selection
+	* still RESOLVES (and can be re-activated), but hidden from the selectable
+	* model list and excluded from the auto format-default pick. Set on the
+	* superseded / consolidated models (older lineages, redundant fp16 IRs) so
+	* the active lineup stays the coherent curated ladder without deleting a
+	* model anyone may still be pinned to. `resolveModelForFormat` keeps honoring
+	* an explicit legacy id that has a build for the node's format.
+	*/
+	legacy: boolean().optional(),
+	/**
+	* Measured quality/latency metadata — populated from the benchmark addon on
+	* the real node classes. Absent = not yet measured (most entries today; the
+	* catalog historically carried only `sizeMB`, a poor cross-architecture
+	* speed proxy). `p95LatencyMs` is keyed by node class (e.g. `n100`, `mac`).
+	*/
+	metrics: object({
+		map50: number().optional(),
+		p95LatencyMs: record(string(), number()).optional()
+	}).optional(),
+	/**
+	* SPDX-ish license id of the model weights (e.g. `AGPL-3.0` for Ultralytics
+	* YOLO26, `GPL-3.0` for YOLOv9, `Apache-2.0` for D-FINE/RF-DETR). Matters for
+	* the retraining addon and any future commercial distribution.
+	*/
+	license: string().optional(),
+	/**
+	* Variant-selector grouping. The UI groups models by `family` + `tier` and
+	* offers `precision` / `optimization` as variant axes WITHIN a tier — so all
+	* of a family's sizes and quantizations collapse into one grouped picker
+	* instead of a flat list of `yolo26s`, `yolo26s-int8`, … Absent ⇒ ungrouped
+	* (legacy / custom models) — never shown in the grouped selector. The flat
+	* `id` stays the source of truth for resolution/download/persistence; grouping
+	* is a presentation overlay resolved back to an `id`.
+	*/
+	group: ModelVariantGroupSchema.optional()
 });
 var ConvertTargetSchema = discriminatedUnion("format", [object({
 	format: literal("openvino"),
@@ -6998,8 +7075,8 @@ var RecordingModeSchema = _enum([
 	"onAudioThreshold"
 ]);
 /**
-* First-class, authoritative per-camera storage mode — the netta choice the UI
-* reads directly (never inferred from `rules`):
+* First-class, authoritative per-camera storage mode — the explicit choice the
+* UI reads directly (never inferred from `rules`):
 *  - `off`        — not recording.
 *  - `events`     — record only around triggers (motion / audio threshold),
 *                   with pre/post-buffer.
@@ -8647,26 +8724,13 @@ DeviceType.Light, method(object({
 	percentage: number().min(0).max(100),
 	lastChangedAt: number()
 });
+/** Stream delivery format. (Relocated from the retired `streaming-engine` cap.) */
 var StreamFormatSchema = _enum([
 	"webrtc",
 	"hls",
 	"mjpeg",
 	"rtsp"
 ]);
-var StreamInfoSchema = object({
-	streamId: string(),
-	format: StreamFormatSchema,
-	url: string().nullable(),
-	active: boolean()
-});
-method(object({
-	streamId: string(),
-	sourceUrl: string(),
-	codec: string().optional()
-}), _void(), { kind: "mutation" }), method(object({ streamId: string() }), _void(), { kind: "mutation" }), method(object({
-	streamId: string(),
-	format: StreamFormatSchema
-}), string().nullable()), method(_void(), array(StreamInfoSchema));
 var RtspRestreamEntrySchema = object({
 	brokerId: string(),
 	url: string(),
@@ -9331,7 +9395,7 @@ var ConsumablesStatusSchema = object({
 	})),
 	lastChangedAt: number()
 });
-DeviceType.Camera, DeviceType.Hub, DeviceType.Light, DeviceType.Siren, DeviceType.Switch, DeviceType.Sensor, DeviceType.Thermostat, DeviceType.Button, DeviceType.EventEmitter, DeviceType.Update, DeviceType.Generic, DeviceType.Notifier, DeviceType.Script, DeviceType.Automation, DeviceType.Lock, DeviceType.Cover, DeviceType.Valve, DeviceType.Humidifier, DeviceType.WaterHeater, DeviceType.Fan, DeviceType.MediaPlayer, DeviceType.AlarmPanel, DeviceType.Control, DeviceType.Presence, DeviceType.Weather, DeviceType.Vacuum, DeviceType.LawnMower, DeviceType.Container, DeviceType.Image, method(object({
+Object.values(DeviceType), method(object({
 	deviceId: number().int().nonnegative(),
 	key: string().min(1)
 }), _void(), {
@@ -10246,7 +10310,7 @@ var BoundingBoxSchema = object({
 	w: number(),
 	h: number()
 });
-var SpatialDetectionSchema = object({
+object({
 	class: string(),
 	originalClass: string(),
 	score: number(),
@@ -10381,7 +10445,6 @@ var PipelineDefaultStepSchema = lazy(() => object({
 	enabled: boolean(),
 	modelId: string(),
 	children: array(PipelineDefaultStepSchema).readonly(),
-	engine: PipelineEngineChoiceSchema.optional(),
 	group: string().optional(),
 	settings: record(string(), unknown()).optional()
 }));
@@ -10406,7 +10469,9 @@ var PipelineModelOptionSchema = object({
 	formats: record(string(), object({
 		downloaded: boolean(),
 		sizeMB: number()
-	}))
+	})),
+	group: ModelVariantGroupSchema.optional(),
+	legacy: boolean().optional()
 });
 var ConfigFieldBridge = custom();
 var PipelineAddonSchemaSchema = object({
@@ -10436,11 +10501,6 @@ var PipelineSchemaSchema = object({
 	selectedEngine: PipelineEngineChoiceSchema,
 	slots: array(PipelineSlotSchemaSchema).readonly()
 });
-var DetectorOutputSchema = object({
-	detections: array(SpatialDetectionSchema).readonly(),
-	inferenceMs: number(),
-	modelId: string()
-});
 var EngineProvisioningSchema = object({
 	runtimeId: _enum([
 		"onnx",
@@ -10457,15 +10517,42 @@ var EngineProvisioningSchema = object({
 	]),
 	progress: number().optional(),
 	error: string().optional(),
-	nextRetryAt: number().optional()
+	nextRetryAt: number().optional(),
+	/**
+	* Gate A (config-correctness gate at engine change): human-readable
+	* config issues surfaced EAGERLY when the node's engine changes — model
+	* substitutions ("chose X, running Y") and zero-build steps ("no model
+	* has a <format> build"). Additive/optional: informational only, never
+	* enforced here — `assertEngineReady` (readiness) still gates inference.
+	* Absent/empty when the node-default tree resolves cleanly.
+	*/
+	configIssues: array(string()).optional()
 });
 var PipelineStepInputSchema = lazy(() => object({
 	addonId: string(),
-	modelId: string(),
+	modelId: string().optional(),
 	enabled: boolean().default(true),
 	children: array(PipelineStepInputSchema).optional(),
 	settings: record(string(), unknown()).optional()
 }));
+var ModelSubstitutionSchema = object({
+	addonId: string(),
+	chosen: string(),
+	running: string(),
+	format: string()
+});
+var PipelineValidationIssueSchema = object({
+	addonId: string(),
+	kind: _enum(["unknown-addon", "no-format-build"]),
+	detail: string()
+});
+var PipelineValidationResultSchema = object({
+	ok: boolean(),
+	issues: array(PipelineValidationIssueSchema).readonly(),
+	substitutions: array(ModelSubstitutionSchema).readonly(),
+	/** The node's `currentEngine.format` this validation ran against. */
+	format: string()
+});
 var ReferenceImageEntrySchema = object({
 	filename: string(),
 	stepIds: array(string()).readonly().optional()
@@ -10536,7 +10623,13 @@ method(_void(), array(PipelineEngineChoiceSchema)), method(_void(), PipelineEngi
 })) }), object({ success: literal(true) }), {
 	kind: "mutation",
 	auth: "admin"
-}), method(_void(), PipelineSchemaSchema), method(_void(), array(PipelineDefaultStepSchema).readonly().nullable()), method(_void(), PipelineConfigBridge), method(_void(), ConfigUISchemaBridge), method(_void(), array(PipelineTemplateSchema$1).readonly()), method(object({
+}), method(object({ nodeId: string() }), object({
+	success: literal(true),
+	clearedDevices: number()
+}), {
+	kind: "mutation",
+	auth: "admin"
+}), method(_void(), PipelineSchemaSchema), method(_void(), array(PipelineDefaultStepSchema).readonly().nullable()), method(_void(), PipelineConfigBridge), method(_void(), ConfigUISchemaBridge), method(object({ steps: array(PipelineStepInputSchema) }), PipelineValidationResultSchema), method(_void(), array(PipelineTemplateSchema$1).readonly()), method(object({
 	name: string(),
 	steps: array(PipelineTemplateStepSchema).readonly(),
 	engine: PipelineEngineChoiceSchema
@@ -10553,10 +10646,6 @@ method(_void(), array(PipelineEngineChoiceSchema)), method(_void(), PipelineEngi
 	modelId: string(),
 	format: ModelFormatSchema$1
 }), object({ success: literal(true) }), { kind: "mutation" }), method(object({
-	addonId: string(),
-	frame: FrameInputSchema,
-	config: record(string(), unknown()).optional()
-}), DetectorOutputSchema), method(object({
 	engine: PipelineEngineChoiceSchema.optional(),
 	steps: array(PipelineStepInputSchema).min(1),
 	frame: FrameInputSchema.optional(),
@@ -10796,6 +10885,13 @@ var RunnerFrameSourceSchema = discriminatedUnion("kind", [object({ kind: literal
 	kind: literal("remote-restream"),
 	/** The camera's source-owner node (slice 1: always the hub). */
 	ownerNodeId: string(),
+	/**
+	* The owner's LAN-reachable host, resolved by the orchestrator from the
+	* per-node `reachableHost` override (Cluster UI). When present the runner
+	* dials THIS host for the owner's restream, in preference to the
+	* `CAMSTACK_HUB_URL`-derived default. Absent → auto-detect fallback.
+	*/
+	ownerReachableHost: string().optional(),
 	/** Operator override for the owner host the runner dials. */
 	hubHostnameOverride: string().optional()
 })]).describe("Per-camera frame-source mode for the runner (P2c)");
@@ -10804,13 +10900,11 @@ var RunnerFrameSourceSchema = discriminatedUnion("kind", [object({ kind: literal
 * specific runner instance via `attachCamera`. Carries everything the
 * runner needs to subscribe to the local broker and execute inference.
 *
-* Stateless-pipeline model: the full pipeline content (`engine`, `steps`,
-* optional `audio`) travels with the attach payload. The runner keeps it
-* in RAM for the lifetime of the attach — on rebalance, edit, or
-* restart the orchestrator re-sends the latest snapshot.
-*
-* `engine`/`steps`/`audio` are optional during the additive migration
-* window; once orchestrator + UI are migrated they become required.
+* Stateless-pipeline model: the pipeline content (`steps`, optional
+* `audio`) travels with the attach payload. The runner keeps it in RAM
+* for the lifetime of the attach — on rebalance, edit, or restart the
+* orchestrator re-sends the latest snapshot. Engine is NOT carried: it is
+* node-local, resolved by the executing runner at dispatch time.
 */
 var RunnerCameraConfigSchema = object({
 	deviceId: number(),
@@ -10861,14 +10955,11 @@ var RunnerCameraConfigSchema = object({
 	*/
 	motionSources: MotionSourcesSchema.default(["analyzer"]),
 	pipelineEnabled: boolean().default(true),
-	/** Engine choice for video steps (runtime+backend+format). */
-	engine: PipelineEngineChoiceSchema.optional(),
 	/** Ordered tree of video steps. Absent → runner skips video detection. */
 	steps: array(PipelineStepInputSchema).readonly().optional(),
 	/** Audio classification branch. `enabled:false` disables, null skips. */
 	audio: object({
-		engine: PipelineEngineChoiceSchema,
-		modelId: string(),
+		modelId: string().optional(),
 		enabled: boolean()
 	}).nullable().optional(),
 	/**
@@ -12249,7 +12340,9 @@ var AddonPageDeclarationSchema$1 = object({
 	icon: string(),
 	path: string(),
 	remoteName: string(),
-	bundle: string()
+	bundle: string(),
+	section: string().optional(),
+	sectionLabel: string().optional()
 });
 var AddonPageInfoSchema = object({
 	addonId: string(),
@@ -12289,7 +12382,18 @@ var AddonPageDeclarationSchema = object({
 	* the static-file route can compute an mtime-based cache-buster URL
 	* without a separate filesystem stat.
 	*/
-	bundle: string()
+	bundle: string(),
+	/**
+	* Sidebar section this page docks into. Well-known ids: `'detection'`,
+	* `'cluster'`, `'administration'` — the page renders inside that group.
+	* Any OTHER string creates (or joins) a custom section rendered after
+	* the built-in groups; its label comes from `sectionLabel` (first
+	* declaration wins), falling back to the id. Absent → the legacy
+	* "Addon Pages" group.
+	*/
+	section: string().optional(),
+	/** Display label for a CUSTOM `section` id (ignored for well-known ids). */
+	sectionLabel: string().optional()
 });
 method(_void(), array(AddonPageDeclarationSchema).readonly());
 var AddonHttpRouteSchema = object({
@@ -12505,6 +12609,17 @@ var WidgetMetadataSchema = object({
 		deviceContext: boolean().default(false),
 		integrationContext: boolean().default(false)
 	}),
+	/**
+	* Loadable BEFORE authentication. The normal widget registry listing
+	* (`addon-widgets.listWidgets`) is auth-gated, so a pre-auth surface
+	* (the login page) cannot discover a widget through it. A widget that
+	* declares `preAuth: true` marks itself as safe to mount on a pre-auth
+	* screen — it is surfaced through the PUBLIC `auth.listLoginMethods`
+	* login-method contribution channel (see `login-method.cap.ts`) rather
+	* than the authenticated registry, and its bundle is served by the
+	* public `/api/addon-widgets/:addonId/*` static route. Defaults false.
+	*/
+	preAuth: boolean().optional().default(false),
 	/** Dashboard placement HINTS (operator can override per instance). */
 	defaultSize: WidgetSizeEnum.default("md"),
 	allowedSizes: array(WidgetSizeEnum).readonly().default([
@@ -12843,6 +12958,66 @@ method(object({
 	password: string()
 }), AuthResultSchema.nullable(), { kind: "mutation" }), method(object({ state: string() }), string()), method(record(string(), string()), AuthResultSchema, { kind: "mutation" }), method(object({ token: string() }), AuthResultSchema.nullable());
 /**
+* `login-method` — collection cap through which auth addons contribute
+* their pre-auth login surfaces to the login page. This is the SINGLE,
+* generic mechanism that supersedes the dead `auth.listProviders` reader:
+* every auth addon (OIDC, magic-link, WebAuthn/passkey) registers a
+* `login-method` provider and the PUBLIC `auth.listLoginMethods`
+* procedure aggregates them for the unauthenticated login page.
+*
+* A contribution is a discriminated union on `kind`:
+*
+*  - `redirect` — a declarative button. The login page renders a generic
+*    button that navigates to `startUrl` (an addon-owned HTTP route).
+*    Covers OIDC (`/addon/auth-oidc/<id>/start`) and magic-link with
+*    ZERO shell-side JS. A future SSO addon plugs in the same way — the
+*    login page needs NO change.
+*
+*  - `widget` — a Module-Federation widget the login page mounts (via
+*    `loadRemoteBundle`) for an in-page ceremony. Covers the passkey
+*    login ceremony, which must run `@simplewebauthn/browser` INSIDE the
+*    addon bundle. The referenced widget also declares `preAuth: true` in
+*    its `addon-widgets-source` catalog entry. `auth.listLoginMethods`
+*    stamps a public `bundleUrl` from `addonId` + `bundle`.
+*
+* Every contribution carries a `stage`:
+*  - `primary`        — shown on the first credentials screen (OIDC /
+*                       magic-link buttons; a future usernameless passkey).
+*  - `second-factor`  — shown AFTER the password leg, gated on the
+*                       returned `factors` (passkey-as-2FA today).
+*
+* `mount: skip` — the cap is read server-side by the core auth router
+* (`registry.getCollection('login-method')`), never mounted as its own
+* tRPC router.
+*/
+/** When a login method renders in the two-phase login flow. */
+var LoginStageEnum = _enum(["primary", "second-factor"]);
+/** One login-method contribution — redirect button OR pre-auth widget. */
+var LoginMethodContributionSchema = discriminatedUnion("kind", [object({
+	kind: literal("redirect"),
+	/** Stable id within the login-method set (e.g. `auth-oidc/google`). */
+	id: string(),
+	/** Operator-facing button label. */
+	label: string(),
+	/** lucide-react icon name. */
+	icon: string().optional(),
+	/** Addon-owned HTTP route the button navigates to (GET). */
+	startUrl: string(),
+	stage: LoginStageEnum
+}), object({
+	kind: literal("widget"),
+	/** Stable id within the login-method set (e.g. `auth-webauthn/passkey-login`). */
+	id: string(),
+	/** Owning addon id — drives the public bundle URL + the MF namespace. */
+	addonId: string(),
+	/** Bundle filename inside the addon's dist dir (`remoteEntry.js`). */
+	bundle: string(),
+	/** MF remote descriptor — `{ remoteName, exposedModule, componentKey }`. */
+	remote: WidgetRemoteSchema,
+	stage: LoginStageEnum
+})]);
+method(_void(), array(LoginMethodContributionSchema).readonly());
+/**
 * Orchestrator-side destination metadata. The orchestrator computes
 * `id = <addonId>:<subId>` from its provider lookup so consumers
 * (admin UI, restore flow) see one canonical key.
@@ -15224,11 +15399,11 @@ DeviceType.Camera, method(object({ deviceId: number() }), array(TrackSchema).rea
 	timestamp: number()
 });
 var CameraPipelineConfigSchema = object({
-	engine: PipelineEngineChoiceSchema,
+	engine: PipelineEngineChoiceSchema.optional(),
 	steps: array(PipelineStepInputSchema).readonly(),
 	audio: object({
-		engine: PipelineEngineChoiceSchema,
-		modelId: string(),
+		engine: PipelineEngineChoiceSchema.optional(),
+		modelId: string().optional(),
 		enabled: boolean(),
 		settings: record(string(), unknown()).readonly().optional()
 	}).nullable().optional()
@@ -15243,7 +15418,7 @@ var PipelineTemplateSchema = object({
 });
 var AgentAddonConfigSchema = object({
 	enabled: boolean(),
-	modelId: string(),
+	modelId: string().optional(),
 	settings: record(string(), unknown()).readonly()
 });
 var AgentPipelineSettingsSchema = object({
@@ -15253,12 +15428,25 @@ var AgentPipelineSettingsSchema = object({
 	detectWeight: number().positive().optional(),
 	/** Node is eligible to run the detection pipeline (decode + inference). */
 	detect: boolean().optional(),
-	/** Node is eligible to host decoder sessions. */
+	/**
+	* DEPRECATED AND IGNORED. Decode is always co-located with its frame
+	* consumer, so decode eligibility IS detect eligibility. Kept optional in
+	* the schema ONLY so persisted stores written before the removal still
+	* parse — no code reads it and no write path emits it.
+	*/
 	decode: boolean().optional(),
 	/** Node is eligible to run audio-analyzer sessions. */
 	audio: boolean().optional(),
 	/** Node is eligible to be the ingest / source-owner (serve the restream). */
-	ingest: boolean().optional()
+	ingest: boolean().optional(),
+	/**
+	* Operator override for the LAN host a cross-node decoder dials to reach
+	* THIS node's restream (Cluster UI). Absent → auto-detect: a remote runner
+	* falls back to its `CAMSTACK_HUB_URL`-derived host (the Moleculer address
+	* it already uses to reach the hub). Set this only when the auto-detected
+	* address is wrong (multi-homed host, NAT, custom interface).
+	*/
+	reachableHost: string().optional()
 });
 var CameraPipelineForAgentSchema = object({
 	steps: array(PipelineStepInputSchema).readonly(),
@@ -15306,25 +15494,6 @@ var PipelineAssignmentSchema = object({
 	assignedAt: number()
 });
 /**
-* Decoder placement record. Symmetric to `PipelineAssignmentSchema` but for
-* the decoder-node placement domain (`balanceDecoder` decision: manual pin
-* → co-located with pipeline → capacity).
-*/
-var DecoderAssignmentSchema = object({
-	deviceId: number(),
-	/** Moleculer node id of the decoder provider currently responsible for this camera. */
-	decoderNodeId: string(),
-	/** True when the assignment was set manually via `assignDecoder`, false when chosen by the balancer. */
-	pinned: boolean(),
-	/** Why this assignment was made — useful for debugging the decoder balancer. */
-	reason: _enum([
-		"manual",
-		"co-located",
-		"capacity",
-		"hardware-affinity"
-	])
-});
-/**
 * Per-agent load summary surfaced to the load balancer + dashboards.
 * Aggregated from each runner's `getLocalLoad` cap call.
 */
@@ -15364,6 +15533,15 @@ var GlobalMetricsSchema = object({
 * capability providers.
 */
 var CapabilityBindingsSchema = record(string(), string());
+/**
+* The cluster's single camera-source owner (`clusterRoles.ingestNode`) plus
+* its LAN-reachable host, if one is registered. See `getIngestOwner`.
+*/
+var IngestOwnerSchema = object({
+	ownerNodeId: string(),
+	reachableHost: string().optional(),
+	configIssue: string().optional()
+});
 /** Source block — always present; derives from the stream catalog. */
 var CameraSourceStatusSchema = object({ streams: array(object({
 	camStreamId: string(),
@@ -15378,6 +15556,14 @@ var CameraAssignmentStatusSchema = object({
 	detectionNodeId: string().nullable(),
 	decoderNodeId: string().nullable(),
 	audioNodeId: string().nullable(),
+	/**
+	* The node that OWNS this camera's physical source pull (dials the RTSP and
+	* hosts the broker/restream) — the cluster ingest owner today
+	* (`clusterRoles.ingestNode`), per-camera once source assignment lands. Lets
+	* the UI show WHERE a camera is sourced without SSH/logs, and is the node the
+	* broker block below was read from (pinned). Nullable only pre-wiring.
+	*/
+	sourceNodeId: string().nullable(),
 	pinned: object({
 		detection: boolean(),
 		decoder: boolean(),
@@ -15510,16 +15696,7 @@ method(object({
 }), object({ success: literal(true) }), {
 	kind: "mutation",
 	auth: "admin"
-}), method(object({
-	deviceId: number(),
-	nodeId: string()
-}), _void(), {
-	kind: "mutation",
-	auth: "admin"
-}), method(object({ deviceId: number() }), _void(), {
-	kind: "mutation",
-	auth: "admin"
-}), method(_void(), array(DecoderAssignmentSchema).readonly()), method(object({
+}), method(_void(), IngestOwnerSchema), method(object({
 	deviceId: number(),
 	nodeId: string()
 }), object({ success: literal(true) }), {
@@ -15540,10 +15717,7 @@ method(object({
 	nodeId: string(),
 	pinned: boolean(),
 	assignedAt: number()
-}))), method(object({
-	deviceId: number(),
-	pipelineNodeId: string().optional()
-}), DecoderAssignmentSchema), method(object({ agentNodeId: string() }), AgentPipelineSettingsSchema.nullable()), method(_void(), array(object({
+}))), method(object({ agentNodeId: string() }), AgentPipelineSettingsSchema.nullable()), method(_void(), array(object({
 	nodeId: string(),
 	settings: AgentPipelineSettingsSchema
 })).readonly()), method(object({
@@ -15573,12 +15747,26 @@ method(object({
 }), method(object({
 	agentNodeId: string(),
 	detect: boolean().nullable().optional(),
-	decode: boolean().nullable().optional(),
 	audio: boolean().nullable().optional(),
 	ingest: boolean().nullable().optional()
 }), object({ success: literal(true) }), {
 	kind: "mutation",
 	auth: "admin"
+}), method(object({
+	agentNodeId: string(),
+	reachableHost: string().nullable()
+}), object({ success: literal(true) }), {
+	kind: "mutation",
+	auth: "admin"
+}), method(object({ agentNodeId: string() }), object({
+	success: literal(true),
+	/** Hardware-aware default detection model now in effect on the node (null when unresolvable). */
+	effectiveModelId: string().nullable(),
+	/** Number of cameras whose node-scoped overrides were cleared. */
+	clearedCameraOverrides: number()
+}), {
+	kind: "mutation",
+	auth: "admin"
 }), method(object({ deviceId: number() }), CameraPipelineSettingsSchema.nullable()), method(object({
 	deviceId: number(),
 	addonId: string(),
@@ -15623,22 +15811,131 @@ method(object({
 	kind: "mutation",
 	auth: "admin"
 });
-var RegisteredStreamSchema = object({
-	streamId: string(),
-	label: string().optional(),
-	codec: string(),
-	type: _enum(["video", "audio"]),
-	sourceUrl: string()
+/**
+* server-management — per-NODE singleton capability for a node's ROOT
+* package lifecycle (runtime-updatable node packages, phase 2: hub + docker
+* agents).
+*
+* Each node's root package (`@camstack/server` on the hub, `@camstack/agent`
+* on agents) carries the whole software stack in its npm dep tree, so ONE
+* version describes the node. Updates install into
+* `<dataDir>/server-root/versions/<v>/` and apply on restart via the baked
+* starter (probation boot + auto-rollback to N-1).
+*
+* Providers:
+*   - HUB: `ServerUpdateService` behind the `server-provided` mount
+*     (`buildServerProviders` in trpc.router.ts) — the default target for
+*     unpinned calls.
+*   - AGENT: `AgentUpdateService` registered by the agent bootstrap under
+*     the synthetic `agent-runtime` addonId and declared in the agent's
+*     `$hub.registerNode` manifest.
+*
+* Node routing: singleton caps get the codegen/runtime-builder `nodeId`
+* injection on every method — `input.nodeId` (or `nodePin(nodeId)` from the
+* SDK) routes the call to that node's provider via the standard remote
+* proxy (`createCapabilityProxy` → `$agent-cap-fwd` → the agent's
+* in-process provider lookup). No `nodeId` → the hub's own provider.
+*
+* Spec: docs/superpowers/specs/2026-07-12-runtime-updatable-node-packages-design.md
+*/
+/**
+* Where the running hub's code was loaded from:
+*  - `workspace` — dev checkout (tsx / workspace dist); the starter defers to
+*    plain resolution and runtime updates are refused.
+*  - `baked`     — the immutable image seed closure (no data-dir root active).
+*  - `data-root` — the runtime-updatable `<dataDir>/server-root` closure.
+*/
+var ServerBootModeSchema = _enum([
+	"workspace",
+	"baked",
+	"data-root"
+]);
+/**
+* Update lifecycle state:
+*  - `idle` / `checking` / `staging` — steady / in-flight registry work.
+*  - `pending-restart` — a version is staged and the node has NOT yet
+*    restarted onto it (still running the OLD version).
+*  - `awaiting-confirmation` — the node HAS restarted onto the staged version
+*    (it is the active probation boot) and is waiting to confirm boot-health.
+*    Apply/rollback are refused in this state and the node must NOT be
+*    manually restarted, or the probation boot auto-rolls-back.
+*/
+var ServerUpdateStateSchema = _enum([
+	"idle",
+	"checking",
+	"staging",
+	"pending-restart",
+	"awaiting-confirmation"
+]);
+var ServerRollbackInfoSchema = object({
+	/** The version that failed (or was manually rolled back). */
+	fromVersion: string(),
+	/** The version rolled back to; null = the baked seed. */
+	toVersion: string().nullable(),
+	atMs: number(),
+	reason: string()
 });
-var ExposedResourceSchema = object({
-	streamId: string(),
-	format: string(),
-	value: string()
+var ServerPackageStatusSchema = object({
+	/** Root package name (`@camstack/server` on the hub). */
+	packageName: string(),
+	/** Version of the code the running process ACTUALLY loaded. */
+	runningVersion: string().nullable(),
+	/** Node.js runtime version the node's process runs on (`process.versions.node`). */
+	nodeRuntimeVersion: string().nullable(),
+	/** Active data-dir root version; null when booted from seed/workspace. */
+	activeVersion: string().nullable(),
+	/** N-1 version kept for rollback; null when no previous version exists. */
+	previousVersion: string().nullable(),
+	/** Version of the immutable baked seed closure (image fallback). */
+	seedVersion: string().nullable(),
+	/** Latest registry version from the most recent check (null = never checked). */
+	latestVersion: string().nullable(),
+	updateAvailable: boolean(),
+	bootMode: ServerBootModeSchema,
+	updateState: ServerUpdateStateSchema,
+	/** Version staged + awaiting its probation boot, when one is pending. */
+	pendingVersion: string().nullable(),
+	/** Set when the last freshly-activated version failed its boot health-check. */
+	rolledBack: ServerRollbackInfoSchema.nullable(),
+	/**
+	* True when `server-root/state.json` EXISTS but is unreadable/corrupt — the
+	* hub is running from the baked seed (or workspace) while installed data-dir
+	* versions are being IGNORED. Surfaced as a warning in the UI.
+	*/
+	stateFileCorrupt: boolean(),
+	lastCheckedAtMs: number().nullable()
+});
+var ServerUpdateCheckResultSchema = object({
+	packageName: string(),
+	runningVersion: string().nullable(),
+	latestVersion: string().nullable(),
+	updateAvailable: boolean(),
+	checkedAtMs: number(),
+	/** Non-null when the registry lookup failed (offline, bad registry, …). */
+	error: string().nullable()
+});
+var ServerUpdateActionResultSchema = object({
+	accepted: boolean(),
+	targetVersion: string().nullable(),
+	/** True when a graceful restart was scheduled to apply the change. */
+	restarting: boolean(),
+	message: string()
+});
+method(_void(), ServerPackageStatusSchema, { auth: "admin" }), method(_void(), ServerUpdateCheckResultSchema, {
+	kind: "mutation",
+	auth: "admin"
+}), method(object({ 
+/** Explicit target version; omitted = latest from the registry. */
+version: string().optional() }), ServerUpdateActionResultSchema, {
+	kind: "mutation",
+	auth: "admin"
+}), method(_void(), ServerUpdateActionResultSchema, {
+	kind: "mutation",
+	auth: "admin"
+}), method(_void(), ServerUpdateActionResultSchema, {
+	kind: "mutation",
+	auth: "admin"
 });
-method(object({
-	deviceId: number(),
-	streams: array(RegisteredStreamSchema).readonly()
-}), _void(), { kind: "mutation" }), method(object({ deviceId: number() }), _void(), { kind: "mutation" }), method(object({ deviceId: number() }), array(ExposedResourceSchema).readonly());
 /**
 * Query filter for settings-store collections.
 */
@@ -15791,9 +16088,9 @@ method(SendEmailInputSchema, SendEmailResultSchema, {
 /**
 * A single device snapshot returned as base64 JPEG/PNG.
 *
-* Shared with the `snapshot-provider` collection cap — the orchestrator
-* receives the same shape from each native provider and from the
-* broker-based fallback.
+* The `SnapshotAddon` wrapper returns this shape whether the frame came from
+* the device-native provider (onboard capture) or from the stream-broker
+* prebuffer fallback.
 */
 var SnapshotImageSchema = object({
 	base64: string(),
@@ -15825,10 +16122,6 @@ DeviceType.Camera, method(object({
 	kind: "mutation",
 	auth: "admin"
 });
-method(object({ deviceId: number() }), boolean()), method(object({
-	deviceId: number(),
-	streamId: string().optional()
-}), SnapshotImageSchema.nullable());
 /**
 * `sso-bridge` — internal hub-only cap that lets SSO-style auth
 * providers (OIDC, SAML, magic-link, …) mint an HMAC-signed token
@@ -16189,9 +16482,10 @@ method(object({
 	auth: "admin"
 });
 /**
-* Optional client-side hints sent at session creation to help the
-* provider pick the best native source. All fields are optional —
-* a viewer that knows nothing still gets a sane default.
+* Optional client-side hints sent at session creation to help the provider
+* pick the best native source. All fields optional — a viewer that knows
+* nothing still gets a sane default. (Relocated from the retired `webrtc`
+* collection cap; this `webrtc-session` cap is the live signaling surface.)
 */
 var webrtcClientHintsSchema = object({
 	viewportWidth: number().int().positive().optional(),
@@ -16202,22 +16496,6 @@ var webrtcClientHintsSchema = object({
 	/** Hard tier override; takes precedence over scoring when registered. */
 	prefersTier: string().optional()
 }).partial();
-method(object({
-	streamId: string(),
-	sdpOffer: string()
-}), string(), { kind: "mutation" }), method(object({ streamId: string() }), boolean()), method(object({
-	streamId: string(),
-	codec: string()
-}), _void(), { kind: "mutation" }), method(object({ streamId: string() }), _void(), { kind: "mutation" }), method(object({
-	streamId: string(),
-	hints: webrtcClientHintsSchema.optional()
-}), object({
-	sessionId: string(),
-	sdpOffer: string()
-}), { kind: "mutation" }), method(object({
-	sessionId: string(),
-	sdpAnswer: string()
-}), _void(), { kind: "mutation" }), method(object({ sessionId: string() }), _void(), { kind: "mutation" }), method(object({ streamId: string() }), boolean());
 /**
 * Discriminated target for a WebRTC session. The client sends this
 * structured object instead of building / parsing brokerId strings;
@@ -17645,6 +17923,16 @@ var TopologyCategorySchema = object({
 	healthy: number(),
 	addons: array(TopologyCategoryAddonSchema).readonly()
 });
+/**
+* The node's runtime-updatable ROOT package (`@camstack/server` on the hub,
+* `@camstack/agent` on agents) as reported by its `registerNode` manifest —
+* version visibility for the Server management surface. Nullable: offline
+* rows and pre-phase-2 nodes report none.
+*/
+var TopologyRootPackageSchema = object({
+	name: string(),
+	version: string()
+});
 var TopologyNodeSchema = object({
 	id: string(),
 	name: string(),
@@ -17668,7 +17956,8 @@ var TopologyNodeSchema = object({
 		status: string()
 	})).readonly(),
 	processes: array(TopologyProcessSchema).readonly(),
-	categories: array(TopologyCategorySchema).readonly()
+	categories: array(TopologyCategorySchema).readonly(),
+	rootPackage: TopologyRootPackageSchema.nullable()
 });
 var CapUsageEdgeSchema = object({
 	callerAddonId: string(),
@@ -20468,6 +20757,12 @@ Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"loginMethod.getLoginMethods": {
+		capName: "login-method",
+		capScope: "system",
+		addonId: null,
+		access: "view"
+	},
 	"mediaPlayer.next": {
 		capName: "media-player",
 		capScope: "device",
@@ -21098,23 +21393,23 @@ Object.freeze({
 		addonId: null,
 		access: "create"
 	},
-	"pipelineExecutor.deleteModel": {
+	"pipelineExecutor.clearDeviceOverrides": {
 		capName: "pipeline-executor",
 		capScope: "system",
 		addonId: null,
 		access: "delete"
 	},
-	"pipelineExecutor.deleteTemplate": {
+	"pipelineExecutor.deleteModel": {
 		capName: "pipeline-executor",
 		capScope: "system",
 		addonId: null,
 		access: "delete"
 	},
-	"pipelineExecutor.detect": {
+	"pipelineExecutor.deleteTemplate": {
 		capName: "pipeline-executor",
 		capScope: "system",
 		addonId: null,
-		access: "view"
+		access: "delete"
 	},
 	"pipelineExecutor.downloadModel": {
 		capName: "pipeline-executor",
@@ -21308,13 +21603,13 @@ Object.freeze({
 		addonId: null,
 		access: "create"
 	},
-	"pipelineOrchestrator.assignAudio": {
-		capName: "pipeline-orchestrator",
+	"pipelineExecutor.validatePipeline": {
+		capName: "pipeline-executor",
 		capScope: "system",
 		addonId: null,
-		access: "create"
+		access: "view"
 	},
-	"pipelineOrchestrator.assignDecoder": {
+	"pipelineOrchestrator.assignAudio": {
 		capName: "pipeline-orchestrator",
 		capScope: "system",
 		addonId: null,
@@ -21398,19 +21693,13 @@ Object.freeze({
 		addonId: null,
 		access: "view"
 	},
-	"pipelineOrchestrator.getDecoderAssignment": {
-		capName: "pipeline-orchestrator",
-		capScope: "system",
-		addonId: null,
-		access: "view"
-	},
-	"pipelineOrchestrator.getDecoderAssignments": {
+	"pipelineOrchestrator.getGlobalMetrics": {
 		capName: "pipeline-orchestrator",
 		capScope: "system",
 		addonId: null,
 		access: "view"
 	},
-	"pipelineOrchestrator.getGlobalMetrics": {
+	"pipelineOrchestrator.getIngestOwner": {
 		capName: "pipeline-orchestrator",
 		capScope: "system",
 		addonId: null,
@@ -21452,6 +21741,12 @@ Object.freeze({
 		addonId: null,
 		access: "delete"
 	},
+	"pipelineOrchestrator.resetNodePipelineDefaults": {
+		capName: "pipeline-orchestrator",
+		capScope: "system",
+		addonId: null,
+		access: "delete"
+	},
 	"pipelineOrchestrator.resolvePipeline": {
 		capName: "pipeline-orchestrator",
 		capScope: "system",
@@ -21488,37 +21783,37 @@ Object.freeze({
 		addonId: null,
 		access: "create"
 	},
-	"pipelineOrchestrator.setCameraPipelineForAgent": {
+	"pipelineOrchestrator.setAgentReachableHost": {
 		capName: "pipeline-orchestrator",
 		capScope: "system",
 		addonId: null,
 		access: "create"
 	},
-	"pipelineOrchestrator.setCameraStepOverride": {
+	"pipelineOrchestrator.setCameraPipelineForAgent": {
 		capName: "pipeline-orchestrator",
 		capScope: "system",
 		addonId: null,
 		access: "create"
 	},
-	"pipelineOrchestrator.setCameraStepToggle": {
+	"pipelineOrchestrator.setCameraStepOverride": {
 		capName: "pipeline-orchestrator",
 		capScope: "system",
 		addonId: null,
 		access: "create"
 	},
-	"pipelineOrchestrator.setCapabilityBinding": {
+	"pipelineOrchestrator.setCameraStepToggle": {
 		capName: "pipeline-orchestrator",
 		capScope: "system",
 		addonId: null,
 		access: "create"
 	},
-	"pipelineOrchestrator.unassignAudio": {
+	"pipelineOrchestrator.setCapabilityBinding": {
 		capName: "pipeline-orchestrator",
 		capScope: "system",
 		addonId: null,
 		access: "create"
 	},
-	"pipelineOrchestrator.unassignDecoder": {
+	"pipelineOrchestrator.unassignAudio": {
 		capName: "pipeline-orchestrator",
 		capScope: "system",
 		addonId: null,
@@ -21818,33 +22113,45 @@ Object.freeze({
 		addonId: null,
 		access: "create"
 	},
-	"restreamer.getExposedResources": {
-		capName: "restreamer",
+	"scriptRunner.run": {
+		capName: "script-runner",
+		capScope: "device",
+		addonId: null,
+		access: "create"
+	},
+	"scriptRunner.stop": {
+		capName: "script-runner",
+		capScope: "device",
+		addonId: null,
+		access: "create"
+	},
+	"serverManagement.applyServerUpdate": {
+		capName: "server-management",
 		capScope: "system",
 		addonId: null,
-		access: "view"
+		access: "create"
 	},
-	"restreamer.registerDevice": {
-		capName: "restreamer",
+	"serverManagement.checkServerUpdate": {
+		capName: "server-management",
 		capScope: "system",
 		addonId: null,
 		access: "create"
 	},
-	"restreamer.unregisterDevice": {
-		capName: "restreamer",
+	"serverManagement.getServerPackageStatus": {
+		capName: "server-management",
 		capScope: "system",
 		addonId: null,
-		access: "delete"
+		access: "view"
 	},
-	"scriptRunner.run": {
-		capName: "script-runner",
-		capScope: "device",
+	"serverManagement.restartServer": {
+		capName: "server-management",
+		capScope: "system",
 		addonId: null,
 		access: "create"
 	},
-	"scriptRunner.stop": {
-		capName: "script-runner",
-		capScope: "device",
+	"serverManagement.rollbackServerUpdate": {
+		capName: "server-management",
+		capScope: "system",
 		addonId: null,
 		access: "create"
 	},
@@ -21938,18 +22245,6 @@ Object.freeze({
 		addonId: null,
 		access: "create"
 	},
-	"snapshotProvider.getSnapshot": {
-		capName: "snapshot-provider",
-		capScope: "system",
-		addonId: null,
-		access: "view"
-	},
-	"snapshotProvider.supportsDevice": {
-		capName: "snapshot-provider",
-		capScope: "system",
-		addonId: null,
-		access: "view"
-	},
 	"ssoBridge.signBridgeToken": {
 		capName: "sso-bridge",
 		capScope: "system",
@@ -22376,30 +22671,6 @@ Object.freeze({
 		addonId: null,
 		access: "view"
 	},
-	"streamingEngine.getStreamUrl": {
-		capName: "streaming-engine",
-		capScope: "system",
-		addonId: null,
-		access: "view"
-	},
-	"streamingEngine.listStreams": {
-		capName: "streaming-engine",
-		capScope: "system",
-		addonId: null,
-		access: "view"
-	},
-	"streamingEngine.registerStream": {
-		capName: "streaming-engine",
-		capScope: "system",
-		addonId: null,
-		access: "create"
-	},
-	"streamingEngine.unregisterStream": {
-		capName: "streaming-engine",
-		capScope: "system",
-		addonId: null,
-		access: "delete"
-	},
 	"streamParams.getConfigSchema": {
 		capName: "stream-params",
 		capScope: "device",
@@ -22748,6 +23019,18 @@ Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"viewerUi.getStaticDir": {
+		capName: "viewer-ui",
+		capScope: "system",
+		addonId: null,
+		access: "view"
+	},
+	"viewerUi.getVersion": {
+		capName: "viewer-ui",
+		capScope: "system",
+		addonId: null,
+		access: "view"
+	},
 	"waterHeater.setAway": {
 		capName: "water-heater",
 		capScope: "device",
@@ -22766,54 +23049,6 @@ Object.freeze({
 		addonId: null,
 		access: "create"
 	},
-	"webrtc.closeSession": {
-		capName: "webrtc",
-		capScope: "system",
-		addonId: null,
-		access: "create"
-	},
-	"webrtc.createSession": {
-		capName: "webrtc",
-		capScope: "system",
-		addonId: null,
-		access: "create"
-	},
-	"webrtc.handleAnswer": {
-		capName: "webrtc",
-		capScope: "system",
-		addonId: null,
-		access: "create"
-	},
-	"webrtc.handleOffer": {
-		capName: "webrtc",
-		capScope: "system",
-		addonId: null,
-		access: "create"
-	},
-	"webrtc.hasAdaptiveBitrate": {
-		capName: "webrtc",
-		capScope: "system",
-		addonId: null,
-		access: "view"
-	},
-	"webrtc.registerStream": {
-		capName: "webrtc",
-		capScope: "system",
-		addonId: null,
-		access: "create"
-	},
-	"webrtc.supportsStream": {
-		capName: "webrtc",
-		capScope: "system",
-		addonId: null,
-		access: "view"
-	},
-	"webrtc.unregisterStream": {
-		capName: "webrtc",
-		capScope: "system",
-		addonId: null,
-		access: "delete"
-	},
 	"webrtcSession.addIceCandidate": {
 		capName: "webrtc-session",
 		capScope: "device",
@@ -23511,276 +23746,6 @@ var FrameDropper = class {
 	}
 };
 //#endregion
-//#region src/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.
-*/
-/**
-* 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.
-*/
-var SEGMENT_NAME_PREFIX = "csf.";
-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 `${SEGMENT_NAME_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;
-	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
 //#region src/frame-stream-splitter.ts
 var FrameStreamSplitter = class {
 	frameSize;