@camstack/addon-pipeline 0.1.8

package/dist/pipeline-runner/index.js

@@ -0,0 +1,1669 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+Object.defineProperties(exports, { __esModule: { value: true }, [Symbol.toStringTag]: { value: "Module" } });
+const types = require("@camstack/types");
+const zod = require("zod");
+class FrameQueue {
+  constructor(maxSize) {
+    this.maxSize = maxSize;
+  }
+  latest = null;
+  _droppedFrames = 0;
+  enqueue(frame) {
+    if (this.latest !== null) {
+      this._droppedFrames++;
+    }
+    this.latest = frame;
+  }
+  dequeue() {
+    const frame = this.latest ?? void 0;
+    this.latest = null;
+    return frame;
+  }
+  get size() {
+    return this.latest !== null ? 1 : 0;
+  }
+  get droppedFrames() {
+    return this._droppedFrames;
+  }
+  clear() {
+    this.latest = null;
+  }
+}
+class Semaphore {
+  _concurrency;
+  _available;
+  waiters = [];
+  constructor(concurrency) {
+    this._concurrency = concurrency;
+    this._available = concurrency;
+  }
+  get concurrency() {
+    return this._concurrency;
+  }
+  get available() {
+    return this._available;
+  }
+  /**
+   * Change the concurrency limit at runtime. Growing wakes as many
+   * pending waiters as possible without exceeding the new headroom;
+   * shrinking simply caps `_available` to `max(0, _available + delta)`.
+   * In-flight permits are never revoked — the excess will drain
+   * naturally as existing callers release.
+   */
+  resize(newConcurrency) {
+    if (newConcurrency < 1) throw new Error("Semaphore: concurrency must be >= 1");
+    const delta = newConcurrency - this._concurrency;
+    this._concurrency = newConcurrency;
+    this._available = Math.max(0, this._available + delta);
+    while (this._available > 0 && this.waiters.length > 0) {
+      const next = this.waiters.shift();
+      if (next) next();
+    }
+  }
+  async acquire() {
+    if (this._available > 0) {
+      this._available--;
+      return () => this.release();
+    }
+    return new Promise((resolve) => {
+      this.waiters.push(() => {
+        this._available--;
+        resolve(() => this.release());
+      });
+    });
+  }
+  release() {
+    this._available++;
+    const next = this.waiters.shift();
+    if (next) next();
+  }
+}
+const REPORT_INTERVAL_MS = 1e4;
+class PipelineTimingSampler {
+  detSamples = /* @__PURE__ */ new Map();
+  motSamples = /* @__PURE__ */ new Map();
+  audioSamples = /* @__PURE__ */ new Map();
+  droppedFrames = 0;
+  reportTimer = null;
+  log = null;
+  runtimeInfo = {};
+  setLogger(logger) {
+    this.log = logger;
+  }
+  start() {
+    if (this.reportTimer) return;
+    this.reportTimer = setInterval(() => this.report(), REPORT_INTERVAL_MS);
+  }
+  stop() {
+    if (this.reportTimer) {
+      clearInterval(this.reportTimer);
+      this.reportTimer = null;
+    }
+  }
+  addSample(deviceId, s) {
+    if (!this.detSamples.has(deviceId)) this.detSamples.set(deviceId, []);
+    this.detSamples.get(deviceId).push(s);
+  }
+  addMotionSample(deviceId, ms) {
+    if (!this.motSamples.has(deviceId)) this.motSamples.set(deviceId, []);
+    this.motSamples.get(deviceId).push(ms);
+  }
+  addAudioSample(deviceId, s) {
+    if (!this.audioSamples.has(deviceId)) this.audioSamples.set(deviceId, []);
+    this.audioSamples.get(deviceId).push(s);
+  }
+  addDrop() {
+    this.droppedFrames++;
+  }
+  report() {
+    if (!this.log) return;
+    const dropped = this.droppedFrames;
+    this.droppedFrames = 0;
+    const avg = (arr) => arr.length > 0 ? Math.round(arr.reduce((a, b) => a + b, 0) / arr.length) : 0;
+    const max = (arr) => arr.length > 0 ? Math.round(Math.max(...arr)) : 0;
+    const p95 = (arr) => {
+      if (arr.length === 0) return 0;
+      const sorted = [...arr].sort((a, b) => a - b);
+      return Math.round(sorted[Math.floor(sorted.length * 0.95)] ?? sorted[sorted.length - 1]);
+    };
+    const rt = this.runtimeInfo;
+    for (const [deviceId, det] of this.detSamples) {
+      if (det.length === 0) continue;
+      const e2e = det.map((s) => s.endToEnd);
+      const inf = det.map((s) => s.inference);
+      const totalDet = det.reduce((s, d) => s + d.detections, 0);
+      this.log.info(
+        "pipeline stats",
+        {
+          tags: { deviceId },
+          meta: {
+            frames: det.length,
+            intervalSec: REPORT_INTERVAL_MS / 1e3,
+            e2e: { avg: avg(e2e), p95: p95(e2e), max: max(e2e) },
+            inference: { avg: avg(inf), p95: p95(inf) },
+            detections: totalDet,
+            dropped,
+            pipelineRuntime: rt.pipelineRuntime ?? null,
+            pipelineModels: rt.pipelineModels ?? null
+          }
+        }
+      );
+    }
+    this.detSamples.clear();
+    for (const [deviceId, mot] of this.motSamples) {
+      if (mot.length === 0) continue;
+      this.log.info(
+        "motion stats",
+        {
+          tags: { deviceId },
+          meta: {
+            frames: mot.length,
+            intervalSec: REPORT_INTERVAL_MS / 1e3,
+            avg: avg(mot),
+            p95: p95(mot),
+            max: max(mot)
+            // motionAddon: rt.motionAddon ?? null,
+          }
+        }
+      );
+    }
+    this.motSamples.clear();
+    for (const [deviceId, aud] of this.audioSamples) {
+      if (aud.length === 0) continue;
+      const classifyTimes = aud.filter((a) => a.classifyMs > 0).map((a) => a.classifyMs);
+      const classified = aud.filter((a) => a.topLabel !== null);
+      const topLabels = /* @__PURE__ */ new Map();
+      for (const a of classified) {
+        if (a.topLabel) topLabels.set(a.topLabel, (topLabels.get(a.topLabel) ?? 0) + 1);
+      }
+      const topSummary = [...topLabels.entries()].sort((a, b) => b[1] - a[1]).slice(0, 3).map(([l, c]) => `${l}×${c}`).join(", ");
+      const avgDbfs = avg(aud.map((a) => Math.round(a.dbfs)));
+      this.log.info(
+        "audio stats",
+        {
+          tags: { deviceId },
+          meta: {
+            chunks: aud.length,
+            intervalSec: REPORT_INTERVAL_MS / 1e3,
+            classified: classified.length,
+            classifyAvgMs: classifyTimes.length > 0 ? avg(classifyTimes) : 0,
+            avgDbfs,
+            topLabels: topSummary,
+            audioEngine: rt.audioEngine ?? null
+          }
+        }
+      );
+    }
+    this.audioSamples.clear();
+  }
+}
+const DEFAULT_MOTION_COOLDOWN_MS = 3e4;
+function toFrameInput$1(frame) {
+  return {
+    data: frame.data,
+    width: frame.width,
+    height: frame.height,
+    format: frame.format,
+    timestamp: frame.timestamp
+  };
+}
+class PipelineRunner {
+  // Config is mutable (not `readonly`) because `updateLimits()` hot-reloads
+  // the four tuning fields when the pipeline-runner addon's
+  // `updateAddonSettings` is invoked via the new three-level settings API.
+  // The callbacks (`processFrame`, `analyzeMotion`) are invariants captured
+  // at construction and never changed.
+  config;
+  cameras = /* @__PURE__ */ new Map();
+  semaphore;
+  resultCallbacks = [];
+  defaultRoundRobinKeys = [];
+  defaultRoundRobinIndex = 0;
+  intervalHandle = null;
+  detectionStreamHandler = null;
+  logger;
+  timingSampler = new PipelineTimingSampler();
+  constructor(config) {
+    this.config = config;
+    this.logger = config.logger;
+    this.semaphore = new Semaphore(config.maxConcurrentInferences);
+  }
+  /**
+   * Hot-reload the four tuning fields without tearing down the runner.
+   * - `maxConcurrentInferences`: resized on the live semaphore; in-flight
+   *   permits are preserved, new capacity is available immediately.
+   * - `maxQueueDepth`: new `FrameQueue`s created from this point on use
+   *   the updated ceiling. Existing per-camera queues are not resized
+   *   (the FrameQueue implementation is latest-only and ignores maxSize
+   *   anyway — see `frame-queue.ts` — so the field is effectively a
+   *   metadata hint for observability).
+   * - `targetLoadPercent` / `minThrottledFps`: stored for future
+   *   throttling logic (not yet consumed in the current runner body).
+   *
+   * Only keys present in the patch are overwritten; unspecified keys
+   * retain their current value. Any illegal combination (e.g.
+   * concurrency < 1) throws and leaves the runner unchanged.
+   */
+  updateLimits(patch) {
+    const next = {
+      ...this.config,
+      maxQueueDepth: patch.maxQueueDepth ?? this.config.maxQueueDepth,
+      maxConcurrentInferences: patch.maxConcurrentInferences ?? this.config.maxConcurrentInferences,
+      targetLoadPercent: patch.targetLoadPercent ?? this.config.targetLoadPercent,
+      minThrottledFps: patch.minThrottledFps ?? this.config.minThrottledFps
+    };
+    if (next.maxConcurrentInferences !== this.config.maxConcurrentInferences) {
+      this.semaphore.resize(next.maxConcurrentInferences);
+    }
+    this.config = next;
+  }
+  /** Read the current tuning fields for diagnostics / tests. */
+  getLimits() {
+    return {
+      maxQueueDepth: this.config.maxQueueDepth,
+      maxConcurrentInferences: this.config.maxConcurrentInferences,
+      targetLoadPercent: this.config.targetLoadPercent,
+      minThrottledFps: this.config.minThrottledFps
+    };
+  }
+  /** Set a handler called when the runner needs to subscribe/unsubscribe the detection stream. */
+  onDetectionStreamChange(handler) {
+    this.detectionStreamHandler = handler;
+  }
+  registerCamera(deviceId, registration) {
+    const motionQueue = new FrameQueue(this.config.maxQueueDepth);
+    const detectionQueue = new FrameQueue(this.config.maxQueueDepth);
+    const initialPhase = registration.detectionMode === "disabled" ? "idle" : registration.detectionMode === "always-on" ? "active" : "watching";
+    const state = {
+      registration,
+      motionQueue,
+      detectionQueue,
+      inferenceTimes: [],
+      processedCount: 0,
+      startTime: Date.now(),
+      phase: initialPhase,
+      motionCooldownTimer: null,
+      lastArmedSource: null,
+      lastArmedRegions: void 0
+    };
+    this.cameras.set(deviceId, state);
+    if (registration.detectionMode === "on-motion") {
+      this.defaultRoundRobinKeys.push(deviceId);
+    }
+    if (initialPhase === "active") {
+      this.detectionStreamHandler?.(deviceId, "subscribe");
+      const cooldownMs = registration.motionCooldownMs ?? DEFAULT_MOTION_COOLDOWN_MS;
+      this.config.onPhaseChanged?.(deviceId, "active", {
+        source: "analyzer",
+        regions: void 0,
+        timestamp: Date.now(),
+        cooldownMs
+      });
+    }
+  }
+  unregisterCamera(deviceId) {
+    const state = this.cameras.get(deviceId);
+    if (!state) return;
+    if (state.motionCooldownTimer !== null) {
+      clearTimeout(state.motionCooldownTimer);
+      state.motionCooldownTimer = null;
+    }
+    if (state.phase === "active") {
+      this.detectionStreamHandler?.(deviceId, "unsubscribe");
+    }
+    state.motionQueue.clear();
+    state.detectionQueue.clear();
+    this.cameras.delete(deviceId);
+    const idx = this.defaultRoundRobinKeys.indexOf(deviceId);
+    if (idx !== -1) {
+      this.defaultRoundRobinKeys.splice(idx, 1);
+      if (this.defaultRoundRobinIndex >= this.defaultRoundRobinKeys.length) {
+        this.defaultRoundRobinIndex = 0;
+      }
+    }
+  }
+  enqueueMotionFrame(deviceId, frame) {
+    const state = this.cameras.get(deviceId);
+    if (!state) return;
+    state.motionQueue.enqueue(frame);
+  }
+  enqueueDetectionFrame(deviceId, frame) {
+    const state = this.cameras.get(deviceId);
+    if (!state) return;
+    if (state.phase !== "active") return;
+    frame._enqueuedAt = Date.now();
+    state.detectionQueue.enqueue(frame);
+  }
+  /**
+   * Report a motion event for a camera. Drives the unified phase
+   * machine for both motion sources (analyzer + onboard):
+   *
+   *   - Every `detected: true` (any source) clears + rearms the
+   *     cooldown timer and transitions watching → active. The same
+   *     timer applies regardless of which source(s) are configured;
+   *     concurrent sources just keep refreshing the same window.
+   *   - `detected: false` is a no-op. Onboard sources never send an
+   *     explicit clear, and the analyzer's "false" pulses would
+   *     otherwise fight the cooldown when motion paused briefly
+   *     during a scene. The timer is the single closure path.
+   *   - Timer expiry transitions active → watching.
+   *
+   * Always-on cameras silently ignore reportMotion calls — they're
+   * already in `active` and have no cooldown.
+   *
+   * `source` and `regions` propagate into the phase-transition event
+   * so the wrapping addon can attach them to the cap-state slice +
+   * bus event.
+   */
+  reportMotion(deviceId, detected, source = "analyzer", regions = void 0) {
+    const state = this.cameras.get(deviceId);
+    if (!state) return;
+    if (state.registration.detectionMode !== "on-motion") return;
+    if (!detected) return;
+    state.lastArmedSource = source;
+    state.lastArmedRegions = regions;
+    const cooldownMs = state.registration.motionCooldownMs ?? DEFAULT_MOTION_COOLDOWN_MS;
+    if (state.motionCooldownTimer !== null) {
+      clearTimeout(state.motionCooldownTimer);
+      state.motionCooldownTimer = null;
+    }
+    if (state.phase === "watching") {
+      this.transitionToActive(deviceId, state, source, regions, cooldownMs);
+    }
+    state.motionCooldownTimer = setTimeout(() => {
+      state.motionCooldownTimer = null;
+      this.transitionToWatching(deviceId, state, cooldownMs);
+    }, cooldownMs);
+  }
+  getPhase(deviceId) {
+    return this.cameras.get(deviceId)?.phase;
+  }
+  onResult(callback) {
+    this.resultCallbacks.push(callback);
+  }
+  start() {
+    if (this.intervalHandle !== null) return;
+    this.intervalHandle = setInterval(() => this.tick(), 10);
+    this.timingSampler.start();
+  }
+  stop() {
+    if (this.intervalHandle !== null) {
+      clearInterval(this.intervalHandle);
+      this.intervalHandle = null;
+    }
+    this.timingSampler.stop();
+    for (const state of this.cameras.values()) {
+      if (state.motionCooldownTimer !== null) {
+        clearTimeout(state.motionCooldownTimer);
+        state.motionCooldownTimer = null;
+      }
+    }
+  }
+  getMetrics() {
+    let totalQueueDepth = 0;
+    let totalInferenceTime = 0;
+    let totalInferenceCount = 0;
+    for (const state of this.cameras.values()) {
+      totalQueueDepth += state.motionQueue.size + state.detectionQueue.size;
+      for (const t of state.inferenceTimes) {
+        totalInferenceTime += t;
+        totalInferenceCount++;
+      }
+    }
+    return {
+      activeCameras: this.cameras.size,
+      throttledCameras: 0,
+      avgInferenceTimeMs: totalInferenceCount > 0 ? totalInferenceTime / totalInferenceCount : 0,
+      queueDepth: totalQueueDepth
+    };
+  }
+  getCameraMetrics(deviceId) {
+    const state = this.cameras.get(deviceId);
+    if (!state) return void 0;
+    const elapsedMs = Date.now() - state.startTime;
+    const elapsedSec = elapsedMs / 1e3;
+    const actualFps = elapsedSec > 0 ? state.processedCount / elapsedSec : 0;
+    const times = state.inferenceTimes;
+    const avgInference = times.length > 0 ? times.reduce((a, b) => a + b, 0) / times.length : 0;
+    return {
+      detectionMode: state.registration.detectionMode,
+      configuredFps: state.registration.fps,
+      actualFps,
+      queueDepth: state.motionQueue.size + state.detectionQueue.size,
+      avgInferenceTimeMs: avgInference,
+      droppedFrames: state.motionQueue.droppedFrames + state.detectionQueue.droppedFrames,
+      phase: state.phase
+    };
+  }
+  getAllCameraMetrics() {
+    const results = [];
+    for (const [deviceId] of this.cameras) {
+      const metrics = this.getCameraMetrics(deviceId);
+      if (metrics) {
+        results.push({ deviceId, ...metrics });
+      }
+    }
+    return results;
+  }
+  getAttachedCameras() {
+    return [...this.cameras.keys()];
+  }
+  transitionToActive(deviceId, state, source, regions, cooldownMs) {
+    state.phase = "active";
+    this.logger?.info("motion gate opened — phase=active", {
+      tags: { deviceId },
+      meta: { detectionMode: state.registration.detectionMode, source }
+    });
+    this.detectionStreamHandler?.(deviceId, "subscribe");
+    this.config.onPhaseChanged?.(deviceId, "active", {
+      source,
+      regions,
+      timestamp: Date.now(),
+      cooldownMs
+    });
+  }
+  transitionToWatching(deviceId, state, cooldownMs) {
+    state.phase = "watching";
+    state.detectionQueue.clear();
+    this.logger?.info("motion gate closed — phase=watching", {
+      tags: { deviceId },
+      meta: { lastSource: state.lastArmedSource }
+    });
+    this.detectionStreamHandler?.(deviceId, "unsubscribe");
+    const source = state.lastArmedSource ?? "analyzer";
+    this.config.onPhaseChanged?.(deviceId, "watching", {
+      source,
+      regions: void 0,
+      timestamp: Date.now(),
+      cooldownMs
+    });
+    state.lastArmedSource = null;
+    state.lastArmedRegions = void 0;
+  }
+  tick() {
+    this.drainMotionQueues();
+    if (this.semaphore.available <= 0) return;
+    const picked = this.pickNextDetectionFrame();
+    if (!picked) return;
+    const { deviceId, frame, state } = picked;
+    const frameInput = toFrameInput$1(frame);
+    void this.processWithSemaphore(deviceId, frame, frameInput, state, "detection");
+  }
+  drainMotionQueues() {
+    for (const [deviceId, state] of this.cameras) {
+      while (state.motionQueue.size > 0) {
+        const frame = state.motionQueue.dequeue();
+        if (frame) {
+          void this.config.analyzeMotion(deviceId, frame);
+        }
+      }
+    }
+  }
+  async processWithSemaphore(deviceId, frame, frameInput, state, streamType) {
+    const pickedAt = Date.now();
+    const captureTs = frame.timestamp;
+    const enqueuedAt = frame._enqueuedAt ?? captureTs;
+    const release = await this.semaphore.acquire();
+    const semAcquiredAt = Date.now();
+    try {
+      const result = await this.config.processFrame(deviceId, frameInput);
+      const inferDoneAt = Date.now();
+      const inferenceMs = inferDoneAt - semAcquiredAt;
+      state.inferenceTimes.push(inferenceMs);
+      if (state.inferenceTimes.length > 100) {
+        state.inferenceTimes.shift();
+      }
+      state.processedCount++;
+      if (result) {
+        await this.notifyCallbacks(deviceId, frame, result, streamType);
+        const emittedAt = Date.now();
+        this.timingSampler.addSample(deviceId, {
+          captureToEnqueue: enqueuedAt - captureTs,
+          queueWait: pickedAt - enqueuedAt,
+          semaphoreWait: semAcquiredAt - pickedAt,
+          inference: inferenceMs,
+          resultToEmit: emittedAt - inferDoneAt,
+          endToEnd: emittedAt - captureTs,
+          detections: result.detections?.length ?? 0
+        });
+      }
+    } finally {
+      release();
+    }
+  }
+  async notifyCallbacks(deviceId, frame, result, streamType) {
+    for (const callback of this.resultCallbacks) {
+      try {
+        await callback(deviceId, frame, result, streamType);
+      } catch {
+      }
+    }
+  }
+  pickNextDetectionFrame() {
+    for (const [deviceId, state] of this.cameras) {
+      if (state.registration.detectionMode === "always-on" && state.detectionQueue.size > 0) {
+        const frame = state.detectionQueue.dequeue();
+        return { deviceId, frame, state };
+      }
+    }
+    if (this.defaultRoundRobinKeys.length === 0) return null;
+    const startIndex = this.defaultRoundRobinIndex;
+    for (let i = 0; i < this.defaultRoundRobinKeys.length; i++) {
+      const idx = (startIndex + i) % this.defaultRoundRobinKeys.length;
+      const deviceId = this.defaultRoundRobinKeys[idx];
+      if (!deviceId) continue;
+      const state = this.cameras.get(deviceId);
+      if (!state) continue;
+      if (state.phase === "active" && state.detectionQueue.size > 0) {
+        this.defaultRoundRobinIndex = (idx + 1) % this.defaultRoundRobinKeys.length;
+        const frame = state.detectionQueue.dequeue();
+        if (!frame) continue;
+        return { deviceId, frame, state };
+      }
+    }
+    return null;
+  }
+}
+const BenchEngineChoiceSchema = zod.z.object({
+  runtime: zod.z.enum(["node", "python"]),
+  backend: zod.z.string(),
+  format: zod.z.enum(["onnx", "coreml", "openvino", "tflite", "pt"]),
+  device: zod.z.string().optional()
+});
+const BenchStepSchema = zod.z.lazy(() => zod.z.object({
+  addonId: zod.z.string(),
+  modelId: zod.z.string(),
+  enabled: zod.z.boolean(),
+  children: zod.z.array(BenchStepSchema).optional()
+}));
+const CacheBenchFrameInputSchema = zod.z.object({
+  imageBase64: zod.z.string(),
+  ttlSeconds: zod.z.number().int().positive().optional()
+});
+const CacheBenchFrameResultSchema = zod.z.object({
+  frameId: zod.z.string(),
+  width: zod.z.number(),
+  height: zod.z.number(),
+  expiresAt: zod.z.number()
+});
+const ReleaseBenchFrameInputSchema = zod.z.object({
+  frameId: zod.z.string()
+});
+const ReleaseBenchFrameResultSchema = zod.z.object({
+  released: zod.z.boolean()
+});
+const RunSyntheticBenchInputSchema = zod.z.object({
+  frameId: zod.z.string(),
+  steps: zod.z.array(BenchStepSchema).min(1),
+  parallel: zod.z.number().int().min(1).max(32),
+  iterations: zod.z.number().int().min(1).max(1e4),
+  warmup: zod.z.number().int().min(0).max(100).optional(),
+  sessionId: zod.z.string().optional(),
+  simulatePipeline: zod.z.boolean().optional(),
+  engine: BenchEngineChoiceSchema.optional()
+});
+const TimingSplitSchema = zod.z.object({
+  mean: zod.z.number(),
+  p50: zod.z.number(),
+  p95: zod.z.number(),
+  p99: zod.z.number()
+});
+const RunSyntheticBenchResultSchema = zod.z.object({
+  runs: zod.z.number(),
+  wallSec: zod.z.number(),
+  fps: zod.z.number(),
+  detectionsPerSec: zod.z.number(),
+  avgDetections: zod.z.number(),
+  callMs: TimingSplitSchema,
+  inferMs: zod.z.number(),
+  preprocessMs: zod.z.number(),
+  predictMs: zod.z.number(),
+  batchSizeMean: zod.z.number(),
+  batchSizeMax: zod.z.number(),
+  engine: zod.z.object({ runtime: zod.z.string(), backend: zod.z.string(), device: zod.z.string().optional() }).optional(),
+  tuning: zod.z.object({ batchMode: zod.z.string(), windowMs: zod.z.number(), maxBatchSize: zod.z.number(), concurrency: zod.z.number() }).optional(),
+  path: zod.z.string().optional()
+});
+const pipelineRunnerBenchActions = types.defineCustomActions({
+  cacheBenchFrame: types.customAction(
+    CacheBenchFrameInputSchema,
+    CacheBenchFrameResultSchema,
+    { kind: "mutation" }
+  ),
+  releaseBenchFrame: types.customAction(
+    ReleaseBenchFrameInputSchema,
+    ReleaseBenchFrameResultSchema,
+    { kind: "mutation" }
+  ),
+  runSyntheticBench: types.customAction(
+    RunSyntheticBenchInputSchema,
+    RunSyntheticBenchResultSchema,
+    { kind: "mutation" }
+  )
+});
+const DEFAULT_CONFIG = {
+  maxQueueDepth: 30,
+  // CoreML window accumulator coalesces concurrent calls into a single
+  // model.predict([list]) — the more in-flight, the larger the batch and
+  // the higher the per-frame throughput. With concurrency=2 the window
+  // never fills past batch=2, capping the pool at ~50 fps single-node.
+  // 16 matches the slider ceiling and lines up with bench numbers
+  // (parallel=16 hits batch=7-8/8, sustaining ~140 fps full path).
+  maxConcurrentInferences: 16,
+  targetLoadPercent: 80,
+  minThrottledFps: 1
+};
+function toFrameInput(frame) {
+  return {
+    data: frame.data,
+    width: frame.width,
+    height: frame.height,
+    format: frame.format,
+    timestamp: frame.timestamp
+  };
+}
+const STEP_LOG_INTERVAL_MS = 3e4;
+const METRICS_SNAPSHOT_INTERVAL_MS = 1e3;
+const METRICS_HEARTBEAT_MS = 3e4;
+class PipelineRunnerAddon extends types.BaseAddon {
+  runner = null;
+  attached = /* @__PURE__ */ new Map();
+  nodeId = "unknown";
+  stepLogTimer = null;
+  metricsSnapshotTimer = null;
+  unsubMotionEvents = null;
+  /** Last analyzer-detected state per device — gates the
+   *  `MotionOnMotionChanged` emit in `runMotionAnalysis` to transitions
+   *  only (otherwise we'd emit on every analyzer frame). */
+  lastAnalyzerDetected = /* @__PURE__ */ new Map();
+  /**
+   * Last positive motion timestamp per device — preserved across the
+   * OFF transition so the motion runtime-state slice keeps a stable
+   * `lastDetectedAt` after the cooldown closes the phase. Cleared on
+   * detach.
+   */
+  lastMotionAt = /* @__PURE__ */ new Map();
+  /**
+   * Snapshot-equality cache for metrics-snapshot defer. The runner
+   * fires per-camera metrics every `METRICS_SNAPSHOT_INTERVAL_MS`;
+   * for an idle camera (no inference, queue empty, fps=0) every tick
+   * carries an identical payload. We skip the bus emit when the
+   * payload deep-equals the previous one so the events tab + remote
+   * subscribers stop seeing 60 metrics-snapshots/min/camera that
+   * convey nothing. A periodic heartbeat re-emits every
+   * METRICS_HEARTBEAT_MS so consumers know the runner is still
+   * alive.
+   */
+  lastEmittedCameraMetrics = /* @__PURE__ */ new Map();
+  lastEmittedRunnerLoad = null;
+  /**
+   * In-memory bench-frame cache (decoded JPEG bytes). Populated by the
+   * `cacheBenchFrame` custom action. Fed into the synthetic-bench loop
+   * via the `frame: FrameInput` shape that mirrors what stream-broker
+   * delivers to this very addon during real camera detection.
+   */
+  benchFrameCache = /* @__PURE__ */ new Map();
+  benchFrameSweeper = null;
+  constructor() {
+    super({ ...DEFAULT_CONFIG });
+  }
+  async onInitialize() {
+    const raw = this.ctx.kernel.localNodeId ?? this.ctx.id;
+    this.nodeId = raw.includes("/") ? raw.split("/")[0] : raw;
+    this.runner = new PipelineRunner({
+      maxQueueDepth: this.config.maxQueueDepth,
+      maxConcurrentInferences: this.config.maxConcurrentInferences,
+      targetLoadPercent: this.config.targetLoadPercent,
+      minThrottledFps: this.config.minThrottledFps,
+      processFrame: (deviceId, frame) => this.runInference(deviceId, frame),
+      analyzeMotion: (deviceId, frame) => this.runMotionAnalysis(deviceId, frame),
+      onPhaseChanged: (deviceId, phase, meta) => this.handlePhaseChanged(deviceId, phase, meta),
+      logger: this.ctx.logger
+    });
+    this.runner.timingSampler.setLogger(this.ctx.logger.child("timing"));
+    this.runner.onDetectionStreamChange((deviceId, action) => {
+      this.handleDetectionStreamChange(deviceId, action);
+    });
+    this.runner.onResult(async (deviceId, frame, result, _streamType) => {
+      this.emitInferenceResult(deviceId, frame, result);
+    });
+    this.runner.start();
+    this.ctx.logger.info(
+      "Pipeline runner started",
+      {
+        tags: { nodeId: this.nodeId },
+        meta: {
+          maxConcurrent: this.config.maxConcurrentInferences,
+          queueDepth: this.config.maxQueueDepth
+        }
+      }
+    );
+    if (this.ctx.eventBus) {
+      this.unsubMotionEvents = this.ctx.eventBus.subscribe(
+        { category: types.EventCategory.MotionOnMotionChanged },
+        (event) => {
+          const data = event.data;
+          const deviceId = data.deviceId;
+          const attachment = this.attached.get(deviceId);
+          if (!attachment) return;
+          const source = data.source;
+          if (!attachment.config.motionSources.includes(source)) return;
+          this.runner?.reportMotion(
+            deviceId,
+            data.detected,
+            source,
+            data.regions ? [...data.regions] : void 0
+          );
+        }
+      );
+    }
+    this.stepLogTimer = setInterval(() => this.logAttachedSteps(), STEP_LOG_INTERVAL_MS);
+    this.metricsSnapshotTimer = setInterval(
+      () => this.emitMetricsSnapshot(),
+      METRICS_SNAPSHOT_INTERVAL_MS
+    );
+    return {
+      providers: [{ capability: types.pipelineRunnerCapability, provider: this }],
+      customActions: pipelineRunnerBenchActions,
+      actionHandlers: {
+        cacheBenchFrame: async (input) => this.cacheBenchFrame(input),
+        releaseBenchFrame: async (input) => this.releaseBenchFrame(input),
+        runSyntheticBench: async (input) => this.runSyntheticBench(input)
+      }
+    };
+  }
+  async onShutdown() {
+    if (this.metricsSnapshotTimer) {
+      clearInterval(this.metricsSnapshotTimer);
+      this.metricsSnapshotTimer = null;
+    }
+    if (this.stepLogTimer) {
+      clearInterval(this.stepLogTimer);
+      this.stepLogTimer = null;
+    }
+    if (this.benchFrameSweeper) {
+      clearInterval(this.benchFrameSweeper);
+      this.benchFrameSweeper = null;
+    }
+    this.benchFrameCache.clear();
+    if (this.unsubMotionEvents) {
+      this.unsubMotionEvents();
+      this.unsubMotionEvents = null;
+    }
+    this.lastAnalyzerDetected.clear();
+    if (this.runner) {
+      this.runner.stop();
+      this.runner = null;
+    }
+    for (const attachment of this.attached.values()) {
+      attachment.motionUnsubscribe?.();
+      attachment.detectionUnsubscribe?.();
+    }
+    this.attached.clear();
+  }
+  // ── Synthetic bench (production-equivalent measurement) ───────────────
+  async cacheBenchFrame(input) {
+    const sharp = (await import("sharp")).default;
+    const jpeg = Buffer.from(input.imageBase64, "base64");
+    const { data, info } = await sharp(jpeg).raw().toBuffer({ resolveWithObject: true });
+    if (info.channels !== 3) {
+      throw new Error(`cacheBenchFrame: expected 3 channels (rgb), got ${info.channels}`);
+    }
+    const rgb = new Uint8Array(data);
+    const ttlMs = Math.max(6e4, (input.ttlSeconds ?? 600) * 1e3);
+    const frameId = `runner-bench-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+    const expiresAt = Date.now() + ttlMs;
+    this.benchFrameCache.set(frameId, { data: rgb, width: info.width, height: info.height, format: "rgb", expiresAt });
+    if (!this.benchFrameSweeper) {
+      this.benchFrameSweeper = setInterval(() => this.sweepBenchFrameCache(), 6e4);
+      this.benchFrameSweeper.unref?.();
+    }
+    this.ctx.logger.info("cached bench frame", {
+      meta: { frameId, width: info.width, height: info.height, bytes: rgb.length, ttlMs }
+    });
+    return { frameId, width: info.width, height: info.height, expiresAt };
+  }
+  async releaseBenchFrame(input) {
+    return { released: this.benchFrameCache.delete(input.frameId) };
+  }
+  sweepBenchFrameCache() {
+    const now = Date.now();
+    for (const [id, entry] of this.benchFrameCache) {
+      if (entry.expiresAt < now) this.benchFrameCache.delete(id);
+    }
+  }
+  async runSyntheticBench(input) {
+    const ctx = this.ctx;
+    const api = ctx.api;
+    if (!api) throw new Error("runSyntheticBench: ctx.api unavailable");
+    ctx.logger.info("runSyntheticBench input", {
+      meta: { frameId: input.frameId, parallel: input.parallel, iterations: input.iterations }
+    });
+    const cached = this.benchFrameCache.get(input.frameId);
+    if (!cached) {
+      throw new Error(`runSyntheticBench: frameId ${input.frameId} not cached (call cacheBenchFrame first)`);
+    }
+    const stepsToRun = input.steps.map((s) => ({
+      addonId: s.addonId,
+      modelId: s.modelId,
+      enabled: s.enabled,
+      children: s.children ?? []
+    }));
+    const enabledSteps = stepsToRun.filter((s) => s.enabled);
+    const isSingleStep = enabledSteps.length === 1 && (!enabledSteps[0].children || enabledSteps[0].children.filter((c) => c.enabled).length === 0);
+    const useFastPath = isSingleStep && !input.simulatePipeline;
+    const rootStep = enabledSteps[0];
+    const sharedFrame = {
+      data: cached.data,
+      format: cached.format,
+      width: cached.width,
+      height: cached.height,
+      timestamp: Date.now()
+    };
+    let poolFrameId = null;
+    if (useFastPath && rootStep) {
+      ctx.logger.info("synthetic bench: using Python cache path", {
+        meta: { step: rootStep.addonId, model: rootStep.modelId }
+      });
+      const cacheResult = await api.pipelineExecutor.cacheFrameInPool.mutate({
+        data: new Uint8Array(cached.data.slice().buffer),
+        width: cached.width,
+        height: cached.height,
+        format: cached.format
+      });
+      poolFrameId = cacheResult.frameId;
+      await api.pipelineExecutor.runPipeline.mutate({
+        steps: stepsToRun,
+        frame: sharedFrame,
+        ...input.engine ? { engine: input.engine } : {}
+      });
+      const warmupCount2 = input.warmup ?? 1;
+      for (let w = 0; w < warmupCount2; w++) {
+        await api.pipelineExecutor.inferCached.mutate({
+          stepId: rootStep.addonId,
+          frameId: poolFrameId
+        });
+      }
+      const wallTimings2 = [];
+      const inferTimings2 = [];
+      const preprocessTimings2 = [];
+      const predictTimings2 = [];
+      const batchSizes2 = [];
+      const detCounts2 = [];
+      let _n = 0;
+      const sessionId2 = input.sessionId ?? `synth-${Date.now().toString(36)}`;
+      const totalRuns2 = input.parallel * input.iterations;
+      const wallStart2 = performance.now();
+      const worker2 = async () => {
+        for (let i = 0; i < input.iterations; i++) {
+          const t0 = performance.now();
+          const result = await api.pipelineExecutor.inferCached.mutate({
+            stepId: rootStep.addonId,
+            frameId: poolFrameId
+          });
+          const wallMs = performance.now() - t0;
+          const r = result;
+          const inferMs = typeof r["inferenceMs"] === "number" ? r["inferenceMs"] : wallMs;
+          const preMs = typeof r["preprocessMs"] === "number" ? r["preprocessMs"] : 0;
+          const predMs = typeof r["predictMs"] === "number" ? r["predictMs"] : 0;
+          const bs = typeof r["batchSize"] === "number" ? r["batchSize"] : 1;
+          const dets = Array.isArray(r["detections"]) ? r["detections"].length : 0;
+          wallTimings2.push(wallMs);
+          inferTimings2.push(inferMs);
+          preprocessTimings2.push(preMs);
+          predictTimings2.push(predMs);
+          batchSizes2.push(bs);
+          detCounts2.push(dets);
+          const n = ++_n;
+          if (n <= 20) {
+            ctx.logger.info("bench call trace (cached)", {
+              meta: { n, wallMs: Math.round(wallMs), inferMs: Math.round(inferMs), preMs: Math.round(preMs * 10) / 10, predMs: Math.round(predMs * 10) / 10, bs }
+            });
+          }
+          if (n % Math.max(1, input.parallel) === 0) {
+            const elapsed = (performance.now() - wallStart2) / 1e3;
+            const fps = elapsed > 0 ? n / elapsed : 0;
+            const meanCallMs = wallTimings2.reduce((s, v) => s + v, 0) / wallTimings2.length;
+            const sorted = [...wallTimings2].sort((a, b) => a - b);
+            const p95 = sorted[Math.min(sorted.length - 1, Math.floor(0.95 * sorted.length))] ?? 0;
+            const totalDet = detCounts2.reduce((s, v) => s + v, 0);
+            const avgDet = detCounts2.length > 0 ? totalDet / detCounts2.length : 0;
+            const bsMean = batchSizes2.reduce((s, v) => s + v, 0) / batchSizes2.length;
+            const msg = `runs ${n}/${totalRuns2} · ${fps.toFixed(1)} fps · call ${meanCallMs.toFixed(1)}ms · batch ${bsMean.toFixed(1)}`;
+            if (ctx.eventBus) {
+              ctx.eventBus.emit({
+                id: `bench-${n}`,
+                timestamp: /* @__PURE__ */ new Date(),
+                source: { type: "pipeline", id: "synthetic-bench" },
+                category: types.EventCategory.PipelineProgress,
+                data: {
+                  nodeId: "hub",
+                  sessionId: sessionId2,
+                  step: "synthetic-bench",
+                  message: msg,
+                  benchProgress: true,
+                  runs: n,
+                  totalRuns: totalRuns2,
+                  fps: Math.round(fps * 100) / 100,
+                  meanMs: Math.round(meanCallMs * 100) / 100,
+                  p95Ms: Math.round(p95 * 100) / 100,
+                  inferMeanMs: Math.round(inferTimings2.reduce((s, v) => s + v, 0) / inferTimings2.length * 100) / 100,
+                  preprocessMeanMs: Math.round(preprocessTimings2.reduce((s, v) => s + v, 0) / preprocessTimings2.length * 100) / 100,
+                  predictMeanMs: Math.round(predictTimings2.reduce((s, v) => s + v, 0) / predictTimings2.length * 100) / 100,
+                  batchSizeMean: Math.round(bsMean * 100) / 100,
+                  detPerSec: elapsed > 0 ? Math.round(totalDet / elapsed * 100) / 100 : 0,
+                  avgDetections: Math.round(avgDet * 100) / 100
+                }
+              });
+            } else {
+              ctx.logger.warn("emitProgress: NO eventBus");
+            }
+          }
+        }
+      };
+      await Promise.all(Array.from({ length: input.parallel }, () => worker2()));
+      const wallSec2 = (performance.now() - wallStart2) / 1e3;
+      await api.pipelineExecutor.uncacheFrame.mutate({ frameId: poolFrameId }).catch(() => {
+      });
+      return this.buildBenchResult(wallTimings2, inferTimings2, preprocessTimings2, predictTimings2, batchSizes2, detCounts2, wallSec2, "cached");
+    }
+    ctx.logger.info("synthetic bench: using full runPipeline path", {
+      meta: { steps: enabledSteps.length, simulatePipeline: !!input.simulatePipeline }
+    });
+    let _callCount = 0;
+    const callOnce = async () => {
+      const t0 = performance.now();
+      const result = await api.pipelineExecutor.runPipeline.mutate({
+        steps: stepsToRun,
+        frame: sharedFrame,
+        ...input.engine ? { engine: input.engine } : {}
+      });
+      const wallMs = performance.now() - t0;
+      const n = ++_callCount;
+      if (n <= 20) {
+        ctx.logger.info("bench call trace", {
+          meta: {
+            n,
+            wallMs: Math.round(wallMs),
+            totalInferenceMs: Math.round(result.debug?.totalInferenceMs ?? 0),
+            predictMs: Math.round((result.debug?.predictMs ?? 0) * 10) / 10,
+            preprocessMs: Math.round((result.debug?.preprocessMs ?? 0) * 10) / 10,
+            batchSize: result.debug?.batchSize ?? 1
+          }
+        });
+      }
+      return { wallMs, result };
+    };
+    const warmupCount = input.warmup ?? 1;
+    for (let i = 0; i < warmupCount; i++) {
+      await callOnce();
+    }
+    const wallTimings = [];
+    const serverWallTimings = [];
+    const inferTimings = [];
+    const preprocessTimings = [];
+    const predictTimings = [];
+    const batchSizes = [];
+    const detCounts = [];
+    const sessionId = input.sessionId ?? `synth-${Date.now().toString(36)}`;
+    const totalRuns = input.parallel * input.iterations;
+    const wallStart = performance.now();
+    const worker = async () => {
+      for (let i = 0; i < input.iterations; i++) {
+        const { wallMs, result } = await callOnce();
+        wallTimings.push(wallMs);
+        serverWallTimings.push(result.debug?.wallMs ?? 0);
+        inferTimings.push(result.debug?.totalInferenceMs ?? 0);
+        preprocessTimings.push(result.debug?.preprocessMs ?? 0);
+        predictTimings.push(result.debug?.predictMs ?? 0);
+        batchSizes.push(result.debug?.batchSize ?? 1);
+        detCounts.push(result.detections?.length ?? 0);
+        const n = wallTimings.length;
+        if (n % Math.max(1, input.parallel) === 0 && ctx.eventBus) {
+          const elapsed = (performance.now() - wallStart) / 1e3;
+          const fps = elapsed > 0 ? n / elapsed : 0;
+          const meanMs = wallTimings.reduce((s, v) => s + v, 0) / n;
+          const sorted = [...wallTimings].sort((a, b) => a - b);
+          const p95 = sorted[Math.min(sorted.length - 1, Math.floor(0.95 * sorted.length))] ?? 0;
+          const totalDet = detCounts.reduce((s, v) => s + v, 0);
+          const bsMean = batchSizes.reduce((s, v) => s + v, 0) / n;
+          ctx.eventBus.emit({
+            id: `bench-${n}`,
+            timestamp: /* @__PURE__ */ new Date(),
+            source: { type: "pipeline", id: "synthetic-bench" },
+            category: types.EventCategory.PipelineProgress,
+            data: {
+              nodeId: "hub",
+              sessionId,
+              step: "synthetic-bench",
+              message: `runs ${n}/${totalRuns} · ${fps.toFixed(1)} fps · call ${meanMs.toFixed(1)}ms · batch ${bsMean.toFixed(1)}`,
+              benchProgress: true,
+              runs: n,
+              totalRuns,
+              fps: Math.round(fps * 100) / 100,
+              meanMs: Math.round(meanMs * 100) / 100,
+              p95Ms: Math.round(p95 * 100) / 100,
+              inferMeanMs: Math.round(inferTimings.reduce((s, v) => s + v, 0) / n * 100) / 100,
+              preprocessMeanMs: Math.round(preprocessTimings.reduce((s, v) => s + v, 0) / n * 100) / 100,
+              predictMeanMs: Math.round(predictTimings.reduce((s, v) => s + v, 0) / n * 100) / 100,
+              batchSizeMean: Math.round(bsMean * 100) / 100,
+              detPerSec: elapsed > 0 ? Math.round(totalDet / elapsed * 100) / 100 : 0,
+              avgDetections: n > 0 ? Math.round(totalDet / n * 100) / 100 : 0
+            }
+          });
+        }
+      }
+    };
+    await Promise.all(Array.from({ length: input.parallel }, () => worker()));
+    const wallSec = (performance.now() - wallStart) / 1e3;
+    return this.buildBenchResult(wallTimings, inferTimings, preprocessTimings, predictTimings, batchSizes, detCounts, wallSec, "pipeline");
+  }
+  async buildBenchResult(wallTimings, inferTimings, preprocessTimings, predictTimings, batchSizes, detCounts, wallSec, path) {
+    const meanOfArr = (xs) => xs.length > 0 ? xs.reduce((s, v) => s + v, 0) / xs.length : 0;
+    this.ctx.logger.info("synthetic bench summary", {
+      meta: {
+        runs: wallTimings.length,
+        wallSec: Math.round(wallSec * 100) / 100,
+        fps: Math.round(wallTimings.length / wallSec * 100) / 100,
+        callMeanMs: Math.round(meanOfArr(wallTimings)),
+        inferMeanMs: Math.round(meanOfArr(inferTimings)),
+        preprocessMeanMs: Math.round(meanOfArr(preprocessTimings)),
+        predictMeanMs: Math.round(meanOfArr(predictTimings)),
+        batchSizeMean: Math.round(meanOfArr(batchSizes) * 100) / 100,
+        batchSizeMax: batchSizes.length > 0 ? Math.max(...batchSizes) : 0
+      }
+    });
+    const sorted = [...wallTimings].sort((a, b) => a - b);
+    const pick = (q) => sorted.length > 0 ? sorted[Math.min(sorted.length - 1, Math.floor(q * sorted.length))] : 0;
+    const meanOf = (xs) => xs.length > 0 ? xs.reduce((s, v) => s + v, 0) / xs.length : 0;
+    const totalRuns = wallTimings.length;
+    const totalDet = detCounts.reduce((s, v) => s + v, 0);
+    return {
+      runs: totalRuns,
+      wallSec: Math.round(wallSec * 1e3) / 1e3,
+      fps: wallSec > 0 ? Math.round(totalRuns / wallSec * 100) / 100 : 0,
+      detectionsPerSec: wallSec > 0 ? Math.round(totalDet / wallSec * 100) / 100 : 0,
+      avgDetections: totalRuns > 0 ? Math.round(totalDet / totalRuns * 100) / 100 : 0,
+      callMs: {
+        mean: Math.round(meanOf(wallTimings) * 100) / 100,
+        p50: Math.round(pick(0.5) * 100) / 100,
+        p95: Math.round(pick(0.95) * 100) / 100,
+        p99: Math.round(pick(0.99) * 100) / 100
+      },
+      inferMs: Math.round(meanOf(inferTimings) * 100) / 100,
+      preprocessMs: Math.round(meanOf(preprocessTimings) * 100) / 100,
+      predictMs: Math.round(meanOf(predictTimings) * 100) / 100,
+      batchSizeMean: Math.round(meanOf(batchSizes) * 100) / 100,
+      batchSizeMax: batchSizes.length > 0 ? Math.max(...batchSizes) : 0,
+      path,
+      ...await this.getEngineAndTuning()
+    };
+  }
+  async getEngineAndTuning() {
+    try {
+      const api = this.ctx.api;
+      if (!api) return {};
+      const [eng, tuning] = await Promise.all([
+        api.pipelineExecutor.getSelectedEngine.query(),
+        api.pipelineExecutor.getEffectiveTuning.query()
+      ]);
+      return {
+        engine: eng ? { runtime: eng.runtime, backend: eng.backend, device: eng.device } : void 0,
+        tuning: tuning ?? void 0
+      };
+    } catch {
+      return {};
+    }
+  }
+  // ── IPipelineRunnerProvider implementation ────────────────────────────
+  async attachCamera(config) {
+    const runner = this.runner;
+    const ctx = this.ctx;
+    if (!runner || !ctx) {
+      throw new Error("PipelineRunnerAddon: attachCamera called before initialize completed");
+    }
+    this.ctx.logger.info("attachCamera received config", {
+      tags: { deviceId: config.deviceId },
+      meta: {
+        motionSources: config.motionSources,
+        motionSourcesType: Array.isArray(config.motionSources) ? `array(${config.motionSources.length})` : typeof config.motionSources,
+        motionStreamId: config.motionStreamId,
+        detectionStreamId: config.detectionStreamId,
+        keys: Object.keys(config)
+      }
+    });
+    if (this.attached.has(config.deviceId)) {
+      this.detachInternal(config.deviceId);
+    }
+    runner.registerCamera(config.deviceId, {
+      detectionMode: config.detectionMode,
+      fps: config.detectionFps,
+      motionCooldownMs: config.motionCooldownMs
+    });
+    const attachment = {
+      config,
+      motionUnsubscribe: null,
+      detectionUnsubscribe: null
+    };
+    this.attached.set(config.deviceId, attachment);
+    if (config.motionSources.includes("analyzer")) {
+      attachment.motionUnsubscribe = await this.subscribeMotionFrames(config);
+    }
+    const stepsCount = config.steps?.length ?? 0;
+    const dispatch = stepsCount > 0 ? `runPipeline(${stepsCount}step${stepsCount === 1 ? "" : "s"})` : config.steps !== void 0 ? "skip(0steps)" : "runFrame(legacy)";
+    const engineLabel = config.engine ? `${config.engine.runtime}+${config.engine.backend}/${config.engine.format}` : "default";
+    this.ctx.logger.info(
+      "attachCamera",
+      {
+        tags: { deviceId: config.deviceId },
+        meta: {
+          detectionMode: config.detectionMode,
+          audioMode: config.audioMode,
+          motionFps: config.motionFps,
+          detectionFps: config.detectionFps,
+          motionSources: config.motionSources,
+          dispatch,
+          engine: engineLabel
+        }
+      }
+    );
+    return { success: true };
+  }
+  async detachCamera(input) {
+    this.detachInternal(input.deviceId);
+    return { success: true };
+  }
+  async reportMotion(input) {
+    this.runner?.reportMotion(input.deviceId, input.detected, input.source, input.regions);
+    return { success: true };
+  }
+  /**
+   * Periodic per-camera step roster dump. Once every
+   * STEP_LOG_INTERVAL_MS (30s) emits one log line per attached camera
+   * with the configured detection step tree + audio classifier branch
+   * so an operator looking at the agent log can quickly see what each
+   * camera is currently running without crossing tRPC. Skips when no
+   * cameras are attached so quiet dev runs stay silent.
+   */
+  logAttachedSteps() {
+    if (this.attached.size === 0) return;
+    for (const [deviceId, attachment] of this.attached) {
+      const cfg = attachment.config;
+      const detectionSteps = cfg.steps && cfg.steps.length > 0 ? this.flattenSteps(cfg.steps).filter((s) => s.enabled) : [];
+      const detectionLabel = detectionSteps.length > 0 ? detectionSteps.map((s) => `${s.addonId}/${s.modelId}`).join(" → ") : "<none>";
+      const audioLabel = cfg.audio && cfg.audio.enabled ? `${cfg.audio.engine.runtime}/${cfg.audio.engine.backend}/${cfg.audio.modelId}` : "<off>";
+      const engineLabel = cfg.engine ? `${cfg.engine.runtime}/${cfg.engine.backend}${cfg.engine.device ? `/${cfg.engine.device}` : ""}` : "<unset>";
+      this.ctx.logger.info("Camera pipeline roster", {
+        tags: { deviceId },
+        meta: {
+          phase: "roster",
+          intervalSec: STEP_LOG_INTERVAL_MS / 1e3,
+          pipelineEnabled: cfg.pipelineEnabled,
+          motionSources: cfg.motionSources,
+          motionFps: cfg.motionFps,
+          detectionFps: cfg.detectionFps,
+          engine: engineLabel,
+          videoSteps: detectionLabel,
+          videoStepCount: detectionSteps.length,
+          audio: audioLabel
+        }
+      });
+    }
+  }
+  /** Recursively flatten the step tree → ordered list of every node. */
+  flattenSteps(steps) {
+    const out = [];
+    const walk = (s) => {
+      out.push(s);
+      if (s.children) {
+        for (const c of s.children) walk(c);
+      }
+    };
+    for (const s of steps) walk(s);
+    return out;
+  }
+  detachInternal(deviceId) {
+    const attachment = this.attached.get(deviceId);
+    if (!attachment) return;
+    attachment.motionUnsubscribe?.();
+    attachment.detectionUnsubscribe?.();
+    this.attached.delete(deviceId);
+    this.lastMotionAt.delete(deviceId);
+    this.lastEmittedCameraMetrics.delete(deviceId);
+    this.runner?.unregisterCamera(deviceId);
+    this.ctx?.logger.info("detachCamera", { tags: { deviceId } });
+  }
+  async getLocalLoad() {
+    const metrics = this.runner?.getMetrics() ?? { avgInferenceTimeMs: 0, queueDepth: 0 };
+    const allCameraMetrics = this.runner?.getAllCameraMetrics() ?? [];
+    let activeCameras = 0;
+    let totalActualFps = 0;
+    for (const cm of allCameraMetrics) {
+      if (cm.phase === "active") activeCameras++;
+      totalActualFps += cm.actualFps;
+    }
+    return {
+      nodeId: this.nodeId,
+      attachedCameras: this.attached.size,
+      activeCameras,
+      avgInferenceFps: totalActualFps,
+      avgInferenceTimeMs: metrics.avgInferenceTimeMs,
+      queueDepthTotal: metrics.queueDepth,
+      hardware: {
+        hasGpu: false,
+        inferenceBackend: void 0
+      }
+    };
+  }
+  async getLocalMetrics() {
+    const m = this.runner?.getMetrics() ?? { activeCameras: 0, throttledCameras: 0, avgInferenceTimeMs: 0, queueDepth: 0 };
+    return { nodeId: this.nodeId, ...m };
+  }
+  async getCameraMetrics(input) {
+    return this.runner?.getCameraMetrics(input.deviceId) ?? null;
+  }
+  getAllCameraMetrics() {
+    return this.runner?.getAllCameraMetrics() ?? [];
+  }
+  getLocalCameras() {
+    return [...this.attached.keys()];
+  }
+  // ── Internal: broker subscription wiring ─────────────────────────────
+  async subscribeMotionFrames(config) {
+    const ctx = this.ctx;
+    const runner = this.runner;
+    if (!ctx || !runner) return null;
+    const log = this.ctx.logger.withTags({ deviceId: config.deviceId });
+    const api = this.ctx.api;
+    if (!api) {
+      log.warn("subscribeMotionFrames: this.ctx.api not available");
+      return null;
+    }
+    const motionBrokerId = `${config.deviceId}/${config.motionStreamId}`;
+    const motionBroker = await api.streamBroker.getBroker.query({ brokerId: motionBrokerId });
+    if (!motionBroker) {
+      log.warn("subscribeMotionFrames: no broker found", { meta: { brokerId: motionBrokerId } });
+      return null;
+    }
+    return motionBroker.onDecodedFrame(
+      (frame) => {
+        runner.enqueueMotionFrame(config.deviceId, frame);
+      },
+      { maxFps: config.motionFps, format: "gray", tag: "motion" }
+    );
+  }
+  handleDetectionStreamChange(deviceId, action) {
+    const attachment = this.attached.get(deviceId);
+    if (!attachment) return;
+    if (action === "subscribe") {
+      void this.subscribeDetectionFrames(attachment.config).then((unsub) => {
+        attachment.detectionUnsubscribe = unsub;
+      });
+    } else {
+      attachment.detectionUnsubscribe?.();
+      attachment.detectionUnsubscribe = null;
+    }
+  }
+  /**
+   * Bridge runner phase transitions to the device's `motion` runtime
+   * state + the bus. Single ownership point — every motion source
+   * (analyzer, onboard, future variants) funnels through the runner's
+   * phase machine and lands here.
+   *
+   * - Cap-state via the unified `device-state.setCapSlice` API.
+   *   `autoClearAfterMs = cooldownMs` on ON, `null` on OFF.
+   *   `lastDetectedAt` is preserved across OFF using `lastMotionAt`.
+   * - Bus event `MotionOnMotionChanged` fires alongside for consumers
+   *   that prefer event-driven over runtime-state polling.
+   */
+  handlePhaseChanged(deviceId, phase, meta) {
+    const detected = phase === "active";
+    if (detected) this.lastMotionAt.set(deviceId, meta.timestamp);
+    const lastDetectedAt = this.lastMotionAt.get(deviceId) ?? null;
+    const slice = {
+      detected,
+      lastDetectedAt,
+      autoClearAfterMs: detected ? meta.cooldownMs : null
+    };
+    void (async () => {
+      const dev = await this.ctx.fetchDevice(deviceId);
+      await dev.deviceState.setCapSlice({ capName: "motion", slice });
+    })().catch((err) => {
+      this.ctx.logger.debug("motion cap-state write failed", {
+        tags: { deviceId },
+        meta: { error: types.errMsg(err) }
+      });
+    });
+    if (this.ctx.eventBus) {
+      const from = detected ? "watching" : "active";
+      const to = detected ? "active" : "watching";
+      const reason = detected ? "motion_detected" : "cooldown_expired";
+      const payload = {
+        deviceId,
+        from,
+        to,
+        reason,
+        source: meta.source,
+        cooldownMs: meta.cooldownMs,
+        timestamp: meta.timestamp
+      };
+      this.ctx.eventBus.emit(types.createEvent(
+        types.EventCategory.DetectionPhaseTransition,
+        { type: "device", id: deviceId, addonId: this.ctx.id, deviceId, nodeId: this.nodeId },
+        payload
+      ));
+    }
+  }
+  async subscribeDetectionFrames(config) {
+    const ctx = this.ctx;
+    const runner = this.runner;
+    if (!ctx || !runner) return null;
+    const log = this.ctx.logger.withTags({ deviceId: config.deviceId });
+    const api = this.ctx.api;
+    if (!api) {
+      log.warn("subscribeDetectionFrames: this.ctx.api not available");
+      return null;
+    }
+    const detectionBrokerId = `${config.deviceId}/${config.detectionStreamId}`;
+    const detectionBroker = await api.streamBroker.getBroker.query({ brokerId: detectionBrokerId });
+    if (!detectionBroker) {
+      log.warn("subscribeDetectionFrames: no broker found", { meta: { brokerId: detectionBrokerId } });
+      return null;
+    }
+    return detectionBroker.onDecodedFrame(
+      (frame) => {
+        runner.enqueueDetectionFrame(config.deviceId, frame);
+      },
+      // `format: 'rgb'` is the Phase 4 hot-path switch: detection now
+      // requests raw RGB24 from the broker so the decoder skips the
+      // sharp JPEG encode and the Python pool skips PIL JPEG decode.
+      // When WebRTC also subscribes (jpeg), the broker derives JPEG
+      // once per frame via its conversion cache — no double work.
+      { maxFps: config.detectionFps, format: "rgb", tag: "detection" }
+    );
+  }
+  // ── Internal: inference + motion callbacks ───────────────────────────
+  async runInference(deviceId, frame) {
+    const ctx = this.ctx;
+    if (!ctx) return null;
+    const log = this.ctx.logger.withTags({ deviceId });
+    const api = this.ctx.api;
+    if (!api) {
+      log.error("runInference: this.ctx.api not available");
+      return null;
+    }
+    const attachment = this.attached.get(deviceId);
+    const camConfig = attachment?.config;
+    const steps = camConfig?.steps;
+    const engine = camConfig?.engine;
+    if (!steps) {
+      log.warn("runInference: no steps in attach config — skipping frame (legacy attach?)");
+      return null;
+    }
+    if (steps.length === 0) {
+      return null;
+    }
+    try {
+      return await api.pipelineExecutor.runPipeline.mutate({
+        // tRPC input is a mutable array; the attach payload holds it
+        // as readonly. One spread copy at the cap boundary is cheap
+        // (pipeline step trees are tiny) and keeps the type surface
+        // clean without casting.
+        steps: [...steps],
+        frame,
+        deviceId,
+        ...engine ? { engine } : {}
+      });
+    } catch (err) {
+      const msg = types.errMsg(err);
+      log.error("runInference failed", { meta: { error: msg } });
+      return null;
+    }
+  }
+  async runMotionAnalysis(deviceId, frame) {
+    const ctx = this.ctx;
+    const runner = this.runner;
+    if (!ctx || !runner) return;
+    const log = this.ctx.logger.withTags({ deviceId });
+    const motionStart = Date.now();
+    try {
+      const api = this.ctx.api;
+      if (!api) {
+        log.warn("runMotionAnalysis: this.ctx.api not available");
+        return;
+      }
+      const result = await api.motionDetection.analyze.mutate({ deviceId, frame: toFrameInput(frame) });
+      if (!result) return;
+      const detected = result.regions.length > 0;
+      const prevDetected = this.lastAnalyzerDetected.get(deviceId) ?? false;
+      if (detected !== prevDetected) {
+        this.lastAnalyzerDetected.set(deviceId, detected);
+        if (this.ctx.eventBus) {
+          this.ctx.eventBus.emit(types.createEvent(
+            types.EventCategory.MotionOnMotionChanged,
+            // EventSource wrapper kept symmetric with the onboard
+            // emit (Reolink/ONVIF/etc.) so consumers grouping by
+            // addonId / deviceId see consistent provenance. `nodeId`
+            // identifies which cluster node ran the analyzer.
+            { type: "device", id: deviceId, addonId: this.ctx.id, deviceId, nodeId: this.nodeId },
+            {
+              deviceId,
+              detected,
+              timestamp: frame.timestamp,
+              source: "analyzer",
+              ...detected ? { regions: result.regions } : {}
+            }
+          ));
+        }
+      }
+      if (this.ctx.eventBus) {
+        const motionPayload = {
+          detected,
+          regionCount: result.regions.length,
+          regions: result.regions.map((r) => ({
+            bbox: { x: r.bbox.x, y: r.bbox.y, w: r.bbox.w, h: r.bbox.h },
+            pixelCount: r.pixelCount,
+            intensity: r.intensity
+          })),
+          frameWidth: frame.width,
+          frameHeight: frame.height,
+          analysisMs: result.analysisMs
+        };
+        const analyzerSource = { type: "device", id: deviceId, addonId: this.ctx.id, deviceId, nodeId: this.nodeId };
+        this.ctx.eventBus.emit(types.createEvent(
+          types.EventCategory.MotionAnalysis,
+          analyzerSource,
+          motionPayload
+        ));
+        const zonesPayload = {
+          deviceId,
+          timestamp: frame.timestamp,
+          zones: result.rawRegions.map((r) => ({
+            bbox: [r.bbox.x, r.bbox.y, r.bbox.x + r.bbox.w, r.bbox.y + r.bbox.h],
+            pixelCount: r.pixelCount,
+            changeScore: r.intensity / 255
+          })),
+          frameSize: { width: frame.width, height: frame.height }
+        };
+        this.ctx.eventBus.emit(types.createEvent(
+          types.EventCategory.MotionZonesRaw,
+          analyzerSource,
+          zonesPayload
+        ));
+      }
+      runner.timingSampler.addMotionSample(deviceId, Date.now() - motionStart);
+    } catch (error) {
+      const msg = types.errMsg(error);
+      log.error("runMotionAnalysis failed", { meta: { error: msg } });
+    }
+  }
+  emitInferenceResult(deviceId, _frame, result) {
+    const ctx = this.ctx;
+    if (!ctx?.eventBus) return;
+    const payload = {
+      deviceId,
+      frame: result,
+      nodeId: this.nodeId
+    };
+    this.ctx.eventBus.emit(types.createEvent(
+      types.EventCategory.PipelineInferenceResult,
+      { type: "device", id: deviceId, nodeId: this.nodeId },
+      payload
+    ));
+  }
+  /**
+   * Emit periodic metric snapshots: one runner-load event for the
+   * node + one camera-metrics event per attached camera. Subscribed
+   * by admin-ui dashboards (LiveLoadPanel, NodeDetailHeader,
+   * CameraStreamPanel) to drive live overlays without polling.
+   *
+   * Skipped when there are no cameras attached so quiet dev runs
+   * don't emit needless bus traffic. The runner-load event is still
+   * emitted in that case because the dashboards rely on it to see
+   * "agent reachable, idle".
+   */
+  emitMetricsSnapshot() {
+    const ctx = this.ctx;
+    const runner = this.runner;
+    if (!ctx?.eventBus || !runner) return;
+    const timestamp = Date.now();
+    void this.getLocalLoad().then((load) => {
+      if (!ctx.eventBus) return;
+      const json = JSON.stringify(load);
+      const prev = this.lastEmittedRunnerLoad;
+      const heartbeatDue = !prev || timestamp - prev.emittedAt >= METRICS_HEARTBEAT_MS;
+      if (prev && prev.json === json && !heartbeatDue) return;
+      this.lastEmittedRunnerLoad = { json, emittedAt: timestamp };
+      ctx.eventBus.emit(types.createEvent(
+        types.EventCategory.PipelineRunnerLoadSnapshot,
+        { type: "node", id: this.nodeId, nodeId: this.nodeId },
+        { nodeId: this.nodeId, load, timestamp }
+      ));
+    }).catch(() => {
+    });
+    if (this.attached.size === 0) return;
+    for (const deviceId of this.attached.keys()) {
+      const metrics = runner.getCameraMetrics(deviceId);
+      if (!metrics) continue;
+      const json = JSON.stringify(metrics);
+      const prev = this.lastEmittedCameraMetrics.get(deviceId);
+      const heartbeatDue = !prev || timestamp - prev.emittedAt >= METRICS_HEARTBEAT_MS;
+      if (prev && prev.json === json && !heartbeatDue) continue;
+      this.lastEmittedCameraMetrics.set(deviceId, { json, emittedAt: timestamp });
+      ctx.eventBus.emit(types.createEvent(
+        types.EventCategory.PipelineCameraMetricsSnapshot,
+        { type: "device", id: deviceId, nodeId: this.nodeId },
+        { deviceId, nodeId: this.nodeId, metrics, timestamp }
+      ));
+    }
+  }
+  // ── Standard ICamstackAddon — three-level settings API (Phase 3) ─────
+  //
+  // The runner is a per-node addon with only ADDON-LEVEL settings (no
+  // per-device overrides, no cluster-wide tunables). All four tuning
+  // fields live in `getAddonSettings()`. When the UI surface moves in
+  // Phase 9 these will be rendered under Pipeline -> node -> Settings.
+  globalSettingsSchema() {
+    return this.schema({
+      sections: [
+        {
+          id: "pipeline-runner-tuning",
+          title: "Pipeline Runner",
+          tab: "scheduler",
+          description: "Per-node detection scheduler tuning. Change only if you understand the pipeline internals.",
+          columns: 2,
+          fields: [
+            {
+              type: "slider",
+              key: "maxConcurrentInferences",
+              label: "Scheduler concurrency",
+              description: 'Max parallel inferences the runner scheduler allows across all cameras on this node. Distinct from the detection-pipeline inference-pool worker count (Pipeline tab → "Worker concurrency"), which controls Python-side thread pool sizing inside a single inference job.',
+              min: 1,
+              max: 16,
+              step: 1,
+              default: DEFAULT_CONFIG.maxConcurrentInferences,
+              showValue: true
+            },
+            {
+              type: "slider",
+              key: "maxQueueDepth",
+              label: "Max queue depth",
+              description: "Maximum frames held per camera before dropping.",
+              min: 5,
+              max: 100,
+              step: 5,
+              default: DEFAULT_CONFIG.maxQueueDepth,
+              showValue: true
+            },
+            {
+              type: "slider",
+              key: "targetLoadPercent",
+              label: "Target load",
+              description: "Percentage of inference capacity to target before throttling FPS.",
+              min: 50,
+              max: 100,
+              step: 5,
+              default: DEFAULT_CONFIG.targetLoadPercent,
+              unit: "%",
+              showValue: true
+            },
+            {
+              type: "slider",
+              key: "minThrottledFps",
+              label: "Min throttled FPS",
+              description: "Lowest FPS the runner will allow when load-shedding.",
+              min: 1,
+              max: 10,
+              step: 1,
+              default: DEFAULT_CONFIG.minThrottledFps,
+              showValue: true
+            }
+          ]
+        }
+      ]
+    });
+  }
+  async onConfigChanged() {
+    this.runner?.updateLimits(this.config);
+    this.ctx.logger.info(
+      "pipeline-runner tuning updated",
+      {
+        meta: {
+          maxQueueDepth: this.config.maxQueueDepth,
+          maxConcurrentInferences: this.config.maxConcurrentInferences,
+          targetLoadPercent: this.config.targetLoadPercent,
+          minThrottledFps: this.config.minThrottledFps
+        }
+      }
+    );
+  }
+}
+exports.FrameQueue = FrameQueue;
+exports.PipelineRunner = PipelineRunner;
+exports.PipelineTimingSampler = PipelineTimingSampler;
+exports.Semaphore = Semaphore;
+exports.customActions = pipelineRunnerBenchActions;
+exports.default = PipelineRunnerAddon;
+//# sourceMappingURL=index.js.map