refactor: extract DistributedFormat type + trim font-cache resolver

Second simplify-review pass on the webm stack flagged two cleanups:

1. **`DistributedFormat` type duplicated 10 times.** Every file in the
   distributed pipeline carried its own copy of
   `"mp4" | "mov" | "png-sequence" | "webm"` — adding a new format
   meant a 10-place edit with no compile-time guarantee they stayed in
   sync. Extract a single source of truth in
   `packages/producer/src/services/distributed/shared.ts`, re-export
   from `@hyperframes/producer/distributed` and
   `@hyperframes/aws-lambda/sdk`, and have all callers pull from
   there. The aws-lambda `ALLOWED_FORMATS` runtime tuple and the CLI's
   `FORMATS` tuple now both use `satisfies readonly DistributedFormat[]`
   so the compiler enforces the runtime allowlist stays in sync with
   the type.

2. **`deterministicFonts.ts` font-cache resolver was over-commented.**
   Trim the 7-line block to 4 lines (drop the aspirational
   "and other read-only-FS execution environments" — only Lambda is
   detected — and the warm-container `/tmp` persistence narration —
   anyone reading already knows Lambda /tmp semantics). Collapse the
   two-step `if (explicit && explicit.length > 0)` into a single
   nullish-coalesce expression now that the empty-string defensive
   check is gone (`process.env.X` is `string | undefined`, no third
   shape to guard against).

Out-of-scope skips (called out by the agents, deferred):
- In-process `RenderConfig.format` and the in-process CLI's
  `render.ts` format union still carry their own inline copies. The
  union happens to coincide today but they're separate concerns —
  leaving them alone limits this PR's blast radius.
- `fontCacheDir(slug)` / `resolveFontCacheRoot()` naming asymmetry
  flagged as taste; skipping.
- Pre-existing redundant `existsSync` before `mkdirSync({ recursive:
  true })` in `fontCacheDir` — out of scope.

All tests + typecheck still pass. Lambda render still works
end-to-end (no functional changes).

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

Author: jrusso1020

packages/aws-lambda/src/events.ts

@@ -16,7 +16,7 @@
  * results per §2.4).
  */
 
-import type { DistributedRenderConfig } from "@hyperframes/producer/distributed";
+import type { DistributedFormat, DistributedRenderConfig } from "@hyperframes/producer/distributed";
 
 /** Discriminator for the three roles the one Lambda image fulfills. */
 export type LambdaAction = "plan" | "renderChunk" | "assemble";
@@ -65,7 +65,7 @@ export interface RenderChunkEvent {
   /** S3 URI prefix where the chunk output should be uploaded (`s3://bucket/{prefix}/`). */
   ChunkOutputS3Prefix: string;
   /** Output container format from the plan's encoder.json; drives file vs frame-dir handling. */
-  Format: "mp4" | "mov" | "png-sequence" | "webm";
+  Format: DistributedFormat;
 }
 
 /** Activity C: fetch planDir + all chunks + audio, assemble, upload final. */
@@ -80,7 +80,7 @@ export interface AssembleEvent {
   /** Final output S3 URI (`s3://bucket/key.mp4`). */
   OutputS3Uri: string;
   /** Output container format; drives file vs frame-dir handling. */
-  Format: "mp4" | "mov" | "png-sequence" | "webm";
+  Format: DistributedFormat;
 }
 
 /**
@@ -106,7 +106,7 @@ export interface PlanLambdaResult {
   Fps: 24 | 30 | 60;
   Width: number;
   Height: number;
-  Format: "mp4" | "mov" | "png-sequence" | "webm";
+  Format: DistributedFormat;
   HasAudio: boolean;
   AudioS3Uri: string | null;
   FfmpegVersion: string;

packages/aws-lambda/src/formatExtension.ts

@@ -6,7 +6,9 @@
  * looks like vs a png-sequence.
  */
 
-export type DistributedFormat = "mp4" | "mov" | "png-sequence" | "webm";
+import type { DistributedFormat } from "@hyperframes/producer/distributed";
+
+export type { DistributedFormat } from "@hyperframes/producer/distributed";
 
 // Closed-enum lookup table. TS enforces exhaustiveness via the
 // `Record<DistributedFormat, string>` annotation — adding a format to

packages/aws-lambda/src/handler.ts

@@ -25,7 +25,7 @@ import {
   renderChunk,
 } from "@hyperframes/producer/distributed";
 import { resolveChromeExecutablePath } from "./chromium.js";
