@hyperframes/aws-lambda 0.8.177 → 0.8.179

package/dist/_chunks/chunk-AK7J3QQN.js

@@ -0,0 +1,1006 @@
+import {
+  downloadS3ObjectToFile,
+  downloadS3ObjectToFileVerified,
+  downloadSiteFiles,
+  ensureContentStoreObject,
+  formatExtension,
+  formatS3Uri,
+  isSiteManifestUri,
+  mapConcurrent,
+  parseS3Uri,
+  presignVerifiedS3GetUrl,
+  putContentStoreFile,
+  tarDirectory,
+  untarDirectory,
+  uploadContentAddressedFileToS3,
+  uploadFileToS3
+} from "./chunk-ZY5YIH5W.js";
+import {
+  CONTENT_STORE_PREFIX
+} from "./chunk-YS3KY3C5.js";
+
+// src/handler.ts
+import { existsSync as existsSync2, mkdirSync as mkdirSync2, mkdtempSync as mkdtempSync2, readFileSync, rmSync as rmSync2, statSync as statSync2 } from "node:fs";
+import { tmpdir as tmpdir2 } from "node:os";
+import { basename, join as join2 } from "node:path";
+import { GetAccountSettingsCommand, LambdaClient } from "@aws-sdk/client-lambda";
+import { S3Client } from "@aws-sdk/client-s3";
+import {
+  assemble,
+  chunksAreStitchedMp4,
+  DEFAULT_MAX_PARALLEL_CHUNKS,
+  listPlanV2ArtifactsForTarget,
+  materializePlanV2Target,
+  plan,
+  isPlanAudioArtifactPath,
+  PLAN_AUDIO_RELATIVE_PATH,
+  resolvePlanAudioPath,
+  planV2WithPublisher,
+  isPlanV2DeferredSourceArtifact,
+  readPlanV2Manifest,
+  renderChunk
+} from "@hyperframes/producer/distributed";
+
+// src/chromium.ts
+import { existsSync } from "node:fs";
+var ChromeBinaryUnavailableError = class extends Error {
+  // Lambda's runtime serializes the error envelope's `errorType` from
+  // `err.name`; this class-field override sets it across the structured
+  // clone. Read indirectly; fallow can't follow.
+  // fallow-ignore-next-line unused-class-member
+  name = "ChromeBinaryUnavailableError";
+  source;
+  resolvedPath;
+  constructor(source, resolvedPath, hint) {
+    super(`[chromium] Chrome binary unavailable (source=${source}): ${hint}`);
+    this.source = source;
+    this.resolvedPath = resolvedPath;
+  }
+};
+var SPARTICUZ_WEDGE_HINT = "@sparticuz/chromium.executablePath() returned a falsy value or a path that doesn't exist on disk. This typically happens after a chunk hits `Sandbox.Timedout` mid-extraction and leaves /tmp in a wedged state \u2014 subsequent invocations land on the same warm instance and never re-extract. Recycle the function (e.g. `aws lambda update-function-configuration ... --environment ...` with a bumped marker var, or redeploy via `hyperframes lambda deploy --skip-build`) to force fresh execution environments. Tracking: investigate the upstream wedge so this auto-recovers.";
+function resolveChromeSource() {
+  const raw = process.env.HYPERFRAMES_LAMBDA_CHROME_SOURCE?.toLowerCase();
+  if (raw === "chrome-headless-shell" || raw === "shell") return "chrome-headless-shell";
+  return "sparticuz";
+}
+async function resolveChromeExecutablePath() {
+  const source = resolveChromeSource();
+  if (source === "sparticuz") {
+    const mod = await loadSparticuzChromium();
+    const path = await mod.executablePath();
+    if (!path || typeof path !== "string") {
+      throw new ChromeBinaryUnavailableError(source, null, SPARTICUZ_WEDGE_HINT);
+    }
+    if (!existsSync(path)) {
+      throw new ChromeBinaryUnavailableError(source, path, SPARTICUZ_WEDGE_HINT);
+    }
+    return path;
+  }
+  const explicit = process.env.HYPERFRAMES_LAMBDA_CHROME_PATH;
+  if (!explicit) {
+    throw new ChromeBinaryUnavailableError(
+      source,
+      null,
+      "HYPERFRAMES_LAMBDA_CHROME_SOURCE=chrome-headless-shell requires HYPERFRAMES_LAMBDA_CHROME_PATH to be set to the absolute path of the bundled binary."
+    );
+  }
+  if (!existsSync(explicit)) {
+    throw new ChromeBinaryUnavailableError(
+      source,
+      explicit,
+      `HYPERFRAMES_LAMBDA_CHROME_PATH=${JSON.stringify(explicit)} does not exist on disk.`
+    );
+  }
+  return explicit;
+}
+async function resolveChromeArgs() {
+  if (resolveChromeSource() !== "sparticuz") return [];
+  const mod = await loadSparticuzChromium();
+  return mod.args;
+}
+var cachedSparticuz = null;
+async function loadSparticuzChromium() {
+  if (cachedSparticuz) return cachedSparticuz;
+  const mod = await import("@sparticuz/chromium");
+  const resolved = "default" in mod ? mod.default : mod;
+  cachedSparticuz = resolved;
+  return resolved;
+}
+
+// src/s3Stitch.ts
+import {
+  AbortMultipartUploadCommand,
+  CompleteMultipartUploadCommand,
+  CreateMultipartUploadCommand,
+  GetObjectCommand,
+  UploadPartCommand,
+  UploadPartCopyCommand
+} from "@aws-sdk/client-s3";
+import { buildStitchedHeader, readMp4Layout } from "@hyperframes/producer/distributed";
+var MIN_PART_BYTES = 5 * 1024 * 1024;
+var segmentSize = (s) => "bytes" in s ? s.bytes.length : s.end - s.start;
+function planParts(segments, min = MIN_PART_BYTES) {
+  const parts = [];
+  let pending = [];
+  let pendingSize = 0;
+  const flush = () => {
+    if (pending.length) parts.push({ upload: pending });
+    pending = [];
+    pendingSize = 0;
+  };
+  for (const segment of segments) {
+    const borrow = pendingSize ? min - pendingSize : 0;
+    if ("uri" in segment && segmentSize(segment) - borrow >= min) {
+      if (borrow) pending.push({ ...segment, end: segment.start + borrow });
+      flush();
+      parts.push({ copy: { ...segment, start: segment.start + borrow } });
+      continue;
+    }
+    pending.push(segment);
+    pendingSize += segmentSize(segment);
+    if (pendingSize >= min) flush();
+  }
+  flush();
+  return parts;
+}
+async function getRange(s3, uri, start, end) {
+  const { bucket, key } = parseS3Uri(uri);
+  const response = await s3.send(
+    new GetObjectCommand({ Bucket: bucket, Key: key, Range: `bytes=${start}-${end - 1}` })
+  );
+  if (!response.Body) throw new Error(`[s3Stitch] empty body for ${uri}`);
+  return Buffer.from(await response.Body.transformToByteArray());
+}
+async function sendPart(s3, part, partNumber, target) {
+  if ("copy" in part) {
+    const { uri, start, end } = part.copy;
+    const source = parseS3Uri(uri);
+    const result2 = await s3.send(
+      new UploadPartCopyCommand({
+        ...target,
+        PartNumber: partNumber,
+        CopySource: encodeURI(`${source.bucket}/${source.key}`),
+        CopySourceRange: `bytes=${start}-${end - 1}`
+      })
+    );
+    return result2.CopyPartResult?.ETag;
+  }
+  const body = await Promise.all(
+    part.upload.map((s) => "bytes" in s ? s.bytes : getRange(s3, s.uri, s.start, s.end))
+  );
+  const result = await s3.send(
+    new UploadPartCommand({ ...target, PartNumber: partNumber, Body: Buffer.concat(body) })
+  );
+  return result.ETag;
+}
+async function sendParts(s3, parts, target) {
+  const settled = await Promise.allSettled(
+    parts.map(async (part, index) => {
+      const etag = await sendPart(s3, part, index + 1, target);
+      if (!etag) throw new Error(`[s3Stitch] part ${index + 1} returned no ETag`);
+      return etag;
+    })
+  );
+  const failure = settled.find(
+    (result) => result.status === "rejected"
+  );
+  if (failure) throw failure.reason;
+  return settled.map((result) => result.value);
+}
+async function uploadParts(s3, parts, destUri, contentType) {
+  const { bucket, key } = parseS3Uri(destUri);
+  const created = await s3.send(
+    new CreateMultipartUploadCommand({ Bucket: bucket, Key: key, ContentType: contentType })
+  );
+  if (!created.UploadId) throw new Error(`[s3Stitch] no upload id for ${destUri}`);
+  const target = { Bucket: bucket, Key: key, UploadId: created.UploadId };
+  try {
+    const etags = await sendParts(s3, parts, target);
+    await s3.send(
+      new CompleteMultipartUploadCommand({
+        ...target,
+        MultipartUpload: { Parts: etags.map((ETag, index) => ({ ETag, PartNumber: index + 1 })) }
+      })
+    );
+  } catch (error) {
+    await s3.send(new AbortMultipartUploadCommand(target)).catch((abortError) => {
+      console.error(
+        `[s3Stitch] abort failed for ${destUri}; parts remain until a lifecycle rule removes them`,
+        abortError
+      );
+    });
+    throw error;
+  }
+}
+async function stitchMp4InS3(s3, chunkUris, destUri, minPartBytes = MIN_PART_BYTES) {
+  const layouts = await Promise.all(
+    chunkUris.map((uri) => readMp4Layout((start, end) => getRange(s3, uri, start, end)))
+  );
+  const segments = [
+    { bytes: buildStitchedHeader(layouts) },
+    ...layouts.map((layout, i) => ({
+      uri: chunkUris[i],
+      start: layout.payloadStart,
+      end: layout.payloadEnd
+    }))
+  ];
+  const parts = planParts(segments, minPartBytes);
+  await uploadParts(s3, parts, destUri, "video/mp4");
+  const uploaded = parts.flatMap((part) => "upload" in part ? part.upload : []);
+  return {
+    fileSize: segments.reduce((total, s) => total + segmentSize(s), 0),
+    parts: parts.length,
+    downloadedBytes: uploaded.reduce((total, s) => total + ("uri" in s ? segmentSize(s) : 0), 0)
+  };
+}
+
+// src/s3PlanV2Publisher.ts
+import { createHash } from "node:crypto";
+import { mkdirSync, mkdtempSync, rmSync, statSync, 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 assertSha256(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 (!isRecord(value) || !Array.isArray(value.artifacts)) {
+    throw new PlanV2IntegrityError("S3 publisher manifest requires an artifacts array");
+  }
+  return new Set(
+    value.artifacts.map((artifact, index) => {
+      if (!isRecord(artifact)) {
+        throw new PlanV2IntegrityError(`S3 publisher artifacts[${index}] must be an object`);
+      }
+      return assertSha256(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;
+  #bucket;
+  #temporaryRoot;
+  #publishedDigests = /* @__PURE__ */ new Set();
+  #state = "open";
+  constructor(options) {
+    const outputPrefix = `${trimTrailingSlash(options.planOutputS3Prefix)}/v2`;
+    const { bucket } = parseS3Uri(outputPrefix);
+    this.#s3 = options.s3;
+    this.#bucket = bucket;
+    this.artifactPrefix = formatS3Uri({ bucket, key: CONTENT_STORE_PREFIX });
+    this.manifestUri = `${outputPrefix}/manifest.json`;
+    this.#temporaryRoot = options.temporaryRoot ?? tmpdir();
+    mkdirSync(this.#temporaryRoot, { recursive: true });
+  }
+  async putBlob(blob) {
+    this.#assertOpen("publish a blob");
+    const digest = assertSha256(blob.sha256, "S3 published blob sha256");
+    if (this.#publishedDigests.has(digest)) return;
+    const sourceSize = statSync(blob.sourcePath).size;
+    if (sourceSize !== blob.sizeBytes) {
+      throw new PlanV2IntegrityError(
+        `S3 published blob size changed for ${digest}: expected ${blob.sizeBytes}, got ${sourceSize}`
+      );
+    }
+    await putContentStoreFile(this.#s3, blob.sourcePath, this.#bucket, digest);
+    this.#publishedDigests.add(digest);
+  }
+  async referenceStoredBlob(blob) {
+    this.#assertOpen("reference a stored blob");
+    const digest = assertSha256(blob.sha256, "S3 referenced blob sha256");
+    await ensureContentStoreObject(this.#s3, this.#bucket, digest, blob.sizeBytes);
+    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 = createHash("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 {
+      rmSync(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() {
+  if (cachedS3Client) return cachedS3Client;
+  cachedS3Client = new S3Client({});
+  return cachedS3Client;
+}
+async function handler(event, deps) {
+  const unwrapped = unwrapEvent(event);
+  validatePlanProtocolShape(unwrapped);
+  validateEventS3Uris(unwrapped);
+  primeRuntimeEnv();
+  logEvent({ event: "handler_start", action: unwrapped.Action, input: summarizeEvent(unwrapped) });
+  try {
+    switch (unwrapped.Action) {
+      case "plan":
+        return await handlePlan(unwrapped, deps);
+      case "renderChunk":
+        return await handleRenderChunk(unwrapped, deps);
+      case "assemble":
+        return await handleAssemble(unwrapped, deps);
+      default: {
+        const _exhaustive = unwrapped;
+        throw new Error(
+          `[handler] unknown Action: ${JSON.stringify(
+            _exhaustive.Action
+          )}. Expected one of "plan", "renderChunk", "assemble".`
+        );
+      }
+    }
+  } 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.code === "FONT_FETCH_FAILED" || candidate.code === "FONT_FETCH_UNAVAILABLE" || candidate.code === "NOT_MEDIA_PAYLOAD" || candidate.code === "VIDEO_SOURCE_UNRENDERABLE" || candidate.code === "VIDEO_EXTRACTION_FAILED" || candidate.code === "INVALID_VIDEO_METADATA" || candidate.code === "FORMAT_NOT_SUPPORTED_IN_DISTRIBUTED" || candidate.code === "CHUNK_EXCEEDS_WORKER_TIMEOUT") {
+    candidate.name = candidate.code;
+  }
+}
+var MAX_ENVELOPE_DEPTH = 4;
+function unwrapEvent(event) {
+  let cursor = event;
+  for (let i = 0; i < MAX_ENVELOPE_DEPTH; i++) {
+    if (cursor && typeof cursor === "object") {
+      const obj = cursor;
+      if (typeof obj.Action === "string" && isLambdaAction(obj.Action)) {
+        return cursor;
+      }
+      if ("Payload" in obj) {
+        cursor = obj.Payload;
+        continue;
+      }
+      if ("Input" in obj) {
+        cursor = obj.Input;
+        continue;
+      }
+    }
+    break;
+  }
+  throw new Error(
+    `[handler] event has no recognised Action; unwrapped ${MAX_ENVELOPE_DEPTH} levels of Payload/Input without finding one.`
+  );
+}
+function isLambdaAction(value) {
+  return value === "plan" || value === "renderChunk" || value === "assemble";
+}
+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 effectiveProtocol = protocol ?? "v2";
+  const hasV1Locator = typeof raw.PlanS3Uri === "string";
+  const hasV2Manifest = typeof raw.PlanV2ManifestS3Uri === "string";
+  const hasV2Prefix = typeof raw.PlanV2ArtifactS3Prefix === "string";
+  const valid = effectiveProtocol === "v2" ? !hasV1Locator && hasV2Manifest && hasV2Prefix : hasV1Locator && !hasV2Manifest && !hasV2Prefix;
+  if (!valid) {
+    const error = new Error(
+      `[handler] ${effectiveProtocol} ${event.Action} event has mixed or missing plan locators`
+    );
+    error.name = "PLAN_PROTOCOL_UNSUPPORTED";
+    throw error;
+  }
+  if (effectiveProtocol === "v2" && event.Action === "assemble" && event.AudioS3Uri !== null) {
+    const error = new Error("[handler] v2 assemble audio must be materialized from the manifest");
+    error.name = "PLAN_PROTOCOL_UNSUPPORTED";
+    throw error;
+  }
+}
+function logEvent(payload) {
+  console.log(JSON.stringify(payload));
+}
+function summarizeEvent(event) {
+  switch (event.Action) {
+    case "plan":
+      return {
+        projectS3Uri: event.ProjectS3Uri,
+        planOutputS3Prefix: event.PlanOutputS3Prefix,
+        planProtocol: event.PlanProtocol ?? "v2",
+        format: event.Config.format,
+        fps: event.Config.fps
+      };
+    case "renderChunk":
+      return {
+        planProtocol: event.PlanProtocol ?? "v2",
+        ...event.PlanProtocol !== "v1" ? { planV2ManifestS3Uri: event.PlanV2ManifestS3Uri } : { planS3Uri: event.PlanS3Uri },
+        chunkIndex: event.ChunkIndex,
+        format: event.Format
+      };
+    case "assemble":
+      return {
+        planProtocol: event.PlanProtocol ?? "v2",
+        ...event.PlanProtocol !== "v1" ? { planV2ManifestS3Uri: event.PlanV2ManifestS3Uri } : { planS3Uri: event.PlanS3Uri },
+        chunkCount: event.ChunkS3Uris.length,
+        hasAudio: event.AudioS3Uri !== null,
+        outputS3Uri: event.OutputS3Uri,
+        format: event.Format
+      };
+  }
+}
+var runtimeEnvPrimed = false;
+function primeRuntimeEnv() {
+  if (runtimeEnvPrimed) return;
+  runtimeEnvPrimed = true;
+  const taskRoot = process.env.LAMBDA_TASK_ROOT ?? "/var/task";
+  const bin = join2(taskRoot, "bin");
+  if (existsSync2(bin)) {
+    process.env.PATH = `${bin}:${process.env.PATH ?? ""}`;
+  }
+}
+var ACCOUNT_CONCURRENCY_SHARE = 0.9;
+async function resolveWorkerConcurrency(event, deps) {
+  if (event.Config.workerConcurrency !== void 0) return event.Config.workerConcurrency;
+  try {
+    return await functionConcurrency(deps?.lambda);
+  } catch (err) {
+    logEvent({
+      event: "worker_concurrency",
+      level: "WARN",
+      source: "fallback",
+      concurrency: DEFAULT_MAX_PARALLEL_CHUNKS,
+      message: `Could not read the account's Lambda concurrency (${String(err)}); planning for ${DEFAULT_MAX_PARALLEL_CHUNKS} chunks at once. Allow lambda:GetAccountSettings on the function role, or set the concurrency explicitly.`
+    });
+    return DEFAULT_MAX_PARALLEL_CHUNKS;
+  }
+}
+async function functionConcurrency(lambda = new LambdaClient({})) {
+  const reserved = Number(process.env.HYPERFRAMES_LAMBDA_RESERVED_CONCURRENCY);
+  if (reserved > 0) return reserved;
+  const { AccountLimit } = await lambda.send(new GetAccountSettingsCommand({}));
+  const unreserved = AccountLimit?.UnreservedConcurrentExecutions;
+  if (unreserved === void 0) throw new Error("no UnreservedConcurrentExecutions in the reply");
+  const concurrency = Math.max(1, Math.floor(unreserved * ACCOUNT_CONCURRENCY_SHARE));
+  logEvent({ event: "worker_concurrency", source: "account", unreserved, concurrency });
+  return concurrency;
+}
+async function planConfig(event, deps) {
+  const config = {
+    ...event.Config,
+    workerConcurrency: await resolveWorkerConcurrency(event, deps)
+  };
+  const remainingMs = deps?.getRemainingTimeInMillis?.();
+  if (config.workerTimeoutSeconds === void 0 && remainingMs !== void 0) {
+    config.workerTimeoutSeconds = Math.ceil(remainingMs / 1e3);
+  }
+  return config;
+}
+async function handlePlan(event, deps) {
+  if (event.PlanProtocol !== "v1") {
+    return handlePlanV2(event, deps);
+  }
+  const started = Date.now();
+  const config = await planConfig(event, deps);
+  const s3 = deps?.s3 ?? getS3Client();
+  const primitive = deps?.primitives?.plan ?? plan;
+  if (!deps?.skipChromeResolution && !process.env.PRODUCER_HEADLESS_SHELL_PATH) {
+    const chromePath = await resolveChromeExecutablePath();
+    process.env.PRODUCER_HEADLESS_SHELL_PATH = chromePath;
+  }
+  const work = mkdtempSync2(join2(deps?.tmpRoot ?? tmpdir2(), "hf-lambda-plan-"));
+  const planDir = join2(work, "plan");
+  try {
+    const { projectDir } = await fetchProject(s3, event.ProjectS3Uri, work);
+    const result = await primitive(projectDir, config, planDir, {
+      chunksCarryAudio: true
+    });
+    const planTar = join2(work, "plan.tar.gz");
+    await tarDirectory(planDir, planTar);
+    const planTarUri = `${trimTrailingSlash2(event.PlanOutputS3Prefix)}/plan.tar.gz`;
+    const audioPath = join2(planDir, PLAN_AUDIO_RELATIVE_PATH);
+    const hasAudio = existsSync2(audioPath) && statSync2(audioPath).size > 0;
+    const audioUri = hasAudio ? `${trimTrailingSlash2(event.PlanOutputS3Prefix)}/${PLAN_AUDIO_RELATIVE_PATH}` : null;
+    await Promise.all([
+      uploadFileToS3(s3, planTar, planTarUri, "application/gzip"),
+      hasAudio && audioUri ? uploadFileToS3(s3, audioPath, audioUri, "audio/aac") : null
+    ]);
+    return {
+      Action: "plan",
+      PlanS3Uri: planTarUri,
+      PlanHash: result.planHash,
+      ChunkCount: result.chunkCount,
+      MaxChunkConcurrency: Math.min(config.workerConcurrency, result.chunkCount),
+      TotalFrames: result.totalFrames,
+      Fps: result.fps,
+      Width: result.width,
+      Height: result.height,
+      Format: result.format,
+      HasAudio: audioUri !== null,
+      AudioS3Uri: audioUri,
+      FfmpegVersion: result.ffmpegVersion,
+      ProducerVersion: result.producerVersion,
+      DurationMs: Date.now() - started
+    };
+  } finally {
+    cleanupDir(work);
+  }
+}
+async function fetchProject(s3, projectS3Uri, work, leaveVideosRemote = false) {
+  const projectDir = join2(work, "project");
+  if (isSiteManifestUri(projectS3Uri)) {
+    const remoteFiles = await downloadSiteFiles(s3, projectS3Uri, projectDir, leaveVideosRemote);
+    return { projectDir, remoteFiles };
+  }
+  const projectArchive = join2(work, "project.tar.gz");
+  let stageStarted = Date.now();
+  await downloadS3ObjectToFile(s3, projectS3Uri, projectArchive);
+  logEvent({ event: "plan_stage", stage: "download", ms: Date.now() - stageStarted });
+  stageStarted = Date.now();
+  await untarDirectory(projectArchive, projectDir);
+  logEvent({ event: "plan_stage", stage: "untar", ms: Date.now() - stageStarted });
+  return { projectDir, remoteFiles: {} };
+}
+async function handlePlanV2(event, deps) {
+  const started = Date.now();
+  const config = await planConfig(event, deps);
+  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-"));
+  try {
+    const { projectDir, remoteFiles } = await fetchProject(s3, event.ProjectS3Uri, work, true);
+    const publisher = new S3PlanV2ArtifactPublisher({
+      s3,
+      planOutputS3Prefix: event.PlanOutputS3Prefix,
+      temporaryRoot: work
+    });
+    const manifest = await primitive(projectDir, config, publisher, {
+      stagingParentDir: work,
+      remoteFiles,
+      chunksCarryAudio: true
+    });
+    return {
+      Action: "plan",
+      PlanProtocol: "v2",
+      PlanV2ManifestS3Uri: publisher.manifestUri,
+      PlanV2ArtifactS3Prefix: publisher.artifactPrefix,
+      PlanHash: manifest.planHash,
+      ChunkCount: manifest.chunkCount,
+      MaxChunkConcurrency: Math.min(config.workerConcurrency, manifest.chunkCount),
+      TotalFrames: manifest.totalFrames,
+      Fps: manifest.fps,
+      Width: manifest.width,
+      Height: manifest.height,
+      Format: manifest.format,
+      HasAudio: manifest.artifacts.some((artifact) => isPlanAudioArtifactPath(artifact.path)),
+      AudioS3Uri: null,
+      FfmpegVersion: manifest.ffmpegVersion,
+      ProducerVersion: manifest.producerVersion,
+      DurationMs: Date.now() - started
+    };
+  } finally {
+    cleanupDir(work);
+  }
+}
+async function handleRenderChunk(event, deps) {
+  if (event.PlanProtocol !== "v1") {
+    return 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) {
+    const chromePath = await resolveChromeExecutablePath();
+    process.env.PRODUCER_HEADLESS_SHELL_PATH = chromePath;
+  }
+  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 = 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,
+      CaptureMode: result.captureMode,
+      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)}`
+    );
+    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,
+      CaptureMode: result.captureMode,
+      DurationMs: Date.now() - started
+    };
+  } finally {
+    cleanupDir(work);
+  }
+}
+async function uploadChunkOutput(s3, result, prefix, chunkIndex) {
+  const trimmed = trimTrailingSlash2(prefix);
+  if (result.outputKind === "file") {
+    const ext = result.outputPath.slice(result.outputPath.lastIndexOf("."));
+    const uri2 = `${trimmed}/chunks/${pad(chunkIndex)}${ext}`;
+    await uploadFileToS3(s3, result.outputPath, uri2);
+    return uri2;
+  }
+  const tarball = `${result.outputPath}.tar.gz`;
+  await tarDirectory(result.outputPath, tarball);
+  const uri = `${trimmed}/chunks/${pad(chunkIndex)}.tar.gz`;
+  await uploadFileToS3(s3, tarball, uri, "application/gzip");
+  return uri;
+}
+async function handleAssemble(event, deps) {
+  if (event.PlanProtocol !== "v1") {
+    return 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-"));
+  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 = resolvePlanAudioPath(planDir) ?? join2(planDir, PLAN_AUDIO_RELATIVE_PATH);
+      await downloadS3ObjectToFile(s3, event.AudioS3Uri, audioPath);
+    }
+    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 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, manifest } = await downloadAndMaterializePlanV2(
+      s3,
+      event,
+      { role: "assembler" },
+      work
+    );
+    if (chunksAreStitchedMp4(planDir, event.Cfr === true)) {
+      return await stitchChunksInS3(s3, event, manifest, started);
+    }
+    const audioPath = resolvePlanAudioPath(planDir);
+    const chunksStarted = Date.now();
+    const chunkPaths = await downloadChunkObjects(s3, event.ChunkS3Uris, work, event.Format);
+    const chunksMs = Date.now() - chunksStarted;
+    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
+    });
+    const uploadStarted = Date.now();
+    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);
+    }
+    logEvent({
+      event: "assemble_stages",
+      planMs: chunksStarted - started,
+      chunksMs,
+      assembleMs: result.durationMs,
+      uploadMs: Date.now() - uploadStarted
+    });
+    return {
+      Action: "assemble",
+      OutputS3Uri: event.OutputS3Uri,
+      FramesEncoded: result.framesEncoded,
+      FileSize: result.fileSize,
+      DurationMs: Date.now() - started
+    };
+  } finally {
+    cleanupDir(work);
+  }
+}
+async function stitchChunksInS3(s3, event, plan2, started) {
+  if (event.ChunkS3Uris.length !== plan2.chunkCount) {
+    throw new Error(
+      `[handler] ${event.ChunkS3Uris.length} chunk URIs for a plan of ${plan2.chunkCount} chunks`
+    );
+  }
+  const stitchStarted = Date.now();
+  const stitched = await stitchMp4InS3(s3, event.ChunkS3Uris, event.OutputS3Uri);
+  logEvent({
+    event: "assemble_stages",
+    mode: "s3-stitch",
+    planMs: stitchStarted - started,
+    stitchMs: Date.now() - stitchStarted,
+    parts: stitched.parts,
+    downloadedBytes: stitched.downloadedBytes
+  });
+  return {
+    Action: "assemble",
+    OutputS3Uri: event.OutputS3Uri,
+    FramesEncoded: plan2.totalFrames,
+    FileSize: stitched.fileSize,
+    DurationMs: Date.now() - started
+  };
+}
+async function downloadAndMaterializePlanV2(s3, event, target, work) {
+  const transportDir = join2(work, "plan-v2");
+  mkdirSync2(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 remoteSources = await presignDeferredSources(s3, event.PlanV2ArtifactS3Prefix, artifacts);
+  const uniqueArtifacts = [
+    ...new Map(
+      artifacts.filter((artifact) => !Object.hasOwn(remoteSources, artifact.path)).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, { remoteSources });
+  return { planDir, manifest };
+}
+var DEFERRED_SOURCE_URL_TTL_SECONDS = 3600;
+async function presignDeferredSources(s3, artifactPrefix, artifacts) {
+  const entries = await Promise.all(
+    artifacts.filter(isPlanV2DeferredSourceArtifact).map(
+      async (artifact) => [
+        artifact.path,
+        await presignVerifiedS3GetUrl(
+          s3,
+          planV2BlobUri(artifactPrefix, artifact.sha256),
+          artifact.sha256,
+          artifact.sizeBytes,
+          DEFERRED_SOURCE_URL_TTL_SECONDS
+        )
+      ]
+    )
+  );
+  return Object.fromEntries(entries);
+}
+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 downloadChunkObjects(s3, uris, workDir, format) {
+  const chunksDir = join2(workDir, "chunks");
+  mkdirSync2(chunksDir, { recursive: true });
+  const local = new Array(uris.length);
+  await Promise.all(
+    uris.map(async (uri, i) => {
+      if (!uri) {
+        throw new Error(`[handler] chunk URI at index ${i} is empty`);
+      }
+      const { key } = parseS3Uri(uri);
+      const localPath = join2(chunksDir, basename(key));
+      await downloadS3ObjectToFile(s3, uri, localPath);
+      if (format === "png-sequence") {
+        const dirPath = join2(chunksDir, `frames-${pad(i)}`);
+        await untarDirectory(localPath, dirPath);
+        local[i] = dirPath;
+      } else {
+        local[i] = localPath;
+      }
+    })
+  );
+  return local;
+}
+function getEventS3Uris(event) {
+  switch (event.Action) {
+    case "plan":
+      return [event.ProjectS3Uri, event.PlanOutputS3Prefix];
+    case "renderChunk":
+      return event.PlanProtocol !== "v1" ? [event.PlanV2ManifestS3Uri, event.PlanV2ArtifactS3Prefix, event.ChunkOutputS3Prefix] : [event.PlanS3Uri, event.ChunkOutputS3Prefix];
+    case "assemble":
+      return [
+        ...event.PlanProtocol !== "v1" ? [event.PlanV2ManifestS3Uri, event.PlanV2ArtifactS3Prefix] : [event.PlanS3Uri],
+        ...event.ChunkS3Uris,
+        event.OutputS3Uri,
+        event.AudioS3Uri
+      ].filter((u) => u != null);
+  }
+}
+function validateEventS3Uris(event) {
+  const allowedBucket = process.env.HYPERFRAMES_RENDER_BUCKET?.trim();
+  if (!allowedBucket) return;
+  for (const uri of getEventS3Uris(event)) {
+    const { bucket } = parseS3Uri(uri);
+    if (bucket !== allowedBucket) {
+      const err = new Error(
+        `[handler] S3_URI_NOT_ALLOWED: URI ${JSON.stringify(uri)} targets bucket "${bucket}" but only "${allowedBucket}" is permitted`
+      );
+      err.name = "S3_URI_NOT_ALLOWED";
+      throw err;
+    }
+  }
+}
+function pad(n) {
+  return n.toString().padStart(4, "0");
+}
+function trimTrailingSlash2(prefix) {
+  return prefix.endsWith("/") ? prefix.slice(0, -1) : prefix;
+}
+function cleanupDir(dir) {
+  try {
+    rmSync2(dir, { recursive: true, force: true });
+  } catch {
+  }
+}
+function verifyPlanHash(planDir, expected) {
+  const planJsonPath = join2(planDir, "plan.json");
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(planJsonPath, "utf-8"));
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    const error = new Error(`PLAN_HASH_MISMATCH: failed to read ${planJsonPath}: ${msg}`);
+    error.name = "PLAN_HASH_MISMATCH";
+    throw error;
+  }
+  const actual = parsed.planHash;
+  if (typeof actual !== "string" || actual !== expected) {
+    const error = new Error(
+      `PLAN_HASH_MISMATCH: event PlanHash=${expected} did not match plan.json planHash=${String(actual)}`
+    );
+    error.name = "PLAN_HASH_MISMATCH";
+    throw error;
+  }
+}
+
+export {
+  ChromeBinaryUnavailableError,
+  resolveChromeSource,
+  resolveChromeExecutablePath,
+  resolveChromeArgs,
+  S3PlanV2ArtifactPublisher,
+  handler,
+  unwrapEvent
+};