@hyperframes/producer 0.8.177 → 0.8.179

package/dist/distributed.js

@@ -3,14 +3,14 @@ import { audioFailureDiagnostics as audioFailureDiagnostics3 } from "@hyperframe
 import {
   copyFileSync as copyFileSync5,
   cpSync as cpSync2,
-  existsSync as existsSync14,
+  existsSync as existsSync15,
   linkSync,
-  mkdirSync as mkdirSync8,
-  renameSync as renameSync3,
-  rmSync as rmSync7,
-  writeFileSync as writeFileSync5
+  mkdirSync as mkdirSync10,
+  renameSync as renameSync4,
+  rmSync as rmSync8,
+  writeFileSync as writeFileSync6
 } from "node:fs";
-import { extname as extname4, isAbsolute as isAbsolute3, join as join20, relative as relative5, sep as sep2 } from "node:path";
+import { extname as extname4, isAbsolute as isAbsolute3, join as join22, relative as relative5, sep as sep2 } from "node:path";
 import {
   fpsToNumber as fpsToNumber10,
   HF_COLOR_GRADING_ATTR as HF_COLOR_GRADING_ATTR2
@@ -1148,6 +1148,9 @@ import {
   extractAudioMetadata
 } from "@hyperframes/engine";
 
+// src/services/render/renderDirOwner.ts
+import { RENDER_TEMP_DIR } from "@hyperframes/core/project-folders";
+
 // src/services/render/capturePlan.ts
 function assertWorkerCount(workerCount) {
   if (!Number.isInteger(workerCount) || workerCount < 1) {
@@ -2337,7 +2340,7 @@ function detectShaderTransitionUsage(html) {
   }
   return false;
 }
-async function resolveMediaDuration(src, mediaStart, playbackRate, baseDir, downloadDir, tagName, elementIdentity, log) {
+async function resolveMediaDuration(src, mediaStart, playbackRate, baseDir, downloadDir, tagName, elementIdentity, log, urlByAbsentLocalPath) {
   let filePath = src;
   if (isHttpUrl(src)) {
     if (!existsSync6(downloadDir)) mkdirSync4(downloadDir, { recursive: true });
@@ -2351,8 +2354,9 @@ async function resolveMediaDuration(src, mediaStart, playbackRate, baseDir, down
   } else {
     filePath = decodedUrlPath(src);
     if (!filePath.startsWith("/")) filePath = join5(baseDir, filePath);
+    filePath = urlByAbsentLocalPath?.get(filePath) ?? filePath;
   }
-  if (!existsSync6(filePath)) {
+  if (!isHttpUrl(filePath) && !existsSync6(filePath)) {
     return { duration: null, resolvedPath: filePath };
   }
   const withSrcContext = (error) => {
@@ -2415,7 +2419,7 @@ function markInferredVariableMediaDurations(html, unresolvedMedia) {
   }
   return changed ? document2.toString() : html;
 }
-async function compileHtmlFile(html, baseDir, downloadDir, log) {
+async function compileHtmlFile(html, baseDir, downloadDir, log, urlByAbsentLocalPath) {
   const { html: staticCompiled, unresolved } = compileTimingAttrs(html);
   const mediaUnresolved = unresolved.filter(
     (el) => (el.tagName === "video" || el.tagName === "audio") && el.src
@@ -2431,7 +2435,8 @@ async function compileHtmlFile(html, baseDir, downloadDir, log) {
         downloadDir,
         el.tagName,
         el.id,
-        log
+        log,
+        urlByAbsentLocalPath
       ).then(({ duration }) => ({ id: el.id, duration }))
     )
   );
@@ -2473,7 +2478,7 @@ async function compileHtmlFile(html, baseDir, downloadDir, log) {
   compiledHtml = compiledHtml.replace(/(<audio\b[^>]*)\s+crossorigin(?:=["'][^"']*["'])?/gi, "$1");
   return { html: compiledHtml, unresolvedCompositions };
 }
-async function parseSubCompositions(html, projectDir, downloadDir, visited = /* @__PURE__ */ new Set()) {
+async function parseSubCompositions(html, projectDir, downloadDir, visited = /* @__PURE__ */ new Set(), urlByAbsentLocalPath) {
   const subCompositions = /* @__PURE__ */ new Map();
   const { document: document2 } = parseHTML4(html);
   const compEls = document2.querySelectorAll("[data-composition-src]");
@@ -2499,13 +2504,16 @@ async function parseSubCompositions(html, projectDir, downloadDir, visited = /*
       const { html: compiledSub } = await compileHtmlFile(
         item.rawSubHtml,
         dirname4(item.filePath),
-        downloadDir
+        downloadDir,
+        void 0,
+        urlByAbsentLocalPath
       );
       const nested = await parseSubCompositions(
         compiledSub,
         projectDir,
         downloadDir,
-        item.nestedVisited
+        item.nestedVisited,
+        urlByAbsentLocalPath
       );
       return {
         srcPath: item.srcPath,
@@ -3263,9 +3271,16 @@ async function compileForRender(projectDir, htmlPath, downloadDir, options = {})
     rawHtml,
     projectDir,
     downloadDir,
-    options.log
+    options.log,
+    options.urlByAbsentLocalPath
+  );
+  const { subCompositions } = await parseSubCompositions(
+    compiledHtml,
+    projectDir,
+    downloadDir,
+    void 0,
+    options.urlByAbsentLocalPath
   );
-  const { subCompositions } = await parseSubCompositions(compiledHtml, projectDir, downloadDir);
   const fullHtml = ensureFullDocument(compiledHtml);
   const inlinedHtml = inlineSubCompositions(
     fullHtml,
@@ -3761,6 +3776,7 @@ async function runCompileStage(input) {
     allowSystemFontCapture,
     abortSignal,
     variables: input.variables,
+    urlByAbsentLocalPath: input.urlByAbsentLocalPath,
     animatedGifCacheDir: cfg.extractCacheDir ? join6(cfg.extractCacheDir, "animated-gif") : void 0,
     ffmpegProcessTimeout: cfg.ffmpegProcessTimeout
   });
@@ -4759,7 +4775,8 @@ async function runExtractVideosStage(input) {
     abortSignal,
     assertNotAborted,
     materializeSymlinks,
-    deferRangeExtraction
+    deferRangeExtraction,
+    urlByAbsentLocalPath
   } = input;
   const stage2Start = Date.now();
   const extractionPolicy = resolveVideoExtractionPolicy();
@@ -4853,7 +4870,8 @@ async function runExtractVideosStage(input) {
         maxTransientRetries: extractionPolicy.maxTransientRetries,
         collectProbeFailures: extractionPolicy.failureMode === "enforce",
         deferRangeExtraction,
-        contentKeyedDirs: [join8(compiledDir, REMOTE_MEDIA_SUBDIR)]
+        contentKeyedDirs: [join8(compiledDir, REMOTE_MEDIA_SUBDIR)],
+        urlByAbsentLocalPath
       },
       abortSignal,
       cfg,
@@ -4936,6 +4954,7 @@ async function runAudioStage(input) {
     audioGain,
     audios,
     masterFxChain,
+    urlByAbsentLocalPath,
     abortSignal,
     assertNotAborted,
     log
@@ -4955,7 +4974,7 @@ async function runAudioStage(input) {
         audioOutputPath,
         duration,
         abortSignal,
-        { ffmpegProcessTimeout, audioGain, masterFxChain },
+        { ffmpegProcessTimeout, audioGain, masterFxChain, urlByAbsentLocalPath },
         compiledDir
       );
     } catch (err) {
@@ -6833,6 +6852,8 @@ function buildChunkCaptureOptions(input) {
     // The controller's snapshot, so the first capture sees the in-process renderer's `__hfVariables`.
     variables: encoder.variables,
     subTimelineWaitMemo: {},
+    skipReadinessVideoIds: input.skipReadinessVideoIds,
+    videoMetadataHints: input.videoMetadataHints,
     ...videoCaptureBeyondViewport !== void 0 ? { captureBeyondViewport: videoCaptureBeyondViewport } : {},
     // A fixed warmup count keeps `beginFrameTimeTicks` host-independent.
     lockWarmupTicks: true,
@@ -6841,6 +6862,19 @@ function buildChunkCaptureOptions(input) {
 }
 async function extractDeferredVideoFramesForChunk(input) {
   const deferred = input.planVideos.extracted.filter((video) => video.deferredRange);
+  const remoteSources = input.remoteSources ?? {};
+  for (const path of Object.keys(remoteSources)) {
+    if (!deferred.some((video) => video.deferredRange.sourcePath === path)) {
+      throw new RenderChunkValidationError(
+        MISSING_PLAN_ARTIFACT,
+        `[renderChunk] ${path} is read by URL but no deferred video uses it`
+      );
+    }
+    defaultLogger.info("[renderChunk] reading video by URL", {
+      path,
+      url: remoteSources[path].split("?")[0]
+    });
+  }
   if (deferred.length === 0) return [];
   const table = createFrameLookupTable2(
     input.planVideos.videos,
@@ -6868,8 +6902,9 @@ async function extractDeferredVideoFramesForChunk(input) {
         return { ...video, outputDir, framePaths: /* @__PURE__ */ new Map(), ownedByLookup: false };
       }
       const range = video.deferredRange;
-      const sourcePath = join16(input.planDir, ...range.sourcePath.split("/"));
-      if (!existsSync12(sourcePath)) {
+      const remoteUrl = remoteSources[range.sourcePath];
+      const sourcePath = remoteUrl ?? join16(input.planDir, ...range.sourcePath.split("/"));
+      if (remoteUrl === void 0 && !existsSync12(sourcePath)) {
         throw new RenderChunkValidationError(
           MISSING_PLAN_ARTIFACT,
           `[renderChunk] planDir is missing the source for video ${JSON.stringify(video.videoId)}: ${range.sourcePath}`
@@ -7209,6 +7244,16 @@ function collectPlanAssetShas(planDir, digests) {
   }
   return { compositionHtml, assets };
 }
+var PLAN_REMOTE_FILES_RELATIVE_PATH = "meta/remote-files.json";
+function writePlanRemoteFiles(planDir, files) {
+  if (files.length === 0) return;
+  const sorted = [...files].sort((a, b) => a.path < b.path ? -1 : 1);
+  writeFileSync4(join18(planDir, PLAN_REMOTE_FILES_RELATIVE_PATH), JSON.stringify(sorted), "utf-8");
+}
+function readPlanRemoteFiles(planDir) {
+  const path = join18(planDir, PLAN_REMOTE_FILES_RELATIVE_PATH);
+  return existsSync13(path) ? JSON.parse(readFileSync8(path, "utf-8")) : [];
+}
 function recomputePlanHashFromPlanDir(planDir, digests) {
   const planJsonPath = join18(planDir, "plan.json");
   const encoderJsonPath = join18(planDir, "meta", "encoder.json");
@@ -7324,167 +7369,677 @@ function applyRuntimeEnvSnapshot(snapshot, env = process.env) {
   };
 }
 
-// src/services/distributed/planSize.ts
-import { createHash as createHash5 } from "node:crypto";
-import { lstatSync, readdirSync as readdirSync6 } from "node:fs";
-import { extname as extname3, join as join19, relative as relative4 } from "node:path";
-var MAX_TOP_COMPONENTS = 10;
-var SOURCE_MEDIA_EXTENSIONS = /* @__PURE__ */ new Set([
-  ".aac",
-  ".aiff",
-  ".avi",
-  ".flac",
-  ".m4a",
-  ".m4v",
-  ".mkv",
-  ".mov",
-  ".mp3",
-  ".mp4",
-  ".mpeg",
-  ".mpg",
-  ".ogg",
-  ".ogv",
-  ".ts",
-  ".wav",
-  ".webm"
-]);
-var PLAN_ROOT_CATEGORY = {
-  compiled: "compiled",
-  [PLAN_AUDIO_RELATIVE_PATH]: "audio",
-  meta: "metadata",
-  "plan.json": "metadata"
-};
-function hashComponent(value) {
-  return createHash5("sha256").update(value).digest("hex").slice(0, 12);
+// src/services/distributed/chunkAudio.ts
+import { closeSync as closeSync4, existsSync as existsSync14, ftruncateSync, mkdirSync as mkdirSync9, openSync as openSync4, readFileSync as readFileSync9 } from "node:fs";
+import { writeFileSync as writeFileSync5, writeSync } from "node:fs";
+import { join as join20 } from "node:path";
+import { appendRenderProvenanceArgs, describeFfmpegFailure as describeFfmpegFailure2, runFfmpeg as runFfmpeg5 } from "@hyperframes/engine";
+
+// src/services/distributed/mp4Stitch.ts
+import {
+  createReadStream as createReadStream4,
+  createWriteStream,
+  mkdirSync as mkdirSync8,
+  mkdtempSync as mkdtempSync3,
+  renameSync as renameSync3,
+  rmSync as rmSync7
+} from "node:fs";
+import { open } from "node:fs/promises";
+import { dirname as dirname9, join as join19 } from "node:path";
+import { finished, pipeline } from "node:stream/promises";
+function boxAt(src, off, at, limit) {
+  let size = src.readUInt32BE(off);
+  let bodyStart = at + 8;
+  if (size === 1) {
+    size = Number(src.readBigUInt64BE(off + 8));
+    bodyStart = at + 16;
+  }
+  if (size < 8 || at + size > limit) throw new Error(`[mp4Stitch] malformed box at ${at}`);
+  return { type: src.toString("latin1", off + 4, off + 8), start: at, bodyStart, end: at + size };
 }
-function classifyFile(segments, rootKind) {
-  const rootName = segments[0] ?? "";
-  const extractedRootName = rootKind === "compiled" ? "__hyperframes_video_frames" : "video-frames";
-  if (rootName === extractedRootName) {
-    const videoKey = segments[1] ?? "unknown";
-    return {
-      category: "video-frames",
-      componentLabel: `video-frames:${hashComponent(videoKey)}`
-    };
+function childBoxes(buf, parent) {
+  const boxes = [];
+  for (let at = parent.bodyStart; at < parent.end; at = boxes.at(-1).end) {
+    boxes.push(boxAt(buf, at, at, parent.end));
   }
-  const category = rootKind === "compiled" ? "compiled" : PLAN_ROOT_CATEGORY[rootName] ?? "other";
-  return { category, componentLabel: category };
+  return boxes;
 }
-function emptyBreakdown() {
-  return {
-    totalBytes: 0,
-    fileCount: 0,
-    compiledBytes: 0,
-    sourceMediaBytes: 0,
-    videoFramesBytes: 0,
-    videoFrameFileCount: 0,
-    audioBytes: 0,
-    metadataBytes: 0,
-    otherBytes: 0,
-    topComponents: []
-  };
+function findChild(buf, parent, type) {
+  return childBoxes(buf, parent).find((box2) => box2.type === type);
 }
-function addCategoryBytes(result, category, filePath, sizeBytes) {
-  if (category === "compiled") {
-    result.compiledBytes += sizeBytes;
-    if (SOURCE_MEDIA_EXTENSIONS.has(extname3(filePath).toLowerCase())) {
-      result.sourceMediaBytes += sizeBytes;
-    }
-    return;
-  }
-  if (category === "video-frames") {
-    result.videoFramesBytes += sizeBytes;
-    result.videoFrameFileCount += 1;
-    return;
-  }
-  if (category === "audio") {
-    result.audioBytes += sizeBytes;
-    return;
-  }
-  if (category === "metadata") {
-    result.metadataBytes += sizeBytes;
-    return;
-  }
-  result.otherBytes += sizeBytes;
+function child(buf, parent, type) {
+  const found = findChild(buf, parent, type);
+  if (!found) throw new Error(`[mp4Stitch] ${parent.type} has no ${type}`);
+  return found;
 }
-function recordFile(result, components, rootDir, rootKind, filePath) {
-  let sizeBytes;
-  try {
-    const stat = lstatSync(filePath);
-    if (!stat.isFile()) return;
-    sizeBytes = stat.size;
-  } catch {
-    return;
-  }
-  const rel = relative4(rootDir, filePath);
-  const segments = rel.split(/[\\/]+/).filter(Boolean);
-  const classified = classifyFile(segments, rootKind);
-  result.totalBytes += sizeBytes;
-  result.fileCount += 1;
-  addCategoryBytes(result, classified.category, filePath, sizeBytes);
-  const component = components.get(classified.componentLabel) ?? {
-    label: classified.componentLabel,
-    sizeBytes: 0,
-    fileCount: 0
+var SCAN_BYTES = 64 * 1024;
+async function readMp4Layout(read) {
+  const found = /* @__PURE__ */ new Map();
+  let payload;
+  let buf = Buffer.alloc(0);
+  let bufAt = 0;
+  const load = async (start, end) => {
+    if (start >= bufAt && end <= bufAt + buf.length) return;
+    buf = await read(start, Math.max(end, start + SCAN_BYTES));
+    bufAt = start;
   };
-  component.sizeBytes += sizeBytes;
-  component.fileCount += 1;
-  components.set(classified.componentLabel, component);
-}
-function walkRegularFiles(dir, visit) {
-  let entries;
-  try {
-    entries = readdirSync6(dir, { withFileTypes: true });
-  } catch {
-    return;
-  }
-  for (const entry of entries) {
-    const full = join19(dir, entry.name);
-    if (entry.isDirectory()) {
-      walkRegularFiles(full, visit);
-    } else if (entry.isFile()) {
-      visit(full);
+  for (let at = 0; !(found.has("ftyp") && found.has("moov") && payload); ) {
+    await load(at, at + 16);
+    if (at + 8 > bufAt + buf.length) {
+      throw new Error(`[mp4Stitch] chunk needs ftyp, moov and mdat; found ${[...found.keys()]}`);
+    }
+    const box2 = boxAt(buf, at - bufAt, at, Number.MAX_SAFE_INTEGER);
+    if (box2.type === "mdat") payload ??= box2;
+    if (box2.type === "ftyp" || box2.type === "moov") {
+      await load(at, box2.end);
+      found.set(box2.type, buf.subarray(at - bufAt, box2.end - bufAt));
     }
+    at = box2.end;
   }
+  const [ftyp, moov] = [found.get("ftyp"), found.get("moov")];
+  if (moov.length !== moovSize(moov)) throw new Error("[mp4Stitch] moov is cut off");
+  return { ftyp, moov, payloadStart: payload.bodyStart, payloadEnd: payload.end };
 }
-function measurePlanSizeBreakdown(rootDir, rootKind = "plan") {
-  const result = emptyBreakdown();
-  const components = /* @__PURE__ */ new Map();
-  walkRegularFiles(
-    rootDir,
-    (filePath) => recordFile(result, components, rootDir, rootKind, filePath)
+var moovSize = (moov) => boxAt(moov, 0, 0, Number.MAX_SAFE_INTEGER).end;
+function readTracks(moov) {
+  const root = boxAt(moov, 0, 0, moov.length);
+  return childBoxes(moov, root).filter((box2) => box2.type === "trak").map((trak) => readTrack(moov, trak));
+}
+function rows(buf, table, columns, countAt = 4) {
+  const count = buf.readUInt32BE(table.bodyStart + countAt);
+  const first = table.bodyStart + countAt + 4;
+  return Array.from(
+    { length: count },
+    (_, row) => Array.from(
+      { length: columns },
+      (_2, col) => buf.readUInt32BE(first + (row * columns + col) * 4)
+    )
   );
-  result.topComponents = [...components.values()].sort((a, b) => b.sizeBytes - a.sizeBytes || a.label.localeCompare(b.label)).slice(0, MAX_TOP_COMPONENTS);
-  return result;
 }
-
-// src/services/distributed/plan.ts
-function logPlanStage(log, stage, startedAt) {
-  log.info("[plan] stage", { stage, ms: Date.now() - startedAt });
+function readMediaTime(moov, trak) {
+  const edts = findChild(moov, trak, "edts");
+  if (!edts) return 0;
+  const elst = child(moov, edts, "elst");
+  const wide = moov[elst.bodyStart] === 1;
+  const entries = moov.readUInt32BE(elst.bodyStart + 4);
+  for (let i = 0, at = elst.bodyStart + 8; i < entries; i++, at += wide ? 20 : 12) {
+    const offset = at + (wide ? 8 : 4);
+    const mediaTime = wide ? Number(moov.readBigInt64BE(offset)) : moov.readInt32BE(offset);
+    if (mediaTime !== -1) return mediaTime;
+  }
+  return 0;
 }
-function applyDistributedAudioWarningPolicy(job, audioError, audioFailures = [], log = defaultLogger) {
-  const failureOwner = audioFailures.length === 0 ? void 0 : audioFailures.some((failure) => failure.owner === "system") ? "system" : "user";
-  const retryable = audioFailures.length === 0 ? void 0 : audioFailures.every((failure) => failure.retryable);
-  applyRenderWarningPolicy(
-    job,
-    [
-      {
-        code: "audio_processing_failed",
-        message: `Audio mix failed; output would be video-only: ${audioError}`,
-        details: {
-          mediaType: "audio",
-          audioFailures: audioFailureDiagnostics3(audioFailures),
-          failureReasons: [...new Set(audioFailures.map((failure) => failure.reason))],
-          failureStages: [...new Set(audioFailures.map((failure) => failure.stage))],
-          failureOwner,
-          retryable
-        }
-      }
-    ],
-    log
-  );
+function readSizes(moov, stsz) {
+  const fixedSize = moov.readUInt32BE(stsz.bodyStart + 4);
+  if (!fixedSize) return rows(moov, stsz, 1, 8).map(([size]) => size);
+  return Array(moov.readUInt32BE(stsz.bodyStart + 8)).fill(fixedSize);
 }
-var PLAN_PROJECT_DIR_SKIP_SEGMENTS = /* @__PURE__ */ new Set([
+function readSync2(moov, stbl, sampleCount) {
+  const stss = findChild(moov, stbl, "stss");
+  if (!stss) return null;
+  const sync = Array(sampleCount).fill(false);
+  for (const [n] of rows(moov, stss, 1)) sync[n - 1] = true;
+  return sync;
+}
+function readChunkOffsets(moov, stbl) {
+  const stco = findChild(moov, stbl, "stco");
+  if (stco) return rows(moov, stco, 1).map(([offset]) => offset);
+  return rows(moov, child(moov, stbl, "co64"), 2).map(([hi, lo]) => hi * 2 ** 32 + lo);
+}
+function readSamplesPerChunk(moov, stbl, chunkCount) {
+  const stsc = rows(moov, child(moov, stbl, "stsc"), 3);
+  return stsc.flatMap(([firstChunk, perChunk, description], i) => {
+    if (description !== 1) throw new Error("[mp4Stitch] chunk uses more than one sample entry");
+    const nextFirst = stsc[i + 1]?.[0] ?? chunkCount + 1;
+    return Array(nextFirst - firstChunk).fill(perChunk);
+  });
+}
+function readTrack(moov, trak) {
+  const mdia = child(moov, trak, "mdia");
+  const hdlr = child(moov, mdia, "hdlr");
+  const stbl = child(moov, child(moov, mdia, "minf"), "stbl");
+  if (findChild(moov, stbl, "ctts")) throw new Error("[mp4Stitch] chunk has ctts (B-frames)");
+  const stts = rows(moov, child(moov, stbl, "stts"), 2);
+  const durations = stts.flatMap(([n, delta]) => Array(n).fill(delta));
+  const sizes = readSizes(moov, child(moov, stbl, "stsz"));
+  const chunkOffsets = readChunkOffsets(moov, stbl);
+  const samplesPerChunk = readSamplesPerChunk(moov, stbl, chunkOffsets.length);
+  if (durations.length !== sizes.length || sum(samplesPerChunk) !== sizes.length) {
+    throw new Error("[mp4Stitch] sample tables disagree on the sample count");
+  }
+  const stsd = child(moov, stbl, "stsd");
+  return {
+    trak,
+    handler: moov.toString("latin1", hdlr.bodyStart + 8, hdlr.bodyStart + 12),
+    timescale: timescaleOf(moov, child(moov, mdia, "mdhd")),
+    mediaTime: readMediaTime(moov, trak),
+    stsd: moov.subarray(stsd.start, stsd.end),
+    durations,
+    sizes,
+    sync: readSync2(moov, stbl, sizes.length),
+    samplesPerChunk,
+    chunkOffsets
+  };
+}
+function sum(values) {
+  return values.reduce((total, value) => total + value, 0);
+}
+function box(type, ...body) {
+  const header = Buffer.alloc(8);
+  header.writeUInt32BE(8 + sum(body.map((part) => part.length)));
+  header.write(type, 4, "latin1");
+  return Buffer.concat([header, ...body]);
+}
+function fullBox(type, version, body) {
+  return box(type, Buffer.from([version, 0, 0, 0]), body);
+}
+function u32s(values) {
+  const buf = Buffer.alloc(values.length * 4);
+  values.forEach((value, i) => buf.writeUInt32BE(value, i * 4));
+  return buf;
+}
+function runs(values) {
+  const out = [];
+  for (const value of values) {
+    const last = out.at(-1);
+    if (last && last[1] === value) last[0]++;
+    else out.push([1, value]);
+  }
+  return out;
+}
+function rebuild(buf, parent, replace) {
+  const parts = childBoxes(buf, parent).map(
+    (box2) => replace[box2.type]?.(box2) ?? buf.subarray(box2.start, box2.end)
+  );
+  return box(parent.type, ...parts);
+}
+var DURATION_AT = {
+  mvhd: [16, 24],
+  mdhd: [16, 24],
+  tkhd: [20, 28]
+};
+function withDuration(buf, target, duration) {
+  const copy = Buffer.from(buf.subarray(target.start, target.end));
+  const body = target.bodyStart - target.start;
+  const wide = copy[body] === 1;
+  const at = body + DURATION_AT[target.type][wide ? 1 : 0];
+  if (wide) copy.writeBigUInt64BE(BigInt(duration), at);
+  else if (duration <= 4294967295) copy.writeUInt32BE(duration, at);
+  else throw new Error(`[mp4Stitch] ${target.type} duration ${duration} needs a version 1 box`);
+  return copy;
+}
+function timescaleOf(buf, header) {
+  return buf.readUInt32BE(header.bodyStart + (buf[header.bodyStart] === 1 ? 20 : 12));
+}
+function buildStbl(stsd, track) {
+  const stts = runs(track.durations);
+  const stsc = [];
+  let firstChunk = 1;
+  for (const [count, perChunk] of runs(track.samplesPerChunk)) {
+    stsc.push([firstChunk, perChunk, 1]);
+    firstChunk += count;
+  }
+  const co64 = Buffer.alloc(4 + track.chunkOffsets.length * 8);
+  co64.writeUInt32BE(track.chunkOffsets.length);
+  track.chunkOffsets.forEach((offset, i) => co64.writeBigUInt64BE(BigInt(offset), 4 + i * 8));
+  const syncSamples = track.sync?.flatMap((isSync, i) => isSync ? [i + 1] : []) ?? null;
+  return box(
+    "stbl",
+    stsd,
+    fullBox("stts", 0, u32s([stts.length, ...stts.flat()])),
+    ...syncSamples ? [fullBox("stss", 0, u32s([syncSamples.length, ...syncSamples]))] : [],
+    fullBox("stsc", 0, u32s([stsc.length, ...stsc.flat()])),
+    fullBox("stsz", 0, u32s([0, track.sizes.length, ...track.sizes])),
+    fullBox("co64", 0, co64)
+  );
+}
+var codecOf = (track) => track.stsd.toString("latin1", 20, 24);
+var sameTrack = (track, plan2) => track.handler === plan2.handler && track.timescale === plan2.timescale && codecOf(track) === codecOf(plan2);
+function planTracksOf(tracks, plan2, index) {
+  let next = 0;
+  const matched = plan2.map((planTrack) => {
+    const track = tracks[next];
+    if (track && sameTrack(track, planTrack)) return tracks[next++];
+    if (planTrack.handler === "soun") return null;
+    throw new Error(`[mp4Stitch] chunk ${index} tracks differ from chunk 0`);
+  });
+  if (next !== tracks.length)
+    throw new Error(`[mp4Stitch] chunk ${index} tracks differ from chunk 0`);
+  for (const track of tracks) {
+    if (track.handler === "vide" && track.mediaTime !== 0) {
+      throw new Error(`[mp4Stitch] chunk ${index} video starts at media time ${track.mediaTime}`);
+    }
+  }
+  return matched;
+}
+function buildStitchedHeader(layouts) {
+  const plan2 = readTracks(layouts[0].moov);
+  const chunks = layouts.map((layout, i) => planTracksOf(readTracks(layout.moov), plan2, i));
+  const payloadBases = [];
+  let payloadBytes = 0;
+  for (const layout of layouts) {
+    payloadBases.push(payloadBytes);
+    payloadBytes += layout.payloadEnd - layout.payloadStart;
+  }
+  const template = layouts[0].moov;
+  const root = boxAt(template, 0, 0, template.length);
+  const movieTimescale = timescaleOf(template, child(template, root, "mvhd"));
+  const buildMoov = (dataStart2) => {
+    const traks = plan2.map((track, t) => {
+      const parts = chunks.flatMap((tracks, chunk) => {
+        const part = tracks[t];
+        return part ? [{ ...part, chunk }] : [];
+      });
+      const merged = {
+        durations: parts.flatMap((part) => part.durations),
+        sizes: parts.flatMap((part) => part.sizes),
+        sync: parts.every((part) => !part.sync) ? null : parts.flatMap((part) => part.sync ?? part.sizes.map(() => true)),
+        samplesPerChunk: parts.flatMap((part) => part.samplesPerChunk),
+        chunkOffsets: parts.flatMap(
+          (part) => part.chunkOffsets.map((offset) => {
+            const i = part.chunk;
+            const { payloadStart, payloadEnd } = layouts[i];
+            if (offset < payloadStart || offset >= payloadEnd) {
+              throw new Error(`[mp4Stitch] chunk ${i} has samples outside its mdat`);
+            }
+            return offset - payloadStart + payloadBases[i] + dataStart2;
+          })
+        )
+      };
+      const mediaDuration = sum(merged.durations);
+      const shown = Math.round(
+        (mediaDuration - track.mediaTime) * movieTimescale / track.timescale
+      );
+      const elst = Buffer.alloc(24);
+      elst.writeUInt32BE(1);
+      elst.writeBigUInt64BE(BigInt(shown), 4);
+      elst.writeBigInt64BE(BigInt(track.mediaTime), 12);
+      elst.writeUInt32BE(65536, 20);
+      const edts = track.mediaTime ? box("edts", fullBox("elst", 1, elst)) : Buffer.alloc(0);
+      const trak = rebuild(template, track.trak, {
+        tkhd: (tkhd) => Buffer.concat([withDuration(template, tkhd, shown), edts]),
+        edts: () => Buffer.alloc(0),
+        mdia: (mdia) => rebuild(template, mdia, {
+          mdhd: (mdhd) => withDuration(template, mdhd, mediaDuration),
+          minf: (minf) => rebuild(template, minf, { stbl: () => buildStbl(track.stsd, merged) })
+        })
+      });
+      return { trak, shown };
+    });
+    let next = 0;
+    return rebuild(template, root, {
+      mvhd: (mvhd) => withDuration(template, mvhd, Math.max(...traks.map((t) => t.shown))),
+      trak: () => traks[next++].trak
+    });
+  };
+  const ftyp = layouts[0].ftyp;
+  const dataStart = ftyp.length + buildMoov(0).length + 16;
+  const mdat = Buffer.alloc(16);
+  mdat.writeUInt32BE(1);
+  mdat.write("mdat", 4, "latin1");
+  mdat.writeBigUInt64BE(BigInt(16 + payloadBytes), 8);
+  return Buffer.concat([ftyp, buildMoov(dataStart), mdat]);
+}
+function fileRange(path) {
+  return async (start, end) => {
+    const file = await open(path, "r", 384);
+    try {
+      const buf = Buffer.alloc(end - start);
+      const { bytesRead } = await file.read(buf, 0, buf.length, start);
+      return buf.subarray(0, bytesRead);
+    } finally {
+      await file.close();
+    }
+  };
+}
+async function copyPayload(path, layout, index, out) {
+  const { payloadStart, payloadEnd } = layout;
+  const payload = createReadStream4(path, { start: payloadStart, end: payloadEnd - 1 });
+  await pipeline(payload, out, { end: false });
+  if (payload.bytesRead !== payloadEnd - payloadStart) {
+    throw new Error(
+      `[mp4Stitch] chunk ${index} mdat holds ${payload.bytesRead} of ${payloadEnd - payloadStart} payload bytes`
+    );
+  }
+}
+async function writeStitchedMp4(chunkPaths, outputPath) {
+  const layouts = await Promise.all(chunkPaths.map((path) => readMp4Layout(fileRange(path))));
+  const header = buildStitchedHeader(layouts);
+  mkdirSync8(dirname9(outputPath), { recursive: true });
+  const workDir = mkdtempSync3(`${outputPath}.stitch-`);
+  const out = createWriteStream(join19(workDir, "out.mp4"));
+  try {
+    out.write(header);
+    for (const [i, path] of chunkPaths.entries()) await copyPayload(path, layouts[i], i, out);
+    out.end();
+    await finished(out);
+    renameSync3(join19(workDir, "out.mp4"), outputPath);
+  } finally {
+    out.destroy();
+    rmSync7(workDir, { recursive: true, force: true });
+  }
+}
+
+// src/services/distributed/chunkAudio.ts
+function audioCutForChunk(grid, chunks, index, fps) {
+  const firstPacketAt = (frame) => Math.min(
+    grid.packetCount,
+    Math.max(
+      0,
+      Math.ceil(
+        (frame * fps.den * grid.sampleRate - grid.firstStart * fps.num) / (grid.packetSamples * fps.num)
+      )
+    )
+  );
+  const first = index === 0 ? 0 : firstPacketAt(chunks[index].startFrame);
+  const end = index === chunks.length - 1 ? grid.packetCount : firstPacketAt(chunks[index + 1].startFrame);
+  if (end <= first) return null;
+  const cutSeconds = (packet) => (grid.firstStart + packet * grid.packetSamples - grid.packetSamples / 2) / grid.sampleRate;
+  const seekSeconds = index === 0 ? null : cutSeconds(first);
+  const durationSeconds = end === grid.packetCount ? null : cutSeconds(end) - (seekSeconds ?? 0);
+  return { seekSeconds, durationSeconds, firstPacket: first, packetCount: end - first };
+}
+async function probeAacPacketGrid(audioPath) {
+  const probe = await runFfprobeJson([
+    "-v",
+    "error",
+    "-select_streams",
+    "a:0",
+    "-show_entries",
+    "stream=sample_rate,time_base,nb_frames:packet=pts,duration",
+    "-read_intervals",
+    "%+#1",
+    "-of",
+    "json",
+    "--",
+    audioPath
+  ]);
+  const stream = probe.streams?.[0] ?? {};
+  const packet = probe.packets?.[0] ?? {};
+  const sampleRate = Number(stream.sample_rate);
+  const [tbNum = NaN, tbDen = NaN] = String(stream.time_base).split("/").map(Number);
+  const toSamples = (ticks) => Number(ticks) * sampleRate * tbNum / tbDen;
+  const grid = {
+    sampleRate,
+    firstStart: toSamples(packet.pts),
+    packetSamples: toSamples(packet.duration),
+    packetCount: Number(stream.nb_frames)
+  };
+  const counts = [grid.sampleRate, grid.packetSamples, grid.packetCount];
+  if (!Number.isFinite(grid.firstStart) || !counts.every((n) => Number.isFinite(n) && n > 0)) {
+    throw new Error(`[chunkAudio] could not read the AAC packet grid: ${JSON.stringify(probe)}`);
+  }
+  return grid;
+}
+var SLICE_DIR = "audio-chunks";
+var SLICE_FRAME = `${SLICE_DIR}/frame.m4a`;
+var SLICE_LAYOUT = `${SLICE_DIR}/layout.json`;
+function chunkAudioSlicePath(index) {
+  return `${SLICE_DIR}/${String(index).padStart(4, "0")}.bin`;
+}
+function chunkAudioSliceTarget(path) {
+  if (path === SLICE_FRAME || path === SLICE_LAYOUT) return "all";
+  const match = /^audio-chunks\/(\d{4,})\.bin$/.exec(path);
+  return match ? Number(match[1]) : null;
+}
+async function writeChunkAudioSlices(input) {
+  const grid = await probeAacPacketGrid(input.audioPath);
+  const { payloadStart, payloadEnd, moov } = await readMp4Layout(fileRange(input.audioPath));
+  const [track] = readTracks(moov);
+  const offsets = [];
+  track.chunkOffsets.forEach((offset, chunk) => {
+    for (let i = 0; i < track.samplesPerChunk[chunk]; i++) {
+      offsets.push(offset);
+      offset += track.sizes[offsets.length - 1];
+    }
+  });
+  const bytes = readFileSync9(input.audioPath);
+  const layout = { sizeBytes: bytes.length, payloadStart, payloadEnd, partStarts: {} };
+  mkdirSync9(join20(input.planDir, SLICE_DIR), { recursive: true });
+  input.chunks.forEach((_, index) => {
+    const cut = audioCutForChunk(grid, input.chunks, index, input.fps);
+    if (!cut) return;
+    const last = cut.firstPacket + cut.packetCount - 1;
+    const start = offsets[cut.firstPacket];
+    layout.partStarts[index] = start;
+    const end = offsets[last] + track.sizes[last];
+    writeFileSync5(join20(input.planDir, chunkAudioSlicePath(index)), bytes.subarray(start, end));
+  });
+  const frame = [bytes.subarray(0, payloadStart), bytes.subarray(payloadEnd)];
+  writeFileSync5(join20(input.planDir, SLICE_FRAME), Buffer.concat(frame));
+  writeFileSync5(join20(input.planDir, SLICE_LAYOUT), JSON.stringify(layout));
+}
+function chunkAudioSource(planDir, chunkIndex, scratchPath) {
+  const layoutPath = join20(planDir, SLICE_LAYOUT);
+  if (!existsSync14(layoutPath)) return resolvePlanAudioPath(planDir);
+  const layout = JSON.parse(readFileSync9(layoutPath, "utf-8"));
+  const frame = readFileSync9(join20(planDir, SLICE_FRAME));
+  const fd = openSync4(scratchPath, "w");
+  try {
+    writeSync(fd, frame, 0, layout.payloadStart, 0);
+    writeSync(
+      fd,
+      frame,
+      layout.payloadStart,
+      frame.length - layout.payloadStart,
+      layout.payloadEnd
+    );
+    const start = layout.partStarts[chunkIndex];
+    if (start !== void 0) {
+      const part = readFileSync9(join20(planDir, chunkAudioSlicePath(chunkIndex)));
+      writeSync(fd, part, 0, part.length, start);
+    }
+    ftruncateSync(fd, layout.sizeBytes);
+  } finally {
+    closeSync4(fd);
+  }
+  return scratchPath;
+}
+function chunkMuxArgs(input, cut) {
+  if (!cut) return ["-i", input.videoPath, "-map", "0:v:0"];
+  const seek = cut.seekSeconds === null ? [] : ["-ss", cut.seekSeconds.toFixed(6)];
+  const length = cut.durationSeconds === null ? [] : ["-t", cut.durationSeconds.toFixed(6)];
+  const exact = seek.length ? ["-copypriorss", "0"] : [];
+  return [
+    ...["-i", input.videoPath, ...seek, ...length, "-i", input.audioPath],
+    ...["-map", "0:v:0", "-map", "1:a:0", ...exact]
+  ];
+}
+async function muxChunkWithAudio(input) {
+  const grid = input.audioPath ? await probeAacPacketGrid(input.audioPath) : null;
+  const cut = grid ? audioCutForChunk(grid, input.chunks, input.chunkIndex, input.fps) : null;
+  const args = [...chunkMuxArgs(input, cut), "-c", "copy"];
+  appendRenderProvenanceArgs(args, input.outputPath);
+  args.push("-y", input.outputPath);
+  const result = await runFfmpeg5(args, { signal: input.signal, timeout: input.timeoutMs });
+  if (!result.success) {
+    throw new Error(
+      `[chunkAudio] chunk mux failed: ${describeFfmpegFailure2(result, input.timeoutMs)}`
+    );
+  }
+  const slice = input.chunks[input.chunkIndex];
+  const expected = { video: slice.endFrame - slice.startFrame };
+  if (cut) expected.audio = cut.packetCount;
+  const probe = await runFfprobeJson([
+    "-v",
+    "error",
+    "-count_packets",
+    "-show_entries",
+    "stream=codec_type,nb_read_packets",
+    "-of",
+    "json",
+    "--",
+    input.outputPath
+  ]);
+  for (const [type, count] of Object.entries(expected)) {
+    const packets = Number(probe.streams?.find((s) => s.codec_type === type)?.nb_read_packets ?? 0);
+    if (packets !== count) {
+      throw new Error(`[chunkAudio] ${type} packets in chunk ${packets}, expected ${count}`);
+    }
+  }
+}
+
+// src/services/distributed/planSize.ts
+import { createHash as createHash5 } from "node:crypto";
+import { lstatSync, readdirSync as readdirSync6 } from "node:fs";
+import { extname as extname3, join as join21, relative as relative4 } from "node:path";
+var MAX_TOP_COMPONENTS = 10;
+var SOURCE_MEDIA_EXTENSIONS = /* @__PURE__ */ new Set([
+  ".aac",
+  ".aiff",
+  ".avi",
+  ".flac",
+  ".m4a",
+  ".m4v",
+  ".mkv",
+  ".mov",
+  ".mp3",
+  ".mp4",
+  ".mpeg",
+  ".mpg",
+  ".ogg",
+  ".ogv",
+  ".ts",
+  ".wav",
+  ".webm"
+]);
+var PLAN_ROOT_CATEGORY = {
+  compiled: "compiled",
+  [PLAN_AUDIO_RELATIVE_PATH]: "audio",
+  meta: "metadata",
+  "plan.json": "metadata"
+};
+function hashComponent(value) {
+  return createHash5("sha256").update(value).digest("hex").slice(0, 12);
+}
+function classifyFile(segments, rootKind) {
+  const rootName = segments[0] ?? "";
+  const extractedRootName = rootKind === "compiled" ? "__hyperframes_video_frames" : "video-frames";
+  if (rootName === extractedRootName) {
+    const videoKey = segments[1] ?? "unknown";
+    return {
+      category: "video-frames",
+      componentLabel: `video-frames:${hashComponent(videoKey)}`
+    };
+  }
+  const category = rootKind === "compiled" ? "compiled" : PLAN_ROOT_CATEGORY[rootName] ?? "other";
+  return { category, componentLabel: category };
+}
+function emptyBreakdown() {
+  return {
+    totalBytes: 0,
+    fileCount: 0,
+    compiledBytes: 0,
+    sourceMediaBytes: 0,
+    videoFramesBytes: 0,
+    videoFrameFileCount: 0,
+    audioBytes: 0,
+    metadataBytes: 0,
+    otherBytes: 0,
+    topComponents: []
+  };
+}
+function addCategoryBytes(result, category, filePath, sizeBytes) {
+  if (category === "compiled") {
+    result.compiledBytes += sizeBytes;
+    if (SOURCE_MEDIA_EXTENSIONS.has(extname3(filePath).toLowerCase())) {
+      result.sourceMediaBytes += sizeBytes;
+    }
+    return;
+  }
+  if (category === "video-frames") {
+    result.videoFramesBytes += sizeBytes;
+    result.videoFrameFileCount += 1;
+    return;
+  }
+  if (category === "audio") {
+    result.audioBytes += sizeBytes;
+    return;
+  }
+  if (category === "metadata") {
+    result.metadataBytes += sizeBytes;
+    return;
+  }
+  result.otherBytes += sizeBytes;
+}
+function recordFile(result, components, rootDir, rootKind, filePath) {
+  let sizeBytes;
+  try {
+    const stat = lstatSync(filePath);
+    if (!stat.isFile()) return;
+    sizeBytes = stat.size;
+  } catch {
+    return;
+  }
+  const rel = relative4(rootDir, filePath);
+  const segments = rel.split(/[\\/]+/).filter(Boolean);
+  const classified = classifyFile(segments, rootKind);
+  result.totalBytes += sizeBytes;
+  result.fileCount += 1;
+  addCategoryBytes(result, classified.category, filePath, sizeBytes);
+  const component = components.get(classified.componentLabel) ?? {
+    label: classified.componentLabel,
+    sizeBytes: 0,
+    fileCount: 0
+  };
+  component.sizeBytes += sizeBytes;
+  component.fileCount += 1;
+  components.set(classified.componentLabel, component);
+}
+function walkRegularFiles(dir, visit) {
+  let entries;
+  try {
+    entries = readdirSync6(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    const full = join21(dir, entry.name);
+    if (entry.isDirectory()) {
+      walkRegularFiles(full, visit);
+    } else if (entry.isFile()) {
+      visit(full);
+    }
+  }
+}
+function measurePlanSizeBreakdown(rootDir, rootKind = "plan") {
+  const result = emptyBreakdown();
+  const components = /* @__PURE__ */ new Map();
+  walkRegularFiles(
+    rootDir,
+    (filePath) => recordFile(result, components, rootDir, rootKind, filePath)
+  );
+  result.topComponents = [...components.values()].sort((a, b) => b.sizeBytes - a.sizeBytes || a.label.localeCompare(b.label)).slice(0, MAX_TOP_COMPONENTS);
+  return result;
+}
+
+// src/services/distributed/plan.ts
+function logPlanStage(log, stage, startedAt) {
+  log.info("[plan] stage", { stage, ms: Date.now() - startedAt });
+}
+function applyDistributedAudioWarningPolicy(job, audioError, audioFailures = [], log = defaultLogger) {
+  const failureOwner = audioFailures.length === 0 ? void 0 : audioFailures.some((failure) => failure.owner === "system") ? "system" : "user";
+  const retryable = audioFailures.length === 0 ? void 0 : audioFailures.every((failure) => failure.retryable);
+  applyRenderWarningPolicy(
+    job,
+    [
+      {
+        code: "audio_processing_failed",
+        message: `Audio mix failed; output would be video-only: ${audioError}`,
+        details: {
+          mediaType: "audio",
+          audioFailures: audioFailureDiagnostics3(audioFailures),
+          failureReasons: [...new Set(audioFailures.map((failure) => failure.reason))],
+          failureStages: [...new Set(audioFailures.map((failure) => failure.stage))],
+          failureOwner,
+          retryable
+        }
+      }
+    ],
+    log
+  );
+}
+var PLAN_PROJECT_DIR_SKIP_SEGMENTS = /* @__PURE__ */ new Set([
   "node_modules",
   ".git",
   ".cache",
@@ -7653,13 +8208,13 @@ function assertPositiveInteger(name, value) {
 }
 var FREEZE_OWNED_PLAN_FILES = [
   "plan.json",
-  join20("meta", "composition.json"),
-  join20("meta", "encoder.json"),
-  join20("meta", "chunks.json")
+  join22("meta", "composition.json"),
+  join22("meta", "encoder.json"),
+  join22("meta", "chunks.json")
 ];
 function removeFreezeOwnedPlanFiles(planDir) {
   for (const relativePath of FREEZE_OWNED_PLAN_FILES) {
-    rmSync7(join20(planDir, relativePath), { force: true });
+    rmSync8(join22(planDir, relativePath), { force: true });
   }
 }
 function buildChunkSlices(totalFrames, chunkCount, effectiveChunkSize) {
@@ -7790,19 +8345,19 @@ function createVideoSourceShipper(input) {
     const known = shipped.get(srcPath);
     if (known) return known;
     const stagedRel = pathInside(input.workVideoFramesDir, srcPath);
-    const current = stagedRel === null ? srcPath : join20(input.planDir, "video-frames", stagedRel);
+    const current = stagedRel === null ? srcPath : join22(input.planDir, "video-frames", stagedRel);
     let result = null;
     for (const root of stagedRel === null ? [input.workCompiledDir, input.projectDir] : []) {
       const rel = pathInside(root, srcPath);
-      if (rel !== null && existsSync14(join20(input.planDir, "compiled", rel))) {
+      if (rel !== null && (existsSync15(join22(input.planDir, "compiled", rel)) || input.isRemote(srcPath))) {
         result = ["compiled", ...rel.split(sep2)].join("/");
         break;
       }
     }
     if (result === null) {
       result = `video-sources/${shipped.size}${extname4(current)}`;
-      const destination = join20(input.planDir, ...result.split("/"));
-      mkdirSync8(join20(input.planDir, "video-sources"), { recursive: true });
+      const destination = join22(input.planDir, ...result.split("/"));
+      mkdirSync10(join22(input.planDir, "video-sources"), { recursive: true });
       try {
         linkSync(current, destination);
       } catch {
@@ -7820,7 +8375,7 @@ async function buildLocalExecutionPlan(projectDir, config, executionPlanDir, opt
     useGpu: false,
     browserGpuMode: "software"
   });
-  if (!existsSync14(planDir)) mkdirSync8(planDir, { recursive: true });
+  if (!existsSync15(planDir)) mkdirSync10(planDir, { recursive: true });
   const log = config.logger ?? defaultLogger;
   const sizeLimitBytes = options.executionPlanSizeLimitBytes ?? config.planDirSizeLimitBytes ?? PLAN_DIR_SIZE_LIMIT_BYTES;
   const abortSignal = config.abortSignal;
@@ -7849,15 +8404,15 @@ async function buildLocalExecutionPlan(projectDir, config, executionPlanDir, opt
     variables: config.variables
   });
   const entryFile = config.entryFile ?? "index.html";
-  const htmlPath = join20(projectDir, entryFile);
-  if (!existsSync14(htmlPath)) {
+  const htmlPath = join22(projectDir, entryFile);
+  if (!existsSync15(htmlPath)) {
     throw new Error(`[plan] entry file not found: ${htmlPath}`);
   }
-  const workDir = join20(planDir, ".plan-work");
-  rmSync7(workDir, { recursive: true, force: true });
-  mkdirSync8(workDir, { recursive: true });
-  const compiledDir = join20(workDir, "compiled");
-  mkdirSync8(compiledDir, { recursive: true });
+  const workDir = join22(planDir, ".plan-work");
+  rmSync8(workDir, { recursive: true, force: true });
+  mkdirSync10(workDir, { recursive: true });
+  const compiledDir = join22(workDir, "compiled");
+  mkdirSync10(compiledDir, { recursive: true });
   let stageStarted = Date.now();
   cpSync2(projectDir, compiledDir, {
     recursive: true,
@@ -7870,10 +8425,19 @@ async function buildLocalExecutionPlan(projectDir, config, executionPlanDir, opt
     }
   });
   logPlanStage(log, "copy", stageStarted);
-  const finalCompiledDir = join20(planDir, "compiled");
+  const finalCompiledDir = join22(planDir, "compiled");
   const needsAlpha = outputNeedsAlpha(config.format);
+  const remoteFiles = Object.entries(options.remoteFiles ?? {});
+  const remoteLocalPath = (rel) => join22(projectDir, ...rel.split("/"));
+  const urlByAbsentLocalPath = new Map(
+    remoteFiles.map(([rel, file]) => [remoteLocalPath(rel), file.url])
+  );
+  const localPathByUrl = new Map(
+    remoteFiles.map(([rel, file]) => [file.url, remoteLocalPath(rel)])
+  );
   stageStarted = Date.now();
   const compileResult = await runCompileStage({
+    urlByAbsentLocalPath,
     projectDir,
     workDir,
     htmlPath,
@@ -7961,30 +8525,32 @@ async function buildLocalExecutionPlan(projectDir, config, executionPlanDir, opt
     abortSignal,
     assertNotAborted,
     materializeSymlinks: true,
-    deferRangeExtraction: options.deferVideoExtraction
+    deferRangeExtraction: options.deferVideoExtraction,
+    urlByAbsentLocalPath
   });
   logPlanStage(log, "extract", stageStarted);
   if (extractResult.failureToEnforce) throw extractResult.failureToEnforce;
   if (extractResult.extractionResult) {
     assertVideoExtractionSucceeded(extractResult.extractionResult);
   }
-  const stagedVideoFrames = join20(compiledDir, "__hyperframes_video_frames");
-  const videoFramesDst = join20(planDir, "video-frames");
-  if (existsSync14(videoFramesDst)) rmSync7(videoFramesDst, { recursive: true, force: true });
-  const videoSourcesDir = join20(planDir, "video-sources");
-  rmSync7(videoSourcesDir, { recursive: true, force: true });
-  if (existsSync14(stagedVideoFrames)) {
-    renameSync3(stagedVideoFrames, videoFramesDst);
+  const stagedVideoFrames = join22(compiledDir, "__hyperframes_video_frames");
+  const videoFramesDst = join22(planDir, "video-frames");
+  if (existsSync15(videoFramesDst)) rmSync8(videoFramesDst, { recursive: true, force: true });
+  const videoSourcesDir = join22(planDir, "video-sources");
+  rmSync8(videoSourcesDir, { recursive: true, force: true });
+  if (existsSync15(stagedVideoFrames)) {
+    renameSync4(stagedVideoFrames, videoFramesDst);
   } else {
-    mkdirSync8(videoFramesDst, { recursive: true });
+    mkdirSync10(videoFramesDst, { recursive: true });
   }
-  if (existsSync14(finalCompiledDir)) rmSync7(finalCompiledDir, { recursive: true, force: true });
-  renameSync3(compiledDir, finalCompiledDir);
+  if (existsSync15(finalCompiledDir)) rmSync8(finalCompiledDir, { recursive: true, force: true });
+  renameSync4(compiledDir, finalCompiledDir);
   const shipVideoSource = createVideoSourceShipper({
     planDir,
     projectDir,
     workCompiledDir: compiledDir,
-    workVideoFramesDir: stagedVideoFrames
+    workVideoFramesDir: stagedVideoFrames,
+    isRemote: (srcPath) => urlByAbsentLocalPath.has(srcPath)
   });
   const sourceRoots = [
     [stagedVideoFrames, "video-frames"],
@@ -7994,19 +8560,30 @@ async function buildLocalExecutionPlan(projectDir, config, executionPlanDir, opt
   const planVideosJson = buildPlanVideosJson({
     videos: composition.videos,
     compositionEnd: job.duration ?? Number.NaN,
-    extracted: (extractResult.extractionResult?.extracted ?? []).map((ext) => ({
-      videoId: ext.videoId,
-      srcPath: stableSourcePath(sourceRoots, ext.srcPath),
-      framePattern: ext.framePattern,
-      fps: ext.fps,
-      totalFrames: ext.totalFrames,
-      metadata: ext.metadata,
-      ...ext.deferredRange ? { deferredRange: { ...ext.deferredRange, sourcePath: shipVideoSource(ext.srcPath) } } : {}
-    }))
+    extracted: (extractResult.extractionResult?.extracted ?? []).map((ext) => {
+      const sourcePath = localPathByUrl.get(ext.srcPath) ?? ext.srcPath;
+      return {
+        videoId: ext.videoId,
+        srcPath: stableSourcePath(sourceRoots, sourcePath),
+        framePattern: ext.framePattern,
+        fps: ext.fps,
+        totalFrames: ext.totalFrames,
+        metadata: ext.metadata,
+        ...ext.deferredRange ? { deferredRange: { ...ext.deferredRange, sourcePath: shipVideoSource(sourcePath) } } : {}
+      };
+    })
   });
-  mkdirSync8(join20(planDir, "meta"), { recursive: true });
-  writeFileSync5(
-    join20(planDir, PLAN_VIDEOS_META_RELATIVE_PATH),
+  mkdirSync10(join22(planDir, "meta"), { recursive: true });
+  writePlanRemoteFiles(
+    planDir,
+    remoteFiles.map(([rel, { sha256, sizeBytes }]) => ({
+      path: `compiled/${rel}`,
+      sha256,
+      sizeBytes
+    }))
+  );
+  writeFileSync6(
+    join22(planDir, PLAN_VIDEOS_META_RELATIVE_PATH),
     JSON.stringify(planVideosJson, null, 2),
     "utf-8"
   );
@@ -8019,6 +8596,7 @@ async function buildLocalExecutionPlan(projectDir, config, executionPlanDir, opt
       projectDir,
       workDir,
       compiledDir: finalCompiledDir,
+      urlByAbsentLocalPath,
       duration: audioSeconds,
       ffmpegProcessTimeout: cfg.ffmpegProcessTimeout,
       audioGain: cfg.audioGain,
@@ -8079,11 +8657,11 @@ async function buildLocalExecutionPlan(projectDir, config, executionPlanDir, opt
   if (audioResult.audioError) {
     applyDistributedAudioWarningPolicy(job, audioResult.audioError, audioResult.audioFailures, log);
   }
-  const planAudioPath = join20(planDir, PLAN_AUDIO_RELATIVE_PATH);
-  if (audioResult.hasAudio && existsSync14(audioResult.audioOutputPath)) {
-    renameSync3(audioResult.audioOutputPath, planAudioPath);
+  const planAudioPath = join22(planDir, PLAN_AUDIO_RELATIVE_PATH);
+  if (audioResult.hasAudio && existsSync15(audioResult.audioOutputPath)) {
+    renameSync4(audioResult.audioOutputPath, planAudioPath);
   }
-  if (chunksCarryAudio2 && existsSync14(planAudioPath)) {
+  if (chunksCarryAudio2 && existsSync15(planAudioPath)) {
     stageStarted = Date.now();
     const peak = await constrainAacTruePeak({
       audioPath: planAudioPath,
@@ -8093,6 +8671,16 @@ async function buildLocalExecutionPlan(projectDir, config, executionPlanDir, opt
     });
     if (!peak.success) throw encoderFailureError("[plan] audio true-peak check failed", peak);
     logPlanStage(log, "audio-peak", stageStarted);
+    if (options.sliceChunkAudio) {
+      stageStarted = Date.now();
+      await writeChunkAudioSlices({
+        audioPath: planAudioPath,
+        planDir,
+        chunks,
+        fps: { num: config.fps, den: 1 }
+      });
+      logPlanStage(log, "audio-slices", stageStarted);
+    }
   }
   const ffmpegVersion = await readFfmpegVersion();
   const producerVersion = readProducerVersion();
@@ -8126,7 +8714,7 @@ async function buildLocalExecutionPlan(projectDir, config, executionPlanDir, opt
     format: config.format
   };
   try {
-    rmSync7(workDir, { recursive: true, force: true });
+    rmSync8(workDir, { recursive: true, force: true });
   } catch (err) {
     log.warn("[plan] failed to remove temp work dir", {
       workDir,
@@ -8197,35 +8785,35 @@ async function plan(projectDir, config, planDir, options = {}) {
 // src/services/distributed/planV2.ts
 import {
   copyFileSync as copyFileSync7,
-  existsSync as existsSync16,
+  existsSync as existsSync17,
   lstatSync as lstatSync2,
-  mkdirSync as mkdirSync10,
-  mkdtempSync as mkdtempSync4,
-  readFileSync as readFileSync9,
+  mkdirSync as mkdirSync12,
+  mkdtempSync as mkdtempSync5,
+  readFileSync as readFileSync10,
   readdirSync as readdirSync7,
-  renameSync as renameSync5,
-  rmSync as rmSync9,
+  renameSync as renameSync6,
+  rmSync as rmSync10,
   statSync as statSync6,
-  writeFileSync as writeFileSync7
+  writeFileSync as writeFileSync8
 } from "node:fs";
 import { tmpdir } from "node:os";
-import { dirname as dirname10, isAbsolute as isAbsolute4, join as join23, relative as relative6, resolve as resolve8, sep as sep3 } from "node:path";
+import { dirname as dirname11, isAbsolute as isAbsolute4, join as join25, relative as relative6, resolve as resolve8, sep as sep3 } from "node:path";
 import { DISTRIBUTED_FPS, isDistributedFps } from "@hyperframes/core";
 import { createFrameLookupTable as createFrameLookupTable4 } from "@hyperframes/engine";
 
 // src/services/distributed/planV2Publisher.ts
 import {
   copyFileSync as copyFileSync6,
-  existsSync as existsSync15,
+  existsSync as existsSync16,
   linkSync as linkSync2,
-  mkdirSync as mkdirSync9,
-  mkdtempSync as mkdtempSync3,
-  renameSync as renameSync4,
-  rmSync as rmSync8,
+  mkdirSync as mkdirSync11,
+  mkdtempSync as mkdtempSync4,
+  renameSync as renameSync5,
+  rmSync as rmSync9,
   statSync as statSync5,
-  writeFileSync as writeFileSync6
+  writeFileSync as writeFileSync7
 } from "node:fs";
-import { dirname as dirname9, join as join22 } from "node:path";
+import { dirname as dirname10, join as join24 } from "node:path";
 
 // src/services/distributed/planV2Errors.ts
 var PLAN_V2_INTEGRITY_UNRECOVERABLE = "PLAN_V2_INTEGRITY_UNRECOVERABLE";
@@ -8240,7 +8828,7 @@ var PlanV2IntegrityError = class extends Error {
 };
 
 // src/services/distributed/planV2Layout.ts
-import { join as join21 } from "node:path";
+import { join as join23 } from "node:path";
 var SHA256_PATTERN = /^[0-9a-f]{64}$/;
 function assertPlanV2Sha256(value, field) {
   if (typeof value !== "string" || !SHA256_PATTERN.test(value)) {
@@ -8250,7 +8838,7 @@ function assertPlanV2Sha256(value, field) {
 }
 function planV2BlobPath(root, sha256) {
   const digest = assertPlanV2Sha256(sha256, "artifact sha256");
-  return join21(root, "artifacts", "sha256", digest.slice(0, 2), digest);
+  return join23(root, "artifacts", "sha256", digest.slice(0, 2), digest);
 }
 
 // src/services/distributed/planV2Publisher.ts
@@ -8285,13 +8873,13 @@ var LocalPlanV2ArtifactPublisher = class {
   #linkFile;
   #committed = false;
   constructor(destinationDir, options = {}) {
-    if (existsSync15(destinationDir)) {
+    if (existsSync16(destinationDir)) {
       throw new PlanV2IntegrityError(`output directory already exists: ${destinationDir}`);
     }
     this.destinationDir = destinationDir;
     this.#linkFile = options.linkFile ?? linkSync2;
-    mkdirSync9(dirname9(destinationDir), { recursive: true });
-    this.temporaryDir = mkdtempSync3(join22(dirname9(destinationDir), ".plan-v2-publish-"));
+    mkdirSync11(dirname10(destinationDir), { recursive: true });
+    this.temporaryDir = mkdtempSync4(join24(dirname10(destinationDir), ".plan-v2-publish-"));
   }
   async putBlob(blob) {
     const digest = assertPlanV2Sha256(blob.sha256, "published blob sha256");
@@ -8302,10 +8890,10 @@ var LocalPlanV2ArtifactPublisher = class {
       );
     }
     const destinationPath = planV2BlobPath(this.temporaryDir, digest);
-    if (existsSync15(destinationPath)) return;
-    mkdirSync9(dirname9(destinationPath), { recursive: true });
-    const stagingDir = mkdtempSync3(join22(dirname9(destinationPath), ".plan-v2-blob-"));
-    const temporaryPath = join22(stagingDir, "blob");
+    if (existsSync16(destinationPath)) return;
+    mkdirSync11(dirname10(destinationPath), { recursive: true });
+    const stagingDir = mkdtempSync4(join24(dirname10(destinationPath), ".plan-v2-blob-"));
+    const temporaryPath = join24(stagingDir, "blob");
     try {
       try {
         this.#linkFile(blob.sourcePath, temporaryPath);
@@ -8313,26 +8901,26 @@ var LocalPlanV2ArtifactPublisher = class {
         if (!canFallbackToCopy(error)) throw error;
         copyFileSync6(blob.sourcePath, temporaryPath);
       }
-      renameSync4(temporaryPath, destinationPath);
+      renameSync5(temporaryPath, destinationPath);
     } finally {
-      rmSync8(stagingDir, { recursive: true, force: true });
+      rmSync9(stagingDir, { recursive: true, force: true });
     }
   }
   async commitManifest(manifestBytes) {
     for (const digest of new Set(manifestDigests(manifestBytes))) {
-      if (!existsSync15(planV2BlobPath(this.temporaryDir, digest))) {
+      if (!existsSync16(planV2BlobPath(this.temporaryDir, digest))) {
         throw new PlanV2IntegrityError(
           `cannot commit manifest before referenced blob is durable: ${digest}`
         );
       }
     }
-    writeFileSync6(join22(this.temporaryDir, "plan.json"), manifestBytes, "utf-8");
-    renameSync4(this.temporaryDir, this.destinationDir);
+    writeFileSync7(join24(this.temporaryDir, "plan.json"), manifestBytes, "utf-8");
+    renameSync5(this.temporaryDir, this.destinationDir);
     this.#committed = true;
   }
   async abort() {
     if (!this.#committed) {
-      rmSync8(this.temporaryDir, { recursive: true, force: true });
+      rmSync9(this.temporaryDir, { recursive: true, force: true });
     }
   }
 };
@@ -8351,7 +8939,7 @@ function isNonNegativeIntegerArray(value) {
   return Array.isArray(value) && value.every((item) => typeof item === "number" && Number.isInteger(item) && item >= 0);
 }
 function readJsonFile(path, label) {
-  const contents = readFileSync9(path, "utf-8");
+  const contents = readFileSync10(path, "utf-8");
   try {
     const parsed = JSON.parse(contents);
     return parsed;
@@ -8371,7 +8959,7 @@ function listFiles(root) {
   const rootResolved = resolve8(root);
   function walk(dir) {
     for (const entry of readdirSync7(dir, { withFileTypes: true })) {
-      const absolutePath = join23(dir, entry.name);
+      const absolutePath = join25(dir, entry.name);
       if (entry.isDirectory()) {
         walk(absolutePath);
       } else if (entry.isFile()) {
@@ -8398,13 +8986,13 @@ function assertValidExtractionCacheCompleteSentinel(path) {
   }
 }
 function validateExtractionCacheCompleteSentinels(executionPlanDir) {
-  const videoRoot = join23(executionPlanDir, "video-frames");
-  if (!existsSync16(videoRoot)) return;
+  const videoRoot = join25(executionPlanDir, "video-frames");
+  if (!existsSync17(videoRoot)) return;
   for (const videoEntry of readdirSync7(videoRoot, { withFileTypes: true })) {
     if (!videoEntry.isDirectory()) continue;
-    const videoDir = join23(videoRoot, videoEntry.name);
+    const videoDir = join25(videoRoot, videoEntry.name);
     if (readdirSync7(videoDir).includes(EXTRACTION_CACHE_COMPLETE_SENTINEL)) {
-      const sentinelPath = join23(videoDir, EXTRACTION_CACHE_COMPLETE_SENTINEL);
+      const sentinelPath = join25(videoDir, EXTRACTION_CACHE_COMPLETE_SENTINEL);
       assertValidExtractionCacheCompleteSentinel(sentinelPath);
     }
   }
@@ -8421,31 +9009,37 @@ function resolveExtractedVideoOutputDir(planDir, videoId) {
   }
   return outputDir;
 }
-function artifactTargets(path, videoDependencies, chunksCarryAudio2) {
+function artifactTargets(path, videoDependencies, chunkAudio) {
   if (isPlanAudioArtifactPath(path)) {
-    return chunksCarryAudio2 ? { chunks: "all", assembler: false } : { chunks: [], assembler: true };
+    if (chunkAudio === "none") return { chunks: [], assembler: true };
+    return { chunks: chunkAudio === "whole" ? "all" : [], assembler: false };
   }
+  const slice = chunkAudioSliceTarget(path);
+  if (slice !== null) return { chunks: slice === "all" ? "all" : [slice], assembler: false };
   if (path === "plan.json" || path === "meta/chunks.json" || path === "meta/encoder.json") {
     return { chunks: "all", assembler: true };
   }
-  if (path === "meta/composition.json" || path === "meta/videos.json" || path.startsWith("compiled/")) {
-    return { chunks: "all", assembler: false };
-  }
-  if (path.startsWith("video-frames/") || path.startsWith("video-sources/")) {
+  if (path.startsWith("video-frames/") || path.startsWith("video-sources/") || path.startsWith("compiled/") && videoDependencies?.has(path)) {
     return {
       chunks: videoDependencies === null ? "all" : videoDependencies.get(path) ?? [],
       assembler: false
     };
   }
+  if (path === "meta/composition.json" || path === "meta/videos.json" || path.startsWith("compiled/")) {
+    return { chunks: "all", assembler: false };
+  }
   return { chunks: "all", assembler: true };
 }
+function isPlanV2DeferredSourceArtifact(artifact) {
+  return artifact.path.startsWith("compiled/") && artifact.chunks !== "all";
+}
 function listVideoFramePaths(executionPlanDir, videos) {
   return videos.extracted.map((video) => {
     const outputDir = resolveExtractedVideoOutputDir(executionPlanDir, video.videoId);
     if (video.deferredRange) {
       const framePaths2 = /* @__PURE__ */ new Map();
       for (let index = 0; index < video.totalFrames; index++) {
-        framePaths2.set(index, join23(outputDir, String(index)));
+        framePaths2.set(index, join25(outputDir, String(index)));
       }
       return { ...video, outputDir, framePaths: framePaths2, ownedByLookup: false };
     }
@@ -8453,7 +9047,7 @@ function listVideoFramePaths(executionPlanDir, videos) {
     const framePaths = /* @__PURE__ */ new Map();
     for (const frameName of frameNames) {
       if (frameName === EXTRACTION_CACHE_COMPLETE_SENTINEL) {
-        assertValidExtractionCacheCompleteSentinel(join23(outputDir, frameName));
+        assertValidExtractionCacheCompleteSentinel(join25(outputDir, frameName));
         continue;
       }
       const match = /(\d+)(?=\.[^.]+$)/.exec(frameName);
@@ -8472,7 +9066,7 @@ function listVideoFramePaths(executionPlanDir, videos) {
           `duplicate extracted frame index ${frameIndex} in ${outputDir}`
         );
       }
-      framePaths.set(frameIndex, join23(outputDir, frameName));
+      framePaths.set(frameIndex, join25(outputDir, frameName));
     }
     return {
       ...video,
@@ -8493,11 +9087,11 @@ function parsePlanVideosJson2(value) {
   }
 }
 function materializeExtractedVideoDirectories(planDir) {
-  const videosPath = join23(planDir, PLAN_VIDEOS_META_RELATIVE_PATH);
-  if (!existsSync16(videosPath)) return;
+  const videosPath = join25(planDir, PLAN_VIDEOS_META_RELATIVE_PATH);
+  if (!existsSync17(videosPath)) return;
   const videos = parsePlanVideosJson2(readJsonFile(videosPath, PLAN_VIDEOS_META_RELATIVE_PATH));
   for (const video of videos.extracted) {
-    mkdirSync10(resolveExtractedVideoOutputDir(planDir, video.videoId), { recursive: true });
+    mkdirSync12(resolveExtractedVideoOutputDir(planDir, video.videoId), { recursive: true });
   }
 }
 function parseChunkSlices(value) {
@@ -8522,13 +9116,13 @@ function parseChunkSlices(value) {
   });
 }
 function buildVideoChunkDependencies(executionPlanDir, dimensions) {
-  const videoRoot = join23(executionPlanDir, "video-frames");
-  const hasExtractedFrames = existsSync16(videoRoot) && listFiles(videoRoot).length > 0;
-  const videosPath = join23(executionPlanDir, PLAN_VIDEOS_META_RELATIVE_PATH);
-  if (!existsSync16(videosPath)) {
+  const videoRoot = join25(executionPlanDir, "video-frames");
+  const hasExtractedFrames = existsSync17(videoRoot) && listFiles(videoRoot).length > 0;
+  const videosPath = join25(executionPlanDir, PLAN_VIDEOS_META_RELATIVE_PATH);
+  if (!existsSync17(videosPath)) {
     return hasExtractedFrames ? { mode: "full-source-pack", dependencies: null } : { mode: "exact-rendered-frames", dependencies: /* @__PURE__ */ new Map() };
   }
-  const chunksPath = join23(executionPlanDir, "meta", "chunks.json");
+  const chunksPath = join25(executionPlanDir, "meta", "chunks.json");
   const videos = readJsonFile(videosPath, PLAN_VIDEOS_META_RELATIVE_PATH);
   const chunks = readJsonFile(chunksPath, "meta/chunks.json");
   const parsedVideos = parsePlanVideosJson2(videos);
@@ -8552,850 +9146,552 @@ function buildVideoChunkDependencies(executionPlanDir, dimensions) {
     chunks: parsedChunks,
     fpsNum,
     fpsDen,
-    deferredSources
-  });
-  return {
-    mode: deferredSources.size > 0 ? "source-extract" : "exact-rendered-frames",
-    dependencies
-  };
-}
-function collectChunkVideoDependencies(input) {
-  const mutable = /* @__PURE__ */ new Map();
-  for (const chunk of input.chunks) {
-    for (let frame = chunk.startFrame; frame < chunk.endFrame; frame++) {
-      const globalTime = frame * input.fpsDen / input.fpsNum;
-      for (const [videoId, payload] of input.table.getActiveFramePayloads(globalTime)) {
-        const path = input.deferredSources.get(videoId) ?? relative6(resolve8(input.executionPlanDir), payload.framePath).split(sep3).join("/");
-        assertSafeRelativePath(path);
-        const indexes = mutable.get(path) ?? /* @__PURE__ */ new Set();
-        indexes.add(chunk.index);
-        mutable.set(path, indexes);
-      }
-    }
-  }
-  return new Map([...mutable].map(([path, indexes]) => [path, [...indexes].sort((a, b) => a - b)]));
-}
-function manifestPayload(manifest) {
-  return manifest;
-}
-function computeManifestHash(manifest) {
-  return sha256Hex(`${PLAN_V2_HASH_PREFIX}${canonicalJsonStringify(manifestPayload(manifest))}`);
-}
-function writeBlob(sourcePath, destinationPath) {
-  if (existsSync16(destinationPath)) return;
-  mkdirSync10(dirname10(destinationPath), { recursive: true });
-  const temporaryDir = mkdtempSync4(join23(dirname10(destinationPath), ".plan-v2-blob-"));
-  const temporaryPath = join23(temporaryDir, "blob");
-  try {
-    copyFileSync7(sourcePath, temporaryPath);
-    renameSync5(temporaryPath, destinationPath);
-  } finally {
-    rmSync9(temporaryDir, { recursive: true, force: true });
-  }
-}
-function publishBlobFor(absolutePath, digests) {
-  return {
-    sourcePath: absolutePath,
-    sha256: planFileSha256(absolutePath, digests),
-    sizeBytes: statSync6(absolutePath).size
-  };
-}
-async function putBlobs(publisher, blobs) {
-  const uploadSlots = 32;
-  let next = 0;
-  let failure;
-  const upload = async () => {
-    while (!failure && next < blobs.length) {
-      const blob = blobs[next++];
-      try {
-        await publisher.putBlob(blob);
-      } catch (reason) {
-        failure ??= { reason };
-      }
-    }
-  };
-  await Promise.all(Array.from({ length: uploadSlots }, upload));
-  if (failure) throw failure.reason;
-}
-function buildPlanV2Publication(executionPlanDir, digests) {
-  const executionPlanPath = join23(executionPlanDir, "plan.json");
-  if (!existsSync16(executionPlanPath)) {
-    throw new PlanV2IntegrityError(`execution plan is missing plan.json: ${executionPlanPath}`);
-  }
-  const executionPlanValue = readJsonFile(executionPlanPath, "execution plan.json");
-  if (!isRecord3(executionPlanValue)) {
-    throw new PlanV2IntegrityError("execution plan.json must be an object");
-  }
-  const executionPlan = executionPlanValue;
-  readPlanProtocolV1(executionPlan);
-  const executionPlanHash = executionPlan.planHash;
-  if (!isSha256(executionPlanHash)) {
-    throw new PlanV2IntegrityError("execution plan.json.planHash must be a sha256 digest");
-  }
-  const recomputedExecutionPlanHash = recomputePlanHashFromPlanDir(executionPlanDir, digests);
-  if (recomputedExecutionPlanHash !== executionPlanHash) {
-    throw new PlanV2IntegrityError(
-      `execution plan content fingerprint does not match plan.json.planHash: expected ${executionPlanHash}, recomputed ${recomputedExecutionPlanHash}`
-    );
-  }
-  const artifacts = [];
-  const blobs = /* @__PURE__ */ new Map();
-  const dimensions = executionPlan.dimensions;
-  if (!isRecord3(dimensions)) {
-    throw new PlanV2IntegrityError("execution plan.json.dimensions must be an object");
-  }
-  validateExtractionCacheCompleteSentinels(executionPlanDir);
-  const videoDependencyPlan = buildVideoChunkDependencies(executionPlanDir, dimensions);
-  const encoder = readJsonFile(join23(executionPlanDir, "meta", "encoder.json"), "meta/encoder.json");
-  const chunksCarryAudio2 = isRecord3(encoder) && encoder.chunksCarryAudio === true;
-  for (const file of listFiles(executionPlanDir)) {
-    if (isExtractionCacheCompleteSentinelPath(file.path)) continue;
-    const targets = artifactTargets(file.path, videoDependencyPlan.dependencies, chunksCarryAudio2);
-    if ((file.path.startsWith("video-frames/") || file.path.startsWith("video-sources/")) && targets.chunks !== "all" && targets.chunks.length === 0 && !targets.assembler) {
-      continue;
-    }
-    const blob = publishBlobFor(file.absolutePath, digests);
-    if (!blobs.has(blob.sha256)) blobs.set(blob.sha256, blob);
-    artifacts.push({
-      path: file.path,
-      sha256: blob.sha256,
-      sizeBytes: blob.sizeBytes,
-      ...targets
-    });
-  }
-  const base = {
-    protocol: PLAN_PROTOCOL_V2,
-    // Retain the established manifest key byte-for-byte. It now acts as the
-    // wire alias for the neutral local execution-plan hash.
-    sourcePlanV1Hash: executionPlanHash,
-    chunkCount: readPositiveInteger2(executionPlan.chunkCount, "chunkCount"),
-    totalFrames: readPositiveInteger2(executionPlan.totalFrames, "totalFrames"),
-    fps: readExecutionPlanFps(dimensions),
-    width: readPositiveInteger2(dimensions.width, "dimensions.width"),
-    height: readPositiveInteger2(dimensions.height, "dimensions.height"),
-    format: readDistributedFormat(dimensions.format),
-    ffmpegVersion: readString2(executionPlan.ffmpegVersion, "ffmpegVersion"),
-    producerVersion: readString2(executionPlan.producerVersion, "producerVersion"),
-    limitations: { videoDependencyMode: videoDependencyPlan.mode },
-    artifacts
-  };
-  return {
-    manifest: {
-      ...base,
-      planHash: computeManifestHash(base)
-    },
-    blobs: [...blobs.values()]
-  };
-}
-function createPlanV2FromExecutionPlan(executionPlanDir, planV2Dir) {
-  if (existsSync16(planV2Dir)) {
-    throw new PlanV2IntegrityError(`output directory already exists: ${planV2Dir}`);
-  }
-  const publication = buildPlanV2Publication(executionPlanDir);
-  mkdirSync10(dirname10(planV2Dir), { recursive: true });
-  const tempDir = mkdtempSync4(join23(dirname10(planV2Dir), ".plan-v2-build-"));
-  try {
-    for (const blob of publication.blobs) {
-      writeBlob(blob.sourcePath, planV2BlobPath(tempDir, blob.sha256));
-    }
-    writeFileSync7(
-      join23(tempDir, "plan.json"),
-      canonicalJsonStringify(publication.manifest),
-      "utf-8"
-    );
-    renameSync5(tempDir, planV2Dir);
-    return resultFromManifest(planV2Dir, publication.manifest);
-  } catch (error) {
-    rmSync9(tempDir, { recursive: true, force: true });
-    throw error;
-  }
-}
-function createPlanV2FromV1(executionPlanDir, planV2Dir) {
-  return createPlanV2FromExecutionPlan(executionPlanDir, planV2Dir);
-}
-async function publishPlanV2FromExecutionPlan(executionPlanDir, publisher) {
-  return publishExecutionPlan(executionPlanDir, publisher, {});
-}
-async function publishExecutionPlan(executionPlanDir, publisher, { digests, log = defaultLogger }) {
-  try {
-    let stageStarted = Date.now();
-    const publication = buildPlanV2Publication(executionPlanDir, digests);
-    logPlanStage(log, "publication", stageStarted);
-    stageStarted = Date.now();
-    await putBlobs(publisher, publication.blobs);
-    logPlanStage(log, "upload", stageStarted);
-    stageStarted = Date.now();
-    await publisher.commitManifest(canonicalJsonStringify(publication.manifest));
-    logPlanStage(log, "manifest", stageStarted);
-    return publication.manifest;
-  } catch (error) {
-    try {
-      await publisher.abort();
-    } catch {
-    }
-    throw error;
-  }
-}
-async function publishPlanV2FromV1(executionPlanDir, publisher) {
-  return publishPlanV2FromExecutionPlan(executionPlanDir, publisher);
-}
-async function planV2WithPublisher(projectDir, config, publisher, options = {}) {
-  const stagingRoot = mkdtempSync4(join23(options.stagingParentDir ?? tmpdir(), ".execution-plan-"));
-  const digests = /* @__PURE__ */ new Map();
-  try {
-    await buildLocalExecutionPlan(projectDir, config, stagingRoot, {
-      executionPlanSizeLimitBytes: Number.MAX_SAFE_INTEGER,
-      deferVideoExtraction: true,
-      digests,
-      // artifactTargets ships every compiled/ file to all chunks, so each is in the manifest.
-      whileAudioMixes: () => putBlobs(
-        publisher,
-        listFiles(join23(stagingRoot, "compiled")).map(
-          (file) => publishBlobFor(file.absolutePath, digests)
-        )
-      ),
-      chunksCarryAudio: options.chunksCarryAudio
-    });
-    return await publishExecutionPlan(stagingRoot, publisher, { digests, log: config.logger });
-  } catch (error) {
-    try {
-      await publisher.abort();
-    } catch {
-    }
-    throw error;
-  } finally {
-    rmSync9(stagingRoot, { recursive: true, force: true });
-  }
-}
-async function planV2(projectDir, config, planV2Dir) {
-  if (existsSync16(planV2Dir)) {
-    throw new PlanV2IntegrityError(`output directory already exists: ${planV2Dir}`);
-  }
-  const publisher = new LocalPlanV2ArtifactPublisher(planV2Dir);
-  const manifest = await planV2WithPublisher(projectDir, config, publisher, {
-    stagingParentDir: dirname10(planV2Dir)
-  });
-  return resultFromManifest(planV2Dir, manifest);
-}
-function resultFromManifest(planV2Dir, manifest) {
-  return {
-    planDir: planV2Dir,
-    manifestPath: join23(planV2Dir, "plan.json"),
-    planProtocol: PLAN_PROTOCOL_V2,
-    planHash: manifest.planHash,
-    sourcePlanV1Hash: getPlanV2ExecutionPlanHash(manifest),
-    chunkCount: manifest.chunkCount,
-    totalFrames: manifest.totalFrames,
-    fps: manifest.fps,
-    width: manifest.width,
-    height: manifest.height,
-    format: manifest.format,
-    ffmpegVersion: manifest.ffmpegVersion,
-    producerVersion: manifest.producerVersion,
-    limitations: manifest.limitations
+    deferredSources
+  });
+  return {
+    mode: deferredSources.size > 0 ? "source-extract" : "exact-rendered-frames",
+    dependencies
   };
 }
-function getPlanV2ExecutionPlanHash(plan2) {
-  return plan2.sourcePlanV1Hash;
-}
-function readString2(value, field) {
-  if (typeof value !== "string" || value.length === 0) {
-    throw new PlanV2IntegrityError(`${field} must be a non-empty string`);
-  }
-  return value;
-}
-function readPositiveInteger2(value, field) {
-  if (typeof value !== "number" || !Number.isInteger(value) || value <= 0) {
-    throw new PlanV2IntegrityError(`${field} must be a positive integer`);
-  }
-  return value;
-}
-function readNonNegativeInteger2(value, field) {
-  if (typeof value !== "number" || !Number.isInteger(value) || value < 0) {
-    throw new PlanV2IntegrityError(`${field} must be a non-negative integer`);
+function collectChunkVideoDependencies(input) {
+  const mutable = /* @__PURE__ */ new Map();
+  for (const chunk of input.chunks) {
+    for (let frame = chunk.startFrame; frame < chunk.endFrame; frame++) {
+      const globalTime = frame * input.fpsDen / input.fpsNum;
+      for (const [videoId, payload] of input.table.getActiveFramePayloads(globalTime)) {
+        const path = input.deferredSources.get(videoId) ?? relative6(resolve8(input.executionPlanDir), payload.framePath).split(sep3).join("/");
+        assertSafeRelativePath(path);
+        const indexes = mutable.get(path) ?? /* @__PURE__ */ new Set();
+        indexes.add(chunk.index);
+        mutable.set(path, indexes);
+      }
+    }
   }
-  return value;
+  return new Map([...mutable].map(([path, indexes]) => [path, [...indexes].sort((a, b) => a - b)]));
 }
-function readSupportedFps(value) {
-  if (!isDistributedFps(value)) {
-    throw new PlanV2IntegrityError(
-      `dimensions.fpsNum must be one of ${DISTRIBUTED_FPS.join(", ")}`
-    );
-  }
-  return value;
+function manifestPayload(manifest) {
+  return manifest;
 }
-function readExecutionPlanFps(dimensions) {
-  const fpsDen = readPositiveInteger2(dimensions.fpsDen, "dimensions.fpsDen");
-  if (fpsDen !== 1) {
-    throw new PlanV2IntegrityError("dimensions.fpsDen must be 1 for plan v2");
-  }
-  return readSupportedFps(dimensions.fpsNum);
+function computeManifestHash(manifest) {
+  return sha256Hex(`${PLAN_V2_HASH_PREFIX}${canonicalJsonStringify(manifestPayload(manifest))}`);
 }
-function readDistributedFormat(value) {
-  if (value !== "mp4" && value !== "mov" && value !== "webm" && value !== "png-sequence") {
-    throw new PlanV2IntegrityError("dimensions.format is unsupported");
+function writeBlob(sourcePath, destinationPath) {
+  if (existsSync17(destinationPath)) return;
+  mkdirSync12(dirname11(destinationPath), { recursive: true });
+  const temporaryDir = mkdtempSync5(join25(dirname11(destinationPath), ".plan-v2-blob-"));
+  const temporaryPath = join25(temporaryDir, "blob");
+  try {
+    copyFileSync7(sourcePath, temporaryPath);
+    renameSync6(temporaryPath, destinationPath);
+  } finally {
+    rmSync10(temporaryDir, { recursive: true, force: true });
   }
-  return value;
 }
-function parseArtifact(value, index) {
-  if (!isRecord3(value)) throw new PlanV2IntegrityError(`artifacts[${index}] must be an object`);
-  const path = readString2(value.path, `artifacts[${index}].path`);
-  assertSafeRelativePath(path);
-  if (!isSha256(value.sha256)) {
-    throw new PlanV2IntegrityError(`artifacts[${index}].sha256 must be a lowercase sha256`);
-  }
-  const sizeBytes = value.sizeBytes;
-  if (typeof sizeBytes !== "number" || !Number.isInteger(sizeBytes) || sizeBytes < 0) {
-    throw new PlanV2IntegrityError(`artifacts[${index}].sizeBytes must be a non-negative integer`);
-  }
-  let chunks;
-  if (value.chunks === "all") {
-    chunks = "all";
-  } else if (isNonNegativeIntegerArray(value.chunks)) {
-    chunks = value.chunks;
-  } else {
-    throw new PlanV2IntegrityError(`artifacts[${index}].chunks is invalid`);
-  }
-  if (typeof value.assembler !== "boolean") {
-    throw new PlanV2IntegrityError(`artifacts[${index}].assembler must be boolean`);
-  }
+function publishBlobFor(absolutePath, digests) {
   return {
-    path,
-    sha256: value.sha256,
-    sizeBytes,
-    chunks,
-    assembler: value.assembler
-  };
-}
-function parsePlanV2Manifest(value) {
-  if (!isRecord3(value)) throw new PlanV2IntegrityError("manifest must be an object");
-  if (!isRecord3(value.protocol) || value.protocol.schemaVersion !== PLAN_PROTOCOL_V2.schemaVersion || value.protocol.artifactLayout !== PLAN_PROTOCOL_V2.artifactLayout || value.protocol.hashSchema !== PLAN_PROTOCOL_V2.hashSchema) {
-    throw new PlanV2IntegrityError("manifest protocol is not the supported v2 descriptor");
-  }
-  if (!isSha256(value.planHash) || !isSha256(value.sourcePlanV1Hash)) {
-    throw new PlanV2IntegrityError("manifest hashes must be lowercase sha256 digests");
-  }
-  if (!Array.isArray(value.artifacts)) throw new PlanV2IntegrityError("artifacts must be an array");
-  const artifacts = value.artifacts.map(parseArtifact);
-  const paths = /* @__PURE__ */ new Set();
-  for (const artifact of artifacts) {
-    if (paths.has(artifact.path))
-      throw new PlanV2IntegrityError(`duplicate artifact path: ${artifact.path}`);
-    paths.add(artifact.path);
-  }
-  if (!paths.has("plan.json"))
-    throw new PlanV2IntegrityError("manifest must include the local execution plan.json artifact");
-  if (!isRecord3(value.limitations) || value.limitations.videoDependencyMode !== "exact-rendered-frames" && value.limitations.videoDependencyMode !== "full-source-pack" && value.limitations.videoDependencyMode !== "source-extract") {
-    throw new PlanV2IntegrityError("unsupported video dependency mode");
-  }
-  const parsed = {
-    protocol: PLAN_PROTOCOL_V2,
-    planHash: value.planHash,
-    sourcePlanV1Hash: value.sourcePlanV1Hash,
-    chunkCount: readPositiveInteger2(value.chunkCount, "chunkCount"),
-    totalFrames: readPositiveInteger2(value.totalFrames, "totalFrames"),
-    fps: readSupportedFps(value.fps),
-    width: readPositiveInteger2(value.width, "width"),
-    height: readPositiveInteger2(value.height, "height"),
-    format: readDistributedFormat(value.format),
-    ffmpegVersion: readString2(value.ffmpegVersion, "ffmpegVersion"),
-    producerVersion: readString2(value.producerVersion, "producerVersion"),
-    limitations: { videoDependencyMode: value.limitations.videoDependencyMode },
-    artifacts
+    sourcePath: absolutePath,
+    sha256: planFileSha256(absolutePath, digests),
+    sizeBytes: statSync6(absolutePath).size
   };
-  const { planHash: _planHash, ...payload } = parsed;
-  const expectedHash = computeManifestHash(payload);
-  if (expectedHash !== parsed.planHash) {
-    throw new PlanV2IntegrityError("manifest integrity hash mismatch");
-  }
-  for (const [index, artifact] of parsed.artifacts.entries()) {
-    if (artifact.chunks !== "all" && artifact.chunks.some((chunkIndex) => chunkIndex >= parsed.chunkCount)) {
-      throw new PlanV2IntegrityError(`artifacts[${index}].chunks contains an out-of-range index`);
-    }
-  }
-  return parsed;
 }
-function readPlanV2Manifest(planV2Dir) {
-  const manifestPath = join23(planV2Dir, "plan.json");
-  if (!existsSync16(manifestPath)) {
-    throw new PlanV2IntegrityError(`missing v2 manifest: ${manifestPath}`);
-  }
-  const value = readJsonFile(manifestPath, "v2 manifest");
-  return parsePlanV2Manifest(value);
+async function putBlobs(publisher, blobs) {
+  await putTasks(blobs.map((blob) => () => publisher.putBlob(blob)));
 }
-function listPlanV2ArtifactsForTarget(manifest, target) {
-  if (target.role === "chunk") {
-    if (!Number.isInteger(target.chunkIndex) || target.chunkIndex < 0 || target.chunkIndex >= manifest.chunkCount) {
-      throw new PlanV2IntegrityError(`chunkIndex ${String(target.chunkIndex)} is out of range`);
+async function putTasks(tasks) {
+  const uploadSlots = 32;
+  let next = 0;
+  let failure;
+  const upload = async () => {
+    while (!failure && next < tasks.length) {
+      const task = tasks[next++];
+      try {
+        await task();
+      } catch (reason) {
+        failure ??= { reason };
+      }
     }
-    return manifest.artifacts.filter(
-      (artifact) => artifact.chunks === "all" || artifact.chunks.some((chunkIndex) => chunkIndex === target.chunkIndex)
-    );
-  }
-  return manifest.artifacts.filter((artifact) => artifact.assembler);
+  };
+  await Promise.all(Array.from({ length: uploadSlots }, upload));
+  if (failure) throw failure.reason;
 }
-function verifyBlob(planV2Dir, artifact) {
-  const sourcePath = planV2BlobPath(planV2Dir, artifact.sha256);
-  if (!existsSync16(sourcePath)) {
-    throw new PlanV2IntegrityError(`missing content-addressed artifact ${artifact.sha256}`);
+function buildPlanV2Publication(executionPlanDir, digests) {
+  const executionPlanPath = join25(executionPlanDir, "plan.json");
+  if (!existsSync17(executionPlanPath)) {
+    throw new PlanV2IntegrityError(`execution plan is missing plan.json: ${executionPlanPath}`);
   }
-  const stats = statSync6(sourcePath);
-  if (!stats.isFile() || stats.size !== artifact.sizeBytes) {
-    throw new PlanV2IntegrityError(`artifact size mismatch for ${artifact.path}`);
+  const executionPlanValue = readJsonFile(executionPlanPath, "execution plan.json");
+  if (!isRecord3(executionPlanValue)) {
+    throw new PlanV2IntegrityError("execution plan.json must be an object");
   }
-  if (sha256File(sourcePath) !== artifact.sha256) {
-    throw new PlanV2IntegrityError(`artifact hash mismatch for ${artifact.path}`);
+  const executionPlan = executionPlanValue;
+  readPlanProtocolV1(executionPlan);
+  const executionPlanHash = executionPlan.planHash;
+  if (!isSha256(executionPlanHash)) {
+    throw new PlanV2IntegrityError("execution plan.json.planHash must be a sha256 digest");
   }
-  return sourcePath;
-}
-function materializePlanV2Target(planV2Dir, target, destinationDir) {
-  if (existsSync16(destinationDir)) {
-    throw new PlanV2IntegrityError(`materialization destination already exists: ${destinationDir}`);
+  const recomputedExecutionPlanHash = recomputePlanHashFromPlanDir(executionPlanDir, digests);
+  if (recomputedExecutionPlanHash !== executionPlanHash) {
+    throw new PlanV2IntegrityError(
+      `execution plan content fingerprint does not match plan.json.planHash: expected ${executionPlanHash}, recomputed ${recomputedExecutionPlanHash}`
+    );
   }
-  const manifest = readPlanV2Manifest(planV2Dir);
-  const artifacts = listPlanV2ArtifactsForTarget(manifest, target);
-  const audioArtifact = artifacts.find((artifact) => isPlanAudioArtifactPath(artifact.path));
-  const verified = artifacts.map((artifact) => ({
-    artifact,
-    sourcePath: verifyBlob(planV2Dir, artifact)
-  }));
-  mkdirSync10(dirname10(destinationDir), { recursive: true });
-  const tempDir = mkdtempSync4(join23(dirname10(destinationDir), ".plan-v2-materialize-"));
-  try {
-    for (const { artifact, sourcePath } of verified) {
-      const destinationPath = join23(tempDir, ...artifact.path.split("/"));
-      mkdirSync10(dirname10(destinationPath), { recursive: true });
-      copyFileSync7(sourcePath, destinationPath);
+  const artifacts = [];
+  const blobs = /* @__PURE__ */ new Map();
+  const dimensions = executionPlan.dimensions;
+  if (!isRecord3(dimensions)) {
+    throw new PlanV2IntegrityError("execution plan.json.dimensions must be an object");
+  }
+  validateExtractionCacheCompleteSentinels(executionPlanDir);
+  const videoDependencyPlan = buildVideoChunkDependencies(executionPlanDir, dimensions);
+  const encoder = readJsonFile(join25(executionPlanDir, "meta", "encoder.json"), "meta/encoder.json");
+  const files = listFiles(executionPlanDir);
+  const chunkAudio = !isRecord3(encoder) || encoder.chunksCarryAudio !== true ? "none" : files.some((file) => chunkAudioSliceTarget(file.path) !== null) ? "sliced" : "whole";
+  for (const file of files) {
+    if (isExtractionCacheCompleteSentinelPath(file.path)) continue;
+    const targets = artifactTargets(file.path, videoDependencyPlan.dependencies, chunkAudio);
+    if ((file.path.startsWith("video-frames/") || file.path.startsWith("video-sources/")) && targets.chunks !== "all" && targets.chunks.length === 0 && !targets.assembler) {
+      continue;
     }
-    if (target.role === "chunk") materializeExtractedVideoDirectories(tempDir);
-    writeFileSync7(
-      join23(tempDir, PLAN_V2_MATERIALIZATION_MARKER),
-      canonicalJsonStringify({ manifest, target }),
-      "utf-8"
-    );
-    renameSync5(tempDir, destinationDir);
-  } catch (error) {
-    rmSync9(tempDir, { recursive: true, force: true });
-    throw error;
+    const blob = publishBlobFor(file.absolutePath, digests);
+    if (!blobs.has(blob.sha256)) blobs.set(blob.sha256, blob);
+    artifacts.push({
+      path: file.path,
+      sha256: blob.sha256,
+      sizeBytes: blob.sizeBytes,
+      ...targets
+    });
   }
-  return {
-    planDir: destinationDir,
-    target,
-    planHash: manifest.planHash,
-    sourcePlanV1Hash: getPlanV2ExecutionPlanHash(manifest),
-    artifactCount: artifacts.length,
-    sizeBytes: artifacts.reduce((sum2, artifact) => sum2 + artifact.sizeBytes, 0),
-    // Join the artifact's OWN name, not the current constant: a plan written
-    // before the container change carries the legacy name, and materializing it
-    // under the new one would point at a file that was never written.
-    audioPath: target.role === "assembler" ? audioArtifact ? join23(destinationDir, audioArtifact.path) : null : null
+  const storedBlobs = /* @__PURE__ */ new Map();
+  for (const remote of readPlanRemoteFiles(executionPlanDir)) {
+    const { sha256, sizeBytes } = remote;
+    if (!blobs.has(sha256)) storedBlobs.set(sha256, { sha256, sizeBytes });
+    artifacts.push({
+      ...remote,
+      ...artifactTargets(remote.path, videoDependencyPlan.dependencies, chunkAudio)
+    });
+  }
+  const base = {
+    protocol: PLAN_PROTOCOL_V2,
+    // Retain the established manifest key byte-for-byte. It now acts as the
+    // wire alias for the neutral local execution-plan hash.
+    sourcePlanV1Hash: executionPlanHash,
+    chunkCount: readPositiveInteger2(executionPlan.chunkCount, "chunkCount"),
+    totalFrames: readPositiveInteger2(executionPlan.totalFrames, "totalFrames"),
+    fps: readExecutionPlanFps(dimensions),
+    width: readPositiveInteger2(dimensions.width, "dimensions.width"),
+    height: readPositiveInteger2(dimensions.height, "dimensions.height"),
+    format: readDistributedFormat(dimensions.format),
+    ffmpegVersion: readString2(executionPlan.ffmpegVersion, "ffmpegVersion"),
+    producerVersion: readString2(executionPlan.producerVersion, "producerVersion"),
+    limitations: { videoDependencyMode: videoDependencyPlan.mode },
+    artifacts
+  };
+  return {
+    manifest: {
+      ...base,
+      planHash: computeManifestHash(base)
+    },
+    blobs: [...blobs.values()],
+    storedBlobs: [...storedBlobs.values()]
   };
 }
-function validatePlanV2MaterializedTarget(planDir, expectedTarget) {
-  const markerPath = join23(planDir, PLAN_V2_MATERIALIZATION_MARKER);
-  if (!existsSync16(markerPath)) return null;
-  const marker = readJsonFile(markerPath, "materialization marker");
-  if (!isRecord3(marker) || !isRecord3(marker.manifest) || !isRecord3(marker.target)) {
-    throw new PlanV2IntegrityError("malformed materialization marker");
+function createPlanV2FromExecutionPlan(executionPlanDir, planV2Dir) {
+  if (existsSync17(planV2Dir)) {
+    throw new PlanV2IntegrityError(`output directory already exists: ${planV2Dir}`);
   }
-  const target = marker.target;
-  if (target.role !== expectedTarget.role || expectedTarget.role === "chunk" && target.chunkIndex !== expectedTarget.chunkIndex) {
-    throw new PlanV2IntegrityError(
-      "materialization target does not match requested execution role"
-    );
+  const publication = buildPlanV2Publication(executionPlanDir);
+  if (publication.storedBlobs.length > 0) {
+    throw new PlanV2IntegrityError("a local plan v2 directory cannot reference remote files");
   }
-  const manifest = parsePlanV2Manifest(marker.manifest);
-  const required = listPlanV2ArtifactsForTarget(manifest, expectedTarget);
-  for (const artifact of required) {
-    const path = join23(planDir, ...artifact.path.split("/"));
-    if (!existsSync16(path) || statSync6(path).size !== artifact.sizeBytes) {
-      throw new PlanV2IntegrityError(
-        `materialized artifact missing or truncated: ${artifact.path}`
-      );
-    }
-    if (sha256File(path) !== artifact.sha256) {
-      throw new PlanV2IntegrityError(`materialized artifact hash mismatch: ${artifact.path}`);
+  mkdirSync12(dirname11(planV2Dir), { recursive: true });
+  const tempDir = mkdtempSync5(join25(dirname11(planV2Dir), ".plan-v2-build-"));
+  try {
+    for (const blob of publication.blobs) {
+      writeBlob(blob.sourcePath, planV2BlobPath(tempDir, blob.sha256));
     }
+    writeFileSync8(
+      join25(tempDir, "plan.json"),
+      canonicalJsonStringify(publication.manifest),
+      "utf-8"
+    );
+    renameSync6(tempDir, planV2Dir);
+    return resultFromManifest(planV2Dir, publication.manifest);
+  } catch (error) {
+    rmSync10(tempDir, { recursive: true, force: true });
+    throw error;
   }
-  return manifest;
-}
-
-// src/services/distributed/planV2Execution.ts
-import { mkdtempSync as mkdtempSync7, rmSync as rmSync13 } from "node:fs";
-import { tmpdir as tmpdir2 } from "node:os";
-import { join as join27 } from "node:path";
-
-// src/services/distributed/assemble.ts
-import {
-  cpSync as cpSync3,
-  existsSync as existsSync17,
-  mkdirSync as mkdirSync12,
-  mkdtempSync as mkdtempSync6,
-  readFileSync as readFileSync10,
-  readdirSync as readdirSync8,
-  renameSync as renameSync7,
-  rmSync as rmSync11,
-  statSync as statSync7,
-  writeFileSync as writeFileSync8
-} from "node:fs";
-import { dirname as dirname12, join as join25 } from "node:path";
-import {
-  appendRenderProvenanceArgs,
-  describeFfmpegFailure as describeFfmpegFailure2,
-  getEncoderPreset as getEncoderPreset5,
-  MIXED_AUDIO_FILENAME as MIXED_AUDIO_FILENAME4,
-  muxVideoWithAudio as muxVideoWithAudio2,
-  resolveConfig as resolveConfig4,
-  runFfmpeg as runFfmpeg5
-} from "@hyperframes/engine";
-import { fpsToFfmpegArg as fpsToFfmpegArg3 } from "@hyperframes/core";
-
-// src/services/distributed/mp4Stitch.ts
-import {
-  createReadStream as createReadStream4,
-  createWriteStream,
-  mkdirSync as mkdirSync11,
-  mkdtempSync as mkdtempSync5,
-  renameSync as renameSync6,
-  rmSync as rmSync10
-} from "node:fs";
-import { open } from "node:fs/promises";
-import { dirname as dirname11, join as join24 } from "node:path";
-import { finished, pipeline } from "node:stream/promises";
-function boxAt(src, off, at, limit) {
-  let size = src.readUInt32BE(off);
-  let bodyStart = at + 8;
-  if (size === 1) {
-    size = Number(src.readBigUInt64BE(off + 8));
-    bodyStart = at + 16;
-  }
-  if (size < 8 || at + size > limit) throw new Error(`[mp4Stitch] malformed box at ${at}`);
-  return { type: src.toString("latin1", off + 4, off + 8), start: at, bodyStart, end: at + size };
-}
-function childBoxes(buf, parent) {
-  const boxes = [];
-  for (let at = parent.bodyStart; at < parent.end; at = boxes.at(-1).end) {
-    boxes.push(boxAt(buf, at, at, parent.end));
-  }
-  return boxes;
 }
-function findChild(buf, parent, type) {
-  return childBoxes(buf, parent).find((box2) => box2.type === type);
+function createPlanV2FromV1(executionPlanDir, planV2Dir) {
+  return createPlanV2FromExecutionPlan(executionPlanDir, planV2Dir);
 }
-function child(buf, parent, type) {
-  const found = findChild(buf, parent, type);
-  if (!found) throw new Error(`[mp4Stitch] ${parent.type} has no ${type}`);
-  return found;
+async function publishPlanV2FromExecutionPlan(executionPlanDir, publisher) {
+  return publishExecutionPlan(executionPlanDir, publisher, {});
 }
-var SCAN_BYTES = 64 * 1024;
-async function readMp4Layout(read) {
-  const found = /* @__PURE__ */ new Map();
-  let payload;
-  let buf = Buffer.alloc(0);
-  let bufAt = 0;
-  const load = async (start, end) => {
-    if (start >= bufAt && end <= bufAt + buf.length) return;
-    buf = await read(start, Math.max(end, start + SCAN_BYTES));
-    bufAt = start;
-  };
-  for (let at = 0; !(found.has("ftyp") && found.has("moov") && payload); ) {
-    await load(at, at + 16);
-    if (at + 8 > bufAt + buf.length) {
-      throw new Error(`[mp4Stitch] chunk needs ftyp, moov and mdat; found ${[...found.keys()]}`);
+async function publishExecutionPlan(executionPlanDir, publisher, { digests, log = defaultLogger }) {
+  try {
+    let stageStarted = Date.now();
+    const publication = buildPlanV2Publication(executionPlanDir, digests);
+    logPlanStage(log, "publication", stageStarted);
+    if (publication.storedBlobs.length > 0 && !publisher.referenceStoredBlob) {
+      throw new PlanV2IntegrityError("this publisher cannot reference remote files");
     }
-    const box2 = boxAt(buf, at - bufAt, at, Number.MAX_SAFE_INTEGER);
-    if (box2.type === "mdat") payload ??= box2;
-    if (box2.type === "ftyp" || box2.type === "moov") {
-      await load(at, box2.end);
-      found.set(box2.type, buf.subarray(at - bufAt, box2.end - bufAt));
+    stageStarted = Date.now();
+    await putTasks([
+      ...publication.blobs.map((blob) => () => publisher.putBlob(blob)),
+      ...publication.storedBlobs.map((blob) => () => publisher.referenceStoredBlob(blob))
+    ]);
+    logPlanStage(log, "upload", stageStarted);
+    stageStarted = Date.now();
+    await publisher.commitManifest(canonicalJsonStringify(publication.manifest));
+    logPlanStage(log, "manifest", stageStarted);
+    return publication.manifest;
+  } catch (error) {
+    try {
+      await publisher.abort();
+    } catch {
     }
-    at = box2.end;
+    throw error;
   }
-  const [ftyp, moov] = [found.get("ftyp"), found.get("moov")];
-  if (moov.length !== moovSize(moov)) throw new Error("[mp4Stitch] moov is cut off");
-  return { ftyp, moov, payloadStart: payload.bodyStart, payloadEnd: payload.end };
-}
-var moovSize = (moov) => boxAt(moov, 0, 0, Number.MAX_SAFE_INTEGER).end;
-function readTracks(moov) {
-  const root = boxAt(moov, 0, 0, moov.length);
-  return childBoxes(moov, root).filter((box2) => box2.type === "trak").map((trak) => readTrack(moov, trak));
 }
-function rows(buf, table, columns, countAt = 4) {
-  const count = buf.readUInt32BE(table.bodyStart + countAt);
-  const first = table.bodyStart + countAt + 4;
-  return Array.from(
-    { length: count },
-    (_, row) => Array.from(
-      { length: columns },
-      (_2, col) => buf.readUInt32BE(first + (row * columns + col) * 4)
-    )
-  );
+async function publishPlanV2FromV1(executionPlanDir, publisher) {
+  return publishPlanV2FromExecutionPlan(executionPlanDir, publisher);
 }
-function readMediaTime(moov, trak) {
-  const edts = findChild(moov, trak, "edts");
-  if (!edts) return 0;
-  const elst = child(moov, edts, "elst");
-  const wide = moov[elst.bodyStart] === 1;
-  const entries = moov.readUInt32BE(elst.bodyStart + 4);
-  for (let i = 0, at = elst.bodyStart + 8; i < entries; i++, at += wide ? 20 : 12) {
-    const offset = at + (wide ? 8 : 4);
-    const mediaTime = wide ? Number(moov.readBigInt64BE(offset)) : moov.readInt32BE(offset);
-    if (mediaTime !== -1) return mediaTime;
+async function planV2WithPublisher(projectDir, config, publisher, options = {}) {
+  const stagingRoot = mkdtempSync5(join25(options.stagingParentDir ?? tmpdir(), ".execution-plan-"));
+  const digests = /* @__PURE__ */ new Map();
+  try {
+    await buildLocalExecutionPlan(projectDir, config, stagingRoot, {
+      executionPlanSizeLimitBytes: Number.MAX_SAFE_INTEGER,
+      deferVideoExtraction: true,
+      remoteFiles: options.remoteFiles,
+      digests,
+      // artifactTargets ships every compiled/ file to all chunks, so each is in the manifest.
+      whileAudioMixes: () => putBlobs(
+        publisher,
+        listFiles(join25(stagingRoot, "compiled")).map(
+          (file) => publishBlobFor(file.absolutePath, digests)
+        )
+      ),
+      chunksCarryAudio: options.chunksCarryAudio,
+      sliceChunkAudio: true
+    });
+    return await publishExecutionPlan(stagingRoot, publisher, { digests, log: config.logger });
+  } catch (error) {
+    try {
+      await publisher.abort();
+    } catch {
+    }
+    throw error;
+  } finally {
+    rmSync10(stagingRoot, { recursive: true, force: true });
   }
-  return 0;
-}
-function readSizes(moov, stsz) {
-  const fixedSize = moov.readUInt32BE(stsz.bodyStart + 4);
-  if (!fixedSize) return rows(moov, stsz, 1, 8).map(([size]) => size);
-  return Array(moov.readUInt32BE(stsz.bodyStart + 8)).fill(fixedSize);
-}
-function readSync2(moov, stbl, sampleCount) {
-  const stss = findChild(moov, stbl, "stss");
-  if (!stss) return null;
-  const sync = Array(sampleCount).fill(false);
-  for (const [n] of rows(moov, stss, 1)) sync[n - 1] = true;
-  return sync;
-}
-function readChunkOffsets(moov, stbl) {
-  const stco = findChild(moov, stbl, "stco");
-  if (stco) return rows(moov, stco, 1).map(([offset]) => offset);
-  return rows(moov, child(moov, stbl, "co64"), 2).map(([hi, lo]) => hi * 2 ** 32 + lo);
 }
-function readSamplesPerChunk(moov, stbl, chunkCount) {
-  const stsc = rows(moov, child(moov, stbl, "stsc"), 3);
-  return stsc.flatMap(([firstChunk, perChunk, description], i) => {
-    if (description !== 1) throw new Error("[mp4Stitch] chunk uses more than one sample entry");
-    const nextFirst = stsc[i + 1]?.[0] ?? chunkCount + 1;
-    return Array(nextFirst - firstChunk).fill(perChunk);
-  });
-}
-function readTrack(moov, trak) {
-  const mdia = child(moov, trak, "mdia");
-  const hdlr = child(moov, mdia, "hdlr");
-  const stbl = child(moov, child(moov, mdia, "minf"), "stbl");
-  if (findChild(moov, stbl, "ctts")) throw new Error("[mp4Stitch] chunk has ctts (B-frames)");
-  const stts = rows(moov, child(moov, stbl, "stts"), 2);
-  const durations = stts.flatMap(([n, delta]) => Array(n).fill(delta));
-  const sizes = readSizes(moov, child(moov, stbl, "stsz"));
-  const chunkOffsets = readChunkOffsets(moov, stbl);
-  const samplesPerChunk = readSamplesPerChunk(moov, stbl, chunkOffsets.length);
-  if (durations.length !== sizes.length || sum(samplesPerChunk) !== sizes.length) {
-    throw new Error("[mp4Stitch] sample tables disagree on the sample count");
+async function planV2(projectDir, config, planV2Dir) {
+  if (existsSync17(planV2Dir)) {
+    throw new PlanV2IntegrityError(`output directory already exists: ${planV2Dir}`);
   }
-  const stsd = child(moov, stbl, "stsd");
-  return {
-    trak,
-    handler: moov.toString("latin1", hdlr.bodyStart + 8, hdlr.bodyStart + 12),
-    timescale: timescaleOf(moov, child(moov, mdia, "mdhd")),
-    mediaTime: readMediaTime(moov, trak),
-    stsd: moov.subarray(stsd.start, stsd.end),
-    durations,
-    sizes,
-    sync: readSync2(moov, stbl, sizes.length),
-    samplesPerChunk,
-    chunkOffsets
-  };
-}
-function sum(values) {
-  return values.reduce((total, value) => total + value, 0);
-}
-function box(type, ...body) {
-  const header = Buffer.alloc(8);
-  header.writeUInt32BE(8 + sum(body.map((part) => part.length)));
-  header.write(type, 4, "latin1");
-  return Buffer.concat([header, ...body]);
+  const publisher = new LocalPlanV2ArtifactPublisher(planV2Dir);
+  const manifest = await planV2WithPublisher(projectDir, config, publisher, {
+    stagingParentDir: dirname11(planV2Dir)
+  });
+  return resultFromManifest(planV2Dir, manifest);
 }
-function fullBox(type, version, body) {
-  return box(type, Buffer.from([version, 0, 0, 0]), body);
+function resultFromManifest(planV2Dir, manifest) {
+  return {
+    planDir: planV2Dir,
+    manifestPath: join25(planV2Dir, "plan.json"),
+    planProtocol: PLAN_PROTOCOL_V2,
+    planHash: manifest.planHash,
+    sourcePlanV1Hash: getPlanV2ExecutionPlanHash(manifest),
+    chunkCount: manifest.chunkCount,
+    totalFrames: manifest.totalFrames,
+    fps: manifest.fps,
+    width: manifest.width,
+    height: manifest.height,
+    format: manifest.format,
+    ffmpegVersion: manifest.ffmpegVersion,
+    producerVersion: manifest.producerVersion,
+    limitations: manifest.limitations
+  };
 }
-function u32s(values) {
-  const buf = Buffer.alloc(values.length * 4);
-  values.forEach((value, i) => buf.writeUInt32BE(value, i * 4));
-  return buf;
+function getPlanV2ExecutionPlanHash(plan2) {
+  return plan2.sourcePlanV1Hash;
 }
-function runs(values) {
-  const out = [];
-  for (const value of values) {
-    const last = out.at(-1);
-    if (last && last[1] === value) last[0]++;
-    else out.push([1, value]);
+function readString2(value, field) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new PlanV2IntegrityError(`${field} must be a non-empty string`);
   }
-  return out;
+  return value;
 }
-function rebuild(buf, parent, replace) {
-  const parts = childBoxes(buf, parent).map(
-    (box2) => replace[box2.type]?.(box2) ?? buf.subarray(box2.start, box2.end)
-  );
-  return box(parent.type, ...parts);
+function readPositiveInteger2(value, field) {
+  if (typeof value !== "number" || !Number.isInteger(value) || value <= 0) {
+    throw new PlanV2IntegrityError(`${field} must be a positive integer`);
+  }
+  return value;
 }
-var DURATION_AT = {
-  mvhd: [16, 24],
-  mdhd: [16, 24],
-  tkhd: [20, 28]
-};
-function withDuration(buf, target, duration) {
-  const copy = Buffer.from(buf.subarray(target.start, target.end));
-  const body = target.bodyStart - target.start;
-  const wide = copy[body] === 1;
-  const at = body + DURATION_AT[target.type][wide ? 1 : 0];
-  if (wide) copy.writeBigUInt64BE(BigInt(duration), at);
-  else if (duration <= 4294967295) copy.writeUInt32BE(duration, at);
-  else throw new Error(`[mp4Stitch] ${target.type} duration ${duration} needs a version 1 box`);
-  return copy;
+function readNonNegativeInteger2(value, field) {
+  if (typeof value !== "number" || !Number.isInteger(value) || value < 0) {
+    throw new PlanV2IntegrityError(`${field} must be a non-negative integer`);
+  }
+  return value;
 }
-function timescaleOf(buf, header) {
-  return buf.readUInt32BE(header.bodyStart + (buf[header.bodyStart] === 1 ? 20 : 12));
+function readSupportedFps(value) {
+  if (!isDistributedFps(value)) {
+    throw new PlanV2IntegrityError(
+      `dimensions.fpsNum must be one of ${DISTRIBUTED_FPS.join(", ")}`
+    );
+  }
+  return value;
 }
-function buildStbl(stsd, track) {
-  const stts = runs(track.durations);
-  const stsc = [];
-  let firstChunk = 1;
-  for (const [count, perChunk] of runs(track.samplesPerChunk)) {
-    stsc.push([firstChunk, perChunk, 1]);
-    firstChunk += count;
+function readExecutionPlanFps(dimensions) {
+  const fpsDen = readPositiveInteger2(dimensions.fpsDen, "dimensions.fpsDen");
+  if (fpsDen !== 1) {
+    throw new PlanV2IntegrityError("dimensions.fpsDen must be 1 for plan v2");
   }
-  const co64 = Buffer.alloc(4 + track.chunkOffsets.length * 8);
-  co64.writeUInt32BE(track.chunkOffsets.length);
-  track.chunkOffsets.forEach((offset, i) => co64.writeBigUInt64BE(BigInt(offset), 4 + i * 8));
-  const syncSamples = track.sync?.flatMap((isSync, i) => isSync ? [i + 1] : []) ?? null;
-  return box(
-    "stbl",
-    stsd,
-    fullBox("stts", 0, u32s([stts.length, ...stts.flat()])),
-    ...syncSamples ? [fullBox("stss", 0, u32s([syncSamples.length, ...syncSamples]))] : [],
-    fullBox("stsc", 0, u32s([stsc.length, ...stsc.flat()])),
-    fullBox("stsz", 0, u32s([0, track.sizes.length, ...track.sizes])),
-    fullBox("co64", 0, co64)
-  );
+  return readSupportedFps(dimensions.fpsNum);
 }
-var codecOf = (track) => track.stsd.toString("latin1", 20, 24);
-var sameTrack = (track, plan2) => track.handler === plan2.handler && track.timescale === plan2.timescale && codecOf(track) === codecOf(plan2);
-function planTracksOf(tracks, plan2, index) {
-  let next = 0;
-  const matched = plan2.map((planTrack) => {
-    const track = tracks[next];
-    if (track && sameTrack(track, planTrack)) return tracks[next++];
-    if (planTrack.handler === "soun") return null;
-    throw new Error(`[mp4Stitch] chunk ${index} tracks differ from chunk 0`);
-  });
-  if (next !== tracks.length)
-    throw new Error(`[mp4Stitch] chunk ${index} tracks differ from chunk 0`);
-  for (const track of tracks) {
-    if (track.handler === "vide" && track.mediaTime !== 0) {
-      throw new Error(`[mp4Stitch] chunk ${index} video starts at media time ${track.mediaTime}`);
-    }
+function readDistributedFormat(value) {
+  if (value !== "mp4" && value !== "mov" && value !== "webm" && value !== "png-sequence") {
+    throw new PlanV2IntegrityError("dimensions.format is unsupported");
   }
-  return matched;
+  return value;
 }
-function buildStitchedHeader(layouts) {
-  const plan2 = readTracks(layouts[0].moov);
-  const chunks = layouts.map((layout, i) => planTracksOf(readTracks(layout.moov), plan2, i));
-  const payloadBases = [];
-  let payloadBytes = 0;
-  for (const layout of layouts) {
-    payloadBases.push(payloadBytes);
-    payloadBytes += layout.payloadEnd - layout.payloadStart;
+function parseArtifact(value, index) {
+  if (!isRecord3(value)) throw new PlanV2IntegrityError(`artifacts[${index}] must be an object`);
+  const path = readString2(value.path, `artifacts[${index}].path`);
+  assertSafeRelativePath(path);
+  if (!isSha256(value.sha256)) {
+    throw new PlanV2IntegrityError(`artifacts[${index}].sha256 must be a lowercase sha256`);
   }
-  const template = layouts[0].moov;
-  const root = boxAt(template, 0, 0, template.length);
-  const movieTimescale = timescaleOf(template, child(template, root, "mvhd"));
-  const buildMoov = (dataStart2) => {
-    const traks = plan2.map((track, t) => {
-      const parts = chunks.flatMap((tracks, chunk) => {
-        const part = tracks[t];
-        return part ? [{ ...part, chunk }] : [];
-      });
-      const merged = {
-        durations: parts.flatMap((part) => part.durations),
-        sizes: parts.flatMap((part) => part.sizes),
-        sync: parts.every((part) => !part.sync) ? null : parts.flatMap((part) => part.sync ?? part.sizes.map(() => true)),
-        samplesPerChunk: parts.flatMap((part) => part.samplesPerChunk),
-        chunkOffsets: parts.flatMap(
-          (part) => part.chunkOffsets.map((offset) => {
-            const i = part.chunk;
-            const { payloadStart, payloadEnd } = layouts[i];
-            if (offset < payloadStart || offset >= payloadEnd) {
-              throw new Error(`[mp4Stitch] chunk ${i} has samples outside its mdat`);
-            }
-            return offset - payloadStart + payloadBases[i] + dataStart2;
-          })
-        )
-      };
-      const mediaDuration = sum(merged.durations);
-      const shown = Math.round(
-        (mediaDuration - track.mediaTime) * movieTimescale / track.timescale
-      );
-      const elst = Buffer.alloc(24);
-      elst.writeUInt32BE(1);
-      elst.writeBigUInt64BE(BigInt(shown), 4);
-      elst.writeBigInt64BE(BigInt(track.mediaTime), 12);
-      elst.writeUInt32BE(65536, 20);
-      const edts = track.mediaTime ? box("edts", fullBox("elst", 1, elst)) : Buffer.alloc(0);
-      const trak = rebuild(template, track.trak, {
-        tkhd: (tkhd) => Buffer.concat([withDuration(template, tkhd, shown), edts]),
-        edts: () => Buffer.alloc(0),
-        mdia: (mdia) => rebuild(template, mdia, {
-          mdhd: (mdhd) => withDuration(template, mdhd, mediaDuration),
-          minf: (minf) => rebuild(template, minf, { stbl: () => buildStbl(track.stsd, merged) })
-        })
-      });
-      return { trak, shown };
-    });
-    let next = 0;
-    return rebuild(template, root, {
-      mvhd: (mvhd) => withDuration(template, mvhd, Math.max(...traks.map((t) => t.shown))),
-      trak: () => traks[next++].trak
-    });
+  const sizeBytes = value.sizeBytes;
+  if (typeof sizeBytes !== "number" || !Number.isInteger(sizeBytes) || sizeBytes < 0) {
+    throw new PlanV2IntegrityError(`artifacts[${index}].sizeBytes must be a non-negative integer`);
+  }
+  let chunks;
+  if (value.chunks === "all") {
+    chunks = "all";
+  } else if (isNonNegativeIntegerArray(value.chunks)) {
+    chunks = value.chunks;
+  } else {
+    throw new PlanV2IntegrityError(`artifacts[${index}].chunks is invalid`);
+  }
+  if (typeof value.assembler !== "boolean") {
+    throw new PlanV2IntegrityError(`artifacts[${index}].assembler must be boolean`);
+  }
+  return {
+    path,
+    sha256: value.sha256,
+    sizeBytes,
+    chunks,
+    assembler: value.assembler
   };
-  const ftyp = layouts[0].ftyp;
-  const dataStart = ftyp.length + buildMoov(0).length + 16;
-  const mdat = Buffer.alloc(16);
-  mdat.writeUInt32BE(1);
-  mdat.write("mdat", 4, "latin1");
-  mdat.writeBigUInt64BE(BigInt(16 + payloadBytes), 8);
-  return Buffer.concat([ftyp, buildMoov(dataStart), mdat]);
 }
-function fileRange(path) {
-  return async (start, end) => {
-    const file = await open(path, "r", 384);
-    try {
-      const buf = Buffer.alloc(end - start);
-      const { bytesRead } = await file.read(buf, 0, buf.length, start);
-      return buf.subarray(0, bytesRead);
-    } finally {
-      await file.close();
-    }
+function parsePlanV2Manifest(value) {
+  if (!isRecord3(value)) throw new PlanV2IntegrityError("manifest must be an object");
+  if (!isRecord3(value.protocol) || value.protocol.schemaVersion !== PLAN_PROTOCOL_V2.schemaVersion || value.protocol.artifactLayout !== PLAN_PROTOCOL_V2.artifactLayout || value.protocol.hashSchema !== PLAN_PROTOCOL_V2.hashSchema) {
+    throw new PlanV2IntegrityError("manifest protocol is not the supported v2 descriptor");
+  }
+  if (!isSha256(value.planHash) || !isSha256(value.sourcePlanV1Hash)) {
+    throw new PlanV2IntegrityError("manifest hashes must be lowercase sha256 digests");
+  }
+  if (!Array.isArray(value.artifacts)) throw new PlanV2IntegrityError("artifacts must be an array");
+  const artifacts = value.artifacts.map(parseArtifact);
+  const paths = /* @__PURE__ */ new Set();
+  for (const artifact of artifacts) {
+    if (paths.has(artifact.path))
+      throw new PlanV2IntegrityError(`duplicate artifact path: ${artifact.path}`);
+    paths.add(artifact.path);
+  }
+  if (!paths.has("plan.json"))
+    throw new PlanV2IntegrityError("manifest must include the local execution plan.json artifact");
+  if (!isRecord3(value.limitations) || value.limitations.videoDependencyMode !== "exact-rendered-frames" && value.limitations.videoDependencyMode !== "full-source-pack" && value.limitations.videoDependencyMode !== "source-extract") {
+    throw new PlanV2IntegrityError("unsupported video dependency mode");
+  }
+  const parsed = {
+    protocol: PLAN_PROTOCOL_V2,
+    planHash: value.planHash,
+    sourcePlanV1Hash: value.sourcePlanV1Hash,
+    chunkCount: readPositiveInteger2(value.chunkCount, "chunkCount"),
+    totalFrames: readPositiveInteger2(value.totalFrames, "totalFrames"),
+    fps: readSupportedFps(value.fps),
+    width: readPositiveInteger2(value.width, "width"),
+    height: readPositiveInteger2(value.height, "height"),
+    format: readDistributedFormat(value.format),
+    ffmpegVersion: readString2(value.ffmpegVersion, "ffmpegVersion"),
+    producerVersion: readString2(value.producerVersion, "producerVersion"),
+    limitations: { videoDependencyMode: value.limitations.videoDependencyMode },
+    artifacts
   };
+  const { planHash: _planHash, ...payload } = parsed;
+  const expectedHash = computeManifestHash(payload);
+  if (expectedHash !== parsed.planHash) {
+    throw new PlanV2IntegrityError("manifest integrity hash mismatch");
+  }
+  for (const [index, artifact] of parsed.artifacts.entries()) {
+    if (artifact.chunks !== "all" && artifact.chunks.some((chunkIndex) => chunkIndex >= parsed.chunkCount)) {
+      throw new PlanV2IntegrityError(`artifacts[${index}].chunks contains an out-of-range index`);
+    }
+  }
+  return parsed;
 }
-async function copyPayload(path, layout, index, out) {
-  const { payloadStart, payloadEnd } = layout;
-  const payload = createReadStream4(path, { start: payloadStart, end: payloadEnd - 1 });
-  await pipeline(payload, out, { end: false });
-  if (payload.bytesRead !== payloadEnd - payloadStart) {
-    throw new Error(
-      `[mp4Stitch] chunk ${index} mdat holds ${payload.bytesRead} of ${payloadEnd - payloadStart} payload bytes`
+function readPlanV2Manifest(planV2Dir) {
+  const manifestPath = join25(planV2Dir, "plan.json");
+  if (!existsSync17(manifestPath)) {
+    throw new PlanV2IntegrityError(`missing v2 manifest: ${manifestPath}`);
+  }
+  const value = readJsonFile(manifestPath, "v2 manifest");
+  return parsePlanV2Manifest(value);
+}
+function listPlanV2ArtifactsForTarget(manifest, target) {
+  if (target.role === "chunk") {
+    if (!Number.isInteger(target.chunkIndex) || target.chunkIndex < 0 || target.chunkIndex >= manifest.chunkCount) {
+      throw new PlanV2IntegrityError(`chunkIndex ${String(target.chunkIndex)} is out of range`);
+    }
+    return manifest.artifacts.filter(
+      (artifact) => artifact.chunks === "all" || artifact.chunks.some((chunkIndex) => chunkIndex === target.chunkIndex)
     );
   }
+  return manifest.artifacts.filter((artifact) => artifact.assembler);
+}
+function verifyBlob(planV2Dir, artifact) {
+  const sourcePath = planV2BlobPath(planV2Dir, artifact.sha256);
+  if (!existsSync17(sourcePath)) {
+    throw new PlanV2IntegrityError(`missing content-addressed artifact ${artifact.sha256}`);
+  }
+  const stats = statSync6(sourcePath);
+  if (!stats.isFile() || stats.size !== artifact.sizeBytes) {
+    throw new PlanV2IntegrityError(`artifact size mismatch for ${artifact.path}`);
+  }
+  if (sha256File(sourcePath) !== artifact.sha256) {
+    throw new PlanV2IntegrityError(`artifact hash mismatch for ${artifact.path}`);
+  }
+  return sourcePath;
 }
-async function writeStitchedMp4(chunkPaths, outputPath) {
-  const layouts = await Promise.all(chunkPaths.map((path) => readMp4Layout(fileRange(path))));
-  const header = buildStitchedHeader(layouts);
-  mkdirSync11(dirname11(outputPath), { recursive: true });
-  const workDir = mkdtempSync5(`${outputPath}.stitch-`);
-  const out = createWriteStream(join24(workDir, "out.mp4"));
+function materializePlanV2Target(planV2Dir, target, destinationDir, options = {}) {
+  if (existsSync17(destinationDir)) {
+    throw new PlanV2IntegrityError(`materialization destination already exists: ${destinationDir}`);
+  }
+  const manifest = readPlanV2Manifest(planV2Dir);
+  const artifacts = listPlanV2ArtifactsForTarget(manifest, target);
+  const remoteSources = options.remoteSources ?? {};
+  assertRemoteSources(remoteSources, artifacts);
+  const audioArtifact = artifacts.find((artifact) => isPlanAudioArtifactPath(artifact.path));
+  const verified = artifacts.filter((artifact) => !Object.hasOwn(remoteSources, artifact.path)).map((artifact) => ({
+    artifact,
+    sourcePath: verifyBlob(planV2Dir, artifact)
+  }));
+  mkdirSync12(dirname11(destinationDir), { recursive: true });
+  const tempDir = mkdtempSync5(join25(dirname11(destinationDir), ".plan-v2-materialize-"));
   try {
-    out.write(header);
-    for (const [i, path] of chunkPaths.entries()) await copyPayload(path, layouts[i], i, out);
-    out.end();
-    await finished(out);
-    renameSync6(join24(workDir, "out.mp4"), outputPath);
-  } finally {
-    out.destroy();
-    rmSync10(workDir, { recursive: true, force: true });
+    for (const { artifact, sourcePath } of verified) {
+      const destinationPath = join25(tempDir, ...artifact.path.split("/"));
+      mkdirSync12(dirname11(destinationPath), { recursive: true });
+      copyFileSync7(sourcePath, destinationPath);
+    }
+    if (target.role === "chunk") materializeExtractedVideoDirectories(tempDir);
+    writeFileSync8(
+      join25(tempDir, PLAN_V2_MATERIALIZATION_MARKER),
+      canonicalJsonStringify({
+        manifest,
+        target,
+        ...Object.keys(remoteSources).length > 0 ? { remoteSources } : {}
+      }),
+      "utf-8"
+    );
+    renameSync6(tempDir, destinationDir);
+  } catch (error) {
+    rmSync10(tempDir, { recursive: true, force: true });
+    throw error;
+  }
+  return {
+    planDir: destinationDir,
+    target,
+    planHash: manifest.planHash,
+    sourcePlanV1Hash: getPlanV2ExecutionPlanHash(manifest),
+    artifactCount: artifacts.length,
+    sizeBytes: artifacts.reduce((sum2, artifact) => sum2 + artifact.sizeBytes, 0),
+    // Join the artifact's OWN name, not the current constant: a plan written
+    // before the container change carries the legacy name, and materializing it
+    // under the new one would point at a file that was never written.
+    audioPath: target.role === "assembler" ? audioArtifact ? join25(destinationDir, audioArtifact.path) : null : null
+  };
+}
+function assertRemoteSources(remoteSources, artifacts) {
+  if (!isRecord3(remoteSources)) throw new PlanV2IntegrityError("remoteSources must be an object");
+  for (const [path, url] of Object.entries(remoteSources)) {
+    const artifact = artifacts.find((candidate) => candidate.path === path);
+    if (!artifact || !isPlanV2DeferredSourceArtifact(artifact)) {
+      throw new PlanV2IntegrityError(`remote source is not a selected deferred video: ${path}`);
+    }
+    if (typeof url !== "string" || !/^https?:\/\//.test(url)) {
+      throw new PlanV2IntegrityError(`remote source for ${path} must be an http(s) URL`);
+    }
+  }
+}
+function validatePlanV2MaterializedTarget(planDir, expectedTarget) {
+  return readValidatedPlanV2Materialization(planDir, expectedTarget)?.manifest ?? null;
+}
+function readValidatedPlanV2Materialization(planDir, expectedTarget) {
+  const markerPath = join25(planDir, PLAN_V2_MATERIALIZATION_MARKER);
+  if (!existsSync17(markerPath)) return null;
+  const marker = readJsonFile(markerPath, "materialization marker");
+  if (!isRecord3(marker) || !isRecord3(marker.manifest) || !isRecord3(marker.target)) {
+    throw new PlanV2IntegrityError("malformed materialization marker");
+  }
+  const target = marker.target;
+  if (target.role !== expectedTarget.role || expectedTarget.role === "chunk" && target.chunkIndex !== expectedTarget.chunkIndex) {
+    throw new PlanV2IntegrityError(
+      "materialization target does not match requested execution role"
+    );
+  }
+  const manifest = parsePlanV2Manifest(marker.manifest);
+  const required = listPlanV2ArtifactsForTarget(manifest, expectedTarget);
+  const remoteSources = marker.remoteSources ?? {};
+  assertRemoteSources(remoteSources, required);
+  for (const artifact of required) {
+    if (Object.hasOwn(remoteSources, artifact.path)) continue;
+    const path = join25(planDir, ...artifact.path.split("/"));
+    if (!existsSync17(path) || statSync6(path).size !== artifact.sizeBytes) {
+      throw new PlanV2IntegrityError(
+        `materialized artifact missing or truncated: ${artifact.path}`
+      );
+    }
+    if (sha256File(path) !== artifact.sha256) {
+      throw new PlanV2IntegrityError(`materialized artifact hash mismatch: ${artifact.path}`);
+    }
   }
+  return { manifest, remoteSources };
 }
 
+// src/services/distributed/planV2Execution.ts
+import { mkdtempSync as mkdtempSync7, rmSync as rmSync13 } from "node:fs";
+import { tmpdir as tmpdir2 } from "node:os";
+import { join as join28 } from "node:path";
+
 // src/services/distributed/assemble.ts
+import {
+  cpSync as cpSync3,
+  existsSync as existsSync18,
+  mkdirSync as mkdirSync13,
+  mkdtempSync as mkdtempSync6,
+  readFileSync as readFileSync11,
+  readdirSync as readdirSync8,
+  renameSync as renameSync7,
+  rmSync as rmSync11,
+  statSync as statSync7,
+  writeFileSync as writeFileSync9
+} from "node:fs";
+import { dirname as dirname12, join as join26 } from "node:path";
+import {
+  appendRenderProvenanceArgs as appendRenderProvenanceArgs2,
+  describeFfmpegFailure as describeFfmpegFailure3,
+  getEncoderPreset as getEncoderPreset5,
+  MIXED_AUDIO_FILENAME as MIXED_AUDIO_FILENAME4,
+  muxVideoWithAudio as muxVideoWithAudio2,
+  resolveConfig as resolveConfig4,
+  runFfmpeg as runFfmpeg6
+} from "@hyperframes/engine";
+import { fpsToFfmpegArg as fpsToFfmpegArg3 } from "@hyperframes/core";
 function cfrRateControlArgs(locked) {
   const preset = getEncoderPreset5(locked.quality ?? "standard", "mp4");
   if (locked.crf == null && locked.bitrate) {
@@ -9422,8 +9718,8 @@ async function assemble(planDir, chunkPaths, audioPath, outputPath, options) {
   }
   const format = plan2.dimensions.format;
   const cfrEncoder = cfr ? readCfrEncoder(planDir, format) : null;
-  if (!existsSync17(dirname12(outputPath))) {
-    mkdirSync12(dirname12(outputPath), { recursive: true });
+  if (!existsSync18(dirname12(outputPath))) {
+    mkdirSync13(dirname12(outputPath), { recursive: true });
   }
   const workDir = mkdtempSync6(`${outputPath}.assemble-work-`);
   const fps = { num: plan2.dimensions.fpsNum, den: plan2.dimensions.fpsDen };
@@ -9445,8 +9741,8 @@ async function assemble(planDir, chunkPaths, audioPath, outputPath, options) {
   };
   try {
     const videoSources = cfrEncoder ? [await reencodeCfr(ctx, chunkPaths, cfrEncoder)] : chunkPaths;
-    const finalPath = join25(workDir, `output.${format}`);
-    const audio = audioPath !== null && existsSync17(audioPath) ? audioPath : null;
+    const finalPath = join26(workDir, `output.${format}`);
+    const audio = audioPath !== null && existsSync18(audioPath) ? audioPath : null;
     await writeJoined(ctx, videoSources, audio, finalPath);
     renameSync7(finalPath, outputPath);
     log.info("[assemble] stage timings", {
@@ -9464,7 +9760,7 @@ async function assemble(planDir, chunkPaths, audioPath, outputPath, options) {
       });
     }
   }
-  const fileSize = existsSync17(outputPath) ? statSync7(outputPath).size : 0;
+  const fileSize = existsSync18(outputPath) ? statSync7(outputPath).size : 0;
   return {
     outputPath,
     durationMs: Date.now() - start,
@@ -9473,25 +9769,25 @@ async function assemble(planDir, chunkPaths, audioPath, outputPath, options) {
   };
 }
 function readAssemblePlan(planDir, chunkPaths) {
-  const planJsonPath = join25(planDir, "plan.json");
-  const chunksJsonPath = join25(planDir, "meta", "chunks.json");
-  if (!existsSync17(planJsonPath)) {
+  const planJsonPath = join26(planDir, "plan.json");
+  const chunksJsonPath = join26(planDir, "meta", "chunks.json");
+  if (!existsSync18(planJsonPath)) {
     throw new Error(`[assemble] planDir missing plan.json: ${planJsonPath}`);
   }
-  const plan2 = JSON.parse(readFileSync10(planJsonPath, "utf-8"));
+  const plan2 = JSON.parse(readFileSync11(planJsonPath, "utf-8"));
   readPlanProtocolV1(plan2, DISTRIBUTED_RENDER_CAPABILITIES.roles.assembler);
   validatePlanV2MaterializedTarget(planDir, { role: "assembler" });
-  if (!existsSync17(chunksJsonPath)) {
+  if (!existsSync18(chunksJsonPath)) {
     throw new Error(`[assemble] planDir missing meta/chunks.json: ${chunksJsonPath}`);
   }
-  const chunks = JSON.parse(readFileSync10(chunksJsonPath, "utf-8"));
+  const chunks = JSON.parse(readFileSync11(chunksJsonPath, "utf-8"));
   if (chunkPaths.length !== chunks.length) {
     throw new Error(
       `[assemble] chunkPaths length (${chunkPaths.length}) does not match chunks.json length (${chunks.length}). Adapters must pass one path per chunk, ordered by index.`
     );
   }
   for (const path of chunkPaths) {
-    if (!existsSync17(path)) {
+    if (!existsSync18(path)) {
       throw new Error(`[assemble] chunk path does not exist: ${path}`);
     }
   }
@@ -9501,7 +9797,7 @@ function videoInputArgs(ctx, videoSources) {
   return videoSources.length === 1 ? ["-i", videoSources[0]] : concatDemuxerInput(videoSources, ctx.workDir, ctx.fpsArg);
 }
 async function reencodeCfr(ctx, chunkPaths, encoder) {
-  const cfrOutputPath = join25(ctx.workDir, `cfr.${ctx.format}`);
+  const cfrOutputPath = join26(ctx.workDir, `cfr.${ctx.format}`);
   const cfrArgs = [
     ...videoInputArgs(ctx, chunkPaths),
     "-c:v",
@@ -9514,7 +9810,7 @@ async function reencodeCfr(ctx, chunkPaths, encoder) {
     "-r",
     ctx.fpsArg
   ];
-  appendRenderProvenanceArgs(cfrArgs, cfrOutputPath);
+  appendRenderProvenanceArgs2(cfrArgs, cfrOutputPath);
   cfrArgs.push("-y", cfrOutputPath);
   await ctx.timed(
     "cfrMs",
@@ -9531,7 +9827,7 @@ async function writeJoined(ctx, videoSources, audioPath, finalPath) {
   if (audioPath === null) {
     const joinArgs = [...videoInputArgs(ctx, videoSources), "-c", "copy"];
     if (ctx.format === "mp4") joinArgs.push("-movflags", "+faststart");
-    appendRenderProvenanceArgs(joinArgs, finalPath);
+    appendRenderProvenanceArgs2(joinArgs, finalPath);
     joinArgs.push("-r", ctx.fpsArg, "-y", finalPath);
     await ctx.timed(
       "joinMs",
@@ -9539,7 +9835,7 @@ async function writeJoined(ctx, videoSources, audioPath, finalPath) {
     );
     return;
   }
-  const paddedAudioPath = join25(ctx.workDir, "audio-padded.m4a");
+  const paddedAudioPath = join26(ctx.workDir, "audio-padded.m4a");
   const padTrimResult = await ctx.timed(
     "audioMs",
     () => padOrTrimAudioToVideoFrameCount({
@@ -9579,9 +9875,9 @@ async function writeJoined(ctx, videoSources, audioPath, finalPath) {
   }
 }
 function concatDemuxerInput(chunkPaths, workDir, fpsArg) {
-  const listPath = join25(workDir, "concat-list.txt");
+  const listPath = join26(workDir, "concat-list.txt");
   const body = chunkPaths.map((path) => `file '${path.replace(/'/g, "'\\''")}'`).join("\n");
-  writeFileSync8(listPath, `${body}
+  writeFileSync9(listPath, `${body}
 `, "utf-8");
   return ["-r", fpsArg, "-f", "concat", "-safe", "0", "-i", listPath];
 }
@@ -9596,10 +9892,10 @@ async function probeJoinedFrameInfo(videoPaths, fps, signal) {
   };
 }
 async function runAssembleFfmpeg(args, step, signal, timeout) {
-  const result = await runFfmpeg5(args, { signal, timeout });
+  const result = await runFfmpeg6(args, { signal, timeout });
   if (!result.success) {
     throw encoderFailureError(`[assemble] ffmpeg ${step} failed`, {
-      error: describeFfmpegFailure2(result, timeout),
+      error: describeFfmpegFailure3(result, timeout),
       failureReason: result.failureReason
     });
   }
@@ -9612,9 +9908,9 @@ function chunksAreStitchedMp4(planDir, cfr) {
   return true;
 }
 function chunksCarryAudio(planDir) {
-  const encoderJsonPath = join25(planDir, "meta", "encoder.json");
-  if (!existsSync17(encoderJsonPath)) return false;
-  return JSON.parse(readFileSync10(encoderJsonPath, "utf-8")).chunksCarryAudio === true;
+  const encoderJsonPath = join26(planDir, "meta", "encoder.json");
+  if (!existsSync18(encoderJsonPath)) return false;
+  return JSON.parse(readFileSync11(encoderJsonPath, "utf-8")).chunksCarryAudio === true;
 }
 function readCfrEncoder(planDir, format) {
   if (format !== "mp4") {
@@ -9622,11 +9918,11 @@ function readCfrEncoder(planDir, format) {
       `[assemble] cfr=true is only supported for format="mp4" (got "${format}"). Stream-copy paths for webm and mov already produce exact avg_frame_rate; cfr re-encode is not needed.`
     );
   }
-  const encoderJsonPath = join25(planDir, "meta", "encoder.json");
-  if (!existsSync17(encoderJsonPath)) {
+  const encoderJsonPath = join26(planDir, "meta", "encoder.json");
+  if (!existsSync18(encoderJsonPath)) {
     throw new Error(`[assemble] planDir missing meta/encoder.json: ${encoderJsonPath}`);
   }
-  const encoderJson = JSON.parse(readFileSync10(encoderJsonPath, "utf-8"));
+  const encoderJson = JSON.parse(readFileSync11(encoderJsonPath, "utf-8"));
   if (encoderJson.encoder === "libx265-software") {
     throw new Error(
       `[assemble] cfr=true is not yet supported with codec: "h265". The cfr re-encode pass uses libx264 and would silently transcode the h265 chunks. Either disable cfr or render with codec: "h264".`
@@ -9635,8 +9931,8 @@ function readCfrEncoder(planDir, format) {
   return encoderJson;
 }
 function mergePngFrameDirs(chunkPaths, outputPath, totalFrames, audioPath, startTimeMs) {
-  if (existsSync17(outputPath)) rmSync11(outputPath, { recursive: true, force: true });
-  mkdirSync12(outputPath, { recursive: true });
+  if (existsSync18(outputPath)) rmSync11(outputPath, { recursive: true, force: true });
+  mkdirSync13(outputPath, { recursive: true });
   let globalIdx = 0;
   for (const chunkDir of chunkPaths) {
     if (!statSync7(chunkDir).isDirectory()) {
@@ -9649,8 +9945,8 @@ function mergePngFrameDirs(chunkPaths, outputPath, totalFrames, audioPath, start
       throw new Error(`[assemble] png-sequence chunk has no frames: ${chunkDir}`);
     }
     for (const frame of frames) {
-      const dst = join25(outputPath, formatExportFrameName(globalIdx, "png"));
-      cpSync3(join25(chunkDir, frame), dst);
+      const dst = join26(outputPath, formatExportFrameName(globalIdx, "png"));
+      cpSync3(join26(chunkDir, frame), dst);
       globalIdx += 1;
     }
   }
@@ -9659,14 +9955,14 @@ function mergePngFrameDirs(chunkPaths, outputPath, totalFrames, audioPath, start
       `[assemble] png-sequence frame count mismatch: merged ${globalIdx} frames vs plan.totalFrames=${totalFrames}. Using on-disk count.`
     );
   }
-  if (audioPath !== null && existsSync17(audioPath)) {
-    const sidecar = join25(outputPath, MIXED_AUDIO_FILENAME4);
+  if (audioPath !== null && existsSync18(audioPath)) {
+    const sidecar = join26(outputPath, MIXED_AUDIO_FILENAME4);
     cpSync3(audioPath, sidecar);
   }
   let fileSize = 0;
   for (const name of readdirSync8(outputPath)) {
     try {
-      fileSize += statSync7(join25(outputPath, name)).size;
+      fileSize += statSync7(join26(outputPath, name)).size;
     } catch {
     }
   }
@@ -9680,8 +9976,8 @@ function mergePngFrameDirs(chunkPaths, outputPath, totalFrames, audioPath, start
 
 // src/services/distributed/renderChunk.ts
 import { randomBytes } from "node:crypto";
-import { existsSync as existsSync18, mkdirSync as mkdirSync13, readFileSync as readFileSync11, readdirSync as readdirSync9, rmSync as rmSync12, writeFileSync as writeFileSync9 } from "node:fs";
-import { join as join26 } from "node:path";
+import { existsSync as existsSync19, mkdirSync as mkdirSync14, readFileSync as readFileSync12, readdirSync as readdirSync9, rmSync as rmSync12, writeFileSync as writeFileSync10 } from "node:fs";
+import { join as join27 } from "node:path";
 import {
   assertSwiftShader,
   BROWSER_GPU_NOT_SOFTWARE as BROWSER_GPU_NOT_SOFTWARE4,
@@ -9697,104 +9993,6 @@ import {
   readWebGlVendorInfoFromCanvas,
   resolveConfig as resolveConfig5
 } from "@hyperframes/engine";
-
-// src/services/distributed/chunkAudio.ts
-import { appendRenderProvenanceArgs as appendRenderProvenanceArgs2, describeFfmpegFailure as describeFfmpegFailure3, runFfmpeg as runFfmpeg6 } from "@hyperframes/engine";
-function audioCutForChunk(grid, chunks, index, fps) {
-  const firstPacketAt = (frame) => Math.min(
-    grid.packetCount,
-    Math.max(
-      0,
-      Math.ceil(
-        (frame * fps.den * grid.sampleRate - grid.firstStart * fps.num) / (grid.packetSamples * fps.num)
-      )
-    )
-  );
-  const first = index === 0 ? 0 : firstPacketAt(chunks[index].startFrame);
-  const end = index === chunks.length - 1 ? grid.packetCount : firstPacketAt(chunks[index + 1].startFrame);
-  if (end <= first) return null;
-  const cutSeconds = (packet) => (grid.firstStart + packet * grid.packetSamples - grid.packetSamples / 2) / grid.sampleRate;
-  const seekSeconds = index === 0 ? null : cutSeconds(first);
-  const durationSeconds = end === grid.packetCount ? null : cutSeconds(end) - (seekSeconds ?? 0);
-  return { seekSeconds, durationSeconds, firstPacket: first, packetCount: end - first };
-}
-async function probeAacPacketGrid(audioPath) {
-  const probe = await runFfprobeJson([
-    "-v",
-    "error",
-    "-select_streams",
-    "a:0",
-    "-show_entries",
-    "stream=sample_rate,time_base,nb_frames:packet=pts,duration",
-    "-read_intervals",
-    "%+#1",
-    "-of",
-    "json",
-    "--",
-    audioPath
-  ]);
-  const stream = probe.streams?.[0] ?? {};
-  const packet = probe.packets?.[0] ?? {};
-  const sampleRate = Number(stream.sample_rate);
-  const [tbNum = NaN, tbDen = NaN] = String(stream.time_base).split("/").map(Number);
-  const toSamples = (ticks) => Number(ticks) * sampleRate * tbNum / tbDen;
-  const grid = {
-    sampleRate,
-    firstStart: toSamples(packet.pts),
-    packetSamples: toSamples(packet.duration),
-    packetCount: Number(stream.nb_frames)
-  };
-  const counts = [grid.sampleRate, grid.packetSamples, grid.packetCount];
-  if (!Number.isFinite(grid.firstStart) || !counts.every((n) => Number.isFinite(n) && n > 0)) {
-    throw new Error(`[chunkAudio] could not read the AAC packet grid: ${JSON.stringify(probe)}`);
-  }
-  return grid;
-}
-function chunkMuxArgs(input, cut) {
-  if (!cut) return ["-i", input.videoPath, "-map", "0:v:0"];
-  const seek = cut.seekSeconds === null ? [] : ["-ss", cut.seekSeconds.toFixed(6)];
-  const length = cut.durationSeconds === null ? [] : ["-t", cut.durationSeconds.toFixed(6)];
-  const exact = seek.length ? ["-copypriorss", "0"] : [];
-  return [
-    ...["-i", input.videoPath, ...seek, ...length, "-i", input.audioPath],
-    ...["-map", "0:v:0", "-map", "1:a:0", ...exact]
-  ];
-}
-async function muxChunkWithAudio(input) {
-  const grid = input.audioPath ? await probeAacPacketGrid(input.audioPath) : null;
-  const cut = grid ? audioCutForChunk(grid, input.chunks, input.chunkIndex, input.fps) : null;
-  const args = [...chunkMuxArgs(input, cut), "-c", "copy"];
-  appendRenderProvenanceArgs2(args, input.outputPath);
-  args.push("-y", input.outputPath);
-  const result = await runFfmpeg6(args, { signal: input.signal, timeout: input.timeoutMs });
-  if (!result.success) {
-    throw new Error(
-      `[chunkAudio] chunk mux failed: ${describeFfmpegFailure3(result, input.timeoutMs)}`
-    );
-  }
-  const slice = input.chunks[input.chunkIndex];
-  const expected = { video: slice.endFrame - slice.startFrame };
-  if (cut) expected.audio = cut.packetCount;
-  const probe = await runFfprobeJson([
-    "-v",
-    "error",
-    "-count_packets",
-    "-show_entries",
-    "stream=codec_type,nb_read_packets",
-    "-of",
-    "json",
-    "--",
-    input.outputPath
-  ]);
-  for (const [type, count] of Object.entries(expected)) {
-    const packets = Number(probe.streams?.find((s) => s.codec_type === type)?.nb_read_packets ?? 0);
-    if (packets !== count) {
-      throw new Error(`[chunkAudio] ${type} packets in chunk ${packets}, expected ${count}`);
-    }
-  }
-}
-
-// src/services/distributed/renderChunk.ts
 import { readWebGlVendorInfoFromCanvas as readWebGlVendorInfoFromCanvas2 } from "@hyperframes/engine";
 var LEGACY_DISTRIBUTED_VP9_CPU_USED = 2;
 function validatePlanVideosForChunk(value) {
@@ -9860,10 +10058,10 @@ async function beginFrameSessionNeedsScreenshotFallback(session, probe = probeBe
   return !await probe(session.page, timeoutMs, probeTick, session.beginFrameIntervalMs);
 }
 function hashChunkOutput(outputPath, kind) {
-  if (kind === "file") return sha256Hex(readFileSync11(outputPath));
+  if (kind === "file") return sha256Hex(readFileSync12(outputPath));
   const entries = readdirSync9(outputPath).filter((name) => /\.(png|jpg|jpeg)$/i.test(name)).sort();
   const lines = entries.map(
-    (name) => `${name}\0${sha256Hex(readFileSync11(join26(outputPath, name)))}`
+    (name) => `${name}\0${sha256Hex(readFileSync12(join27(outputPath, name)))}`
   );
   return sha256Hex(lines.join("\0"));
 }
@@ -9880,37 +10078,39 @@ function resolveLockedVp9CpuUsed(lockedEncoder) {
 async function renderChunk(planDir, chunkIndex, outputChunkPath) {
   const start = Date.now();
   const log = defaultLogger;
-  const planJsonPath = join26(planDir, "plan.json");
-  const encoderJsonPath = join26(planDir, "meta", "encoder.json");
-  const chunksJsonPath = join26(planDir, "meta", "chunks.json");
-  if (!existsSync18(planJsonPath)) {
+  const planJsonPath = join27(planDir, "plan.json");
+  const encoderJsonPath = join27(planDir, "meta", "encoder.json");
+  const chunksJsonPath = join27(planDir, "meta", "chunks.json");
+  if (!existsSync19(planJsonPath)) {
     throw new RenderChunkValidationError(
       MISSING_PLAN_ARTIFACT,
       `[renderChunk] planDir is missing required artifact: ${planJsonPath}`
     );
   }
-  const plan2 = JSON.parse(readFileSync11(planJsonPath, "utf-8"));
+  const plan2 = JSON.parse(readFileSync12(planJsonPath, "utf-8"));
   readPlanProtocolV1(plan2, DISTRIBUTED_RENDER_CAPABILITIES.roles.chunk);
   const planHashStarted = Date.now();
-  const v2Manifest = validatePlanV2MaterializedTarget(planDir, {
+  const v2Materialization = readValidatedPlanV2Materialization(planDir, {
     role: "chunk",
     chunkIndex
   });
+  const v2Manifest = v2Materialization?.manifest ?? null;
+  const remoteSources = v2Materialization?.remoteSources ?? {};
   for (const required of [encoderJsonPath, chunksJsonPath]) {
-    if (!existsSync18(required)) {
+    if (!existsSync19(required)) {
       throw new RenderChunkValidationError(
         MISSING_PLAN_ARTIFACT,
         `[renderChunk] planDir is missing required artifact: ${required}`
       );
     }
   }
-  const encoder = JSON.parse(readFileSync11(encoderJsonPath, "utf-8"));
-  const chunks = JSON.parse(readFileSync11(chunksJsonPath, "utf-8"));
-  const videosJsonPath = join26(planDir, PLAN_VIDEOS_META_RELATIVE_PATH);
+  const encoder = JSON.parse(readFileSync12(encoderJsonPath, "utf-8"));
+  const chunks = JSON.parse(readFileSync12(chunksJsonPath, "utf-8"));
+  const videosJsonPath = join27(planDir, PLAN_VIDEOS_META_RELATIVE_PATH);
   let planVideos = null;
-  if (existsSync18(videosJsonPath)) {
+  if (existsSync19(videosJsonPath)) {
     try {
-      planVideos = validatePlanVideosForChunk(JSON.parse(readFileSync11(videosJsonPath, "utf-8")));
+      planVideos = validatePlanVideosForChunk(JSON.parse(readFileSync12(videosJsonPath, "utf-8")));
     } catch (err) {
       if (err instanceof RenderChunkValidationError) throw err;
       throw new RenderChunkValidationError(
@@ -9936,8 +10136,8 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath) {
       `[renderChunk] chunk ${chunkIndex} has non-positive frame count: ${framesInChunk}`
     );
   }
-  const compiledDir = join26(planDir, "compiled");
-  if (!existsSync18(compiledDir)) {
+  const compiledDir = join27(planDir, "compiled");
+  if (!existsSync19(compiledDir)) {
     throw new RenderChunkValidationError(
       MISSING_PLAN_ARTIFACT,
       `[renderChunk] planDir missing compiled/ directory: ${compiledDir}`
@@ -9993,10 +10193,28 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath) {
       forceScreenshotExplicitlyOptedOut: !encoder.forceScreenshot
     };
     const workDir = `${outputChunkPath}.work.${process.pid}.${randomBytes(4).toString("hex")}`;
-    mkdirSync13(workDir, { recursive: true });
-    const framesDir = join26(workDir, "captured-frames");
-    mkdirSync13(framesDir, { recursive: true });
+    mkdirSync14(workDir, { recursive: true });
+    const framesDir = join27(workDir, "captured-frames");
+    mkdirSync14(framesDir, { recursive: true });
     const videoFramesDir = `${workDir}.video-frames`;
+    const deferredVideoFrames = planVideos ? await extractDeferredVideoFramesForChunk({
+      planDir,
+      planVideos,
+      frames: Array.from(
+        { length: slice.endFrame - slice.startFrame },
+        (_, i) => slice.startFrame + i
+      ),
+      fps: { num: plan2.dimensions.fpsNum, den: plan2.dimensions.fpsDen },
+      outputRoot: videoFramesDir,
+      cfg,
+      remoteSources
+    }) : [];
+    const remoteVideoIds = new Set(
+      planVideos?.extracted.filter(
+        (video) => video.deferredRange && Object.hasOwn(remoteSources, video.deferredRange.sourcePath)
+      ).map((video) => video.videoId)
+    );
+    const remoteVideos = deferredVideoFrames.filter((video) => remoteVideoIds.has(video.videoId));
     const videoFrameLookup = planVideos && planVideos.extracted.length > 0 ? createFrameLookupTable5(
       planVideos.videos,
       [
@@ -10005,17 +10223,7 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath) {
           planVideos.extracted.filter((video) => !video.deferredRange),
           v2Manifest === null ? "dense-v1" : "sparse-v2"
         ),
-        ...await extractDeferredVideoFramesForChunk({
-          planDir,
-          planVideos,
-          frames: Array.from(
-            { length: slice.endFrame - slice.startFrame },
-            (_, i) => slice.startFrame + i
-          ),
-          fps: { num: plan2.dimensions.fpsNum, den: plan2.dimensions.fpsDen },
-          outputRoot: videoFramesDir,
-          cfg
-        })
+        ...deferredVideoFrames
       ],
       resolveRenderFpsConfig(job.config.fps).value
     ) : null;
@@ -10033,7 +10241,10 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath) {
       dimensions: plan2.dimensions,
       encoder,
       videoCount: planVideos?.videos.length ?? 0,
-      html: readFileSync11(join26(compiledDir, "index.html"), "utf-8")
+      html: readFileSync12(join27(compiledDir, "index.html"), "utf-8"),
+      // The plan ships a deferred source only to chunks that show it; don't wait on the rest.
+      skipReadinessVideoIds: deferredVideoFrames.filter((video) => video.framePaths.size === 0 || remoteVideoIds.has(video.videoId)).map((video) => video.videoId),
+      videoMetadataHints: collectVideoMetadataHints(remoteVideos)
     });
     const chunkWorkerCount = calculateOptimalWorkers2(framesInChunk, void 0, cfg);
     let session = null;
@@ -10164,7 +10375,7 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath) {
         },
         resetForScreenshotRetry: () => {
           rmSync12(workDir, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
-          mkdirSync13(framesDir, { recursive: true });
+          mkdirSync14(framesDir, { recursive: true });
           capturePerfs.length = 0;
           captureAttempts.length = 0;
           job.framesRendered = 0;
@@ -10195,10 +10406,10 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath) {
       const effectiveBitrate = encoder.crf != null ? void 0 : encoder.bitrate;
       const videoOnlyPath = encoder.chunksCarryAudio ? `${outputChunkPath}.video.mp4` : outputChunkPath;
       if (isPngSequence) {
-        if (!existsSync18(outputChunkPath)) mkdirSync13(outputChunkPath, { recursive: true });
+        if (!existsSync19(outputChunkPath)) mkdirSync14(outputChunkPath, { recursive: true });
       } else {
-        const outDir = join26(outputChunkPath, "..");
-        if (!existsSync18(outDir)) mkdirSync13(outDir, { recursive: true });
+        const outDir = join27(outputChunkPath, "..");
+        if (!existsSync19(outDir)) mkdirSync14(outDir, { recursive: true });
       }
       const encodeStarted = Date.now();
       await runEncodeStage({
@@ -10241,9 +10452,10 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath) {
         gopSize: framesInChunk
       });
       if (encoder.chunksCarryAudio) {
+        const audioScratchPath = `${outputChunkPath}.audio.m4a`;
         await muxChunkWithAudio({
           videoPath: videoOnlyPath,
-          audioPath: resolvePlanAudioPath(planDir),
+          audioPath: chunkAudioSource(planDir, chunkIndex, audioScratchPath),
           outputPath: outputChunkPath,
           chunks,
           chunkIndex,
@@ -10251,6 +10463,7 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath) {
           timeoutMs: cfg.ffmpegProcessTimeout
         });
         rmSync12(videoOnlyPath, { force: true });
+        rmSync12(audioScratchPath, { force: true });
       }
       encodeStageMs = Date.now() - encodeStarted;
     } finally {
@@ -10289,7 +10502,7 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath) {
       producerVersion: plan2.producerVersion,
       ffmpegVersion
     };
-    writeFileSync9(perfPath, `${JSON.stringify(perfPayload, null, 2)}
+    writeFileSync10(perfPath, `${JSON.stringify(perfPayload, null, 2)}
 `, "utf-8");
     try {
       rmSync12(workDir, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
@@ -10321,8 +10534,8 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath) {
 
 // src/services/distributed/planV2Execution.ts
 async function renderChunkV2(planV2Dir, chunkIndex, outputChunkPath) {
-  const workRoot = mkdtempSync7(join27(tmpdir2(), "hf-plan-v2-chunk-"));
-  const materializedPlanDir = join27(workRoot, "plan");
+  const workRoot = mkdtempSync7(join28(tmpdir2(), "hf-plan-v2-chunk-"));
+  const materializedPlanDir = join28(workRoot, "plan");
   try {
     materializePlanV2Target(planV2Dir, { role: "chunk", chunkIndex }, materializedPlanDir);
     return await renderChunk(materializedPlanDir, chunkIndex, outputChunkPath);
@@ -10331,8 +10544,8 @@ async function renderChunkV2(planV2Dir, chunkIndex, outputChunkPath) {
   }
 }
 async function assembleV2(planV2Dir, chunkPaths, outputPath, options) {
-  const workRoot = mkdtempSync7(join27(tmpdir2(), "hf-plan-v2-assembler-"));
-  const materializedPlanDir = join27(workRoot, "plan");
+  const workRoot = mkdtempSync7(join28(tmpdir2(), "hf-plan-v2-assembler-"));
+  const materializedPlanDir = join28(workRoot, "plan");
   try {
     const materialized = materializePlanV2Target(
       planV2Dir,
@@ -10594,28 +10807,46 @@ function validateIntDimension(field, value) {
 }
 
 // src/services/distributed/projectHash.ts
-import { readdirSync as readdirSync10, readFileSync as readFileSync12 } from "node:fs";
+import { readdirSync as readdirSync10, readFileSync as readFileSync13, realpathSync as realpathSync2, statSync as statSync8 } from "node:fs";
 import { createHash as createHash6 } from "node:crypto";
-import { join as join28, relative as relative7 } from "node:path";
-function hashProjectDir(projectDir) {
-  const hash = createHash6("sha256");
+import { join as join29 } from "node:path";
+var SITE_ID_SCHEME = "site-v2\0";
+function listSiteFiles(projectDir) {
   const files = [];
-  function walk(dir, isRoot) {
-    for (const entry of readdirSync10(dir, { withFileTypes: true }).sort(
-      (a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0
-    )) {
-      if (isRoot && PLAN_PROJECT_DIR_SKIP_SEGMENTS.has(entry.name)) continue;
-      const full = join28(dir, entry.name);
-      if (entry.isDirectory()) walk(full, false);
-      else if (entry.isFile()) files.push(full);
+  const ancestors = /* @__PURE__ */ new Set([realpathSync2(projectDir)]);
+  function walk(dir, rel) {
+    for (const name of readdirSync10(dir).sort()) {
+      if (rel === "" && PLAN_PROJECT_DIR_SKIP_SEGMENTS.has(name)) continue;
+      const full = join29(dir, name);
+      const relPath = rel === "" ? name : `${rel}/${name}`;
+      let stat;
+      try {
+        stat = statSync8(full);
+      } catch (err) {
+        throw new Error(`[listSiteFiles] cannot read ${relPath} (dangling symlink?)`, {
+          cause: err
+        });
+      }
+      if (stat.isFile()) {
+        files.push(relPath);
+      } else if (stat.isDirectory()) {
+        const real = realpathSync2(full);
+        if (ancestors.has(real)) continue;
+        ancestors.add(real);
+        walk(full, relPath);
+        ancestors.delete(real);
+      }
     }
   }
-  walk(projectDir, true);
-  for (const file of files) {
-    const rel = relative7(projectDir, file).replaceAll("\\", "/");
+  walk(projectDir, "");
+  return files;
+}
+function hashProjectDir(projectDir, files = listSiteFiles(projectDir)) {
+  const hash = createHash6("sha256").update(SITE_ID_SCHEME);
+  for (const rel of files) {
     hash.update(rel);
     hash.update("\0");
-    hash.update(readFileSync12(file));
+    hash.update(readFileSync13(join29(projectDir, rel)));
   }
   return hash.digest("hex").slice(0, 16);
 }
@@ -10670,7 +10901,9 @@ export {
   getPlanV2ExecutionPlanHash,
   hashProjectDir,
   isPlanAudioArtifactPath,
+  isPlanV2DeferredSourceArtifact,
   listPlanV2ArtifactsForTarget,
+  listSiteFiles,
   materializePlanV2Target,
   measurePlanDirBytes,
   muxChunkWithAudio,