refactor: address simplify-review findings on webm stack

Folds in cleanups identified by a multi-agent code-review pass over the
4-PR webm-distributed stack:

- plan.ts: `resolveEncoderTriple()` webm case now calls
  `getEncoderPreset(quality, "webm")` for its preset string instead of
  hardcoding "good". The hardcode was wrong for `quality: "draft"`
  (`getEncoderPreset` returns "realtime" for that tier) — would have
  silently overridden the draft → realtime mapping for distributed webm
  renders.
- chunkEncoder.ts: trim the new VP9 closed-GOP comment block from ~18
  lines of WHY narration down to the 6 lines that actually explain why
  (alt-ref + cpu-used drift). Match the alpha branch's idempotent-push
  comment to the same standard.
- chunkEncoder.test.ts: drop the duplicate WHY comment that restated
  the implementation comment in plain words.
- webm-concat-copy.test.ts: rewrite the file-header docstring to
  describe the contract being tested instead of the PR-8.1-gating
  history; strip "PR 8.2 / Path A / Path B" references from error
  messages (they belong in PR bodies, not in test output). Consolidate
  the yuva420p alpha smoke into a single `it()` block (was a full
  4-test describe with duplicated setup) — the yuv420p block already
  covers the probe/decode/frame-count contract; the alpha smoke only
  needs to prove the alpha args don't break concat-copy.
- plan.test.ts: drop the "PR 8.1 proved the contract" comment.
- webm-vp9 fixture: drop the aspirational "Other webm-with-audio
  fixtures cover the mux path separately when added" sentence (no
  other fixtures exist). Regenerated the baseline via
  `docker:test:update webm-vp9` to reflect the updated comment.
- migrating-to-hyperframes-lambda.mdx: add a paragraph about
  distributed webm's perf cost — ~10-25% larger files at constant CRF
  due to forced keyframes, and slower per-chunk encode due to
  `-cpu-used 2` being more conservative than the libvpx default.

All unit tests + the webm-vp9 distributed-simulated regression still
pass after these changes.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: jrusso1020

docs/deploy/migrating-to-hyperframes-lambda.mdx

@@ -68,6 +68,8 @@ HyperFrames refuses `data-gpu-mode="hardware"` in distributed mode — hardware
 
 webm distributed renders go through libvpx-vp9 with `-g <chunkSize>`, `-keyint_min <chunkSize>`, `-auto-alt-ref 0`, and `-cpu-used 2`. The alt-ref disable is the load-bearing bit: libvpx-vp9's default non-displayable alt-ref frames can land anywhere in a GOP, which breaks concat-copy at chunk seams. Closed-GOP forces a keyframe at every chunk boundary so `ffmpeg -f concat -c copy` round-trips losslessly. Output is `yuva420p` to preserve alpha. Audio is muxed as Opus.
 
+Distributed webm files are typically ~10-25% larger than the same composition rendered in-process at the same CRF, because closed-GOP forces more keyframes than the in-process single-pass would emit. Per-chunk encode is also slower than libvpx-vp9's default speed/quality tradeoff (`-cpu-used 2` is more conservative than the default for `-deadline good`). The single-machine in-process renderer remains the right choice for short webm renders; distributed pays for itself once a render's wall-clock exceeds what one machine delivers.
+
 ### State files are local by default
 
 `hyperframes lambda deploy` writes `<cwd>/.hyperframes/lambda-stack-<name>.json` so subsequent verbs don't re-derive the bucket / state-machine ARN. Two worktrees produce two distinct state files. If you need a shared default location across CI workers, symlink the directory or pass `--stack-name` explicitly on every call.

packages/engine/src/services/chunkEncoder.test.ts

@@ -551,10 +551,6 @@ describe("buildEncoderArgs lockGopForChunkConcat", () => {
     expect(args.indexOf("-x264-params")).toBe(-1);
   });
 
