@hyperframes/gcp-cloud-run 0.7.71 → 0.7.73

package/dist/server.js

@@ -1,14 +1,18 @@
 // src/server.ts
-import { existsSync as existsSync3, mkdirSync as mkdirSync2, mkdtempSync, readFileSync, rmSync as rmSync2, statSync as statSync2 } from "node:fs";
-import { tmpdir } from "node:os";
-import { basename, extname, join } from "node:path";
+import { existsSync as existsSync3, mkdirSync as mkdirSync3, mkdtempSync as mkdtempSync2, readFileSync, rmSync as rmSync3, statSync as statSync3 } from "node:fs";
+import { tmpdir as tmpdir2 } from "node:os";
+import { basename, extname, join as join2 } from "node:path";
 import { fileURLToPath } from "node:url";
 import { serve } from "@hono/node-server";
 import { Storage } from "@google-cloud/storage";
 import { Hono } from "hono";
 import {
   assemble,
+  listPlanV2ArtifactsForTarget,
+  materializePlanV2Target,
   plan,
+  planV2WithPublisher,
+  readPlanV2Manifest,
   renderChunk
 } from "@hyperframes/producer/distributed";
 
@@ -74,7 +78,15 @@ function formatExtension(format) {
 }
 
 // src/gcsTransport.ts
-import { createWriteStream, existsSync as existsSync2, mkdirSync, rmSync, statSync } from "node:fs";
+import {
+  createReadStream,
+  createWriteStream,
+  existsSync as existsSync2,
+  mkdirSync,
+  rmSync,
+  statSync
+} from "node:fs";
+import { createHash } from "node:crypto";
 import { dirname } from "node:path";
 import { pipeline } from "node:stream/promises";
 import * as tar from "tar";
@@ -100,6 +112,19 @@ async function downloadGcsObjectToFile(storage, uri, destPath) {
   const file = storage.bucket(bucket).file(key);
   await pipeline(file.createReadStream(), createWriteStream(destPath));
 }
+async function downloadGcsObjectToFileVerified(storage, uri, destPath, expectedSha256) {
+  assertSha256(expectedSha256);
+  await downloadGcsObjectToFile(storage, uri, destPath);
+  const actual = await sha256File(destPath);
+  if (actual !== expectedSha256) {
+    rmSync(destPath, { force: true });
+    const error = new Error(
+      `[gcsTransport] PLAN_ARTIFACT_DIGEST_MISMATCH: ${uri} expected ${expectedSha256}, got ${actual}`
+    );
+    error.name = "PLAN_ARTIFACT_DIGEST_MISMATCH";
+    throw error;
+  }
+}
 async function uploadFileToGcs(storage, localPath, uri, contentType) {
   if (!existsSync2(localPath)) {
     throw new Error(`[gcsTransport] upload source missing: ${localPath}`);
@@ -114,6 +139,73 @@ async function uploadFileToGcs(storage, localPath, uri, contentType) {
     contentType
   });
 }
