@hyperframes/aws-lambda 0.8.172 → 0.8.174

package/dist/cdk/index.js

@@ -3,6 +3,7 @@ import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { Duration, RemovalPolicy, Size } from "aws-cdk-lib";
 import * as cloudwatch from "aws-cdk-lib/aws-cloudwatch";
+import * as iam from "aws-cdk-lib/aws-iam";
 import * as lambda from "aws-cdk-lib/aws-lambda";
 import * as logs from "aws-cdk-lib/aws-logs";
 import * as s3 from "aws-cdk-lib/aws-s3";
@@ -59,10 +60,14 @@ var HyperframesRenderStack = class extends Construct {
         NODE_OPTIONS: "--enable-source-maps",
         TMPDIR: "/tmp",
         HYPERFRAMES_LAMBDA_CHROME_SOURCE: chromeSource,
-        HYPERFRAMES_RENDER_BUCKET: this.bucket.bucketName
+        HYPERFRAMES_RENDER_BUCKET: this.bucket.bucketName,
+        HYPERFRAMES_LAMBDA_RESERVED_CONCURRENCY: String(props.reservedConcurrency ?? -1)
       }
     });
     this.bucket.grantReadWrite(this.renderFunction);
+    this.renderFunction.addToRolePolicy(
+      new iam.PolicyStatement({ actions: ["lambda:GetAccountSettings"], resources: ["*"] })
+    );
     const stateMachineLogGroup = new logs.LogGroup(this, "RenderStateMachineLogGroup", {
       logGroupName: `/aws/states/${projectName}-render`,
       retention: logs.RetentionDays.ONE_MONTH,
@@ -143,6 +148,7 @@ var HyperframesRenderStack = class extends Construct {
       "PlanV2IntegrityError",
       "PLAN_ARTIFACT_DIGEST_MISMATCH",
       "FORMAT_NOT_SUPPORTED_IN_DISTRIBUTED",
+      "CHUNK_EXCEEDS_WORKER_TIMEOUT",
       "ChromeBinaryUnavailableError"
     ];
     const NON_RETRYABLE_CHUNK = [
@@ -174,6 +180,14 @@ var HyperframesRenderStack = class extends Construct {
       "PLAN_ARTIFACT_DIGEST_MISMATCH",
       "ChromeBinaryUnavailableError"
     ];
+    const THROTTLED_RETRY = {
+      errors: ["Lambda.TooManyRequestsException"],
+      interval: Duration.seconds(5),
+      maxAttempts: 10,
+      backoffRate: 2,
+      maxDelay: Duration.seconds(60),
+      jitterStrategy: sfn.JitterType.FULL
+    };
     const plan = new tasks.LambdaInvoke(this, "Plan", {
       lambdaFunction: this.renderFunction,
       payload: sfn.TaskInput.fromObject({
@@ -188,6 +202,7 @@ var HyperframesRenderStack = class extends Construct {
         "PlanS3Uri.$": "$.Payload.PlanS3Uri",
         "PlanHash.$": "$.Payload.PlanHash",
         "ChunkCount.$": "$.Payload.ChunkCount",
+        "MaxChunkConcurrency.$": "$.Payload.MaxChunkConcurrency",
         "Format.$": "$.Payload.Format",
         "HasAudio.$": "$.Payload.HasAudio",
         "AudioS3Uri.$": "$.Payload.AudioS3Uri"
@@ -198,6 +213,7 @@ var HyperframesRenderStack = class extends Construct {
       errors: NON_RETRYABLE_PLAN,
       maxAttempts: 0
     });
+    plan.addRetry(THROTTLED_RETRY);
     plan.addRetry({
       errors: ["States.ALL"],
       interval: Duration.seconds(2),
@@ -220,12 +236,14 @@ var HyperframesRenderStack = class extends Construct {
         "PlanV2ArtifactS3Prefix.$": "$.Payload.PlanV2ArtifactS3Prefix",
         "PlanHash.$": "$.Payload.PlanHash",
         "ChunkCount.$": "$.Payload.ChunkCount",
+        "MaxChunkConcurrency.$": "$.Payload.MaxChunkConcurrency",
         "Format.$": "$.Payload.Format",
         "HasAudio.$": "$.Payload.HasAudio"
       },
       resultPath: "$.Plan"
     });
     planV2.addRetry({ errors: NON_RETRYABLE_PLAN, maxAttempts: 0 });
+    planV2.addRetry(THROTTLED_RETRY);
     planV2.addRetry({
       errors: ["States.ALL"],
       interval: Duration.seconds(2),
@@ -257,13 +275,16 @@ var HyperframesRenderStack = class extends Construct {
       resultSelector: {
         "ChunkS3Uri.$": "$.Payload.ChunkS3Uri",
         "ChunkIndex.$": "$.Payload.ChunkIndex",
-        "Sha256.$": "$.Payload.Sha256"
+        "Sha256.$": "$.Payload.Sha256",
+        "FramesEncoded.$": "$.Payload.FramesEncoded",
+        "DurationMs.$": "$.Payload.DurationMs"
       }
     });
     renderChunkTask.addRetry({
       errors: NON_RETRYABLE_CHUNK,
       maxAttempts: 0
     });
+    renderChunkTask.addRetry(THROTTLED_RETRY);
     renderChunkTask.addRetry({
       errors: ["States.ALL"],
       interval: Duration.seconds(2),
@@ -271,7 +292,10 @@ var HyperframesRenderStack = class extends Construct {
       backoffRate: 2,
       maxDelay: Duration.seconds(60)
     });
-    const renderChunks = new sfn.Map(this, "RenderChunks", {
+    const renderChunks = new sfn.DistributedMap(this, "RenderChunks", {
+      label: "RenderChunks",
+      // Standard-type children: express ones stop at 5 minutes and a chunk may run the Lambda's full 15.
+      mapExecutionType: sfn.StateMachineType.STANDARD,
       itemsPath: "$.Iterator.ChunkIndexes",
       itemSelector: {
         "ChunkIndex.$": "$$.Map.Item.Value",
@@ -280,7 +304,8 @@ var HyperframesRenderStack = class extends Construct {
         "ChunkOutputS3Prefix.$": "$.PlanOutputS3Prefix",
         "Format.$": "$.Plan.Format"
       },
-      maxConcurrencyPath: "$.Plan.ChunkCount",
+      // Chunks past the plan's concurrency queue here instead of being throttled by Lambda.
+      maxConcurrencyPath: "$.Plan.MaxChunkConcurrency",
       resultPath: "$.Chunks"
     });
     renderChunks.itemProcessor(renderChunkTask);
@@ -306,6 +331,7 @@ var HyperframesRenderStack = class extends Construct {
       errors: NON_RETRYABLE_ASSEMBLE,
       maxAttempts: 0
     });
+    assemble.addRetry(THROTTLED_RETRY);
     assemble.addRetry({
       errors: ["States.ALL"],
       interval: Duration.seconds(2),
@@ -328,10 +354,13 @@ var HyperframesRenderStack = class extends Construct {
       resultSelector: {
         "ChunkS3Uri.$": "$.Payload.ChunkS3Uri",
         "ChunkIndex.$": "$.Payload.ChunkIndex",
-        "Sha256.$": "$.Payload.Sha256"
+        "Sha256.$": "$.Payload.Sha256",
+        "FramesEncoded.$": "$.Payload.FramesEncoded",
+        "DurationMs.$": "$.Payload.DurationMs"
       }
     });
     renderChunkV2Task.addRetry({ errors: NON_RETRYABLE_CHUNK, maxAttempts: 0 });
+    renderChunkV2Task.addRetry(THROTTLED_RETRY);
     renderChunkV2Task.addRetry({
       errors: ["States.ALL"],
       interval: Duration.seconds(2),
@@ -339,7 +368,9 @@ var HyperframesRenderStack = class extends Construct {
       backoffRate: 2,
       maxDelay: Duration.seconds(60)
     });
-    const renderChunksV2 = new sfn.Map(this, "RenderChunksV2", {
+    const renderChunksV2 = new sfn.DistributedMap(this, "RenderChunksV2", {
+      label: "RenderChunksV2",
+      mapExecutionType: sfn.StateMachineType.STANDARD,
       itemsPath: "$.Iterator.ChunkIndexes",
       itemSelector: {
         "ChunkIndex.$": "$$.Map.Item.Value",
@@ -349,7 +380,7 @@ var HyperframesRenderStack = class extends Construct {
         "ChunkOutputS3Prefix.$": "$.PlanOutputS3Prefix",
         "Format.$": "$.Plan.Format"
       },
-      maxConcurrencyPath: "$.Plan.ChunkCount",
+      maxConcurrencyPath: "$.Plan.MaxChunkConcurrency",
       resultPath: "$.Chunks"
     });
     renderChunksV2.itemProcessor(renderChunkV2Task);
@@ -374,6 +405,7 @@ var HyperframesRenderStack = class extends Construct {
       resultPath: "$.Output"
     });
     assembleV2.addRetry({ errors: NON_RETRYABLE_ASSEMBLE, maxAttempts: 0 });
+    assembleV2.addRetry(THROTTLED_RETRY);
     assembleV2.addRetry({
       errors: ["States.ALL"],
       interval: Duration.seconds(2),

package/dist/events.d.ts

@@ -140,6 +140,7 @@ interface PlanLambdaResultBase {
     Action: "plan";
     PlanHash: string;
     ChunkCount: number;
+    MaxChunkConcurrency: number;
     TotalFrames: number;
     Fps: SerializableDistributedRenderConfig["fps"];
     Width: number;

package/dist/handler.d.ts

@@ -10,6 +10,7 @@
  * primitives. The handler is thin glue: parse event → S3 download → call
  * primitive → S3 upload → return small JSON result.
  */
+import { LambdaClient } from "@aws-sdk/client-lambda";
 import { S3Client } from "@aws-sdk/client-s3";
 import { assemble, type ChunkRenderer, plan, planV2WithPublisher } from "@hyperframes/producer/distributed";
 import type { AssembleEvent, LambdaEvent, LambdaResult, PlanEvent, RenderChunkEvent } from "./events.js";
@@ -22,6 +23,8 @@ import type { AssembleEvent, LambdaEvent, LambdaResult, PlanEvent, RenderChunkEv
  */
 export interface HandlerDeps {
     s3?: S3Client;
+    /** Reads the account's concurrency when the render does not set one. */
+    lambda?: LambdaClient;
     primitives?: {
         plan: typeof plan;
         planV2WithPublisher?: typeof planV2WithPublisher;

package/dist/handler.js

@@ -2,9 +2,12 @@
 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 { GetAccountSettingsCommand, LambdaClient } from "@aws-sdk/client-lambda";
 import { S3Client } from "@aws-sdk/client-s3";
 import {
   assemble,
+  chunksAreStitchedMp4,
+  DEFAULT_MAX_PARALLEL_CHUNKS,
   listPlanV2ArtifactsForTarget,
   materializePlanV2Target,
   plan,
@@ -77,16 +80,16 @@ async function loadSparticuzChromium() {
   return resolved;
 }
 
-// src/formatExtension.ts
-var FORMAT_EXTENSIONS = {
-  mp4: ".mp4",
-  mov: ".mov",
-  webm: ".webm",
-  "png-sequence": ""
-};
-function formatExtension(format) {
-  return FORMAT_EXTENSIONS[format];
-}
+// src/s3Stitch.ts
+import {
+  AbortMultipartUploadCommand,
+  CompleteMultipartUploadCommand,
+  CreateMultipartUploadCommand,
+  GetObjectCommand as GetObjectCommand2,
+  UploadPartCommand,
+  UploadPartCopyCommand
+} from "@aws-sdk/client-s3";
+import { buildStitchedHeader, readMp4Layout } from "@hyperframes/producer/distributed";
 
 // src/s3Transport.ts
 import {
@@ -262,6 +265,135 @@ async function untarDirectory(tarballPath, destDir) {
   await tar.extract({ file: tarballPath, cwd: destDir });
 }
 
+// src/s3Stitch.ts
+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 GetObjectCommand2({ 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/formatExtension.ts
+var FORMAT_EXTENSIONS = {
+  mp4: ".mp4",
+  mov: ".mov",
+  webm: ".webm",
+  "png-sequence": ""
+};
+function formatExtension(format) {
+  return FORMAT_EXTENSIONS[format];
+}
+
 // 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";
@@ -515,19 +647,49 @@ function primeRuntimeEnv() {
     process.env.PATH = `${bin}:${process.env.PATH ?? ""}`;
   }
 }
-function planConfig(event, deps) {
+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 (event.Config.workerTimeoutSeconds !== void 0 || remainingMs === void 0) {
-    return { ...event.Config };
+  if (config.workerTimeoutSeconds === void 0 && remainingMs !== void 0) {
+    config.workerTimeoutSeconds = Math.ceil(remainingMs / 1e3);
   }
-  return { ...event.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 = planConfig(event, deps);
+  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) {
@@ -541,7 +703,9 @@ async function handlePlan(event, deps) {
   try {
     await downloadS3ObjectToFile(s3, event.ProjectS3Uri, projectArchive);
     await untarDirectory(projectArchive, projectDir);
-    const result = await primitive(projectDir, config, planDir);
+    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`;
@@ -557,6 +721,7 @@ async function handlePlan(event, deps) {
       PlanS3Uri: planTarUri,
       PlanHash: result.planHash,
       ChunkCount: result.chunkCount,
+      MaxChunkConcurrency: Math.min(config.workerConcurrency, result.chunkCount),
       TotalFrames: result.totalFrames,
       Fps: result.fps,
       Width: result.width,
@@ -574,7 +739,7 @@ async function handlePlan(event, deps) {
 }
 async function handlePlanV2(event, deps) {
   const started = Date.now();
-  const config = planConfig(event, deps);
+  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) {
@@ -596,7 +761,8 @@ async function handlePlanV2(event, deps) {
       temporaryRoot: work
     });
     const manifest = await primitive(projectDir, config, publisher, {
-      stagingParentDir: work
+      stagingParentDir: work,
+      chunksCarryAudio: true
     });
     return {
       Action: "plan",
@@ -605,6 +771,7 @@ async function handlePlanV2(event, deps) {
       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,
@@ -671,7 +838,7 @@ async function handleRenderChunkV2(event, deps) {
   }
   const work = mkdtempSync2(join2(deps?.tmpRoot ?? tmpdir2(), "hf-lambda-chunk-v2-"));
   try {
-    const planDir = await downloadAndMaterializePlanV2(
+    const { planDir } = await downloadAndMaterializePlanV2(
       s3,
       event,
       { role: "chunk", chunkIndex: event.ChunkIndex },
@@ -762,7 +929,15 @@ async function handleAssembleV2(event, deps) {
   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 { 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);
@@ -797,6 +972,30 @@ async function handleAssembleV2(event, deps) {
     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");
   mkdirSync3(transportDir, { recursive: true });
@@ -814,7 +1013,7 @@ async function downloadAndMaterializePlanV2(s3, event, target, work) {
   });
   const planDir = join2(work, "plan");
   materializePlanV2Target(transportDir, target, planDir);
-  return planDir;
+  return { planDir, manifest };
 }
 async function downloadPlanV2Artifact(s3, artifactPrefix, planV2Dir, artifact) {
   await downloadS3ObjectToFileVerified(

package/dist/index.js

@@ -2,9 +2,12 @@
 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 { GetAccountSettingsCommand, LambdaClient } from "@aws-sdk/client-lambda";
 import { S3Client } from "@aws-sdk/client-s3";
 import {
   assemble,
+  chunksAreStitchedMp4,
+  DEFAULT_MAX_PARALLEL_CHUNKS,
   listPlanV2ArtifactsForTarget,
   materializePlanV2Target,
   plan,
@@ -82,16 +85,16 @@ async function loadSparticuzChromium() {
   return resolved;
 }
 
-// src/formatExtension.ts
-var FORMAT_EXTENSIONS = {
-  mp4: ".mp4",
-  mov: ".mov",
-  webm: ".webm",
-  "png-sequence": ""
-};
-function formatExtension(format) {
-  return FORMAT_EXTENSIONS[format];
-}
+// src/s3Stitch.ts
+import {
+  AbortMultipartUploadCommand,
+  CompleteMultipartUploadCommand,
+  CreateMultipartUploadCommand,
+  GetObjectCommand as GetObjectCommand2,
+  UploadPartCommand,
+  UploadPartCopyCommand
+} from "@aws-sdk/client-s3";
+import { buildStitchedHeader, readMp4Layout } from "@hyperframes/producer/distributed";
 
 // src/s3Transport.ts
 import {
@@ -270,6 +273,135 @@ async function untarDirectory(tarballPath, destDir) {
   await tar.extract({ file: tarballPath, cwd: destDir });
 }
 
+// src/s3Stitch.ts
+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 GetObjectCommand2({ 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/formatExtension.ts
+var FORMAT_EXTENSIONS = {
+  mp4: ".mp4",
+  mov: ".mov",
+  webm: ".webm",
+  "png-sequence": ""
+};
+function formatExtension(format) {
+  return FORMAT_EXTENSIONS[format];
+}
+
 // 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";
@@ -523,19 +655,49 @@ function primeRuntimeEnv() {
     process.env.PATH = `${bin}:${process.env.PATH ?? ""}`;
   }
 }
-function planConfig(event, deps) {
+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 (event.Config.workerTimeoutSeconds !== void 0 || remainingMs === void 0) {
-    return { ...event.Config };
+  if (config.workerTimeoutSeconds === void 0 && remainingMs !== void 0) {
+    config.workerTimeoutSeconds = Math.ceil(remainingMs / 1e3);
   }
-  return { ...event.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 = planConfig(event, deps);
+  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) {
@@ -549,7 +711,9 @@ async function handlePlan(event, deps) {
   try {
     await downloadS3ObjectToFile(s3, event.ProjectS3Uri, projectArchive);
     await untarDirectory(projectArchive, projectDir);
-    const result = await primitive(projectDir, config, planDir);
+    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`;
@@ -565,6 +729,7 @@ async function handlePlan(event, deps) {
       PlanS3Uri: planTarUri,
       PlanHash: result.planHash,
       ChunkCount: result.chunkCount,
+      MaxChunkConcurrency: Math.min(config.workerConcurrency, result.chunkCount),
       TotalFrames: result.totalFrames,
       Fps: result.fps,
       Width: result.width,
@@ -582,7 +747,7 @@ async function handlePlan(event, deps) {
 }
 async function handlePlanV2(event, deps) {
   const started = Date.now();
-  const config = planConfig(event, deps);
+  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) {
@@ -604,7 +769,8 @@ async function handlePlanV2(event, deps) {
       temporaryRoot: work
     });
     const manifest = await primitive(projectDir, config, publisher, {
-      stagingParentDir: work
+      stagingParentDir: work,
+      chunksCarryAudio: true
     });
     return {
       Action: "plan",
@@ -613,6 +779,7 @@ async function handlePlanV2(event, deps) {
       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,
@@ -679,7 +846,7 @@ async function handleRenderChunkV2(event, deps) {
   }
   const work = mkdtempSync2(join2(deps?.tmpRoot ?? tmpdir2(), "hf-lambda-chunk-v2-"));
   try {
-    const planDir = await downloadAndMaterializePlanV2(
+    const { planDir } = await downloadAndMaterializePlanV2(
       s3,
       event,
       { role: "chunk", chunkIndex: event.ChunkIndex },
@@ -770,7 +937,15 @@ async function handleAssembleV2(event, deps) {
   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 { 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);
@@ -805,6 +980,30 @@ async function handleAssembleV2(event, deps) {
     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");
   mkdirSync3(transportDir, { recursive: true });
@@ -822,7 +1021,7 @@ async function downloadAndMaterializePlanV2(s3, event, target, work) {
   });
   const planDir = join2(work, "plan");
   materializePlanV2Target(transportDir, target, planDir);
-  return planDir;
+  return { planDir, manifest };
 }
 async function downloadPlanV2Artifact(s3, artifactPrefix, planV2Dir, artifact) {
   await downloadS3ObjectToFileVerified(
@@ -1103,7 +1302,9 @@ async function renderToLambda(opts) {
 // src/sdk/getRenderProgress.ts
 import {
   DescribeExecutionCommand,
+  DescribeMapRunCommand,
   GetExecutionHistoryCommand,
+  ListExecutionsCommand,
   SFNClient as SFNClient2
 } from "@aws-sdk/client-sfn";
 
@@ -1140,11 +1341,14 @@ function formatUsd(usd) {
 
 // src/sdk/getRenderProgress.ts
 var DEFAULT_MEMORY_MB = 10240;
+function createProgressSfnClient(config = {}) {
+  return new SFNClient2({ maxAttempts: 8, ...config });
+}
 async function getRenderProgress(opts) {
   if (!opts.executionArn) {
     throw new Error("[getRenderProgress] executionArn is required");
   }
-  const sfn = opts.sfn ?? new SFNClient2({ region: opts.region });
+  const sfn = opts.sfn ?? createProgressSfnClient({ region: opts.region });
   const memoryMb = opts.defaultMemorySizeMb ?? DEFAULT_MEMORY_MB;
   const describe = await sfn.send(
     new DescribeExecutionCommand({ executionArn: opts.executionArn })
@@ -1154,6 +1358,15 @@ async function getRenderProgress(opts) {
   const endedAt = describe.stopDate?.toISOString() ?? null;
   const history = await loadFullHistory(sfn, opts.executionArn);
   const summary = summarizeHistory(history, memoryMb);
+  const mapRun = findChunkMapRun(history);
+  const warnings = [];
+  if (mapRun?.exited) addChunkResults(summary, mapRun.output, memoryMb);
+  else if (mapRun) {
+    await addRunningMapRun(sfn, mapRun.arn, summary, memoryMb).catch((err) => {
+      if (err?.name !== "AccessDeniedException") throw err;
+      warnings.push(MAP_RUN_ACCESS_DENIED);
+    });
+  }
   const costs = computeRenderCost(summary.lambdaInvocations, summary.stateTransitions);
   const overallProgress = computeOverallProgress({
     status,
@@ -1171,6 +1384,7 @@ async function getRenderProgress(opts) {
     outputFile: summary.outputFile,
     errors: summary.errors,
     fatalErrorEncountered: isTerminalFailure(status),
+    warnings,
     startedAt,
     endedAt
   };
@@ -1193,6 +1407,62 @@ async function loadFullHistory(sfn, executionArn) {
   }
   return events;
 }
+var FAILED_CHUNK_HISTORIES_READ = 5;
+var MAP_RUN_ACCESS_DENIED = "Chunk progress is hidden until the chunks finish: this caller lacks states:DescribeMapRun. Re-apply the policy from `hyperframes lambda policies user`.";
+function findChunkMapRun(events) {
+  let run = null;
+  for (const ev of events) {
+    const arn = ev.mapRunStartedEventDetails?.mapRunArn;
+    if (arn) run = { arn, exited: false, output: void 0 };
+    const exit = ev.stateExitedEventDetails;
+    if (run && ev.type === "MapStateExited" && isRenderChunksMapState(exit?.name)) {
+      run = { ...run, exited: true, output: exit?.output };
+    }
+  }
+  return run;
+}
+function addChunkResults(summary, mapOutput, memoryMb) {
+  const chunks = parseJson(mapOutput)?.Chunks;
+  for (const chunk of Array.isArray(chunks) ? chunks : []) {
+    summary.lambdasInvoked++;
+    summary.stateTransitions++;
+    const billedDurationMs = inferBilledMs(chunk);
+    summary.lambdaInvocations.push({
+      billedDurationMs,
+      memorySizeMb: memoryMb,
+      estimated: billedDurationMs === 0
+    });
+    applyPayloadFrameCounts(chunk, "RenderChunk", (delta) => {
+      summary.framesRendered += delta;
+    });
+  }
+}
+async function addRunningMapRun(sfn, mapRunArn, summary, memoryMb) {
+  const res = await sfn.send(new DescribeMapRunCommand({ mapRunArn }));
+  const { total = 0, pending = 0, succeeded = 0, failed = 0 } = res.itemCounts ?? {};
+  summary.lambdasInvoked += total - pending;
+  summary.stateTransitions += total - pending;
+  if (summary.totalFrames !== null && total > 0) {
+    summary.framesRendered += Math.floor(summary.totalFrames * succeeded / total);
+  }
+  if (failed > 0) summary.errors.push(...await failedChunkErrors(sfn, mapRunArn, memoryMb));
+}
+async function failedChunkErrors(sfn, mapRunArn, memoryMb) {
+  const failed = await sfn.send(
+    new ListExecutionsCommand({
+      mapRunArn,
+      statusFilter: "FAILED",
+      maxResults: FAILED_CHUNK_HISTORIES_READ
+    })
+  );
+  const errors = [];
+  for (const child of failed.executions ?? []) {
+    if (!child.executionArn) continue;
+    const childHistory = await loadFullHistory(sfn, child.executionArn);
+    errors.push(...summarizeHistory(childHistory, memoryMb).errors);
+  }
+  return errors;
+}
 function summarizeHistory(events, memoryMb) {
   let framesRendered = 0;
   let totalFrames = null;
@@ -1351,6 +1621,9 @@ function applyPayloadFrameCounts(payload, currentLambdaState, bump) {
 function isRenderChunkState(name) {
   return name === "RenderChunk" || name === "RenderChunkV2";
 }
+function isRenderChunksMapState(name) {
+  return name === "RenderChunks" || name === "RenderChunksV2";
+}
 function isAssembleState(name) {
   return name === "Assemble" || name === "AssembleV2";
 }

package/dist/s3Stitch.d.ts

@@ -0,0 +1,26 @@
+import { type S3Client } from "@aws-sdk/client-s3";
+/** Bytes `[start, end)` of an S3 object. */
+interface RangeSegment {
+    uri: string;
+    start: number;
+    end: number;
+}
+type Segment = {
+    bytes: Buffer;
+} | RangeSegment;
+export type Part = {
+    copy: RangeSegment;
+} | {
+    upload: Segment[];
+};
+export declare function planParts(segments: readonly Segment[], min?: number): Part[];
+/** Writes `parts` in order to `destUri`; a failure aborts the upload so no parts linger. */
+export declare function uploadParts(s3: S3Client, parts: readonly Part[], destUri: string, contentType: string): Promise<void>;
+export interface StitchResult {
+    fileSize: number;
+    parts: number;
+    downloadedBytes: number;
+}
+/** One faststart mp4 at `destUri` from the stitched mp4 chunks at `chunkUris`, in order. */
+export declare function stitchMp4InS3(s3: S3Client, chunkUris: readonly string[], destUri: string, minPartBytes?: number): Promise<StitchResult>;
+export {};

package/dist/sdk/getRenderProgress.d.ts

@@ -2,10 +2,10 @@
  * `getRenderProgress` — read-only progress + cost snapshot for a single
  * render started by {@link renderToLambda}.
  *
- * Pulls one `DescribeExecution` + one `GetExecutionHistory` per call. The
- * history is paginated server-side; the helper loops until exhausted so a
- * 1,000-event Step Functions execution still produces a single
- * `RenderProgress` snapshot.
+ * Pulls one `DescribeExecution` + one `GetExecutionHistory` per call. While
+ * the chunk Distributed Map runs, one `DescribeMapRun` adds its item counts;
+ * once it exits, chunk frames and cost come from the Map's output. Failed
+ * chunks' histories are read only when the counts show a failure.
  *
  * Progress math:
  *   - 0  before Plan completes (no frame count is known yet)
@@ -19,7 +19,7 @@
  * `events.ts`, so the parser doesn't need to know anything beyond
  * "JSON.parse this string and grab two fields."
  */
-import { SFNClient } from "@aws-sdk/client-sfn";
+import { SFNClient, type SFNClientConfig } from "@aws-sdk/client-sfn";
 import { type RenderCost } from "./costAccounting.js";
 /** Options for {@link getRenderProgress}. */
 export interface GetRenderProgressOptions {
@@ -64,8 +64,12 @@ export interface RenderProgress {
     errors: RenderError[];
     /** `true` once the execution has terminated in a non-`SUCCEEDED` state. */
     fatalErrorEncountered: boolean;
+    /** Problems reading progress that leave the render itself untouched, such as a missing IAM permission. */
+    warnings: string[];
     startedAt: string;
     endedAt: string | null;
 }
+/** Rides out `ThrottlingException` with the SDK's backoff instead of throwing after the default 3 tries. */
+export declare function createProgressSfnClient(config?: SFNClientConfig): SFNClient;
 /** Pull a current progress snapshot for one render. */
 export declare function getRenderProgress(opts: GetRenderProgressOptions): Promise<RenderProgress>;

package/dist/sdk/index.js

@@ -227,7 +227,9 @@ async function renderToLambda(opts) {
 // src/sdk/getRenderProgress.ts
 import {
   DescribeExecutionCommand,
+  DescribeMapRunCommand,
   GetExecutionHistoryCommand,
+  ListExecutionsCommand,
   SFNClient as SFNClient2
 } from "@aws-sdk/client-sfn";
 
@@ -264,11 +266,14 @@ function formatUsd(usd) {
 
 // src/sdk/getRenderProgress.ts
 var DEFAULT_MEMORY_MB = 10240;
+function createProgressSfnClient(config = {}) {
+  return new SFNClient2({ maxAttempts: 8, ...config });
+}
 async function getRenderProgress(opts) {
   if (!opts.executionArn) {
     throw new Error("[getRenderProgress] executionArn is required");
   }
-  const sfn = opts.sfn ?? new SFNClient2({ region: opts.region });
+  const sfn = opts.sfn ?? createProgressSfnClient({ region: opts.region });
   const memoryMb = opts.defaultMemorySizeMb ?? DEFAULT_MEMORY_MB;
   const describe = await sfn.send(
     new DescribeExecutionCommand({ executionArn: opts.executionArn })
@@ -278,6 +283,15 @@ async function getRenderProgress(opts) {
   const endedAt = describe.stopDate?.toISOString() ?? null;
   const history = await loadFullHistory(sfn, opts.executionArn);
   const summary = summarizeHistory(history, memoryMb);
+  const mapRun = findChunkMapRun(history);
+  const warnings = [];
+  if (mapRun?.exited) addChunkResults(summary, mapRun.output, memoryMb);
+  else if (mapRun) {
+    await addRunningMapRun(sfn, mapRun.arn, summary, memoryMb).catch((err) => {
+      if (err?.name !== "AccessDeniedException") throw err;
+      warnings.push(MAP_RUN_ACCESS_DENIED);
+    });
+  }
   const costs = computeRenderCost(summary.lambdaInvocations, summary.stateTransitions);
   const overallProgress = computeOverallProgress({
     status,
@@ -295,6 +309,7 @@ async function getRenderProgress(opts) {
     outputFile: summary.outputFile,
     errors: summary.errors,
     fatalErrorEncountered: isTerminalFailure(status),
+    warnings,
     startedAt,
     endedAt
   };
@@ -317,6 +332,62 @@ async function loadFullHistory(sfn, executionArn) {
   }
   return events;
 }
+var FAILED_CHUNK_HISTORIES_READ = 5;
+var MAP_RUN_ACCESS_DENIED = "Chunk progress is hidden until the chunks finish: this caller lacks states:DescribeMapRun. Re-apply the policy from `hyperframes lambda policies user`.";
+function findChunkMapRun(events) {
+  let run = null;
+  for (const ev of events) {
+    const arn = ev.mapRunStartedEventDetails?.mapRunArn;
+    if (arn) run = { arn, exited: false, output: void 0 };
+    const exit = ev.stateExitedEventDetails;
+    if (run && ev.type === "MapStateExited" && isRenderChunksMapState(exit?.name)) {
+      run = { ...run, exited: true, output: exit?.output };
+    }
+  }
+  return run;
+}
+function addChunkResults(summary, mapOutput, memoryMb) {
+  const chunks = parseJson(mapOutput)?.Chunks;
+  for (const chunk of Array.isArray(chunks) ? chunks : []) {
+    summary.lambdasInvoked++;
+    summary.stateTransitions++;
+    const billedDurationMs = inferBilledMs(chunk);
+    summary.lambdaInvocations.push({
+      billedDurationMs,
+      memorySizeMb: memoryMb,
+      estimated: billedDurationMs === 0
+    });
+    applyPayloadFrameCounts(chunk, "RenderChunk", (delta) => {
+      summary.framesRendered += delta;
+    });
+  }
+}
+async function addRunningMapRun(sfn, mapRunArn, summary, memoryMb) {
+  const res = await sfn.send(new DescribeMapRunCommand({ mapRunArn }));
+  const { total = 0, pending = 0, succeeded = 0, failed = 0 } = res.itemCounts ?? {};
+  summary.lambdasInvoked += total - pending;
+  summary.stateTransitions += total - pending;
+  if (summary.totalFrames !== null && total > 0) {
+    summary.framesRendered += Math.floor(summary.totalFrames * succeeded / total);
+  }
+  if (failed > 0) summary.errors.push(...await failedChunkErrors(sfn, mapRunArn, memoryMb));
+}
+async function failedChunkErrors(sfn, mapRunArn, memoryMb) {
+  const failed = await sfn.send(
+    new ListExecutionsCommand({
+      mapRunArn,
+      statusFilter: "FAILED",
+      maxResults: FAILED_CHUNK_HISTORIES_READ
+    })
+  );
+  const errors = [];
+  for (const child of failed.executions ?? []) {
+    if (!child.executionArn) continue;
+    const childHistory = await loadFullHistory(sfn, child.executionArn);
+    errors.push(...summarizeHistory(childHistory, memoryMb).errors);
+  }
+  return errors;
+}
 function summarizeHistory(events, memoryMb) {
   let framesRendered = 0;
   let totalFrames = null;
@@ -475,6 +546,9 @@ function applyPayloadFrameCounts(payload, currentLambdaState, bump) {
 function isRenderChunkState(name) {
   return name === "RenderChunk" || name === "RenderChunkV2";
 }
+function isRenderChunksMapState(name) {
+  return name === "RenderChunks" || name === "RenderChunksV2";
+}
 function isAssembleState(name) {
   return name === "Assemble" || name === "AssembleV2";
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/aws-lambda",
-  "version": "0.8.172",
+  "version": "0.8.174",
   "description": "AWS Lambda adapter for HyperFrames distributed rendering — handler, client-side SDK, and CDK construct.",
   "repository": {
     "type": "git",
@@ -38,6 +38,7 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
+    "@aws-sdk/client-lambda": "^3.1146.0",
     "@aws-sdk/client-s3": "^3.1146.0",
     "@aws-sdk/client-sfn": "^3.1146.0",
     "@sparticuz/chromium": "148.0.0",
@@ -45,7 +46,7 @@
     "ffprobe-static": "^3.1.0",
     "puppeteer-core": "^25.8.0",
     "tar": "^7.4.3",
-    "@hyperframes/producer": "^0.8.172"
+    "@hyperframes/producer": "^0.8.174"
   },
   "devDependencies": {
     "@types/aws-lambda": "^8.10.146",

package/scripts/build-zip.ts

@@ -228,6 +228,7 @@ async function bundleHandler(stagingDir: string): Promise<void> {
       "puppeteer",
       // AWS SDK v3 is pre-installed in the Lambda Node 22 runtime; mark
       // external so we don't double-bundle 3+ MiB of SDK.
+      "@aws-sdk/client-lambda",
       "@aws-sdk/client-s3",
     ],
     plugins: [workspaceAliasPlugin],