-  // Closed-GOP for libvpx-vp9 is required to make `ffmpeg -f concat -c copy`
-  // stitch VP9 chunks losslessly: every chunk's first frame must be an
-  // independently-decodable keyframe with no alt-ref references reaching
-  // back across the seam.
   it("true appends closed-GOP args for libvpx-vp9", () => {
     const args = buildEncoderArgs(
       {
@@ -570,16 +566,9 @@ describe("buildEncoderArgs lockGopForChunkConcat", () => {
     );
     expect(args[args.indexOf("-g") + 1]).toBe("240");
     expect(args[args.indexOf("-keyint_min") + 1]).toBe("240");
-    // Alt-ref frames are non-displayable references that break concat-copy
-    // at chunk seams; closed-GOP must disable them.
     expect(args[args.indexOf("-auto-alt-ref") + 1]).toBe("0");
-    // cpu-used is locked so workers with different libvpx-vp9 defaults
-    // produce visually consistent output across chunk boundaries.
     expect(args[args.indexOf("-cpu-used") + 1]).toBe("2");
-    // libvpx-vp9 uses `-deadline good` for non-ultrafast presets — the
-    // closed-GOP path doesn't change that.
     expect(args[args.indexOf("-deadline") + 1]).toBe("good");
-    // x264/x265-only params must not leak into the VP9 branch.
     expect(args.indexOf("-x264-params")).toBe(-1);
     expect(args.indexOf("-x265-params")).toBe(-1);
     expect(args.indexOf("-sc_threshold")).toBe(-1);

packages/engine/src/services/chunkEncoder.ts

@@ -255,25 +255,13 @@ export function buildEncoderArgs(
     args.push("-deadline", preset === "ultrafast" ? "realtime" : "good");
     args.push("-row-mt", "1");
 
-    // Closed-GOP args for distributed chunk concat-copy. Mirrors the
-    // libx264/libx265 branch above: `lockGopForChunkConcat=true` lays a
-    // keyframe at every chunk boundary so `ffmpeg -f concat -c copy` can
-    // stitch sibling chunks losslessly.
-    //
-    // VP9-specific: `-auto-alt-ref 0` is mandatory. Alt-ref (a.k.a.
-    // "ARNR") frames are non-displayable references libvpx-vp9 inserts
-    // anywhere in the GOP for compression; they break concat-copy at
-    // chunk seams because the boundary frame is no longer the first
-    // displayable reference. The alpha branch below already disables
-    // alt-ref for an unrelated reason (alpha + alt-ref is unsupported);
-    // closed-GOP extends that to every pixel format.
-    //
-    // `-cpu-used 2` pins the libvpx-vp9 speed/quality tradeoff so chunks
-    // encoded on workers with different default cpu-used values still
-    // produce visually consistent output across seams. libvpx-vp9's
-    // default with `-deadline good` has drifted across versions
-    // historically — locking it makes the planHash round-trip
-    // deterministic.
+    // `-auto-alt-ref 0` is mandatory for chunk concat-copy: libvpx-vp9's
+    // alt-ref frames can reference frames in either direction inside a
+    // GOP, so a chunk-boundary frame is not guaranteed to be the first
+    // displayable reference when alt-ref is on. `-cpu-used 2` pins the
+    // speed/quality tradeoff against libvpx-vp9 default drift across
+    // versions, so the planHash round-trips deterministically across
+    // worker images.
     const lockGopVp9 = options.lockGopForChunkConcat === true;
     if (lockGopVp9) {
       if (
@@ -299,10 +287,8 @@ export function buildEncoderArgs(
     }
     if (pixelFormat === "yuva420p") {
       // Alpha + alt-ref is unsupported by libvpx-vp9. The closed-GOP
-      // branch above already disables alt-ref; only push the flag for
-      // the non-locked alpha case to keep the args list clean (a second
-      // `-auto-alt-ref 0` is harmless but noisier in `ffmpeg -loglevel`
-      // diagnostics).
+      // branch above already emits `-auto-alt-ref 0`, so skip the
+      // duplicate push.
       if (!lockGopVp9) {
         args.push("-auto-alt-ref", "0");
       }

packages/producer/src/services/distributed/plan.test.ts

@@ -467,10 +467,9 @@ describe("plan() — webm format (distributed VP9)", () => {
   it(
     'maps `format: "webm"` to libvpx-vp9-software + yuva420p',
     async () => {
-      // Webm is distributed-supported via closed-GOP concat-copy (PR 8.1
-      // proved the contract; this test pins the plan-time encoder choice).
-      // yuva420p preserves the format's reason for existing — alpha video
-      // for web playback over colored backgrounds.
+      // Pins the plan-time encoder choice for webm: libvpx-vp9-software
+      // with yuva420p so the format's alpha-channel contract round-trips
+      // through chunked rendering.
       const planDir = join(runRoot, "plan-webm-vp9");
       mkdirSync(planDir, { recursive: true });
       const result = await plan(

packages/producer/src/services/distributed/plan.ts

@@ -36,7 +36,7 @@ import {
 } from "node:fs";
 import { join, relative, sep } from "node:path";
 import { type CanvasResolution } from "@hyperframes/core";
-import { type EngineConfig, resolveConfig } from "@hyperframes/engine";
+import { type EngineConfig, getEncoderPreset, resolveConfig } from "@hyperframes/engine";
 import { defaultLogger, type ProducerLogger } from "../../logger.js";
 import { runAudioStage } from "../render/stages/audioStage.js";
 import { runCompileStage } from "../render/stages/compileStage.js";
@@ -557,12 +557,16 @@ function resolveEncoderTriple(config: DistributedRenderConfig): {
     return { encoder: "prores-software", pixelFormat: "yuva444p10le", preset: "4444" };
   }
   if (config.format === "webm") {
-    // webm distributes via closed-GOP libvpx-vp9 + concat-copy. yuva420p
-    // matches the in-process renderer's webm pixel format (alpha-capable
-    // — the format's main reason for existing). `getEncoderPreset` in
-    // the engine returns "good" for non-draft quality tiers; that becomes
-    // libvpx-vp9's `-deadline good` at encode time.
-    return { encoder: "libvpx-vp9-software", pixelFormat: "yuva420p", preset: "good" };
+    // Defer to `getEncoderPreset` for the libvpx-vp9 preset string so the
+    // draft tier maps to `-deadline realtime` instead of `-deadline good`;
+    // hardcoding "good" here would silently override that mapping for
+    // `quality: "draft"`.
+    const enginePreset = getEncoderPreset(config.quality ?? "standard", "webm");
+    return {
+      encoder: "libvpx-vp9-software",
+      pixelFormat: enginePreset.pixelFormat,
+      preset: enginePreset.preset,
+    };
   }
   return { encoder: "png-sequence", pixelFormat: "rgba", preset: "lossless" };
 }