+async function uploadContentAddressedFileToGcs(storage, localPath, uri, expectedSha256, contentType) {
+  assertSha256(expectedSha256);
+  if (!existsSync2(localPath)) {
+    throw new Error(`[gcsTransport] upload source missing: ${localPath}`);
+  }
+  const actualSha256 = await sha256File(localPath);
+  if (actualSha256 !== expectedSha256) {
+    throwDigestMismatch(
+      `local artifact ${localPath} expected ${expectedSha256}, got ${actualSha256}`
+    );
+  }
+  const { bucket, key } = parseGcsUri(uri);
+  const bucketHandle = storage.bucket(bucket);
+  const file = bucketHandle.file(key);
+  const size = statSync(localPath).size;
+  if (await isReusableContentAddressedObject(file, uri, size, expectedSha256)) {
+    return "reused";
+  }
+  try {
+    await bucketHandle.upload(localPath, {
+      destination: key,
+      contentType,
+      metadata: { metadata: { sha256: expectedSha256 } },
+      preconditionOpts: { ifGenerationMatch: 0 }
+    });
+    return "uploaded";
+  } catch (error) {
+    if (isGcsPreconditionFailed(error) && await isReusableContentAddressedObject(file, uri, size, expectedSha256)) {
+      return "reused";
+    }
+    throw error;
+  }
+}
+async function isReusableContentAddressedObject(file, uri, expectedSize, expectedSha256) {
+  const [exists] = await file.exists();
+  if (!exists) return false;
+  const [metadata] = await file.getMetadata();
+  if (Number(metadata.size) === expectedSize && metadata.metadata?.sha256 === expectedSha256) {
+    return true;
+  }
+  throwDigestMismatch(
+    `immutable object ${uri} already exists with different digest metadata or size`
+  );
+}
+async function sha256File(path) {
+  const hash = createHash("sha256");
+  for await (const chunk of createReadStream(path)) {
+    hash.update(chunk);
+  }
+  return hash.digest("hex");
+}
+function assertSha256(value) {
+  if (!/^[a-f0-9]{64}$/.test(value)) {
+    throw new Error(
+      `[gcsTransport] expected lowercase SHA-256 digest, got ${JSON.stringify(value)}`
+    );
+  }
+}
+function throwDigestMismatch(detail) {
+  const error = new Error(`[gcsTransport] PLAN_ARTIFACT_DIGEST_MISMATCH: ${detail}`);
+  error.name = "PLAN_ARTIFACT_DIGEST_MISMATCH";
+  throw error;
+}
+function isGcsPreconditionFailed(error) {
+  if (!error || typeof error !== "object") return false;
+  return error.code === 412;
+}
 async function tarDirectory(sourceDir, destTarball) {
   if (!existsSync2(sourceDir) || !statSync(sourceDir).isDirectory()) {
     throw new Error(`[gcsTransport] tar source must be an existing directory: ${sourceDir}`);
@@ -132,6 +224,112 @@ async function untarDirectory(tarballPath, destDir) {
   await tar.extract({ file: tarballPath, cwd: destDir });
 }
 
+// src/gcsPlanV2Publisher.ts
+import { createHash as createHash2 } from "node:crypto";
+import { mkdirSync as mkdirSync2, mkdtempSync, rmSync as rmSync2, statSync as statSync2, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  PlanV2IntegrityError
+} from "@hyperframes/producer/distributed";
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function assertSha2562(value, label) {
+  if (typeof value !== "string" || !/^[a-f0-9]{64}$/.test(value)) {
+    throw new PlanV2IntegrityError(`${label} must be a lowercase SHA-256 digest`);
+  }
+  return value;
+}
+function manifestDigests(manifestBytes) {
+  let value;
+  try {
+    value = JSON.parse(manifestBytes);
+  } catch {
+    throw new PlanV2IntegrityError("GCS publisher received invalid manifest JSON");
+  }
+  if (!isRecord(value) || !Array.isArray(value.artifacts)) {
+    throw new PlanV2IntegrityError("GCS publisher manifest requires an artifacts array");
+  }
+  return new Set(
+    value.artifacts.map((artifact, index) => {
+      if (!isRecord(artifact)) {
+        throw new PlanV2IntegrityError(`GCS publisher artifacts[${index}] must be an object`);
+      }
+      return assertSha2562(artifact.sha256, `GCS publisher artifacts[${index}].sha256`);
+    })
+  );
+}
+function trimTrailingSlash(value) {
+  let end = value.length;
+  while (end > 0 && value.charCodeAt(end - 1) === 47) end -= 1;
+  return value.slice(0, end);
+}
+var GcsPlanV2ArtifactPublisher = class {
+  artifactPrefix;
+  manifestUri;
+  #storage;
+  #temporaryRoot;
+  #publishedDigests = /* @__PURE__ */ new Set();
+  #state = "open";
+  constructor(options) {
+    const outputPrefix = `${trimTrailingSlash(options.planOutputGcsPrefix)}/v2`;
+    parseGcsUri(outputPrefix);
+    this.#storage = options.storage;
+    this.artifactPrefix = `${outputPrefix}/artifacts/sha256`;
+    this.manifestUri = `${outputPrefix}/manifest.json`;
+    this.#temporaryRoot = options.temporaryRoot ?? tmpdir();
+    mkdirSync2(this.#temporaryRoot, { recursive: true });
+  }
+  async putBlob(blob) {
+    this.#assertOpen("publish a blob");
+    const digest = assertSha2562(blob.sha256, "GCS published blob sha256");
+    const sourceSize = statSync2(blob.sourcePath).size;
+    if (sourceSize !== blob.sizeBytes) {
+      throw new PlanV2IntegrityError(
+        `GCS published blob size changed for ${digest}: expected ${blob.sizeBytes}, got ${sourceSize}`
+      );
+    }
+    const uri = `${this.artifactPrefix}/${digest.slice(0, 2)}/${digest}`;
+    await uploadContentAddressedFileToGcs(this.#storage, blob.sourcePath, uri, digest);
+    this.#publishedDigests.add(digest);
+  }
+  async commitManifest(manifestBytes) {
+    this.#assertOpen("commit a manifest");
+    for (const digest of manifestDigests(manifestBytes)) {
+      if (!this.#publishedDigests.has(digest)) {
+        throw new PlanV2IntegrityError(
+          `cannot commit GCS manifest before referenced blob is durable: ${digest}`
+        );
+      }
+    }
+    const manifestDigest = createHash2("sha256").update(manifestBytes, "utf8").digest("hex");
+    const stagingDir = mkdtempSync(join(this.#temporaryRoot, "hf-plan-v2-manifest-"));
+    const manifestPath = join(stagingDir, "manifest.json");
+    try {
+      writeFileSync(manifestPath, manifestBytes, "utf8");
+      await uploadContentAddressedFileToGcs(
+        this.#storage,
+        manifestPath,
+        this.manifestUri,
+        manifestDigest,
+        "application/json"
+      );
+      this.#state = "committed";
+    } finally {
+      rmSync2(stagingDir, { recursive: true, force: true });
+    }
+  }
+  async abort() {
+    if (this.#state === "open") this.#state = "aborted";
+  }
+  #assertOpen(operation) {
+    if (this.#state !== "open") {
+      throw new PlanV2IntegrityError(`cannot ${operation} after publisher is ${this.#state}`);
+    }
+  }
+};
+
 // src/server.ts
 var cachedStorage = null;
 function getStorage() {
@@ -141,6 +339,7 @@ function getStorage() {
 }
 async function dispatch(event, deps) {
   const unwrapped = unwrapEvent(event);
+  validatePlanProtocolShape(unwrapped);
   validateEventGcsUris(unwrapped);
   logEvent({ event: "handler_start", action: unwrapped.Action, input: summarizeEvent(unwrapped) });
   try {
@@ -161,15 +360,52 @@ async function dispatch(event, deps) {
       }
     }
   } catch (err) {
+    normalizeTerminalErrorName(err);
     logEvent({
       event: "handler_error",
       action: unwrapped.Action,
+      input: summarizeEvent(unwrapped),
       message: err instanceof Error ? err.message : String(err),
       name: err instanceof Error ? err.name : void 0
     });
     throw err;
   }
 }
+function validatePlanProtocolShape(event) {
+  const raw = event;
+  const protocol = raw.PlanProtocol;
+  if (protocol !== void 0 && protocol !== "v1" && protocol !== "v2") {
+    const error = new Error(
+      `[handler] unsupported PlanProtocol ${JSON.stringify(protocol)}; expected "v1", "v2", or absent`
+    );
+    error.name = "PLAN_PROTOCOL_UNSUPPORTED";
+    throw error;
+  }
+  if (event.Action === "plan") return;
+  const hasV1Locator = typeof raw.PlanGcsUri === "string";
+  const hasV2Manifest = typeof raw.PlanV2ManifestGcsUri === "string";
+  const hasV2Prefix = typeof raw.PlanV2ArtifactGcsPrefix === "string";
+  const valid = protocol === "v2" ? !hasV1Locator && hasV2Manifest && hasV2Prefix : hasV1Locator && !hasV2Manifest && !hasV2Prefix;
+  if (!valid) {
+    const error = new Error(
+      `[handler] ${protocol === "v2" ? "v2" : "v1"} ${event.Action} event has mixed or missing plan locators`
+    );
+    error.name = "PLAN_PROTOCOL_UNSUPPORTED";
+    throw error;
+  }
+  if (protocol === "v2" && event.Action === "assemble" && event.AudioGcsUri !== null) {
+    const error = new Error("[handler] v2 assemble audio must be materialized from the manifest");
+    error.name = "PLAN_PROTOCOL_UNSUPPORTED";
+    throw error;
+  }
+}
+function normalizeTerminalErrorName(error) {
+  if (!error || typeof error !== "object") return;
+  const candidate = error;
+  if (candidate.code === "PLAN_PROTOCOL_UNSUPPORTED" || candidate.code === "PLAN_TOO_LARGE" || candidate.code === "PLAN_V2_INTEGRITY_UNRECOVERABLE") {
+    candidate.name = candidate.code;
+  }
+}
 var MAX_ENVELOPE_DEPTH = 4;
 function unwrapEvent(event) {
   let cursor = event;
@@ -206,18 +442,21 @@ function summarizeEvent(event) {
       return {
         projectGcsUri: event.ProjectGcsUri,
         planOutputGcsPrefix: event.PlanOutputGcsPrefix,
+        planProtocol: event.PlanProtocol ?? "v1",
         format: event.Config.format,
         fps: event.Config.fps
       };
     case "renderChunk":
       return {
-        planGcsUri: event.PlanGcsUri,
+        planProtocol: event.PlanProtocol ?? "v1",
+        ...event.PlanProtocol === "v2" ? { planV2ManifestGcsUri: event.PlanV2ManifestGcsUri } : { planGcsUri: event.PlanGcsUri },
         chunkIndex: event.ChunkIndex,
         format: event.Format
       };
     case "assemble":
       return {
-        planGcsUri: event.PlanGcsUri,
+        planProtocol: event.PlanProtocol ?? "v1",
+        ...event.PlanProtocol === "v2" ? { planV2ManifestGcsUri: event.PlanV2ManifestGcsUri } : { planGcsUri: event.PlanGcsUri },
         chunkCount: event.ChunkGcsUris.length,
         hasAudio: event.AudioGcsUri !== null,
         outputGcsUri: event.OutputGcsUri,
@@ -231,14 +470,17 @@ function primeChrome(deps) {
   process.env.PRODUCER_HEADLESS_SHELL_PATH = resolveChromeExecutablePath();
 }
 async function handlePlan(event, deps) {
+  if (event.PlanProtocol === "v2") {
+    return handlePlanV2(event, deps);
+  }
   const started = Date.now();
   const storage = deps?.storage ?? getStorage();
   const primitive = deps?.primitives?.plan ?? plan;
   primeChrome(deps);
-  const work = mkdtempSync(join(deps?.tmpRoot ?? tmpdir(), "hf-cr-plan-"));
-  const projectArchive = join(work, "project.tar.gz");
-  const projectDir = join(work, "project");
-  const planDir = join(work, "plan");
+  const work = mkdtempSync2(join2(deps?.tmpRoot ?? tmpdir2(), "hf-cr-plan-"));
+  const projectArchive = join2(work, "project.tar.gz");
+  const projectDir = join2(work, "project");
+  const planDir = join2(work, "plan");
   try {
     await downloadGcsObjectToFile(storage, event.ProjectGcsUri, projectArchive);
     await untarDirectory(projectArchive, projectDir);
@@ -246,11 +488,11 @@ async function handlePlan(event, deps) {
       ...event.Config
     };
     const result = await primitive(projectDir, config, planDir);
-    const planTar = join(work, "plan.tar.gz");
+    const planTar = join2(work, "plan.tar.gz");
     await tarDirectory(planDir, planTar);
-    const planTarUri = `${trimTrailingSlash(event.PlanOutputGcsPrefix)}/plan.tar.gz`;
-    const audioPath = join(planDir, "audio.aac");
-    const hasAudio = existsSync3(audioPath) && statSync2(audioPath).size > 0;
+    const planTarUri = `${trimTrailingSlash2(event.PlanOutputGcsPrefix)}/plan.tar.gz`;
+    const audioPath = join2(planDir, "audio.aac");
+    const hasAudio = existsSync3(audioPath) && statSync3(audioPath).size > 0;
     await uploadFileToGcs(storage, planTar, planTarUri, "application/gzip");
     return {
       Action: "plan",
@@ -272,19 +514,99 @@ async function handlePlan(event, deps) {
     cleanupDir(work);
   }
 }
+async function handlePlanV2(event, deps) {
+  const started = Date.now();
+  const storage = deps?.storage ?? getStorage();
+  const primitive = deps?.primitives?.planV2WithPublisher ?? planV2WithPublisher;
+  primeChrome(deps);
+  const work = mkdtempSync2(join2(deps?.tmpRoot ?? tmpdir2(), "hf-cr-plan-v2-"));
+  const projectArchive = join2(work, "project.tar.gz");
+  const projectDir = join2(work, "project");
+  try {
+    await downloadGcsObjectToFile(storage, event.ProjectGcsUri, projectArchive);
+    await untarDirectory(projectArchive, projectDir);
+    const publisher = new GcsPlanV2ArtifactPublisher({
+      storage,
+      planOutputGcsPrefix: event.PlanOutputGcsPrefix,
+      temporaryRoot: work
+    });
+    const manifest = await primitive(projectDir, { ...event.Config }, publisher, {
+      stagingParentDir: work
+    });
+    return {
+      Action: "plan",
+      PlanProtocol: "v2",
+      PlanV2ManifestGcsUri: publisher.manifestUri,
+      PlanV2ArtifactGcsPrefix: publisher.artifactPrefix,
+      PlanHash: manifest.planHash,
+      ChunkCount: manifest.chunkCount,
+      TotalFrames: manifest.totalFrames,
+      Fps: manifest.fps,
+      Width: manifest.width,
+      Height: manifest.height,
+      Format: manifest.format,
+      HasAudio: manifest.artifacts.some((artifact) => artifact.path === "audio.aac"),
+      AudioGcsUri: null,
+      FfmpegVersion: manifest.ffmpegVersion,
+      ProducerVersion: manifest.producerVersion,
+      DurationMs: Date.now() - started
+    };
+  } finally {
+    cleanupDir(work);
+  }
+}
 async function handleRenderChunk(event, deps) {
+  if (event.PlanProtocol === "v2") {
+    return handleRenderChunkV2(event, deps);
+  }
   const started = Date.now();
   const storage = deps?.storage ?? getStorage();
   const primitive = deps?.primitives?.renderChunk ?? renderChunk;
   primeChrome(deps);
-  const work = mkdtempSync(join(deps?.tmpRoot ?? tmpdir(), "hf-cr-chunk-"));
-  const planTar = join(work, "plan.tar.gz");
-  const planDir = join(work, "plan");
+  const work = mkdtempSync2(join2(deps?.tmpRoot ?? tmpdir2(), "hf-cr-chunk-"));
+  const planTar = join2(work, "plan.tar.gz");
+  const planDir = join2(work, "plan");
   try {
     await downloadGcsObjectToFile(storage, event.PlanGcsUri, planTar);
     await untarDirectory(planTar, planDir);
     verifyPlanHash(planDir, event.PlanHash);
-    const chunkOutputBase = join(
+    const chunkOutputBase = join2(
+      work,
+      event.Format === "png-sequence" ? `chunk-${pad(event.ChunkIndex)}` : `chunk-${pad(event.ChunkIndex)}${formatExtension(event.Format)}`
+    );
+    const result = await primitive(planDir, event.ChunkIndex, chunkOutputBase);
+    const chunkUri = await uploadChunkOutput(
+      storage,
+      result,
+      event.ChunkOutputGcsPrefix,
+      event.ChunkIndex
+    );
+    return {
+      Action: "renderChunk",
+      ChunkGcsUri: chunkUri,
+      ChunkIndex: event.ChunkIndex,
+      Sha256: result.sha256,
+      FramesEncoded: result.framesEncoded,
+      DurationMs: Date.now() - started
+    };
+  } finally {
+    cleanupDir(work);
+  }
+}
+async function handleRenderChunkV2(event, deps) {
+  const started = Date.now();
+  const storage = deps?.storage ?? getStorage();
+  const primitive = deps?.primitives?.renderChunk ?? renderChunk;
+  primeChrome(deps);
+  const work = mkdtempSync2(join2(deps?.tmpRoot ?? tmpdir2(), "hf-cr-chunk-v2-"));
+  try {
+    const planDir = await downloadAndMaterializePlanV2(
+      storage,
+      event,
+      { role: "chunk", chunkIndex: event.ChunkIndex },
+      work
+    );
+    const chunkOutputBase = join2(
       work,
       event.Format === "png-sequence" ? `chunk-${pad(event.ChunkIndex)}` : `chunk-${pad(event.ChunkIndex)}${formatExtension(event.Format)}`
     );
@@ -308,7 +630,7 @@ async function handleRenderChunk(event, deps) {
   }
 }
 async function uploadChunkOutput(storage, result, prefix, chunkIndex) {
-  const trimmed = trimTrailingSlash(prefix);
+  const trimmed = trimTrailingSlash2(prefix);
   if (result.outputKind === "file") {
     const ext = extname(result.outputPath);
     const uri2 = `${trimmed}/chunks/${pad(chunkIndex)}${ext}`;
@@ -322,25 +644,28 @@ async function uploadChunkOutput(storage, result, prefix, chunkIndex) {
   return uri;
 }
 async function handleAssemble(event, deps) {
+  if (event.PlanProtocol === "v2") {
+    return handleAssembleV2(event, deps);
+  }
   const started = Date.now();
   const storage = deps?.storage ?? getStorage();
   const primitive = deps?.primitives?.assemble ?? assemble;
-  const work = mkdtempSync(join(deps?.tmpRoot ?? tmpdir(), "hf-cr-assemble-"));
-  const planTar = join(work, "plan.tar.gz");
-  const planDir = join(work, "plan");
+  const work = mkdtempSync2(join2(deps?.tmpRoot ?? tmpdir2(), "hf-cr-assemble-"));
+  const planTar = join2(work, "plan.tar.gz");
+  const planDir = join2(work, "plan");
   try {
     await downloadGcsObjectToFile(storage, event.PlanGcsUri, planTar);
     await untarDirectory(planTar, planDir);
     const chunkPaths = await downloadChunkObjects(storage, event.ChunkGcsUris, work, event.Format);
     let audioPath = null;
-    const planAudio = join(planDir, "audio.aac");
-    if (existsSync3(planAudio) && statSync2(planAudio).size > 0) {
+    const planAudio = join2(planDir, "audio.aac");
+    if (existsSync3(planAudio) && statSync3(planAudio).size > 0) {
       audioPath = planAudio;
     } else if (event.AudioGcsUri) {
       audioPath = planAudio;
       await downloadGcsObjectToFile(storage, event.AudioGcsUri, audioPath);
     }
-    const finalOutput = event.Format === "png-sequence" ? join(work, "output-frames") : join(work, `output${formatExtension(event.Format)}`);
+    const finalOutput = event.Format === "png-sequence" ? join2(work, "output-frames") : join2(work, `output${formatExtension(event.Format)}`);
     const result = await primitive(planDir, chunkPaths, audioPath, finalOutput, {
       cfr: event.Cfr === true
     });
@@ -362,9 +687,100 @@ async function handleAssemble(event, deps) {
     cleanupDir(work);
   }
 }
+async function handleAssembleV2(event, deps) {
+  const started = Date.now();
+  const storage = deps?.storage ?? getStorage();
+  const primitive = deps?.primitives?.assemble ?? assemble;
+  const work = mkdtempSync2(join2(deps?.tmpRoot ?? tmpdir2(), "hf-cr-assemble-v2-"));
+  try {
+    const planDir = await downloadAndMaterializePlanV2(storage, event, { role: "assembler" }, work);
+    const audioPath = existsSync3(join2(planDir, "audio.aac")) ? join2(planDir, "audio.aac") : null;
+    const chunkPaths = await downloadChunkObjects(storage, event.ChunkGcsUris, work, event.Format);
+    const finalOutput = event.Format === "png-sequence" ? join2(work, "output-frames") : join2(work, `output${formatExtension(event.Format)}`);
+    const result = await primitive(planDir, chunkPaths, audioPath, finalOutput, {
+      cfr: event.Cfr === true
+    });
+    if (event.Format === "png-sequence") {
+      const tarball = `${finalOutput}.tar.gz`;
+      await tarDirectory(finalOutput, tarball);
+      await uploadFileToGcs(storage, tarball, event.OutputGcsUri, "application/gzip");
+    } else {
+      await uploadFileToGcs(storage, finalOutput, event.OutputGcsUri);
+    }
+    return {
+      Action: "assemble",
+      OutputGcsUri: event.OutputGcsUri,
+      FramesEncoded: result.framesEncoded,
+      FileSize: result.fileSize,
+      DurationMs: Date.now() - started
+    };
+  } finally {
+    cleanupDir(work);
+  }
+}
+async function downloadAndMaterializePlanV2(storage, event, target, work) {
+  const transportDir = join2(work, "plan-v2");
+  mkdirSync3(transportDir, { recursive: true });
+  await downloadGcsObjectToFile(
+    storage,
+    event.PlanV2ManifestGcsUri,
+    join2(transportDir, "plan.json")
+  );
+  const manifest = readPlanV2Manifest(transportDir);
+  if (manifest.planHash !== event.PlanHash) {
+    throwPlanHashMismatch(event.PlanHash, manifest.planHash);
+  }
+  const artifacts = listPlanV2ArtifactsForTarget(manifest, target);
+  const uniqueArtifacts = [
+    ...new Map(artifacts.map((artifact) => [artifact.sha256, artifact])).values()
+  ];
+  await mapConcurrent(uniqueArtifacts, 16, async (artifact) => {
+    await downloadPlanV2Artifact(storage, event.PlanV2ArtifactGcsPrefix, transportDir, artifact);
+  });
+  const planDir = join2(work, "plan");
+  materializePlanV2Target(transportDir, target, planDir);
+  return planDir;
+}
+async function downloadPlanV2Artifact(storage, artifactPrefix, planV2Dir, artifact) {
+  await downloadGcsObjectToFileVerified(
+    storage,
+    planV2BlobUri(artifactPrefix, artifact.sha256),
+    planV2BlobPath(planV2Dir, artifact.sha256),
+    artifact.sha256
+  );
+}
+function planV2BlobPath(planV2Dir, digest) {
+  return join2(planV2Dir, "artifacts", "sha256", digest.slice(0, 2), digest);
+}
+function planV2BlobUri(prefix, digest) {
+  return `${trimTrailingSlash2(prefix)}/${digest.slice(0, 2)}/${digest}`;
+}
+function throwPlanHashMismatch(expected, actual) {
+  const error = new Error(
+    `PLAN_HASH_MISMATCH: event PlanHash=${expected} did not match v2 manifest planHash=${actual}`
+  );
+  error.name = "PLAN_HASH_MISMATCH";
+  throw error;
+}
+async function mapConcurrent(values, concurrency, fn) {
+  let cursor = 0;
+  async function worker() {
+    while (cursor < values.length) {
+      const index = cursor++;
+      await fn(values[index]);
+    }
+  }
+  const results = await Promise.allSettled(
+    Array.from({ length: Math.min(concurrency, values.length) }, () => worker())
+  );
+  const failure = results.find(
+    (result) => result.status === "rejected"
+  );
+  if (failure) throw failure.reason;
+}
 async function downloadChunkObjects(storage, uris, workDir, format) {
-  const chunksDir = join(workDir, "chunks");
-  mkdirSync2(chunksDir, { recursive: true });
+  const chunksDir = join2(workDir, "chunks");
+  mkdirSync3(chunksDir, { recursive: true });
   const local = new Array(uris.length);
   await Promise.all(
     uris.map(async (uri, i) => {
@@ -372,10 +788,10 @@ async function downloadChunkObjects(storage, uris, workDir, format) {
         throw new Error(`[handler] chunk URI at index ${i} is empty`);
       }
       const { key } = parseGcsUri(uri);
-      const localPath = join(chunksDir, basename(key));
+      const localPath = join2(chunksDir, basename(key));
       await downloadGcsObjectToFile(storage, uri, localPath);
       if (format === "png-sequence") {
-        const dirPath = join(chunksDir, `frames-${pad(i)}`);
+        const dirPath = join2(chunksDir, `frames-${pad(i)}`);
         await untarDirectory(localPath, dirPath);
         local[i] = dirPath;
       } else {
@@ -390,10 +806,10 @@ function getEventGcsUris(event) {
     case "plan":
       return [event.ProjectGcsUri, event.PlanOutputGcsPrefix];
     case "renderChunk":
-      return [event.PlanGcsUri, event.ChunkOutputGcsPrefix];
+      return event.PlanProtocol === "v2" ? [event.PlanV2ManifestGcsUri, event.PlanV2ArtifactGcsPrefix, event.ChunkOutputGcsPrefix] : [event.PlanGcsUri, event.ChunkOutputGcsPrefix];
     case "assemble":
       return [
-        event.PlanGcsUri,
+        ...event.PlanProtocol === "v2" ? [event.PlanV2ManifestGcsUri, event.PlanV2ArtifactGcsPrefix] : [event.PlanGcsUri],
         ...event.ChunkGcsUris,
         event.OutputGcsUri,
         event.AudioGcsUri
@@ -429,17 +845,17 @@ function validateEventGcsUris(event) {
 function pad(n) {
   return n.toString().padStart(4, "0");
 }
-function trimTrailingSlash(prefix) {
+function trimTrailingSlash2(prefix) {
   return prefix.endsWith("/") ? prefix.slice(0, -1) : prefix;
 }
 function cleanupDir(dir) {
   try {
-    rmSync2(dir, { recursive: true, force: true });
+    rmSync3(dir, { recursive: true, force: true });
   } catch {
   }
 }
 function verifyPlanHash(planDir, expected) {
-  const planJsonPath = join(planDir, "plan.json");
+  const planJsonPath = join2(planDir, "plan.json");
   let parsed;
   try {
     parsed = JSON.parse(readFileSync(planJsonPath, "utf-8"));
@@ -462,12 +878,17 @@ var NON_RETRYABLE_ERROR_NAMES = /* @__PURE__ */ new Set([
   // Handler-boundary guards.
   "GCS_URI_NOT_ALLOWED",
   "PLAN_HASH_MISMATCH",
+  "PLAN_ARTIFACT_DIGEST_MISMATCH",
+  "PLAN_PROTOCOL_UNSUPPORTED",
+  "PLAN_V2_INTEGRITY_UNRECOVERABLE",
   // Producer error class names (`.name`) + their string code aliases — the
   // class sets `.name` to the class name but wraps a `code`; cover both so a
   // raw-code throw is caught too. Mirrors the AWS state machine's
   // non-retryable list.
   "FormatNotSupportedInDistributedError",
   "PlanTooLargeError",
+  "PlanProtocolUnsupportedError",
+  "PlanV2IntegrityError",
   "RenderChunkValidationError",
   "FFMPEG_VERSION_MISMATCH",
   "FORMAT_NOT_SUPPORTED_IN_DISTRIBUTED",