fix(lambda): address PR 878 review feedback

- Verify event.PlanHash against the untarred plan.json at the handler
  boundary before invoking the producer primitive. Throws typed
  PLAN_HASH_MISMATCH on divergence so Step Functions routes it as
  non-retryable; previously the field was schema bloat the handler
  ignored, leaving enforcement entirely inside the producer.
- Standardize on MiB throughout build-zip.ts, verify-zip-size.ts, and
  the README. Lambda's hard ceiling is 250 MiB (AWS docs label "250 MB"
  but use binary mebibytes); previously mixed units made the 248 MiB
  budget look like a ~5 MB margin instead of the 2 MiB it actually is.
- stageChromeHeadlessShell now picks Chrome versions via numeric semver
  comparison instead of lexicographic sort+reverse — the latter would
  silently pick "99.x" over "131.x" once Chrome cached three-digit
  majors that aren't width-aligned.
- Drop _setSparticuzChromiumForTests from the public index barrel.
  Test-only DI seam imported directly from ./chromium.js in tests.
- Replace require("node:fs") inside walkSize() with the top-level fs
  imports — file is ESM and the same module is already imported.

Author: jrusso1020

packages/aws-lambda/README.md

@@ -49,10 +49,10 @@ inside Step Functions' history budget (under 200 bytes per chunk).
 
 The package supports two Chromium sources:
 
-| Source                          | Default | Size              | When to pick it                                                                                                       |
-| ------------------------------- | ------- | ----------------- | --------------------------------------------------------------------------------------------------------------------- |
-| `@sparticuz/chromium`           | yes     | ~70 MB compressed | Lambda. Decompresses into `/tmp` at runtime; the rest of the ecosystem already uses it for headless-Chrome-in-Lambda. |
-| Bundled `chrome-headless-shell` | no      | ~140 MB           | Fallback. Used if `@sparticuz/chromium` ever drops `HeadlessExperimental.beginFrame` support.                         |
+| Source                          | Default | Size               | When to pick it                                                                                                       |
+| ------------------------------- | ------- | ------------------ | --------------------------------------------------------------------------------------------------------------------- |
+| `@sparticuz/chromium`           | yes     | ~70 MiB compressed | Lambda. Decompresses into `/tmp` at runtime; the rest of the ecosystem already uses it for headless-Chrome-in-Lambda. |
+| Bundled `chrome-headless-shell` | no      | ~140 MiB           | Fallback. Used if `@sparticuz/chromium` ever drops `HeadlessExperimental.beginFrame` support.                         |
 
 Pick the source at build time:
 
@@ -98,8 +98,8 @@ designed to extract cleanly into Lambda's `/var/task/`.
 
 `verify:zip-size` enforces:
 
-- Unzipped ≤ 248 MB (in-house budget; Lambda hard ceiling is 250 MB unzipped)
-- Zipped ≤ 150 MB (in-house budget; Lambda has no hard zipped cap for S3-deployed functions)
+- Unzipped ≤ 248 MiB (in-house budget; Lambda hard ceiling is 250 MiB unzipped — AWS docs label this "250 MB" but use binary mebibytes)
+- Zipped ≤ 150 MiB (in-house budget; Lambda has no hard zipped cap for S3-deployed functions)
 
 CI fails the PR if either is exceeded.
 

packages/aws-lambda/scripts/build-zip.ts

