@hyperframes/aws-lambda 0.7.71 → 0.7.73

package/dist/handler.js

@@ -1,11 +1,15 @@
 // src/handler.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, 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, join as join2 } from "node:path";
 import { S3Client } from "@aws-sdk/client-s3";
 import {
   assemble,
+  listPlanV2ArtifactsForTarget,
+  materializePlanV2Target,
   plan,
+  planV2WithPublisher,
+  readPlanV2Manifest,
   renderChunk
 } from "@hyperframes/producer/distributed";
 
@@ -90,9 +94,14 @@ import {
   rmSync,
   statSync
 } from "node:fs";
+import { createHash } from "node:crypto";
 import { dirname } from "node:path";
 import { pipeline } from "node:stream/promises";
-import { GetObjectCommand, PutObjectCommand } from "@aws-sdk/client-s3";
+import {
+  GetObjectCommand,
+  HeadObjectCommand,
+  PutObjectCommand
+} from "@aws-sdk/client-s3";
 import * as tar from "tar";
 function parseS3Uri(uri) {
   if (!uri.startsWith("s3://")) {
@@ -120,6 +129,19 @@ async function downloadS3ObjectToFile(client, uri, destPath) {
   mkdirSync(dirname(destPath), { recursive: true });
   await pipeline(body, createWriteStream(destPath));
 }
+async function downloadS3ObjectToFileVerified(client, uri, destPath, expectedSha256) {
+  assertSha256(expectedSha256);
+  await downloadS3ObjectToFile(client, uri, destPath);
+  const actual = await sha256File(destPath);
+  if (actual !== expectedSha256) {
+    rmSync(destPath, { force: true });
+    const error = new Error(
+      `[s3Transport] PLAN_ARTIFACT_DIGEST_MISMATCH: ${uri} expected ${expectedSha256}, got ${actual}`
+    );
+    error.name = "PLAN_ARTIFACT_DIGEST_MISMATCH";
+    throw error;
+  }
+}
 async function uploadFileToS3(client, localPath, uri, contentType) {
   if (!existsSync2(localPath)) {
     throw new Error(`[s3Transport] upload source missing: ${localPath}`);
@@ -136,6 +158,97 @@ async function uploadFileToS3(client, localPath, uri, contentType) {
     })
   );
 }
+async function uploadContentAddressedFileToS3(client, localPath, uri, expectedSha256, contentType) {
+  assertSha256(expectedSha256);
+  if (!existsSync2(localPath)) {
+    throw new Error(`[s3Transport] upload source missing: ${localPath}`);
+  }
+  const actualSha256 = await sha256File(localPath);
+  if (actualSha256 !== expectedSha256) {
+    const error = new Error(
+      `[s3Transport] PLAN_ARTIFACT_DIGEST_MISMATCH: local artifact ${localPath} expected ${expectedSha256}, got ${actualSha256}`
+    );
+    error.name = "PLAN_ARTIFACT_DIGEST_MISMATCH";
+    throw error;
+  }
+  const { bucket, key } = parseS3Uri(uri);
+  const size = statSync(localPath).size;
+  const existing = await inspectContentAddressedObject(client, bucket, key, size, expectedSha256);
+  if (existing === "matching") return "reused";
+  if (existing === "conflict") throwImmutableObjectConflict(uri);
+  const body = createReadStream(localPath);
+  try {
+    await client.send(
+      new PutObjectCommand({
+        Bucket: bucket,
+        Key: key,
+        Body: body,
+        ContentType: contentType,
+        ContentLength: size,
+        Metadata: { sha256: expectedSha256 },
+        ChecksumSHA256: Buffer.from(expectedSha256, "hex").toString("base64"),
+        // HEAD followed by an unconditional PUT can overwrite a conflicting
+        // object published by a concurrent planner. Conditional create makes
+        // immutable CAS and fixed-key manifest publication race-safe.
+        IfNoneMatch: "*"
+      })
+    );
+    return "uploaded";
+  } catch (error) {
+    if (!isS3PreconditionFailed(error)) throw error;
+    const raced = await inspectContentAddressedObject(client, bucket, key, size, expectedSha256);
+    if (raced === "matching") return "reused";
+    if (raced === "conflict") throwImmutableObjectConflict(uri);
+    throw error;
+  } finally {
+    body.destroy();
+  }
+}
+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(
+      `[s3Transport] expected lowercase SHA-256 digest, got ${JSON.stringify(value)}`
+    );
+  }
+}
+async function inspectContentAddressedObject(client, bucket, key, expectedSize, expectedSha256) {
+  try {
+    const existing = await client.send(
+      new HeadObjectCommand({ Bucket: bucket, Key: key, ChecksumMode: "ENABLED" })
+    );
+    return existing.ContentLength === expectedSize && existing.Metadata?.sha256 === expectedSha256 ? "matching" : "conflict";
+  } catch (error) {
+    if (isS3NotFound(error)) return "missing";
+    throw error;
+  }
+}
+function throwImmutableObjectConflict(uri) {
+  const error = new Error(
+    `[s3Transport] PLAN_ARTIFACT_DIGEST_MISMATCH: immutable object ${uri} already exists with different digest metadata or size`
+  );
+  error.name = "PLAN_ARTIFACT_DIGEST_MISMATCH";
+  throw error;
+}
+function isS3NotFound(error) {
+  if (!isRecord(error)) return false;
+  const metadata = isRecord(error.$metadata) ? error.$metadata : void 0;
+  return error.name === "NotFound" || error.name === "NoSuchKey" || metadata?.httpStatusCode === 404;
+}
+function isS3PreconditionFailed(error) {
+  if (!isRecord(error)) return false;
+  const metadata = isRecord(error.$metadata) ? error.$metadata : void 0;
+  return error.name === "PreconditionFailed" || metadata?.httpStatusCode === 412;
+}
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
 async function tarDirectory(sourceDir, destTarball) {
   if (!existsSync2(sourceDir) || !statSync(sourceDir).isDirectory()) {
     throw new Error(`[s3Transport] tar source must be an existing directory: ${sourceDir}`);
@@ -154,6 +267,112 @@ async function untarDirectory(tarballPath, destDir) {
   await tar.extract({ file: tarballPath, cwd: destDir });
 }
 
+// src/s3PlanV2Publisher.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 isRecord2(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("S3 publisher received invalid manifest JSON");
+  }
+  if (!isRecord2(value) || !Array.isArray(value.artifacts)) {
+    throw new PlanV2IntegrityError("S3 publisher manifest requires an artifacts array");
+  }
+  return new Set(
+    value.artifacts.map((artifact, index) => {
+      if (!isRecord2(artifact)) {
+        throw new PlanV2IntegrityError(`S3 publisher artifacts[${index}] must be an object`);
+      }
+      return assertSha2562(artifact.sha256, `S3 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 S3PlanV2ArtifactPublisher = class {
+  artifactPrefix;
+  manifestUri;
+  #s3;
+  #temporaryRoot;
+  #publishedDigests = /* @__PURE__ */ new Set();
+  #state = "open";
+  constructor(options) {
+    const outputPrefix = `${trimTrailingSlash(options.planOutputS3Prefix)}/v2`;
+    parseS3Uri(outputPrefix);
+    this.#s3 = options.s3;
+    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, "S3 published blob sha256");
+    const sourceSize = statSync2(blob.sourcePath).size;
+    if (sourceSize !== blob.sizeBytes) {
+      throw new PlanV2IntegrityError(
+        `S3 published blob size changed for ${digest}: expected ${blob.sizeBytes}, got ${sourceSize}`
+      );
+    }
+    const uri = `${this.artifactPrefix}/${digest.slice(0, 2)}/${digest}`;
+    await uploadContentAddressedFileToS3(this.#s3, 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 S3 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 uploadContentAddressedFileToS3(
+        this.#s3,
+        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/handler.ts
 var cachedS3Client = null;
 function getS3Client() {
@@ -184,15 +403,24 @@ async function handler(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 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;
@@ -229,18 +457,21 @@ function summarizeEvent(event) {
       return {
         projectS3Uri: event.ProjectS3Uri,
         planOutputS3Prefix: event.PlanOutputS3Prefix,
+        planProtocol: event.PlanProtocol ?? "v1",
         format: event.Config.format,
         fps: event.Config.fps
       };
     case "renderChunk":
       return {
-        planS3Uri: event.PlanS3Uri,
+        planProtocol: event.PlanProtocol ?? "v1",
+        ...event.PlanProtocol === "v2" ? { planV2ManifestS3Uri: event.PlanV2ManifestS3Uri } : { planS3Uri: event.PlanS3Uri },
         chunkIndex: event.ChunkIndex,
         format: event.Format
       };
     case "assemble":
       return {
-        planS3Uri: event.PlanS3Uri,
+        planProtocol: event.PlanProtocol ?? "v1",
+        ...event.PlanProtocol === "v2" ? { planV2ManifestS3Uri: event.PlanV2ManifestS3Uri } : { planS3Uri: event.PlanS3Uri },
         chunkCount: event.ChunkS3Uris.length,
         hasAudio: event.AudioS3Uri !== null,
         outputS3Uri: event.OutputS3Uri,
@@ -253,12 +484,15 @@ function primeRuntimeEnv() {
   if (runtimeEnvPrimed) return;
   runtimeEnvPrimed = true;
   const taskRoot = process.env.LAMBDA_TASK_ROOT ?? "/var/task";
-  const bin = join(taskRoot, "bin");
+  const bin = join2(taskRoot, "bin");
   if (existsSync3(bin)) {
     process.env.PATH = `${bin}:${process.env.PATH ?? ""}`;
   }
 }
 async function handlePlan(event, deps) {
+  if (event.PlanProtocol === "v2") {
+    return handlePlanV2(event, deps);
+  }
   const started = Date.now();
   const s3 = deps?.s3 ?? getS3Client();
   const primitive = deps?.primitives?.plan ?? plan;
@@ -266,10 +500,10 @@ async function handlePlan(event, deps) {
     const chromePath = await resolveChromeExecutablePath();
     process.env.PRODUCER_HEADLESS_SHELL_PATH = chromePath;
   }
-  const work = mkdtempSync(join(deps?.tmpRoot ?? tmpdir(), "hf-lambda-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-lambda-plan-"));
+  const projectArchive = join2(work, "project.tar.gz");
+  const projectDir = join2(work, "project");
+  const planDir = join2(work, "plan");
   try {
     await downloadS3ObjectToFile(s3, event.ProjectS3Uri, projectArchive);
     await untarDirectory(projectArchive, projectDir);
@@ -277,12 +511,12 @@ 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.PlanOutputS3Prefix)}/plan.tar.gz`;
-    const audioPath = join(planDir, "audio.aac");
-    const hasAudio = existsSync3(audioPath) && statSync2(audioPath).size > 0;
-    const audioUri = hasAudio ? `${trimTrailingSlash(event.PlanOutputS3Prefix)}/audio.aac` : null;
+    const planTarUri = `${trimTrailingSlash2(event.PlanOutputS3Prefix)}/plan.tar.gz`;
+    const audioPath = join2(planDir, "audio.aac");
+    const hasAudio = existsSync3(audioPath) && statSync3(audioPath).size > 0;
+    const audioUri = hasAudio ? `${trimTrailingSlash2(event.PlanOutputS3Prefix)}/audio.aac` : null;
     await Promise.all([
       uploadFileToS3(s3, planTar, planTarUri, "application/gzip"),
       hasAudio && audioUri ? uploadFileToS3(s3, audioPath, audioUri, "audio/aac") : null
@@ -307,7 +541,53 @@ async function handlePlan(event, deps) {
     cleanupDir(work);
   }
 }
+async function handlePlanV2(event, deps) {
+  const started = Date.now();
+  const s3 = deps?.s3 ?? getS3Client();
+  const primitive = deps?.primitives?.planV2WithPublisher ?? planV2WithPublisher;
+  if (!deps?.skipChromeResolution && !process.env.PRODUCER_HEADLESS_SHELL_PATH) {
+    process.env.PRODUCER_HEADLESS_SHELL_PATH = await resolveChromeExecutablePath();
+  }
+  const work = mkdtempSync2(join2(deps?.tmpRoot ?? tmpdir2(), "hf-lambda-plan-v2-"));
+  const projectArchive = join2(work, "project.tar.gz");
+  const projectDir = join2(work, "project");
+  try {
+    await downloadS3ObjectToFile(s3, event.ProjectS3Uri, projectArchive);
+    await untarDirectory(projectArchive, projectDir);
+    const publisher = new S3PlanV2ArtifactPublisher({
+      s3,
+      planOutputS3Prefix: event.PlanOutputS3Prefix,
+      temporaryRoot: work
+    });
+    const manifest = await primitive(projectDir, { ...event.Config }, publisher, {
+      stagingParentDir: work
+    });
+    return {
+      Action: "plan",
+      PlanProtocol: "v2",
+      PlanV2ManifestS3Uri: publisher.manifestUri,
+      PlanV2ArtifactS3Prefix: 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"),
+      AudioS3Uri: 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 s3 = deps?.s3 ?? getS3Client();
   const primitive = deps?.primitives?.renderChunk ?? renderChunk;
@@ -315,14 +595,52 @@ async function handleRenderChunk(event, deps) {
     const chromePath = await resolveChromeExecutablePath();
     process.env.PRODUCER_HEADLESS_SHELL_PATH = chromePath;
   }
-  const work = mkdtempSync(join(deps?.tmpRoot ?? tmpdir(), "hf-lambda-chunk-"));
-  const planTar = join(work, "plan.tar.gz");
-  const planDir = join(work, "plan");
+  const work = mkdtempSync2(join2(deps?.tmpRoot ?? tmpdir2(), "hf-lambda-chunk-"));
+  const planTar = join2(work, "plan.tar.gz");
+  const planDir = join2(work, "plan");
   try {
     await downloadS3ObjectToFile(s3, event.PlanS3Uri, 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(
+      s3,
+      result,
+      event.ChunkOutputS3Prefix,
+      event.ChunkIndex
+    );
+    return {
+      Action: "renderChunk",
+      ChunkS3Uri: 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 s3 = deps?.s3 ?? getS3Client();
+  const primitive = deps?.primitives?.renderChunk ?? renderChunk;
+  if (!deps?.skipChromeResolution && !process.env.PRODUCER_HEADLESS_SHELL_PATH) {
+    process.env.PRODUCER_HEADLESS_SHELL_PATH = await resolveChromeExecutablePath();
+  }
+  const work = mkdtempSync2(join2(deps?.tmpRoot ?? tmpdir2(), "hf-lambda-chunk-v2-"));
+  try {
+    const planDir = await downloadAndMaterializePlanV2(
+      s3,
+      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)}`
     );
@@ -346,7 +664,7 @@ async function handleRenderChunk(event, deps) {
   }
 }
 async function uploadChunkOutput(s3, result, prefix, chunkIndex) {
-  const trimmed = trimTrailingSlash(prefix);
+  const trimmed = trimTrailingSlash2(prefix);
   if (result.outputKind === "file") {
     const ext = result.outputPath.slice(result.outputPath.lastIndexOf("."));
     const uri2 = `${trimmed}/chunks/${pad(chunkIndex)}${ext}`;
@@ -360,22 +678,25 @@ async function uploadChunkOutput(s3, result, prefix, chunkIndex) {
   return uri;
 }
 async function handleAssemble(event, deps) {
+  if (event.PlanProtocol === "v2") {
+    return handleAssembleV2(event, deps);
+  }
   const started = Date.now();
   const s3 = deps?.s3 ?? getS3Client();
   const primitive = deps?.primitives?.assemble ?? assemble;
-  const work = mkdtempSync(join(deps?.tmpRoot ?? tmpdir(), "hf-lambda-assemble-"));
-  const planTar = join(work, "plan.tar.gz");
-  const planDir = join(work, "plan");
+  const work = mkdtempSync2(join2(deps?.tmpRoot ?? tmpdir2(), "hf-lambda-assemble-"));
+  const planTar = join2(work, "plan.tar.gz");
+  const planDir = join2(work, "plan");
   try {
     await downloadS3ObjectToFile(s3, event.PlanS3Uri, planTar);
     await untarDirectory(planTar, planDir);
     const chunkPaths = await downloadChunkObjects(s3, event.ChunkS3Uris, work, event.Format);
     let audioPath = null;
     if (event.AudioS3Uri) {
-      audioPath = join(planDir, "audio.aac");
+      audioPath = join2(planDir, "audio.aac");
       await downloadS3ObjectToFile(s3, event.AudioS3Uri, 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
     });
@@ -397,9 +718,96 @@ async function handleAssemble(event, deps) {
     cleanupDir(work);
   }
 }
+async function handleAssembleV2(event, deps) {
+  const started = Date.now();
+  const s3 = deps?.s3 ?? getS3Client();
+  const primitive = deps?.primitives?.assemble ?? assemble;
+  const work = mkdtempSync2(join2(deps?.tmpRoot ?? tmpdir2(), "hf-lambda-assemble-v2-"));
+  try {
+    const planDir = await downloadAndMaterializePlanV2(s3, event, { role: "assembler" }, work);
+    const audioPath = existsSync3(join2(planDir, "audio.aac")) ? join2(planDir, "audio.aac") : null;
+    const chunkPaths = await downloadChunkObjects(s3, event.ChunkS3Uris, 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 uploadFileToS3(s3, tarball, event.OutputS3Uri, "application/gzip");
+    } else {
+      await uploadFileToS3(s3, finalOutput, event.OutputS3Uri);
+    }
+    return {
+      Action: "assemble",
+      OutputS3Uri: event.OutputS3Uri,
+      FramesEncoded: result.framesEncoded,
+      FileSize: result.fileSize,
+      DurationMs: Date.now() - started
+    };
+  } finally {
+    cleanupDir(work);
+  }
+}
+async function downloadAndMaterializePlanV2(s3, event, target, work) {
+  const transportDir = join2(work, "plan-v2");
+  mkdirSync3(transportDir, { recursive: true });
+  await downloadS3ObjectToFile(s3, event.PlanV2ManifestS3Uri, 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(s3, event.PlanV2ArtifactS3Prefix, transportDir, artifact);
+  });
+  const planDir = join2(work, "plan");
+  materializePlanV2Target(transportDir, target, planDir);
+  return planDir;
+}
+async function downloadPlanV2Artifact(s3, artifactPrefix, planV2Dir, artifact) {
+  await downloadS3ObjectToFileVerified(
+    s3,
+    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(s3, 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) => {
@@ -407,10 +815,10 @@ async function downloadChunkObjects(s3, uris, workDir, format) {
         throw new Error(`[handler] chunk URI at index ${i} is empty`);
       }
       const { key } = parseS3Uri(uri);
-      const localPath = join(chunksDir, basename(key));
+      const localPath = join2(chunksDir, basename(key));
       await downloadS3ObjectToFile(s3, 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 {
@@ -425,11 +833,14 @@ function getEventS3Uris(event) {
     case "plan":
       return [event.ProjectS3Uri, event.PlanOutputS3Prefix];
     case "renderChunk":
-      return [event.PlanS3Uri, event.ChunkOutputS3Prefix];
+      return event.PlanProtocol === "v2" ? [event.PlanV2ManifestS3Uri, event.PlanV2ArtifactS3Prefix, event.ChunkOutputS3Prefix] : [event.PlanS3Uri, event.ChunkOutputS3Prefix];
     case "assemble":
-      return [event.PlanS3Uri, ...event.ChunkS3Uris, event.OutputS3Uri, event.AudioS3Uri].filter(
-        (u) => u != null
-      );
+      return [
+        ...event.PlanProtocol === "v2" ? [event.PlanV2ManifestS3Uri, event.PlanV2ArtifactS3Prefix] : [event.PlanS3Uri],
+        ...event.ChunkS3Uris,
+        event.OutputS3Uri,
+        event.AudioS3Uri
+      ].filter((u) => u != null);
   }
 }
 function validateEventS3Uris(event) {
@@ -449,17 +860,17 @@ function validateEventS3Uris(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"));