-import { formatExtension } from "./formatExtension.js";
+import { type DistributedFormat, formatExtension } from "./formatExtension.js";
 import type {
   AssembleEvent,
   AssembleLambdaResult,
@@ -433,7 +433,7 @@ async function downloadChunkObjects(
   s3: S3Client,
   uris: string[],
   workDir: string,
-  format: "mp4" | "mov" | "png-sequence" | "webm",
+  format: DistributedFormat,
 ): Promise<string[]> {
   const chunksDir = join(workDir, "chunks");
   mkdirSync(chunksDir, { recursive: true });

packages/aws-lambda/src/sdk/index.ts

@@ -24,3 +24,4 @@ export {
 } from "./costAccounting.js";
 export { InvalidConfigError, validateDistributedRenderConfig } from "./validateConfig.js";
 export type { SerializableDistributedRenderConfig } from "../events.js";
+export type { DistributedFormat } from "../formatExtension.js";

packages/aws-lambda/src/sdk/validateConfig.ts

@@ -18,6 +18,7 @@
  * size cap, GPU mode at runtime) needs the actual planner.
  */
 
+import type { DistributedFormat } from "../formatExtension.js";
 import type { SerializableDistributedRenderConfig } from "../events.js";
 
 /** Thrown for any client-side `SerializableDistributedRenderConfig` violation. */
@@ -32,7 +33,12 @@ export class InvalidConfigError extends Error {
 }
 
 const ALLOWED_FPS = [24, 30, 60] as const;
-const ALLOWED_FORMATS = ["mp4", "mov", "png-sequence", "webm"] as const;
+const ALLOWED_FORMATS = [
+  "mp4",
+  "mov",
+  "png-sequence",
+  "webm",
+] as const satisfies readonly DistributedFormat[];
 const ALLOWED_CODECS = ["h264", "h265"] as const;
 const ALLOWED_QUALITIES = ["draft", "standard", "high"] as const;
 const ALLOWED_RUNTIME_CAPS = ["lambda", "temporal", "cloud-run-job", "k8s-job", "none"] as const;

packages/cli/src/commands/lambda.ts

@@ -9,6 +9,7 @@
  */
 
 import { defineCommand } from "citty";
+import type { DistributedFormat } from "@hyperframes/aws-lambda/sdk";
 import type { Example } from "./_examples.js";
 import { c } from "../ui/colors.js";
 
@@ -325,7 +326,12 @@ function parseEnum<T extends string>(
   throw new Error(`${errorPrefix} must be ${allowed.join("|")}; got ${s}`);
 }
 
-const FORMATS = ["mp4", "mov", "png-sequence", "webm"] as const;
+const FORMATS = [
+  "mp4",
+  "mov",
+  "png-sequence",
+  "webm",
+] as const satisfies readonly DistributedFormat[];
 const CODECS = ["h264", "h265"] as const;
 const QUALITIES = ["draft", "standard", "high"] as const;
 const CHROME_SOURCES = ["sparticuz", "chrome-headless-shell"] as const;

packages/cli/src/commands/lambda/render.ts

@@ -5,7 +5,10 @@
  */
 
 import { resolve as resolvePath } from "node:path";
-import type { SerializableDistributedRenderConfig } from "@hyperframes/aws-lambda/sdk";
+import type {
+  DistributedFormat,
+  SerializableDistributedRenderConfig,
+} from "@hyperframes/aws-lambda/sdk";
 import { c } from "../../ui/colors.js";
 import { requireStack, stateFilePath } from "./state.js";
 
@@ -23,7 +26,7 @@ export interface RenderArgs {
   fps: 24 | 30 | 60;
   width: number;
   height: number;
-  format: "mp4" | "mov" | "png-sequence" | "webm";
+  format: DistributedFormat;
   codec?: "h264" | "h265";
   quality?: "draft" | "standard" | "high";
   chunkSize?: number;

packages/producer/src/distributed.ts

@@ -70,6 +70,11 @@ export {
 // ── Assemble (Activity C) ───────────────────────────────────────────────────
 export { assemble, type AssembleResult } from "./services/distributed/assemble.js";
 
+// ── Format union ────────────────────────────────────────────────────────────
+// Canonical output-format type. The aws-lambda package re-exports it so
+// CLI / adopter SDKs can derive runtime allowlists from one source.
+export type { DistributedFormat } from "./services/distributed/shared.js";
+
 // ── Plan-time shared types from `freezePlan` ───────────────────────────────
 // Re-exported so adopters that deserialize a planDir's `meta/encoder.json`
 // or `meta/chunks.json` see the same shapes the producer wrote them as.

packages/producer/src/regression-harness-distributed.ts

@@ -35,6 +35,7 @@ import { existsSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
 import type { Fps } from "@hyperframes/core";
 import { assemble, plan, renderChunk } from "./distributed.js";
+import type { DistributedFormat } from "./services/distributed/shared.js";
 
 /**
  * Three-mode contract that backs `--mode=<value>` on the regression
@@ -81,7 +82,7 @@ export type DistributedSupportResult = { supported: true } | { supported: false;
  */
 export function checkDistributedSupport(renderConfig: {
   fps: Fps;
-  format?: "mp4" | "webm" | "mov" | "png-sequence";
+  format?: DistributedFormat;
   hdr?: boolean;
 }): DistributedSupportResult {
   if (renderConfig.fps.den !== 1) {
@@ -120,7 +121,7 @@ export interface RunDistributedSimulatedInput {
   renderedOutputPath: string;
   /** From the fixture's renderConfig — must pass `checkDistributedSupport`. */
   fps: 24 | 30 | 60;
-  format: "mp4" | "mov" | "png-sequence" | "webm";
+  format: DistributedFormat;
   /**
    * Codec for `format: "mp4"`. Defaults to `"h264"`; pass `"h265"` to
    * exercise the libx265 closed-GOP path. Ignored for non-mp4 formats —

packages/producer/src/regression-harness-lambda-local-types.ts

@@ -9,6 +9,8 @@
  * type-check pass.
  */
 
+import type { DistributedFormat } from "./services/distributed/shared.js";
+
 /** Inputs for {@link runLambdaLocalRender}. Same contract as `runDistributedSimulatedRender`. */
 export interface RunLambdaLocalInput {
   projectDir: string;
@@ -26,7 +28,7 @@ export interface RunLambdaLocalInput {
    */
   width: number;
   height: number;
-  format: "mp4" | "mov" | "png-sequence" | "webm";
+  format: DistributedFormat;
   codec?: "h264" | "h265";
   chunkSize?: number;
   maxParallelChunks?: number;