@@ -35,6 +35,7 @@ import {
   cpSync,
   existsSync,
   mkdirSync,
+  readdirSync,
   readFileSync,
   rmSync,
   statSync,
@@ -52,26 +53,27 @@ const distDir = join(packageRoot, "dist");
 
 interface BuildOptions {
   source: "sparticuz" | "chrome-headless-shell";
-  /** Hard upper bound on the unzipped bundle size in bytes (Lambda limit is 250 MB). */
+  /** Hard upper bound on the unzipped bundle size in bytes (Lambda limit is 250 MiB). */
   maxUnzippedBytes: number;
   /** Hard upper bound on the ZIP file size in bytes. */
   maxZippedBytes: number;
 }
 
 const DEFAULT_OPTIONS: BuildOptions = {
   source: "sparticuz",
-  // Lambda's hard ceiling for ZIP-deployed functions is 250 MB unzipped.
-  // We gate at 248 MiB to keep a couple of MiB of headroom — the
-  // sparticuz Chrome (70 MB) + ffmpeg (80 MB) + ffprobe (62 MB) +
-  // bundled Node deps put us close to the ceiling. Chrome itself
+  // Lambda's hard ceiling for ZIP-deployed functions is 250 MiB unzipped
+  // (AWS docs label it "250 MB" but the 262144000-byte value is 250
+  // binary mebibytes). We gate at 248 MiB to keep ~2 MiB of headroom —
+  // the sparticuz Chrome (~70 MiB) + ffmpeg (~80 MiB) + ffprobe (~62
+  // MiB) + bundled Node deps put us close to the ceiling. Chrome itself
   // decompresses into Lambda's `/tmp` at cold start, which has its own
-  // 10 GB budget, so the unzipped /var/task footprint above is what
-  // actually competes with Lambda's 250 MB limit.
+  // 10 GiB budget, so the unzipped /var/task footprint above is what
+  // actually competes with Lambda's 250 MiB limit.
   maxUnzippedBytes: 248 * 1024 * 1024,
-  // Lambda's only zipped-size cap is for direct console/CLI uploads (50 MB);
-  // S3-deployed functions are bounded by the unzipped ceiling. We gate at
-  // 150 MiB to flag a sudden bundle-size regression without false-failing
-  // on the natural ~100 MiB sparticuz + ffmpeg payload.
+  // Lambda's only zipped-size cap is for direct console/CLI uploads (50
+  // MiB); S3-deployed functions are bounded by the unzipped ceiling. We
+  // gate at 150 MiB to flag a sudden bundle-size regression without
+  // false-failing on the natural ~100 MiB sparticuz + ffmpeg payload.
   maxZippedBytes: 150 * 1024 * 1024,
 };
 
@@ -142,7 +144,7 @@ async function main(): Promise<void> {
     throw new Error(
       `[build-zip] unzipped bundle ${formatBytes(unzippedBytes)} exceeds limit ${formatBytes(
         opts.maxUnzippedBytes,
-      )} (Lambda ZIP ceiling: 250 MB unzipped). ` +
+      )} (Lambda ZIP ceiling: 250 MiB unzipped). ` +
         `Switch --source to the lighter option, or move Chrome to a Lambda Layer.`,
     );
   }
@@ -221,14 +223,14 @@ async function bundleHandler(stagingDir: string): Promise<void> {
       "puppeteer-core",
       "puppeteer",
       // AWS SDK v3 is pre-installed in the Lambda Node 22 runtime; mark
-      // external so we don't double-bundle 3+ MB of SDK.
+      // external so we don't double-bundle 3+ MiB of SDK.
       "@aws-sdk/client-s3",
     ],
     plugins: [workspaceAliasPlugin],
     minify: false,
-    // sourcemap=false: the ZIP is tight on Lambda's 250 MB unzipped cap
-    // (Chrome 70 MB + ffmpeg 80 MB + ffprobe 62 MB + Node deps). A 4-5 MB
-    // sourcemap puts us over. Re-enable for local debugging by passing
+    // sourcemap=false: the ZIP is tight on Lambda's 250 MiB unzipped cap
+    // (Chrome ~70 MiB + ffmpeg ~80 MiB + ffprobe ~62 MiB + Node deps). A
+    // 4-5 MiB sourcemap puts us over. Re-enable for local debugging by passing
     // --sourcemap; the bundle's stack traces stay readable enough without
     // it because we don't minify.
     sourcemap: false,
@@ -399,8 +401,11 @@ function stageChromeHeadlessShell(stagingDir: string): void {
         `before --source=chrome-headless-shell.`,
     );
   }
-  const { readdirSync } = require("node:fs") as typeof import("node:fs");
-  const versions = readdirSync(baseDir).sort().reverse();
+  // Sort by numeric semver descending. `sort().reverse()` is lexicographic,
+  // which silently picks "99.0.0" over "131.0.0" once Chrome ships
+  // three-digit majors that aren't strictly width-aligned. `compareSemver`
+  // returns negative/zero/positive on (a, b), so descending = `b - a`.
+  const versions = readdirSync(baseDir).sort((a, b) => compareSemver(b, a));
   for (const v of versions) {
     const candidate = join(baseDir, v, "chrome-headless-shell-linux64", "chrome-headless-shell");
     if (existsSync(candidate)) {
@@ -415,6 +420,28 @@ function stageChromeHeadlessShell(stagingDir: string): void {
   throw new Error(`[build-zip] no linux64 chrome-headless-shell binary found under ${baseDir}.`);
 }
 
+/**
+ * Compare two semver-shaped strings like "131.0.6778.108". Treats any
+ * non-numeric directory name as `-Infinity` so it sorts to the bottom
+ * (Puppeteer's cache layout sometimes includes `latest` or branch tags).
+ * Used by `stageChromeHeadlessShell` to pick the newest cached Chrome
+ * without tripping on the lexicographic "99 > 131" trap.
+ */
+function compareSemver(a: string, b: string): number {
+  const partsA = a.split(".").map((s) => Number.parseInt(s, 10));
+  const partsB = b.split(".").map((s) => Number.parseInt(s, 10));
+  const len = Math.max(partsA.length, partsB.length);
+  for (let i = 0; i < len; i++) {
+    const ai = partsA[i] ?? 0;
+    const bi = partsB[i] ?? 0;
+    if (Number.isNaN(ai) && Number.isNaN(bi)) continue;
+    if (Number.isNaN(ai)) return -1;
+    if (Number.isNaN(bi)) return 1;
+    if (ai !== bi) return ai - bi;
+  }
+  return 0;
+}
+
 function zipDirectory(sourceDir: string, zipPath: string): void {
   const result = spawnSync("zip", ["-rq", zipPath, "."], { cwd: sourceDir, stdio: "inherit" });
   if (result.status !== 0) {
@@ -437,12 +464,11 @@ function directorySizeBytes(dir: string): number {
 }
 
 function walkSize(dir: string): number {
-  const { readdirSync, statSync: stat } = require("node:fs") as typeof import("node:fs");
   let total = 0;
   for (const entry of readdirSync(dir, { withFileTypes: true })) {
     const full = join(dir, entry.name);
     if (entry.isDirectory()) total += walkSize(full);
-    else if (entry.isFile()) total += stat(full).size;
+    else if (entry.isFile()) total += statSync(full).size;
   }
   return total;
 }

packages/aws-lambda/scripts/verify-zip-size.ts

@@ -5,7 +5,8 @@
  * Reads `dist/handler.zip.manifest.json` (written by `build-zip.ts`) and
  * exits non-zero if either the unzipped or zipped size exceeds the
  * declared limits. Lambda's hard ceiling for ZIP-deployed functions is
- * 250 MB unzipped; the in-house budget is 240 MB to keep headroom for
+ * 250 MiB unzipped (262144000 bytes — AWS docs label it "250 MB" but use
+ * binary mebibytes); the in-house budget is 248 MiB to keep headroom for
  * the Chrome tarball decompression that happens at cold start.
  */
 
@@ -55,15 +56,15 @@ function main(): void {
   if (manifest.unzippedBytes > IN_HOUSE_UNZIPPED_LIMIT) {
     console.error(
       `[verify-zip-size] FAIL unzipped: ${formatBytes(manifest.unzippedBytes)} > ` +
-        `${formatBytes(IN_HOUSE_UNZIPPED_LIMIT)} (in-house limit; Lambda hard ceiling is 250 MB).`,
+        `${formatBytes(IN_HOUSE_UNZIPPED_LIMIT)} (in-house limit; Lambda hard ceiling is 250 MiB).`,
     );
     failed = true;
   }
   if (actualZipped > IN_HOUSE_ZIPPED_LIMIT) {
     console.error(
       `[verify-zip-size] FAIL zipped: ${formatBytes(actualZipped)} > ` +
-        `${formatBytes(IN_HOUSE_ZIPPED_LIMIT)} (in-house limit; Lambda direct-upload ceiling is 50 MB, ` +
-        `S3-deploy ceiling is 250 MB).`,
+        `${formatBytes(IN_HOUSE_ZIPPED_LIMIT)} (in-house limit; Lambda direct-upload ceiling is 50 MiB, ` +
+        `S3-deploy ceiling is 250 MiB).`,
     );
     failed = true;
   }

packages/aws-lambda/src/events.ts

@@ -52,7 +52,13 @@ export interface RenderChunkEvent {
   Action: "renderChunk";
   /** S3 URI of the plan tar produced by a PlanEvent invocation. */
   PlanS3Uri: string;
-  /** `PlanResult.planHash` — checked against the planDir's `plan.json` post-download. */
+  /**
+   * `PlanResult.planHash` from the Plan invocation. The handler verifies
+   * this against the untarred planDir's `plan.json` before invoking the
+   * producer, throwing a typed `PLAN_HASH_MISMATCH` on divergence so the
+   * state machine routes it as non-retryable. Defense-in-depth — the
+   * producer also re-checks internally.
+   */
   PlanHash: string;
   /** 0-based chunk index this invocation should render. */
   ChunkIndex: number;

packages/aws-lambda/src/handler.test.ts

@@ -272,6 +272,56 @@ describe("handler dispatch", () => {
     expect(renderChunkMock).toHaveBeenCalledTimes(1);
   });
 
+  it("rejects renderChunk when event.PlanHash diverges from plan.json", async () => {
+    const tmpRoot = makeTmpRoot();
+    const s3 = new FakeS3Client();
+    // The fixture's plan.json has planHash="fakehash"; the event below
+    // claims something else, so the handler must throw PLAN_HASH_MISMATCH
+    // before invoking the primitive.
+    s3.objects.set("s3://bucket/plan.tar.gz", await makeMinimalPlanTar());
+
+    const renderChunkMock = mock(async () => {
+      throw new Error("primitive should not be called on a hash mismatch");
+    });
+    const planMock = mock(async () => {
+      throw new Error("should not be called");
+    });
+    const assembleMock = mock(async () => {
+      throw new Error("should not be called");
+    });
+
+    const event: RenderChunkEvent = {
+      Action: "renderChunk",
+      PlanS3Uri: "s3://bucket/plan.tar.gz",
+      PlanHash: "not-the-real-hash",
+      ChunkIndex: 0,
+      ChunkOutputS3Prefix: "s3://bucket/renders/abc/",
+      Format: "mp4",
+    };
+
+    let caught: unknown;
+    try {
+      await handler(event, {
+        s3: s3 as unknown as import("@aws-sdk/client-s3").S3Client,
+        primitives: {
+          plan: planMock as unknown as typeof import("@hyperframes/producer/distributed").plan,
+          renderChunk:
+            renderChunkMock as unknown as typeof import("@hyperframes/producer/distributed").renderChunk,
+          assemble:
+            assembleMock as unknown as typeof import("@hyperframes/producer/distributed").assemble,
+        },
+        tmpRoot,
+        skipChromeResolution: true,
+      });
+    } catch (err) {
+      caught = err;
+    }
+    expect(caught).toBeInstanceOf(Error);
+    expect((caught as Error).name).toBe("PLAN_HASH_MISMATCH");
+    expect((caught as Error).message).toMatch(/not-the-real-hash/);
+    expect(renderChunkMock).not.toHaveBeenCalled();
+  });
+
   it("routes Action='assemble' to the assemble primitive", async () => {
     const tmpRoot = makeTmpRoot();
     const s3 = new FakeS3Client();

packages/aws-lambda/src/handler.ts

@@ -11,7 +11,7 @@
  * primitive → S3 upload → return small JSON result.
  */
 
-import { existsSync, mkdirSync, mkdtempSync, rmSync, statSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { basename, join } from "node:path";
 import { S3Client } from "@aws-sdk/client-s3";
@@ -315,6 +315,14 @@ async function handleRenderChunk(
     await downloadS3ObjectToFile(s3, event.PlanS3Uri, planTar);
     await untarDirectory(planTar, planDir);
 
+    // Verify the plan's hash matches what Step Functions told us to render.
+    // The producer's renderChunk re-checks internally (defense-in-depth),
+    // but doing it here at the handler boundary lets us fail before paying
+    // the Chrome-launch + render cost on a misrouted chunk. Throws a
+    // typed PLAN_HASH_MISMATCH that Step Functions can route as
+    // non-retryable.
+    verifyPlanHash(planDir, event.PlanHash);
+
     const chunkOutputBase = join(
       work,
       event.Format === "png-sequence"
@@ -489,3 +497,34 @@ function cleanupDir(dir: string): void {
     // Best-effort — leak is preferable to crashing on success path.
   }
 }
+
+/**
+ * Read the untarred planDir's `plan.json` and assert its `planHash`
+ * matches what the Step Functions event claims. Throws on mismatch with
+ * a typed `PLAN_HASH_MISMATCH` error name so the state machine's typed
+ * non-retryable list routes it correctly.
+ *
+ * This is defense-in-depth — the producer's `renderChunk` does the same
+ * check internally — but performing it here lets us fail before paying
+ * the Chrome-launch + per-frame capture cost on a misrouted chunk.
+ */
+function verifyPlanHash(planDir: string, expected: string): void {
+  const planJsonPath = join(planDir, "plan.json");
+  let parsed: { planHash?: unknown };
+  try {
+    parsed = JSON.parse(readFileSync(planJsonPath, "utf-8")) as { planHash?: unknown };
+  } 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;
+  }
+}

packages/aws-lambda/src/index.ts

@@ -25,8 +25,10 @@ export {
   type RenderChunkLambdaResult,
   type SerializableDistributedRenderConfig,
 } from "./events.js";
+// `_setSparticuzChromiumForTests` is intentionally NOT re-exported from
+// the package barrel — it's a test-only DI seam. Test files import it
+// directly from `./chromium.js`.
 export {
-  _setSparticuzChromiumForTests,
   type ChromeSource,
   resolveChromeArgs,
   resolveChromeExecutablePath,