@camstack/addon-benchmark 1.2.32 → 1.2.34

package/dist/index.mjs

@@ -14811,6 +14811,28 @@ var SustainedThroughputResultSchema = external_exports.object({
   batchSize: external_exports.number(),
   concurrency: external_exports.number()
 });
+var ReplaySourceSchema = external_exports.custom();
+var ReplayOverlaySchema = external_exports.custom();
+var OrchestrateReplayRunResultSchema = external_exports.custom();
+var StoredReplayRunSchema = external_exports.custom();
+var ReplayDiffSchema = external_exports.custom();
+var RunReplayClipInputSchema = external_exports.object({
+  deviceId: external_exports.number(),
+  nodeId: external_exports.string(),
+  source: ReplaySourceSchema,
+  overlay: ReplayOverlaySchema,
+  fps: external_exports.number().positive(),
+  maxFrames: external_exports.number().int().positive(),
+  maxWidth: external_exports.number().int().positive().default(1920),
+  deviceKey: external_exports.string().optional()
+});
+var UploadReplayClipInputSchema = external_exports.object({
+  dataBase64: external_exports.string(),
+  durationMs: external_exports.number().positive()
+});
+var UploadReplayClipResultSchema = external_exports.object({ clipId: external_exports.string() });
+var ListReplayRunsInputSchema = external_exports.object({ deviceId: external_exports.number() });
+var DiffReplayRunsInputSchema = external_exports.object({ runIdA: external_exports.string(), runIdB: external_exports.string() });
 
 // src/benchmark-actions.ts
 var benchmarkActions = defineCustomActions({
@@ -14913,6 +14935,20 @@ var benchmarkActions = defineCustomActions({
   clearBenchmarkHistory: customAction(external_exports.object({}), external_exports.object({ success: external_exports.literal(true) }), {
     kind: "mutation"
   }),
+  // Replay — rigiocare una pipeline vera su una clip fissa. Regia qui,
+  // FrameProcessor pass in `addon-post-analysis` via
+  // `pipelineAnalytics.runReplayFrameProcessor` (see `replay/replay-wiring.ts`).
+  uploadReplayClip: customAction(UploadReplayClipInputSchema, UploadReplayClipResultSchema, {
+    kind: "mutation"
+  }),
+  runReplayClip: customAction(RunReplayClipInputSchema, OrchestrateReplayRunResultSchema, {
+    kind: "mutation"
+  }),
+  listReplayRuns: customAction(
+    ListReplayRunsInputSchema,
+    external_exports.array(StoredReplayRunSchema).readonly()
+  ),
+  diffReplayRuns: customAction(DiffReplayRunsInputSchema, ReplayDiffSchema),
   // Decoder perf — fixture discovery + run control.
   // `z.object({})` for the same reason as `listBenchmarkHistory` above.
   listDecoderFixtures: customAction(external_exports.object({}), external_exports.array(DecoderFixtureSchema).readonly()),
@@ -14926,6 +14962,9 @@ var benchmarkActions = defineCustomActions({
   )
 });
 
+// src/benchmark-addon.ts
+import { createHash } from "crypto";
+
 // src/decoder-perf-runner.ts
 import * as fs from "fs";
 import * as path from "path";
@@ -15224,6 +15263,557 @@ async function runDecoderPerfTest(input, deps) {
   };
 }
 
+// src/replay/replay-decode.ts
+import { spawn } from "child_process";
+function buildReplaySequenceArgs(opts) {
+  const { startSec, durationSec, fps, maxWidth } = opts;
+  return [
+    "-hide_banner",
+    "-loglevel",
+    "error",
+    "-nostdin",
+    "-ss",
+    String(Math.max(0, startSec)),
+    "-i",
+    "pipe:0",
+    "-t",
+    String(Math.max(0, durationSec)),
+    "-vf",
+    `fps=${fps},scale='min(${maxWidth},iw)':-2`,
+    "-f",
+    "mjpeg",
+    "pipe:1"
+  ];
+}
+var REPLAY_DECODE_MAX_CONCURRENT = 2;
+var REPLAY_DECODE_TIMEOUT_MS = 15e3;
+var KILL_GRACE_MS = 500;
+var ReplayDecoder = class {
+  ffmpegPath;
+  spawnFn;
+  maxConcurrent;
+  timeoutMs;
+  inFlight = 0;
+  constructor(deps) {
+    this.ffmpegPath = deps.ffmpegPath;
+    this.spawnFn = deps.spawnFn ?? ((bin, args) => spawn(bin, [...args]));
+    this.maxConcurrent = deps.maxConcurrent ?? REPLAY_DECODE_MAX_CONCURRENT;
+    this.timeoutMs = deps.timeoutMs ?? REPLAY_DECODE_TIMEOUT_MS;
+  }
+  /** Decodes currently running (tests / metrics). */
+  get running() {
+    return this.inFlight;
+  }
+  /**
+   * Run the sequence once, feeding `input` on stdin (`-i pipe:0` in
+   * {@link buildReplaySequenceArgs}) — the same shape as
+   * `RecordedStillService`, which pipes a GOP rather than pointing ffmpeg at
+   * a file path, because the source bytes (a recorder GOP window, or an
+   * uploaded clip) are fetched through a capability call, not a local path.
+   * Resolves with the whole MJPEG stdout stream.
+   */
+  async decodeSequence(args, input) {
+    if (this.inFlight >= this.maxConcurrent) {
+      throw new Error(
+        `replay decode busy: node already running ${this.inFlight}/${this.maxConcurrent} decodes`
+      );
+    }
+    this.inFlight += 1;
+    try {
+      return await this.runOnce(args, input);
+    } finally {
+      this.inFlight -= 1;
+    }
+  }
+  runOnce(args, input) {
+    return new Promise((resolve2, reject) => {
+      const chunks = [];
+      const stderrTail = [];
+      let settled = false;
+      const child = (() => {
+        try {
+          return this.spawnFn(this.ffmpegPath, args);
+        } catch (err) {
+          reject(new Error(`replay decode: ffmpeg spawn failed: ${String(err)}`));
+          return null;
+        }
+      })();
+      if (child === null) return;
+      const settle = (fn) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        fn();
+      };
+      const kill = () => {
+        try {
+          child.kill("SIGTERM");
+        } catch {
+        }
+        const t = setTimeout(() => {
+          if (child.exitCode === null && child.signalCode === null) {
+            try {
+              child.kill("SIGKILL");
+            } catch {
+            }
+          }
+        }, KILL_GRACE_MS);
+        t.unref?.();
+      };
+      const timer = setTimeout(() => {
+        settle(() => reject(new Error("replay decode: timed out")));
+        kill();
+      }, this.timeoutMs);
+      timer.unref?.();
+      child.stdout?.on("data", (chunk) => chunks.push(chunk));
+      child.stderr?.on("data", (data) => {
+        const line = data.toString().trim();
+        if (line) {
+          stderrTail.push(line);
+          if (stderrTail.length > 8) stderrTail.shift();
+        }
+      });
+      child.on("error", (err) => {
+        settle(() => reject(new Error(`replay decode: ffmpeg process error: ${err.message}`)));
+      });
+      child.on("exit", (code, signal) => {
+        const stdout = Buffer.concat(chunks);
+        if (code === 0) {
+          settle(() => resolve2(stdout));
+          return;
+        }
+        settle(
+          () => reject(
+            new Error(
+              `replay decode: ffmpeg exited code=${String(code)} signal=${String(signal)}: ${stderrTail.join(" | ") || "(no stderr)"}`
+            )
+          )
+        );
+      });
+      try {
+        child.stdin?.write(Buffer.from(input.buffer, input.byteOffset, input.byteLength));
+        child.stdin?.end();
+      } catch {
+      }
+    });
+  }
+};
+
+// src/replay/replay-store.ts
+var REPLAY_RUNS_COLLECTION = "benchmark:replay-runs";
+var REPLAY_RUNS_COLUMNS = [
+  { name: "id", type: "TEXT", primaryKey: true, notNull: true },
+  { name: "deviceId", type: "INTEGER", notNull: true },
+  { name: "nodeId", type: "TEXT", notNull: true },
+  { name: "clipId", type: "TEXT", notNull: true },
+  { name: "createdAtMs", type: "INTEGER", notNull: true },
+  { name: "source", type: "JSON", notNull: true },
+  { name: "plan", type: "JSON", notNull: true },
+  { name: "verdict", type: "JSON", notNull: true }
+];
+var REPLAY_RUNS_INDEXES = [
+  { name: "idx_replay_runs_device_created", columns: ["deviceId", "createdAtMs"] },
+  { name: "idx_replay_runs_created", columns: ["createdAtMs"] }
+];
+var ReplayStore = class {
+  constructor(store) {
+    this.store = store;
+  }
+  store;
+  /** Declare the collection. Call in `onInitialize`, before the first
+   *  `save` — an undeclared collection crash-loops the runner. */
+  static async declare(store) {
+    await store.declareCollection.mutate({
+      collection: REPLAY_RUNS_COLLECTION,
+      columns: [...REPLAY_RUNS_COLUMNS],
+      indexes: [...REPLAY_RUNS_INDEXES]
+    });
+  }
+  async save(run) {
+    const { id, ...rest } = run;
+    await this.store.insert.mutate({
+      collection: REPLAY_RUNS_COLLECTION,
+      record: { id, data: rest }
+      // TECH-DEBT: settings-store boundary, see the comment above.
+    });
+  }
+  /** Runs newest-first, optionally scoped to one device. */
+  async list(query) {
+    const filter = { orderBy: { field: "createdAtMs", direction: "desc" } };
+    if (query.deviceId !== void 0) filter.where = { deviceId: query.deviceId };
+    if (query.limit !== void 0) filter.limit = query.limit;
+    const rows = await this.store.query.query({ collection: REPLAY_RUNS_COLLECTION, filter });
+    return rows.map((r) => ({ id: r.id, ...r.data }));
+  }
+  /** Delete every run created before `cutoffMs`. This store's OWN retention
+   *  clock — see the file header for why that matters. Returns the count so
+   *  a caller can log it, the way `OpsLogStore`-adjacent sweeps do. */
+  async pruneBefore(cutoffMs) {
+    const { deleted } = await this.store.deleteWhere.mutate({
+      collection: REPLAY_RUNS_COLLECTION,
+      filter: { whereBetween: { createdAtMs: [0, cutoffMs] } }
+    });
+    return deleted;
+  }
+};
+
+// src/replay/replay-plan.ts
+function readPreflight(result) {
+  if (!result.ok) {
+    const detail = result.issues.map((i) => `${i.addonId}: ${i.detail}`).join("; ");
+    return { kind: "refused", reason: "step-unrunnable", detail };
+  }
+  if (result.substitutions.length > 0) {
+    const detail = result.substitutions.map((s) => `${s.addonId}: chose \`${s.chosen}\`, running \`${s.running}\` (${s.format})`).join("; ");
+    return { kind: "refused", reason: "model-substituted", detail };
+  }
+  return { kind: "runnable", format: result.format };
+}
+var PACKAGE_DETECTION_STEP_ID = "package-detection";
+function hasPackageZone(overlay) {
+  return overlay.packageZone !== void 0;
+}
+function applyPackageZoneOverlay(steps, overlay) {
+  const existing = steps.find((s) => s.addonId === PACKAGE_DETECTION_STEP_ID);
+  if (!hasPackageZone(overlay)) {
+    if (!existing) return steps;
+    return steps.filter((s) => s.addonId !== PACKAGE_DETECTION_STEP_ID);
+  }
+  if (existing) {
+    if (existing.enabled === true) return steps;
+    return steps.map((s) => s.addonId === PACKAGE_DETECTION_STEP_ID ? { ...s, enabled: true } : s);
+  }
+  const node = {
+    addonId: PACKAGE_DETECTION_STEP_ID,
+    enabled: true,
+    children: []
+  };
+  return [...steps, node];
+}
+function applySettingsAndModels(steps, overlay, ignored) {
+  const settingsKeys = new Set(Object.keys(overlay.stepSettings ?? {}));
+  const modelKeys = new Set(Object.keys(overlay.stepModels ?? {}));
+  const presentIds = new Set(steps.map((s) => s.addonId));
+  for (const id of settingsKeys) if (!presentIds.has(id)) ignored.add(id);
+  for (const id of modelKeys) if (!presentIds.has(id)) ignored.add(id);
+  return steps.map((s) => {
+    const settingsPatch = overlay.stepSettings?.[s.addonId];
+    const modelOverride = overlay.stepModels?.[s.addonId];
+    if (settingsPatch === void 0 && modelOverride === void 0) return s;
+    return {
+      ...s,
+      ...modelOverride !== void 0 ? { modelId: modelOverride } : {},
+      ...settingsPatch !== void 0 ? { settings: { ...s.settings, ...settingsPatch } } : {}
+    };
+  });
+}
+function buildReplayPlan(base, overlay) {
+  const ignored = /* @__PURE__ */ new Set();
+  const withPackageZone = applyPackageZoneOverlay(base.steps, overlay);
+  if (!hasPackageZone(overlay) && (overlay.stepSettings?.[PACKAGE_DETECTION_STEP_ID] !== void 0 || overlay.stepModels?.[PACKAGE_DETECTION_STEP_ID] !== void 0)) {
+    ignored.add(PACKAGE_DETECTION_STEP_ID);
+  }
+  const steps = applySettingsAndModels(withPackageZone, overlay, ignored);
+  return { steps, ignoredOverlays: [...ignored] };
+}
+
+// src/replay/replay-source.ts
+function planReplayFrames(source, fps, maxFrames) {
+  const durationMs = source.kind === "recording" ? source.toMs - source.fromMs : source.durationMs;
+  if (durationMs <= 0) return { kind: "refused", reason: "empty-window" };
+  const stepMs = 1e3 / fps;
+  const startAt = source.kind === "recording" ? source.fromMs : 0;
+  const rawCount = Math.max(1, Math.floor(durationMs / stepMs));
+  const truncated = rawCount > maxFrames;
+  const count = Math.min(rawCount, maxFrames);
+  const instants = [];
+  for (let i = 0; i < count; i++) instants.push(startAt + Math.round(i * stepMs));
+  return { kind: "planned", deviceId: source.deviceId, instants, truncated };
+}
+
+// src/replay/mjpeg-split.ts
+var SOI = Buffer.from([255, 216]);
+var EOI = Buffer.from([255, 217]);
+function splitMjpegStream(bytes) {
+  const buf = Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const out = [];
+  let pos = 0;
+  for (; ; ) {
+    const soi = buf.indexOf(SOI, pos);
+    if (soi === -1) break;
+    const eoi = buf.indexOf(EOI, soi + SOI.length);
+    if (eoi === -1) break;
+    out.push(buf.subarray(soi, eoi + EOI.length));
+    pos = eoi + EOI.length;
+  }
+  return out;
+}
+
+// src/replay/replay-run.ts
+var DEFAULT_REPLAY_BUDGET_MS = 12e4;
+var DEFAULT_REPLAY_PACING_MS = 50;
+function sleep(ms) {
+  return new Promise((resolve2) => setTimeout(resolve2, ms));
+}
+async function runReplay(deps, frames) {
+  const now = deps.now ?? Date.now;
+  const budgetMs = deps.budgetMs ?? DEFAULT_REPLAY_BUDGET_MS;
+  const pacingMs = deps.pacingMs ?? DEFAULT_REPLAY_PACING_MS;
+  const startedAt = now();
+  const tags = { deviceId: deps.deviceId };
+  deps.logger.info("replay: run starting", {
+    tags,
+    meta: { framesPlanned: frames.length, nodeId: deps.nodeId, pacingMs, budgetMs }
+  });
+  const succeeded = [];
+  const discarded = [];
+  let framesFailed = 0;
+  let stoppedOnBudget = false;
+  for (let i = 0; i < frames.length; i++) {
+    if (now() - startedAt >= budgetMs) {
+      stoppedOnBudget = true;
+      deps.logger.warn("replay: run stopped on budget \u2014 a partial census, reported as such", {
+        tags,
+        meta: {
+          framesPlanned: frames.length,
+          framesRan: succeeded.length,
+          framesFailed,
+          budgetMs
+        }
+      });
+      break;
+    }
+    const f = frames[i];
+    if (f === void 0) continue;
+    try {
+      const frame = await deps.runPipeline({
+        timestamp: f.timestamp,
+        image: f.image,
+        nodeId: deps.nodeId
+      });
+      succeeded.push({ timestamp: f.timestamp, frame });
+      if (frame.discarded !== void 0) discarded.push(...frame.discarded);
+    } catch (err) {
+      framesFailed += 1;
+      deps.logger.warn("replay: frame failed on the node \u2014 counted, run continues", {
+        tags,
+        meta: { timestamp: f.timestamp, error: err instanceof Error ? err.message : String(err) }
+      });
+    }
+    if (pacingMs > 0 && i < frames.length - 1) await sleep(pacingMs);
+  }
+  const tracks = succeeded.length > 0 ? (await deps.runTracking(succeeded)).tracks : [];
+  const complete = !stoppedOnBudget && framesFailed === 0;
+  deps.logger.info("replay: run finished", {
+    tags,
+    meta: {
+      framesPlanned: frames.length,
+      framesRan: succeeded.length,
+      framesFailed,
+      complete,
+      tracks: tracks.length
+    }
+  });
+  return {
+    kind: succeeded.length === 0 ? "no-frame-ran" : "ran",
+    deviceId: deps.deviceId,
+    nodeId: deps.nodeId,
+    complete,
+    tracks,
+    discarded,
+    counters: { framesPlanned: frames.length, framesRan: succeeded.length, framesFailed }
+  };
+}
+
+// src/replay/replay-wiring.ts
+function clipIdOf(source) {
+  return source.kind === "upload" ? source.clipId : `recording:${source.deviceId}:${source.fromMs}`;
+}
+async function orchestrateReplayRun(deps, input) {
+  const tags = { deviceId: input.deviceId };
+  const base = await deps.resolveBaseTree(input.deviceId);
+  const plan = buildReplayPlan(base, input.overlay);
+  if (plan.ignoredOverlays.length > 0) {
+    deps.logger.warn("replay: overlay named a step the resolved tree does not run", {
+      tags,
+      meta: { ignoredOverlays: plan.ignoredOverlays }
+    });
+  }
+  const preflight = await deps.api.pipelineExecutor.validatePipeline.query({
+    steps: [...plan.steps]
+  });
+  const preflightVerdict = readPreflight(preflight);
+  if (preflightVerdict.kind === "refused") {
+    deps.logger.warn("replay: run refused at preflight", {
+      tags,
+      meta: { reason: preflightVerdict.reason, detail: preflightVerdict.detail }
+    });
+    return { kind: "refused", reason: `${preflightVerdict.reason}: ${preflightVerdict.detail}` };
+  }
+  const framePlan = planReplayFrames(input.source, input.fps, input.maxFrames);
+  if (framePlan.kind === "refused") {
+    deps.logger.warn("replay: run refused \u2014 empty window", { tags });
+    return { kind: "refused", reason: framePlan.reason };
+  }
+  if (framePlan.truncated) {
+    deps.logger.warn("replay: frame plan truncated by maxFrames", {
+      tags,
+      meta: { maxFrames: input.maxFrames, planned: framePlan.instants.length }
+    });
+  }
+  const sourceFetch = await deps.fetchSourceBytes(input.source);
+  if (sourceFetch.kind === "refused") {
+    deps.logger.warn("replay: run refused \u2014 could not fetch source bytes", {
+      tags,
+      meta: { reason: sourceFetch.reason }
+    });
+    return { kind: "refused", reason: sourceFetch.reason };
+  }
+  const sourceBytes = sourceFetch.bytes;
+  const first = framePlan.instants[0] ?? 0;
+  const last = framePlan.instants[framePlan.instants.length - 1] ?? first;
+  const startSec = (first - sourceFetch.startMs) / 1e3;
+  const durationSec = Math.max(1 / input.fps, (last - first) / 1e3 + 1 / input.fps);
+  const args = buildReplaySequenceArgs({
+    startSec,
+    durationSec,
+    fps: input.fps,
+    maxWidth: input.maxWidth
+  });
+  const mjpeg = await deps.decoder.decodeSequence(args, sourceBytes);
+  const jpegFrames = splitMjpegStream(mjpeg);
+  const frames = [];
+  for (let i = 0; i < framePlan.instants.length; i++) {
+    const timestamp = framePlan.instants[i];
+    const image = jpegFrames[i];
+    if (timestamp === void 0 || image === void 0) continue;
+    frames.push({ timestamp, image });
+  }
+  if (frames.length < framePlan.instants.length) {
+    deps.logger.warn("replay: decode produced fewer frames than planned", {
+      tags,
+      meta: { planned: framePlan.instants.length, decoded: frames.length }
+    });
+  }
+  const verdict = await runReplay(
+    {
+      deviceId: input.deviceId,
+      nodeId: input.nodeId,
+      runPipeline: async (call) => deps.api.pipelineExecutor.runPipeline.mutate({
+        nodeId: call.nodeId,
+        steps: [...plan.steps],
+        // Copy into a fresh `Uint8Array<ArrayBuffer>` — `mjpeg-split.ts`
+        // hands back a `Buffer` view (`Uint8Array<ArrayBufferLike>`), and
+        // the generated cap input is typed against the narrower
+        // `ArrayBuffer` backing.
+        image: new Uint8Array(call.image),
+        deviceId: input.deviceId,
+        ...input.deviceKey !== void 0 ? { deviceKey: input.deviceKey } : {}
+      }),
+      // THE cross-addon call this whole track exists for: the FrameProcessor
+      // pass lives in `addon-post-analysis`, reached only through this cap
+      // method — see the file header.
+      runTracking: async (tracked) => deps.api.pipelineAnalytics.runReplayFrameProcessor.mutate({
+        deviceId: input.deviceId,
+        source: "pipeline",
+        frames: [...tracked]
+      }),
+      logger: deps.logger
+    },
+    frames
+  );
+  const now = deps.now ?? Date.now;
+  const newId = deps.newId ?? (() => `replay-${now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`);
+  const replayRunId = newId();
+  const record2 = {
+    id: replayRunId,
+    deviceId: input.deviceId,
+    nodeId: input.nodeId,
+    clipId: clipIdOf(input.source),
+    createdAtMs: now(),
+    source: input.source,
+    plan,
+    verdict
+  };
+  await deps.store.save(record2);
+  return { kind: "ran", replayRunId, verdict };
+}
+
+// src/replay/replay-diff.ts
+function iou(a, b) {
+  const x1 = Math.max(a.x, b.x);
+  const y1 = Math.max(a.y, b.y);
+  const x2 = Math.min(a.x + a.w, b.x + b.w);
+  const y2 = Math.min(a.y + a.h, b.y + b.h);
+  const interW = Math.max(0, x2 - x1);
+  const interH = Math.max(0, y2 - y1);
+  const inter = interW * interH;
+  if (inter <= 0) return 0;
+  const union2 = a.w * a.h + b.w * b.h - inter;
+  return union2 <= 0 ? 0 : inter / union2;
+}
+function windowsOverlap(a, b) {
+  return a.firstSeenMs <= b.lastSeenMs && b.firstSeenMs <= a.lastSeenMs;
+}
+var TRACK_PAIR_MIN_IOU = 0.3;
+function diffTracks(a, b) {
+  const bMatched = /* @__PURE__ */ new Set();
+  const lost = [];
+  for (const ta of a) {
+    let bestIdx = -1;
+    let bestIou = 0;
+    for (let i = 0; i < b.length; i++) {
+      if (bMatched.has(i)) continue;
+      const tb = b[i];
+      if (tb === void 0 || tb.className !== ta.className) continue;
+      if (!windowsOverlap(ta, tb)) continue;
+      const score = iou(ta.bbox, tb.bbox);
+      if (score >= TRACK_PAIR_MIN_IOU && score > bestIou) {
+        bestIou = score;
+        bestIdx = i;
+      }
+    }
+    if (bestIdx === -1) lost.push(ta);
+    else bMatched.add(bestIdx);
+  }
+  const gained = b.filter((_, i) => !bMatched.has(i));
+  return { gained, lost };
+}
+function diffKnobs(a, b) {
+  const stepIds = /* @__PURE__ */ new Set([...Object.keys(a), ...Object.keys(b)]);
+  const changed = [];
+  for (const stepId of stepIds) {
+    const aStep = a[stepId] ?? {};
+    const bStep = b[stepId] ?? {};
+    const keys = /* @__PURE__ */ new Set([...Object.keys(aStep), ...Object.keys(bStep)]);
+    for (const key of keys) {
+      const from = aStep[key];
+      const to = bStep[key];
+      if (from !== to) changed.push({ stepId, key, from, to });
+    }
+  }
+  return changed;
+}
+function diffPromoted(discardedA, tracksB) {
+  const promoted = [];
+  for (const d of discardedA) {
+    const nowTracked = tracksB.some((t) => t.className === d.macroClass);
+    if (nowTracked)
+      promoted.push({ macroClass: d.macroClass, score: d.score, wasDiscardedBy: d.reason });
+  }
+  return promoted;
+}
+function diffReplayRuns(a, b) {
+  if (a.clipId !== b.clipId) return { kind: "incomparable", reason: "different-input" };
+  if (a.nodeId !== b.nodeId) return { kind: "incomparable", reason: "different-node" };
+  return {
+    kind: "compared",
+    changedKnobs: diffKnobs(a.settings, b.settings),
+    tracks: diffTracks(a.tracks, b.tracks),
+    promoted: diffPromoted(a.discarded, b.tracks)
+  };
+}
+
 // src/throughput/sustained-runner.ts
 async function runSustainedLoop(opts) {
   const concurrency = Math.max(1, Math.floor(opts.concurrency));
@@ -15351,7 +15941,7 @@ function resolveFixturesDir() {
   const pkgRoot = path2.resolve(path2.dirname(here), "..");
   return path2.join(pkgRoot, "assets", "fixtures");
 }
-var BenchmarkAddon = class extends BaseAddon {
+var BenchmarkAddon = class _BenchmarkAddon extends BaseAddon {
   id = "benchmark";
   /** Per-sessionId abort flags for in-flight decoder perf runs. */
   decoderPerfAbortFlags = /* @__PURE__ */ new Map();
@@ -15372,6 +15962,17 @@ var BenchmarkAddon = class extends BaseAddon {
   frameCache = /* @__PURE__ */ new Map();
   /** Periodic GC handle — clears expired frames every 60s. */
   frameCacheSweeper = null;
+  /** The replay run collection — declared in `onInitialize`, before any
+   *  `runReplayClip` call can save into it. See `replay/replay-store.ts`. */
+  replayStore = null;
+  /** The replay's one ffmpeg spawn, bounded — see `replay/replay-decode.ts`. */
+  replayDecoder = new ReplayDecoder({
+    ffmpegPath: process.env["FFMPEG_PATH"] ?? "ffmpeg"
+  });
+  /** `replay:<StoredReplayRun>` — an in-memory index would drift from the
+   *  store; this is a thin cache over `replayStore.list`, keyed for the
+   *  diff action's two-id lookup. */
+  replayRunCache = /* @__PURE__ */ new Map();
   pages = [
     {
       id: "benchmark",
@@ -15392,6 +15993,8 @@ var BenchmarkAddon = class extends BaseAddon {
       id: this.id,
       listPages: () => this.pages
     };
+    await ReplayStore.declare(this.api.settingsStore);
+    this.replayStore = new ReplayStore(this.api.settingsStore);
     return {
       providers: [{ capability: addonPagesSourceCapability, provider }],
       customActions: benchmarkActions,
@@ -15410,7 +16013,11 @@ var BenchmarkAddon = class extends BaseAddon {
         clearBenchmarkHistory: async () => this.clearBenchmarkHistory(),
         listDecoderFixtures: async () => this.listDecoderFixtures(),
         runDecoderPerformanceTest: async (input) => this.runDecoderPerformanceTest(input),
-        abortDecoderPerformanceTest: async (input) => this.abortDecoderPerformanceTest(input)
+        abortDecoderPerformanceTest: async (input) => this.abortDecoderPerformanceTest(input),
+        uploadReplayClip: async (input) => this.uploadReplayClip(input),
+        runReplayClip: async (input) => this.runReplayClip(input),
+        listReplayRuns: async (input) => this.listReplayRuns(input),
+        diffReplayRuns: async (input) => this.diffReplayRunsAction(input)
       }
     };
   }
@@ -15513,6 +16120,197 @@ var BenchmarkAddon = class extends BaseAddon {
       "runPipelineTest"
     );
   }
+  // ── Replay ────────────────────────────────────────────────────────────
+  /**
+   * Storage location a replay upload lands on. `replayClips` is a NEW
+   * `StorageLocationType` (an open string, no schema change needed — see
+   * `storage-location.ts:19`) but it still needs an actual location
+   * REGISTERED for that type before `storage.write`/`.read` can resolve it
+   * (`storage.upsertLocation`, `cardinality: 'single'`, its own retention).
+   * That registration is an operator/boot-time provisioning step this
+   * change does not perform — see the report's open items.
+   */
+  static REPLAY_CLIPS_LOCATION = "replayClips";
+  async uploadReplayClip(input) {
+    const bytes = Buffer.from(input.dataBase64, "base64");
+    const clipId = `clip:${createHash("sha256").update(bytes).digest("hex").slice(0, 32)}`;
+    await this.api.storage.write.mutate({
+      location: _BenchmarkAddon.REPLAY_CLIPS_LOCATION,
+      relativePath: `${clipId}.bin`,
+      data: new Uint8Array(bytes)
+    });
+    this.ctx.logger.info("replay: clip uploaded", { meta: { clipId, bytes: bytes.length } });
+    return { clipId };
+  }
+  async runReplayClip(input) {
+    if (this.replayStore === null) throw new Error("replay: store not initialized");
+    const store = this.replayStore;
+    const source = input.source;
+    const result = await orchestrateReplayRun(
+      {
+        api: this.api,
+        logger: this.ctx.logger,
+        decoder: this.replayDecoder,
+        store,
+        ffmpegPath: process.env["FFMPEG_PATH"] ?? "ffmpeg",
+        resolveBaseTree: (deviceId) => this.api.pipelineOrchestrator.resolvePipeline.query({ deviceId }),
+        fetchSourceBytes: (src) => this.fetchReplaySourceBytes(src)
+      },
+      {
+        deviceId: input.deviceId,
+        nodeId: input.nodeId,
+        source,
+        overlay: input.overlay,
+        fps: input.fps,
+        maxFrames: input.maxFrames,
+        maxWidth: input.maxWidth,
+        ...input.deviceKey !== void 0 ? { deviceKey: input.deviceKey } : {}
+      }
+    );
+    if (result.kind === "ran")
+      this.replayRunCache.set(result.replayRunId, {
+        id: result.replayRunId,
+        deviceId: input.deviceId,
+        nodeId: input.nodeId,
+        clipId: source.kind === "upload" ? source.clipId : `recording:${source.deviceId}:${source.fromMs}`,
+        createdAtMs: Date.now(),
+        source,
+        plan: null,
+        verdict: result.verdict
+      });
+    return result;
+  }
+  /**
+   * The profile a replay window is read from. `high` — same choice
+   * `RECORDED_STILL_PROFILE` makes in `addon-post-analysis` — because the
+   * whole point of `recording` over `upload` is NATIVE pixels (`-c:v copy`
+   * means the recorded frame IS the live frame); a window cut from a
+   * lower-rate rendition would be a worse version of the thing this source
+   * exists to avoid.
+   */
+  static REPLAY_RECORDING_PROFILE = "high";
+  /**
+   * Byte source for the replay decode step.
+   *
+   * `upload` is `storage.read` against the `replayClips` location. `recording`
+   * is `recording.getDeviceConfig` → `recording.locateSegment` →
+   * `recording.readWindowBytes` — the same "cheap question first" ordering
+   * `RecordedStillService` uses (a camera that is not recording costs a
+   * settings read, never a disk read), through `ctx.api` because addons never
+   * import each other.
+   *
+   * Every expected failure — not recording, no footage covering `fromMs`, a
+   * window that runs past its covering segment — returns a NAMED `refused`,
+   * never a thrown error: "the window has no segments" is a RESULT this
+   * whole feature exists to make legible (see the plan's stated unknown about
+   * whether device 615's footage covers 2026-08-26 18:12), not a failure to
+   * hide behind a generic exception.
+   */
+  async fetchReplaySourceBytes(source) {
+    if (source.kind === "upload") {
+      try {
+        const bytes = await this.api.storage.read.query({
+          location: _BenchmarkAddon.REPLAY_CLIPS_LOCATION,
+          relativePath: `${source.clipId}.bin`
+        });
+        return { kind: "ok", bytes, startMs: 0 };
+      } catch (err) {
+        return { kind: "refused", reason: `clip-not-found: ${errMsg(err)}` };
+      }
+    }
+    const profile = _BenchmarkAddon.REPLAY_RECORDING_PROFILE;
+    const tags = { deviceId: source.deviceId };
+    const config2 = await this.api.recording.getDeviceConfig.query({ deviceId: source.deviceId });
+    if (config2.enabled === false) {
+      this.ctx.logger.warn("replay: recording source refused \u2014 camera is not recording", {
+        tags
+      });
+      return {
+        kind: "refused",
+        reason: `no-recording: device ${source.deviceId} does not have recording enabled`
+      };
+    }
+    const located = await this.api.recording.locateSegment.query({
+      deviceId: source.deviceId,
+      profile,
+      epochMs: source.fromMs
+    });
+    if (located.kind !== "segment") {
+      this.ctx.logger.warn(
+        "replay: recording source refused \u2014 no footage covers the window start",
+        { tags, meta: { fromMs: source.fromMs, toMs: source.toMs, profile } }
+      );
+      return {
+        kind: "refused",
+        reason: `no-footage: device ${source.deviceId} has no ${profile} recording covering ${new Date(source.fromMs).toISOString()}`
+      };
+    }
+    const window = await this.api.recording.readWindowBytes.query({
+      deviceId: source.deviceId,
+      profile,
+      startMs: located.startMs,
+      fromMs: source.fromMs,
+      toMs: source.toMs
+    });
+    if (window.kind !== "ok") {
+      this.ctx.logger.warn(
+        "replay: recording source refused \u2014 window runs past the covering segment",
+        {
+          tags,
+          meta: { fromMs: source.fromMs, toMs: source.toMs, segmentEndMs: window.segmentEndMs }
+        }
+      );
+      return {
+        kind: "refused",
+        reason: `window-spans-multiple-segments: footage for device ${source.deviceId} changes segment at ${window.segmentEndMs}, before the requested end ${source.toMs} \u2014 shorten the window or align it to one segment`
+      };
+    }
+    if (!window.reachesRequestedEnd) {
+      this.ctx.logger.warn(
+        "replay: recording window bytes truncated by the recorder read safety cap",
+        { tags, meta: { fromMs: source.fromMs, toMs: source.toMs, gopDurMs: window.gopDurMs } }
+      );
+    }
+    return { kind: "ok", bytes: window.data, startMs: window.gopStartMs };
+  }
+  async listReplayRuns(input) {
+    if (this.replayStore === null) return [];
+    const rows = await this.replayStore.list({ deviceId: input.deviceId });
+    for (const row of rows) this.replayRunCache.set(row.id, row);
+    return rows;
+  }
+  /** `verdict` round-trips through the store as opaque JSON
+   *  (`StoredReplayRun.verdict: unknown`) — this is the ONE narrowing back
+   *  to the shape `diffReplayRuns` needs, at the ONE place that reads it
+   *  for that purpose. Same documented boundary `ReplayStore.list` itself
+   *  crosses (`replay-store.ts`): this addon is the only reader that knows
+   *  what it wrote. */
+  static verdictTracksAndDiscarded(verdict) {
+    return verdict;
+  }
+  async diffReplayRunsAction(input) {
+    const a = this.replayRunCache.get(input.runIdA);
+    const b = this.replayRunCache.get(input.runIdB);
+    if (a === void 0 || b === void 0) {
+      throw new Error(
+        "replay: diff \u2014 one or both run ids are not loaded (call listReplayRuns first)"
+      );
+    }
+    return diffReplayRuns(
+      {
+        clipId: a.clipId,
+        nodeId: a.nodeId,
+        settings: {},
+        ..._BenchmarkAddon.verdictTracksAndDiscarded(a.verdict)
+      },
+      {
+        clipId: b.clipId,
+        nodeId: b.nodeId,
+        settings: {},
+        ..._BenchmarkAddon.verdictTracksAndDiscarded(b.verdict)
+      }
+    );
+  }
   /**
    * Batched pipeline tester.
    *