chore: import upstream snapshot with attribution

examples/aws-lambda/.gitignore

@@ -0,0 +1,3 @@
+# SAM CLI state — written by `sam deploy --guided`, contains user choices.
+samconfig.toml
+.aws-sam/

examples/aws-lambda/README.md

@@ -0,0 +1,227 @@
+# AWS Lambda + Step Functions deployment
+
+Reference SAM template for deploying HyperFrames distributed rendering on
+AWS. One Lambda function, three roles (Plan / RenderChunk / Assemble),
+choreographed by a Step Functions standard workflow with a Map state for
+parallel chunk rendering.
+
+See [`packages/aws-lambda/README.md`](../../packages/aws-lambda/README.md)
+for the Lambda handler architecture.
+
+## Prerequisites
+
+- AWS account with IAM permissions to deploy CloudFormation stacks
+  containing Lambda, Step Functions, S3, IAM, and CloudWatch resources.
+- [`sam` CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-sam-cli.html)
+  installed (≥ 1.100).
+- [`bun`](https://bun.sh) installed (≥ 1.3) to build the handler ZIP.
+
+## One-shot deploy
+
+```bash
+# 1. Build the handler ZIP that `template.yaml`'s CodeUri points at.
+bun install                                       # at repo root
+bun run --cwd packages/aws-lambda build:zip
+
+# 2. Deploy. First time: `--guided` to set stack name + region.
+cd examples/aws-lambda
+sam deploy --guided --resolve-s3
+```
+
+`--resolve-s3` lets SAM pick (or create) a per-account bucket to host the
+uploaded ZIP. After the first deploy, subsequent updates can omit
+`--guided` and `--resolve-s3` — SAM remembers your choices in
+`samconfig.toml`.
+
+## What gets created
+
+| Resource                                 | Purpose                                                                                            |
+| ---------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| `Render Lambda`                          | Single function, handler `handler.handler`. Dispatches on `event.Action`.                          |
+| `Render State Machine`                   | Step Functions standard workflow. Plan → Map(N) RenderChunk → Assemble.                            |
+| `Render Bucket`                          | S3 bucket for plan tarballs, chunk outputs, and final mp4. `renders/` prefix expires after 7 days. |
+| IAM role for the state machine           | Invokes the Lambda; writes CloudWatch logs; X-Ray traces.                                          |
+| IAM role for the Lambda (managed by SAM) | S3 CRUD on the render bucket; CloudWatch logs.                                                     |
+| Runaway-invocation alarm                 | Fires if RenderChunk runs more than `ChunkInvocationAlarmThreshold` times in an hour.              |
+
+## Running a render
+
+Upload your project as a zip to the render bucket, then start a Step
+Functions execution:
+
+```bash
+STACK_NAME=hyperframes-render          # whatever you picked at deploy
+RENDER_BUCKET=$(aws cloudformation describe-stacks \
+  --stack-name "$STACK_NAME" \
+  --query 'Stacks[0].Outputs[?OutputKey==`RenderBucketName`].OutputValue' \
+  --output text)
+STATE_MACHINE_ARN=$(aws cloudformation describe-stacks \
+  --stack-name "$STACK_NAME" \
+  --query 'Stacks[0].Outputs[?OutputKey==`RenderStateMachineArn`].OutputValue' \
+  --output text)
+
+# Tar + upload the project directory. The handler uses `tar` (not
+# `unzip`, which Lambda's base image doesn't ship), so the on-the-wire
+# archive format is `.tar.gz`.
+tar -czf my-project.tar.gz -C ./my-project .
+aws s3 cp my-project.tar.gz "s3://${RENDER_BUCKET}/projects/my-project.tar.gz"
+
+# Start the execution. The input JSON tells the state machine where to
+# read inputs and write outputs.
+aws stepfunctions start-execution \
+  --state-machine-arn "$STATE_MACHINE_ARN" \
+  --input "$(cat <<EOF
+{
+  "ProjectS3Uri": "s3://${RENDER_BUCKET}/projects/my-project.tar.gz",
+  "PlanOutputS3Prefix": "s3://${RENDER_BUCKET}/renders/$(date +%s)/",
+  "OutputS3Uri": "s3://${RENDER_BUCKET}/output.mp4",
+  "Config": {
+    "fps": 30,
+    "width": 1920,
+    "height": 1080,
+    "format": "mp4",
+    "chunkSize": 240,
+    "maxParallelChunks": 8,
+    "runtimeCap": "lambda"
+  }
+}
+EOF
+)"
+```
+
+The Step Functions execution kicks off Plan, fans out RenderChunk via
+the Map state, and finally Assemble. Final mp4 lands at `OutputS3Uri`.
+
+## Local invocation
+
+You can test the Lambda handler without deploying anything via SAM
+local:
+
+```bash
+# Build the ZIP first.
+bun run --cwd packages/aws-lambda build:zip
+
+# Launch a local Lambda runtime emulator and run a sample plan event.
+cd examples/aws-lambda
+sam validate
+sam local invoke RenderFunction --event sample-events/plan.json
+```
+
+The `sample-events/` directory ships small JSON payloads for each of the
+three actions. They reference fake S3 URIs — useful for sanity-checking
+the handler's dispatch logic; not for full end-to-end testing (real S3
+calls require credentials and a project zip to actually exist).
+
+## End-to-end smoke + benchmark
+
+For full end-to-end validation against real AWS — the gate that proves
+the architecture works on a deployed Lambda — use the local smoke
+script:
+
+```bash
+# All defaults (mp4-h264-sdr fixture, chunk counts 2/4/8, PSNR >= 40 dB).
+./scripts/smoke.sh
+
+# Customised:
+./scripts/smoke.sh \
+  --fixture mp4-h264-sdr \
+  --chunk-counts 2,4,8,16 \
+  --psnr-threshold 40 \
+  --reserved-concurrency 8
+
+# Keep the stack alive for inspection afterward:
+./scripts/smoke.sh --keep-stack
+
+# Show all flags including cost notes:
+./scripts/smoke.sh --help
+```
+
+The script builds the handler ZIP, deploys this template under a
+per-run stack name, renders the fixture at each chunk count via the
+Step Functions state machine, PSNR-compares against the in-process
+baseline (which is git-LFS tracked under
+`packages/producer/tests/distributed/<fixture>/output/`), captures
+per-execution Step Functions history, and tears the stack down.
+
+**Wall-clock methodology caveat (`eval.sh` only).** `eval.sh` reports a
+local-vs-Lambda "speedup" column. The local timing includes `bun` +
+`tsx` + harness scaffolding (not just renderer-internal time); the
+Lambda timing measures Step Functions execution only. This biases the
+speedup against Lambda on tiny fixtures and in favour of Lambda on
+larger ones. Treat the number as "end-to-end CLI experience," not as a
+renderer-vs-renderer benchmark. Cold-start variance is ±5-10s per
+chunk; run with `--iterations 3+` to report medians.
+
+**Cost per pass.** Each `eval.sh` invocation runs `SAM deploy` (~$0.01
+in CFN operations) plus N fixtures × ITERATIONS × CHUNK_COUNT Lambda
+invocations at `MemorySize` (default 10 GiB) × per-chunk wall clock.
+With defaults (4 fixtures, 1 iteration, chunk-count 4) the Lambda
+spend is roughly $0.10-$0.20 per pass before S3 transfer. Lower
+`--reserved-concurrency` for cost-conscious accounts; higher
+`--iterations` improves median stability at proportional cost.
+
+Outputs land under `<repo-root>/lambda-smoke-artifacts/`:
+
+- `results.json` — `chunkCount × wallClockMs × psnrAvgDb`
+- `renders/N<N>-output.mp4` — each rendered chunk count
+- `renders/N<N>-history.json` — full Step Functions execution history
+
+Prerequisites: `aws` (v2), `sam` (≥ 1.100), `bun` (≥ 1.3), `ffmpeg`,
+`jq`, `zip`. AWS credentials come from the standard resolution chain
+(env vars → `~/.aws/credentials` → SSO → IMDS). Pin a specific profile
+with `--profile <name>` or `AWS_PROFILE=<name>`.
+
+## Parameters
+
+| Parameter                       | Default       | Notes                                                                                           |
+| ------------------------------- | ------------- | ----------------------------------------------------------------------------------------------- |
+| `ProjectName`                   | `hyperframes` | Prefix for created resource names.                                                              |
+| `LambdaMemoryMb`                | `10240`       | Lambda memory; Lambda allocates CPU proportionally. 10 GB recommended for 1080p.                |
+| `LambdaTimeoutSec`              | `900`         | Per-invocation timeout. 15 min is Lambda's hard ceiling.                                        |
+| `ReservedConcurrency`           | `-1`          | Hard cap on simultaneous Lambda invocations. `-1` = unreserved. Set to e.g. `50` to bound cost. |
+| `ChromeSource`                  | `sparticuz`   | Must match the `--source=` flag passed to `build-zip.ts`.                                       |
+| `ChunkInvocationAlarmThreshold` | `1000`        | CloudWatch alarm threshold (RenderChunk invocations per hour).                                  |
+
+## Cleanup
+
+```bash
+sam delete --stack-name hyperframes-render
+```
+
+S3 buckets are `Retain`ed on delete to protect rendered artifacts.
+Empty + delete the bucket manually after `sam delete` if you want to
+fully tear down.
+
+## Cost model
+
+| Service                 | Driver                                  | Approximate cost                                               |
+| ----------------------- | --------------------------------------- | -------------------------------------------------------------- |
+| Lambda                  | Per-invocation billed duration × memory | ≈ $0.0000167/GB-s; a 10 GB function running 5 min costs ~$0.50 |
+| Step Functions Standard | Per state transition                    | $0.025/1k transitions                                          |
+| S3                      | Storage + GET/PUT                       | Dominated by mp4 storage; plan tarballs expire in 7 days       |
+| CloudWatch Logs         | Ingestion + storage                     | Logs are not throttled; set retention manually if cost matters |
+
+A 60-second 1080p30 composition at default chunkSize=240 (8 chunks)
+typically costs ~$0.04 in Lambda time + ~$0.001 in Step Functions.
+The eval script under `scripts/eval.sh` produces real per-fixture cost
+numbers when you run it against your own AWS account.
+
+## Troubleshooting
+
+- **"Chrome failed to launch"** — the ZIP was likely built with the wrong
+  `--source`. Match `ChromeSource` to the build flag.
+- **"PLAN_HASH_MISMATCH"** — non-retryable. The plan tarball was written
+  by a different version of the producer than the chunk worker is
+  running. Re-plan from scratch.
+- **"BROWSER_GPU_NOT_SOFTWARE"** — Chromium fell back to a hardware GL
+  backend. Should not happen in Lambda (no GPU); file an issue.
+- **CloudWatch alarm firing on `runaway-chunk-invocations`** — check
+  the state machine execution history for an unintended Map fan-out, or
+  raise the threshold if your workload genuinely exceeds it.
+
+## What's NOT in this directory
+
+- CDK construct shipping the same topology programmatically — follow-up.
+- `hyperframes lambda deploy / render / progress / destroy` CLI — follow-up.
+- Migration guide — follow-up.
+- Lambda RIE local smoke harness mode — follow-up.

examples/aws-lambda/sample-events/assemble.json

@@ -0,0 +1,13 @@
+{
+  "Action": "assemble",
+  "PlanS3Uri": "s3://example-bucket/renders/sample/plan.tar.gz",
+  "ChunkS3Uris": [
+    "s3://example-bucket/renders/sample/chunks/0000.mp4",
+    "s3://example-bucket/renders/sample/chunks/0001.mp4",
+    "s3://example-bucket/renders/sample/chunks/0002.mp4",
+    "s3://example-bucket/renders/sample/chunks/0003.mp4"
+  ],
+  "AudioS3Uri": null,
+  "OutputS3Uri": "s3://example-bucket/renders/sample/output.mp4",
+  "Format": "mp4"
+}

examples/aws-lambda/sample-events/plan.json

@@ -0,0 +1,14 @@
+{
+  "Action": "plan",
+  "ProjectS3Uri": "s3://example-bucket/projects/sample-composition.tar.gz",
+  "PlanOutputS3Prefix": "s3://example-bucket/renders/sample/",
+  "Config": {
+    "fps": 30,
+    "width": 1920,
+    "height": 1080,
+    "format": "mp4",
+    "chunkSize": 240,
+    "maxParallelChunks": 8,
+    "runtimeCap": "lambda"
+  }
+}

examples/aws-lambda/sample-events/render-chunk.json

@@ -0,0 +1,8 @@
+{
+  "Action": "renderChunk",
+  "PlanS3Uri": "s3://example-bucket/renders/sample/plan.tar.gz",
+  "PlanHash": "0000000000000000000000000000000000000000000000000000000000000000",
+  "ChunkIndex": 0,
+  "ChunkOutputS3Prefix": "s3://example-bucket/renders/sample/",
+  "Format": "mp4"
+}

examples/aws-lambda/scripts/eval.sh

@@ -0,0 +1,468 @@
+#!/usr/bin/env bash
+# Eval: local in-process renderer vs Lambda distributed across a set of
+# fixtures. For each fixture:
+#
+#   1. Render in-process locally (regression harness) → wall-clock
+#   2. Render via Lambda Step Functions at the configured chunk count → wall-clock + output mp4
+#   3. ffmpeg-psnr (Lambda output, in-process baseline) → visual equivalence
+#
+# This is a maintainer-run benchmark, not a CI gate. It deploys a real
+# Lambda stack (same template as smoke.sh) and tears it down at the end.
+#
+# Wall-clock methodology caveat:
+#   The "local" timing includes `bun` + `tsx` + harness startup
+#   scaffolding, not just renderer-internal time. Lambda timing measures
+#   pure Step-Functions execution. The "speedup" column therefore biases
+#   AGAINST Lambda on tiny fixtures (where harness boot dominates) and
+#   IN FAVOUR of Lambda on larger ones. Treat the speedup as a rough
+#   "what does the end-to-end CLI experience feel like" number, not as
+#   "renderer-vs-renderer." Use --iterations N to get medians instead of
+#   single-sample readings — cold-start variance is ±5-10s.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../../.." && pwd)"
+SAM_DIR="$SCRIPT_DIR/.."
+
+FIXTURES="${FIXTURES:-mp4-h264-sdr,many-cuts,gsap-letters-render-compat,heygen-promo-preview-assets}"
+CHUNK_COUNT="${CHUNK_COUNT:-4}"
+# Pin chunkSize across all fixtures so wall-clock comparisons are
+# meaningful — without a fixed value, each fixture's plan() picks
+# `min(default 240, frameCount)` and short compositions render in 1
+# chunk regardless of CHUNK_COUNT. 60 frames keeps every fixture in
+# the table chunked.
+CHUNK_SIZE="${CHUNK_SIZE:-60}"
+PSNR_THRESHOLD="${PSNR_THRESHOLD:-40}"
+STACK_NAME="${STACK_NAME:-hyperframes-lambda-eval-$(date +%s)}"
+AWS_REGION="${AWS_REGION:-us-east-1}"
+AWS_PROFILE="${AWS_PROFILE:-}"
+KEEP_STACK="false"
+SKIP_BUILD="false"
+SKIP_LOCAL="false"
+# Lambda Map-state concurrency cap. 16 is aggressive; lower for cheaper
+# runs, raise as far as your account's regional quota allows.
+RESERVED_CONCURRENCY="${RESERVED_CONCURRENCY:-16}"
+# Number of Lambda renders per fixture. Cold-start variance is ±5-10s
+# per chunk; a single sample is noisy. With --iterations 3+ we report
+# the median Lambda wall-clock and use it for the speedup calculation.
+ITERATIONS="${ITERATIONS:-1}"
+ARTIFACT_DIR="$REPO_ROOT/lambda-eval-artifacts"
+
+usage() {
+  cat <<'EOF'
+Usage: eval.sh [flags]
+
+Maintainer-run benchmark comparing local in-process rendering to Lambda
+distributed rendering across a set of fixtures. Deploys a real Lambda
+stack, renders each fixture twice (locally + via Step Functions), and
+tears the stack down.
+
+Flags:
+  --fixtures <comma-sep>        fixture names (default: mp4-h264-sdr,many-cuts,gsap-letters-render-compat,heygen-promo-preview-assets)
+  --chunk-count <N>             chunk fan-out per Lambda render (default: 4)
+  --chunk-size <frames>         frames per chunk; pinned across fixtures (default: 60)
+  --psnr-threshold <db>         PSNR floor in dB for visual equivalence (default: 40)
+  --iterations <N>              Lambda renders per fixture; report median (default: 1)
+  --stack-name <name>           SAM stack name (default: hyperframes-lambda-eval-<timestamp>)
+  --region <region>             AWS region (default: $AWS_REGION or us-east-1)
+  --profile <name>              AWS profile (default: $AWS_PROFILE)
+  --reserved-concurrency <N>    Lambda Map MaxConcurrency cap (default: 16)
+  --keep-stack                  skip `sam delete` at the end
+  --skip-build                  reuse existing dist/handler.zip
+  --skip-local                  skip the in-process local render (Lambda-only)
+  -h, --help                    show this help and exit
+
+Cost notes:
+  Each pass: SAM deploy (~$0.01) + N fixtures × ITERATIONS × CHUNK_COUNT
+  Lambda invocations at MemorySize (default 10240 MB) × per-chunk wall
+  clock. With defaults (4 fixtures, 1 iteration, chunk-count 4) the
+  Lambda spend is roughly $0.10-$0.20 per pass before S3 PUT/GET. Drop
+  --reserved-concurrency for cost-conscious accounts; bump --iterations
+  for stable median timing at proportional cost.
+EOF
+}
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --fixtures)        FIXTURES="$2"; shift 2 ;;
+    --chunk-count)     CHUNK_COUNT="$2"; shift 2 ;;
+    --chunk-size)      CHUNK_SIZE="$2"; shift 2 ;;
+    --psnr-threshold)  PSNR_THRESHOLD="$2"; shift 2 ;;
+    --iterations)      ITERATIONS="$2"; shift 2 ;;
+    --stack-name)      STACK_NAME="$2"; shift 2 ;;
+    --region)          AWS_REGION="$2"; shift 2 ;;
+    --profile)         AWS_PROFILE="$2"; shift 2 ;;
+    --reserved-concurrency) RESERVED_CONCURRENCY="$2"; shift 2 ;;
+    --keep-stack)      KEEP_STACK="true"; shift ;;
+    --skip-build)      SKIP_BUILD="true"; shift ;;
+    --skip-local)      SKIP_LOCAL="true"; shift ;;
+    -h|--help)         usage; exit 0 ;;
+    *) echo "Unknown flag: $1" >&2; exit 1 ;;
+  esac
+done
+
+# Validate ITERATIONS is a positive integer (used as awk numeric input
+# in the median computation; a non-numeric value would silently produce
+# garbage timings).
+case "$ITERATIONS" in
+  ''|*[!0-9]*) echo "ERROR: --iterations must be a positive integer (got '$ITERATIONS')" >&2; exit 1 ;;
+esac
+if [ "$ITERATIONS" -lt 1 ]; then
+  echo "ERROR: --iterations must be >= 1 (got $ITERATIONS)" >&2
+  exit 1
+fi
+
+# AWS_DEFAULT_REGION is required for SAM (it doesn't honour AWS_REGION
+# alone). Export both so any sub-tool resolves the same region.
+export AWS_REGION
+export AWS_DEFAULT_REGION="$AWS_REGION"
+if [ -n "$AWS_PROFILE" ]; then
+  export AWS_PROFILE
+fi
+
+BUCKET=""
+
+cleanup_and_exit() {
+  local code="${1:-0}"
+  # The EXIT trap re-enters cleanup_and_exit on the way out; disarm it
+  # so we don't recurse infinitely if `aws s3 rm` itself trips set -e.
+  trap - EXIT
+  if [ "$KEEP_STACK" = "true" ]; then
+    echo "→ Keeping stack (--keep-stack); stack=$STACK_NAME"
+  else
+    echo "→ Tearing down stack $STACK_NAME"
+    if [ -n "$BUCKET" ]; then
+      aws s3 rm "s3://$BUCKET" --recursive >/dev/null 2>&1 || true
+      aws s3 rb "s3://$BUCKET" --force >/dev/null 2>&1 || true
+    fi
+    (cd "$SAM_DIR" && sam delete --stack-name "$STACK_NAME" --no-prompts) >/dev/null 2>&1 || true
+  fi
+  exit "$code"
+}
+
+# Trap unexpected failures (set -e trips, SIGINT, etc.) so we don't leak
+# the deployed stack + S3 bucket on a non-routed error. Explicit
+# cleanup_and_exit calls disarm the trap first so the teardown runs
+# exactly once.
+trap 'cleanup_and_exit $?' EXIT
+
+# ── Pre-flight ───────────────────────────────────────────────────────────
+for cmd in aws sam bun ffmpeg jq zip; do
+  if ! command -v "$cmd" >/dev/null 2>&1; then
+    echo "ERROR: '$cmd' not found on PATH." >&2
+    exit 1
+  fi
+done
+
+echo "→ Verifying AWS credentials"
+aws sts get-caller-identity --output text >/dev/null
+
+mkdir -p "$ARTIFACT_DIR/lambda" "$ARTIFACT_DIR/local"
+RESULTS_CSV="$ARTIFACT_DIR/results.csv"
+echo "fixture,localMs,lambdaMs,speedup,psnrLambdaVsBaselineDb,audioStatus,audioResidualRmsDb" > "$RESULTS_CSV"
+
+# ── 1. Build + deploy once ───────────────────────────────────────────────
+if [ "$SKIP_BUILD" = "false" ]; then
+  echo "→ Building handler ZIP"
+  bun run --cwd "$REPO_ROOT/packages/aws-lambda" build:zip
+fi
+
+echo "→ SAM deploy (stack=$STACK_NAME)"
+(cd "$SAM_DIR" && sam deploy \
+  --stack-name "$STACK_NAME" \
+  --region "$AWS_REGION" \
+  --resolve-s3 \
+  --capabilities CAPABILITY_IAM \
+  --no-confirm-changeset \
+  --no-fail-on-empty-changeset \
+  --parameter-overrides \
+    ChromeSource=sparticuz \
+    "ReservedConcurrency=$RESERVED_CONCURRENCY") || cleanup_and_exit 3
+
+BUCKET=$(aws cloudformation describe-stacks \
+  --stack-name "$STACK_NAME" \
+  --query "Stacks[0].Outputs[?OutputKey=='RenderBucketName'].OutputValue" \
+  --output text)
+STATE_MACHINE_ARN=$(aws cloudformation describe-stacks \
+  --stack-name "$STACK_NAME" \
+  --query "Stacks[0].Outputs[?OutputKey=='RenderStateMachineArn'].OutputValue" \
+  --output text)
+echo "→ Stack ready: bucket=$BUCKET"
+
+# ── 2. Per-fixture eval ──────────────────────────────────────────────────
+IFS=',' read -ra FIXTURE_LIST <<< "$FIXTURES"
+for FIXTURE in "${FIXTURE_LIST[@]}"; do
+  echo
+  echo "================== Fixture: $FIXTURE =================="
+
+  FIXTURE_DIR=""
+  for cand in "$REPO_ROOT/packages/producer/tests/distributed/$FIXTURE" "$REPO_ROOT/packages/producer/tests/$FIXTURE"; do
+    if [ -f "$cand/meta.json" ] && [ -f "$cand/src/index.html" ]; then
+      FIXTURE_DIR="$cand"
+      break
+    fi
+  done
+  if [ -z "$FIXTURE_DIR" ]; then
+    echo "WARN: fixture $FIXTURE not found, skipping" >&2
+    continue
+  fi
+  BASELINE_MP4="$FIXTURE_DIR/output/output.mp4"
+  LAMBDA_MP4="$ARTIFACT_DIR/lambda/$FIXTURE.mp4"
+
+  # ── 2a. Local in-process timing via the regression harness ────────────
+  # The harness renders the fixture in-process locally and compares it to
+  # the committed Docker-built baseline. We don't keep the rendered mp4
+  # (the harness discards its tempdir); we only need its wall-clock here
+  # because the PSNR comparisons below all run against the committed
+  # `output/output.mp4` baseline — the same artifact the harness produced
+  # when the fixture was first authored.
+  LOCAL_MS=""
+  if [ "$SKIP_LOCAL" = "false" ]; then
+    echo "→ Local in-process render via regression harness"
+    LOCAL_START=$(date +%s%3N)
+    if bun run --cwd "$REPO_ROOT/packages/producer" --silent test -- "$FIXTURE" \
+         >"$ARTIFACT_DIR/local/$FIXTURE.harness.log" 2>&1; then
+      LOCAL_END=$(date +%s%3N)
+      LOCAL_MS=$((LOCAL_END - LOCAL_START))
+      echo "  local wall=${LOCAL_MS}ms"
+    else
+      echo "WARN: regression harness failed for $FIXTURE (see $ARTIFACT_DIR/local/$FIXTURE.harness.log)" >&2
+      LOCAL_MS=""
+    fi
+  else
+    echo "→ Skipping local render (--skip-local)"
+    LOCAL_MS="0"
+  fi
+
+  # ── 2b. Lambda render ───────────────────────────────────────────────────
+  echo "→ Lambda render (N=$CHUNK_COUNT, iterations=$ITERATIONS)"
+  FIXTURE_META="$FIXTURE_DIR/meta.json"
+  # Some fixtures store fps as a number (e.g. 30), others as {num,den}.
+  # Pick the integer fps the Lambda config wants out of either shape.
+  BASE_FPS=$(jq -r '
+    .renderConfig.fps
+    | if type == "object" then .num // 30 else . end
+    // 30
+  ' "$FIXTURE_META")
+  BASE_W=$(jq -r '.renderConfig.width // 640' "$FIXTURE_META")
+  BASE_H=$(jq -r '.renderConfig.height // 360' "$FIXTURE_META")
+
+  # Pack + upload once per fixture (the project tarball is content-
+  # addressable; iterations reuse the same S3 object).
+  TMP=$(mktemp -d)
+  tar -czf "$TMP/project.tar.gz" -C "$FIXTURE_DIR/src" .
+  aws s3 cp "$TMP/project.tar.gz" "s3://$BUCKET/projects/$FIXTURE.tar.gz" >/dev/null
+  rm -rf "$TMP"
+
+  ITER_TIMINGS=()
+  ITER_FAILED=0
+  for ITER in $(seq 1 "$ITERATIONS"); do
+    if [ "$ITERATIONS" -gt 1 ]; then
+      echo "  iter $ITER/$ITERATIONS"
+    fi
+    EXEC_NAME="eval-$FIXTURE-$(date +%s)-${ITER}"
+    OUTPUT_KEY="renders/$EXEC_NAME/output.mp4"
+    INPUT_JSON=$(jq -n \
+      --arg project "s3://$BUCKET/projects/$FIXTURE.tar.gz" \
+      --arg prefix "s3://$BUCKET/renders/$EXEC_NAME/" \
+      --arg output "s3://$BUCKET/$OUTPUT_KEY" \
+      --argjson n "$CHUNK_COUNT" \
+      --argjson cs "$CHUNK_SIZE" \
+      --argjson fps "$BASE_FPS" \
+      --argjson w "$BASE_W" \
+      --argjson h "$BASE_H" \
+      '{ProjectS3Uri:$project,PlanOutputS3Prefix:$prefix,OutputS3Uri:$output,Config:{fps:$fps,width:$w,height:$h,format:"mp4",chunkSize:$cs,maxParallelChunks:$n,runtimeCap:"lambda"}}')
+
+    LAMBDA_START=$(date +%s%3N)
+    EXEC_ARN=$(aws stepfunctions start-execution \
+      --state-machine-arn "$STATE_MACHINE_ARN" \
+      --name "$EXEC_NAME" \
+      --input "$INPUT_JSON" \
+      --query executionArn --output text)
+    STATUS="RUNNING"
+    for _ in $(seq 1 360); do
+      sleep 5
+      STATUS=$(aws stepfunctions describe-execution \
+        --execution-arn "$EXEC_ARN" --query status --output text)
+      if [ "$STATUS" != "RUNNING" ]; then break; fi
+    done
+    LAMBDA_END=$(date +%s%3N)
+    ITER_MS=$((LAMBDA_END - LAMBDA_START))
+
+    if [ "$STATUS" != "SUCCEEDED" ]; then
+      echo "WARN: Lambda render of $FIXTURE (iter $ITER) failed ($STATUS); saving execution history" >&2
+      aws stepfunctions describe-execution --execution-arn "$EXEC_ARN" \
+        > "$ARTIFACT_DIR/lambda/$FIXTURE.iter${ITER}.execution.json" 2>/dev/null || true
+      aws stepfunctions get-execution-history --execution-arn "$EXEC_ARN" --max-results 1000 --output json \
+        > "$ARTIFACT_DIR/lambda/$FIXTURE.iter${ITER}.history.json" 2>/dev/null || true
+      cause=$(jq -r '.events[] | select(.type=="ExecutionFailed" or .type=="TaskFailed") | (.executionFailedEventDetails // .taskFailedEventDetails) | .cause // .error' "$ARTIFACT_DIR/lambda/$FIXTURE.iter${ITER}.history.json" 2>/dev/null | head -1)
+      [ -n "$cause" ] && echo "  cause: $(echo "$cause" | head -c 300)" >&2
+      ITER_FAILED=1
+      break
+    fi
+
+    # Keep the last successful iteration's mp4 as the PSNR/audio input.
+    aws s3 cp "s3://$BUCKET/$OUTPUT_KEY" "$LAMBDA_MP4" >/dev/null
+    ITER_TIMINGS+=("$ITER_MS")
+    if [ "$ITERATIONS" -gt 1 ]; then
+      echo "    iter $ITER wall=${ITER_MS}ms"
+    fi
+  done
+
+  if [ "$ITER_FAILED" -eq 1 ] || [ ${#ITER_TIMINGS[@]} -eq 0 ]; then
+    continue
+  fi
+
+  # Median of the iteration wall-clocks. Awk handles both odd (middle
+  # element) and even (mean of middle two) sample counts without
+  # bash-side branching. For ITERATIONS=1 the median is just the sample.
+  LAMBDA_MS=$(printf '%s\n' "${ITER_TIMINGS[@]}" \
+    | sort -n \
+    | awk '
+        { a[NR] = $1 }
+        END {
+          n = NR
+          if (n % 2 == 1) print a[int((n + 1) / 2)]
+          else printf("%.0f\n", (a[n/2] + a[n/2 + 1]) / 2)
+        }
+      ')
+  if [ "$ITERATIONS" -gt 1 ]; then
+    echo "  lambda median wall=${LAMBDA_MS}ms (samples: ${ITER_TIMINGS[*]})"
+  else
+    echo "  lambda wall=${LAMBDA_MS}ms"
+  fi
+
+  # ── 2c. PSNR comparisons ───────────────────────────────────────────────
+  psnr_of() {
+    local a="$1" b="$2"
+    local log
+    log=$(mktemp)
+    ffmpeg -nostdin -v error -i "$a" -i "$b" -lavfi "psnr=stats_file=$log" -f null - 2>/dev/null || true
+    awk '/psnr_avg:/ { for(i=1;i<=NF;i++) if($i ~ /^psnr_avg:/){split($i,kv,":"); sum+=kv[2]; c++} } END { if(c>0) printf("%.2f", sum/c); else print "0" }' "$log"
+    rm -f "$log"
+  }
+  # The "local" mp4 IS the baseline (we don't keep a fresh in-process
+  # render — the harness above discards its tempdir, and the baseline
+  # IS the canonical in-process output). So `psnr(lambda, baseline)` is
+  # the only PSNR we report. A future revision that retains a fresh
+  # local render could split this back into three comparisons.
+  PSNR_LAMBDA_BASE=$(psnr_of "$LAMBDA_MP4" "$BASELINE_MP4")
+
+  # ── 2d. Audio equivalence (residual RMS) ──────────────────────────────
+  # Subtract baseline audio from Lambda audio; measure residual RMS in
+  # dBFS. A perfectly-equivalent track produces residual silence
+  # (≤ -90 dBFS in practice for AAC-vs-AAC); we treat ≤ -50 dBFS as
+  # "effectively identical." For fixtures with no audio stream on either
+  # side, we emit `n/a` rather than a number.
+  audio_residual_rms_db() {
+    local a="$1" b="$2"
+    local has_a has_b
+    has_a=$(ffprobe -v error -select_streams a -show_entries stream=index -of csv=p=0 "$a" 2>/dev/null | head -1)
+    has_b=$(ffprobe -v error -select_streams a -show_entries stream=index -of csv=p=0 "$b" 2>/dev/null | head -1)
+    if [ -z "$has_a" ] && [ -z "$has_b" ]; then
+      printf "no-audio-on-either"
+      return
+    fi
+    if [ -z "$has_a" ] || [ -z "$has_b" ]; then
+      printf "audio-stream-mismatch"
+      return
+    fi
+    # ffmpeg emits astats summary at log level `info`; -v error would
+    # suppress it. Use -v info and parse from the combined stderr.
+    #
+    # `amix normalize=0` is load-bearing: the default normalize=true
+    # scales each input by 1/N before summing, so a 2-input subtract
+    # reports the residual at -6 dB versus the true difference, making
+    # the -50 dBFS gate effectively -44 dBFS. Disabling normalization
+    # gives the actual sample-cancellation reading.
+    local out
+    out=$(ffmpeg -nostdin -v info -i "$a" -i "$b" \
+            -filter_complex "[0:a]aresample=48000,pan=stereo|c0=c0|c1=c1,asetpts=N/SR/TB[a0];[1:a]aresample=48000,pan=stereo|c0=c0|c1=c1,asetpts=N/SR/TB,volume=-1[a1];[a0][a1]amix=inputs=2:duration=shortest:dropout_transition=0:normalize=0,astats=metadata=1:reset=1[out]" \
+            -map "[out]" -f null - 2>&1)
+    # Match the Overall-RMS line (variant forms across ffmpeg versions).
+    local rms
+    rms=$(printf '%s\n' "$out" | grep -oE "Overall RMS level(\s*dB)?\s*:\s*(-?inf|[-0-9.]+)" | head -1 | sed -E 's/.*:\s*//')
+    if [ -z "$rms" ]; then
+      # Fallback 1: per-channel "RMS level dB:" lines, which most modern
+      # ffmpeg builds emit. Picks the first (most pessimistic).
+      rms=$(printf '%s\n' "$out" | grep -oE "RMS level\s*dB\s*:\s*(-?inf|[-0-9.]+)" | head -1 | sed -E 's/.*:\s*//')
+    fi
+    if [ -z "$rms" ]; then
+      # Fallback 2: very old ffmpeg builds emit `RMS level:` with no `dB`
+      # suffix and the unit trailing the value (e.g. `RMS level: -42.3 dB`).
+      # Use word boundaries to avoid eating `RMS peak level` lines.
+      rms=$(printf '%s\n' "$out" | grep -oE "\bRMS level\b\s*:\s*(-?inf|[-0-9.]+)" | head -1 | sed -E 's/.*:\s*//')
+    fi
+    if [ -z "$rms" ]; then
+      rms="0"
+    fi
+    # Normalize ffmpeg's "-inf" / "inf" sentinels to a sortable number well
+    # below any sensible threshold so downstream awk comparisons don't trip
+    # on the literal string. ("-inf" = perfect cancellation; -200 dBFS is
+    # far below the -50 dBFS gate.) Done in an if/then/fi rather than
+    # `[ A ] || [ B ] && C` — that compound form is parsed as `(A||B)&&C`
+    # and silently returns nonzero when both LHS checks fail, which trips
+    # `set -e` callers.
+    if [ "$rms" = "-inf" ] || [ "$rms" = "inf" ]; then
+      rms="-200"
+    fi
+    printf "%s" "$rms"
+  }
+  AUDIO_RMS=$(audio_residual_rms_db "$LAMBDA_MP4" "$BASELINE_MP4")
+  if [[ "$AUDIO_RMS" =~ ^-?[0-9.]+$ ]]; then
+    if awk -v r="$AUDIO_RMS" 'BEGIN{exit !(r<=-50)}'; then
+      AUDIO_STATUS="OK"
+    else
+      AUDIO_STATUS="DRIFT"
+    fi
+  else
+    AUDIO_STATUS="$AUDIO_RMS"
+    AUDIO_RMS="n/a"
+  fi
+
+  if [ -n "$LOCAL_MS" ] && [ "$LOCAL_MS" != "0" ] && [ "$LAMBDA_MS" != "0" ]; then
+    SPEEDUP=$(awk -v a="$LOCAL_MS" -v b="$LAMBDA_MS" 'BEGIN { printf("%.2f", a/b) }')
+  else
+    SPEEDUP="n/a"
+  fi
+  LOCAL_MS_FOR_CSV="${LOCAL_MS:-n/a}"
+  echo "  psnr(lambda,baseline)=${PSNR_LAMBDA_BASE}dB"
+  echo "  audio(lambda,baseline)=${AUDIO_STATUS} (residual RMS=${AUDIO_RMS} dBFS)  speedup=${SPEEDUP}x"
+
+  echo "$FIXTURE,$LOCAL_MS_FOR_CSV,$LAMBDA_MS,$SPEEDUP,$PSNR_LAMBDA_BASE,$AUDIO_STATUS,$AUDIO_RMS" >> "$RESULTS_CSV"
+done
+
+# ── 3. Summary ───────────────────────────────────────────────────────────
+echo
+echo "================ RESULTS ================"
+column -t -s, < "$RESULTS_CSV"
+echo
+echo "Artifacts: $ARTIFACT_DIR"
+
+# Gate on lambda-vs-baseline PSNR (visual equivalence) AND audio status.
+# Pass states: "OK" (residual ≤ -50 dBFS, audio matches), "no-audio-on-either"
+# (fixture intentionally silent on both sides). Everything else
+# ("DRIFT", "audio-stream-mismatch", "n/a", future statuses) fails.
+#
+# Use process substitution `done < <(tail ...)` rather than the pipeline
+# form `tail | while`. The pipeline form runs the while loop in a
+# subshell where FAILED=1 mutations are discarded when the subshell
+# exits, so the parent's FAILED stays 0 forever — the gate would
+# silently pass even on real failures.
+FAILED=0
+while IFS=, read -r fixture localMs lambdaMs speedup psnr audioStatus audioRms; do
+  if awk -v p="$psnr" -v t="$PSNR_THRESHOLD" 'BEGIN{exit !(p<t)}'; then
+    echo "FAIL: $fixture lambda-vs-baseline PSNR=$psnr dB below threshold $PSNR_THRESHOLD" >&2
+    FAILED=1
+  fi
+  case "$audioStatus" in
+    OK|no-audio-on-either) ;;
+    *)
+      echo "FAIL: $fixture audio status=$audioStatus (residual RMS=$audioRms dBFS)" >&2
+      FAILED=1
+      ;;
+  esac
+done < <(tail -n +2 "$RESULTS_CSV")
+
+cleanup_and_exit "$FAILED"

examples/aws-lambda/scripts/smoke.sh

@@ -0,0 +1,400 @@
+#!/usr/bin/env bash
+# Real-AWS smoke + benchmark for the HyperFrames Lambda adapter.
+#
+# Run this from a workstation with `aws` CLI credentials. Builds the
+# handler ZIP, deploys the SAM template at examples/aws-lambda/ to your
+# AWS account, renders a fixture composition through the Step Functions
+# state machine at several chunk counts, PSNR-compares each output
+# against the in-process baseline, and tears the stack down.
+#
+# Usage:
+#   ./smoke.sh                                   # all defaults
+#   ./smoke.sh --chunk-counts 2,4,8
+#   ./smoke.sh --fixture mp4-h264-sdr --keep-stack
+#   AWS_PROFILE=<your-profile> ./smoke.sh
+#
+# Required tools on PATH:
+#   - aws (v2)
+#   - sam (AWS SAM CLI, >= 1.100)
+#   - bun (>= 1.3, to build the handler ZIP)
+#   - ffmpeg (system or built-in; PSNR computation)
+#   - jq
+#   - zip
+#
+# Inputs (flags or env vars):
+#   --fixture <name>           (default: mp4-h264-sdr)
+#   --chunk-counts <list>      (default: 2,4,8)
+#   --psnr-threshold <db>      (default: 40)
+#   --stack-name <name>        (default: hyperframes-lambda-smoke-<timestamp>)
+#   --region <region>          (default: $AWS_REGION or us-east-1)
+#   --profile <name>           (default: $AWS_PROFILE, otherwise the AWS
+#                               default profile resolution chain)
+#   --keep-stack               (skip `sam delete` at the end)
+#   --skip-build               (skip the ZIP rebuild; use the existing one)
+#
+# Outputs:
+#   ./lambda-smoke-artifacts/results.json  (chunkCount x wallClockMs x psnrAvgDb)
+#   ./lambda-smoke-artifacts/renders/N<N>-output.mp4
+#   ./lambda-smoke-artifacts/renders/N<N>-history.json
+#
+# Exit codes:
+#   0  all good
+#   1  argument / pre-flight error
+#   2  ZIP build failed
+#   3  SAM deploy failed
+#   4  one or more renders failed
+#   5  PSNR below threshold
+
+set -euo pipefail
+
+# ── Resolve script directory + repo root ──────────────────────────────────
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../../.." && pwd)"
+SAM_DIR="$SCRIPT_DIR/.."
+
+# ── Defaults ──────────────────────────────────────────────────────────────
+FIXTURE="${FIXTURE:-mp4-h264-sdr}"
+CHUNK_COUNTS="${CHUNK_COUNTS:-2,4,8}"
+# The producer regression harness uses 50 dB as its PSNR floor for
+# distributed-vs-in-process renders within the SAME runtime — both
+# modes execute inside the same Dockerfile.test image, so pixel drift
+# is minimal. Real Lambda runs against a different ffmpeg build
+# (`ffmpeg-static`) and a different Chromium build (`@sparticuz/chromium`)
+# than the in-process baseline (Debian-bookworm-slim's apt ffmpeg +
+# Puppeteer-managed chrome-headless-shell). Expected drift across those
+# environments is ~3 dB on simple fixtures, more on font-heavy ones.
+# The gate defaults to 40 dB to absorb that drift; tighten it via
+# --psnr-threshold for a stricter check.
+PSNR_THRESHOLD="${PSNR_THRESHOLD:-40}"
+STACK_NAME="${STACK_NAME:-hyperframes-lambda-smoke-$(date +%s)}"
+AWS_REGION="${AWS_REGION:-us-east-1}"
+AWS_PROFILE="${AWS_PROFILE:-}"
+KEEP_STACK="false"
+SKIP_BUILD="false"
+# Lambda Map-state concurrency cap. 16 fans out the chunks aggressively
+# at the cost of a higher peak Lambda bill. Drop to 2-4 for cheaper runs;
+# raise as far as your AWS account's regional concurrency quota allows.
+RESERVED_CONCURRENCY="${RESERVED_CONCURRENCY:-16}"
+ARTIFACT_DIR="$REPO_ROOT/lambda-smoke-artifacts"
+
+usage() {
+  cat <<'EOF'
+Usage: smoke.sh [flags]
+
+Real-AWS smoke + benchmark for the HyperFrames Lambda adapter. Builds the
+handler ZIP, deploys the SAM stack to your AWS account, renders a fixture
+through Step Functions at several chunk counts, PSNR-compares each
+output against the in-process baseline, and tears the stack down.
+
+Flags:
+  --fixture <name>              fixture under packages/producer/tests/distributed/ (default: mp4-h264-sdr)
+  --chunk-counts <list>         comma-separated chunk counts to benchmark (default: 2,4,8)
+  --psnr-threshold <db>         PSNR floor in dB for visual equivalence (default: 40)
+  --stack-name <name>           SAM stack name (default: hyperframes-lambda-smoke-<timestamp>)
+  --region <region>             AWS region (default: $AWS_REGION or us-east-1)
+  --profile <name>              AWS profile (default: $AWS_PROFILE)
+  --reserved-concurrency <N>    Lambda Map MaxConcurrency cap (default: 16)
+  --keep-stack                  skip `sam delete` at the end (manual teardown later)
+  --skip-build                  reuse existing dist/handler.zip
+  -h, --help                    show this help and exit
+
+Cost notes:
+  Each run: build (free) + SAM deploy (~$0.01 in CFN ops) + per-chunk
+  Lambda invocations × MemorySize (default 10240 MB) × wall-clock seconds.
+  At 10 GB Lambda + ~30s per chunk × 8 chunks × 3 chunk-counts ≈ $0.04
+  per run before S3 PUT/GET. Set --reserved-concurrency lower for
+  cost-conscious accounts.
+
+Required tools on PATH: aws (v2), sam (>= 1.100), bun (>= 1.3), ffmpeg, jq, zip.
+EOF
+}
+
+# ── Arg parsing ───────────────────────────────────────────────────────────
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --fixture)        FIXTURE="$2"; shift 2 ;;
+    --chunk-counts)   CHUNK_COUNTS="$2"; shift 2 ;;
+    --psnr-threshold) PSNR_THRESHOLD="$2"; shift 2 ;;
+    --stack-name)     STACK_NAME="$2"; shift 2 ;;
+    --region)         AWS_REGION="$2"; shift 2 ;;
+    --profile)        AWS_PROFILE="$2"; shift 2 ;;
+    --keep-stack)     KEEP_STACK="true"; shift ;;
+    --skip-build)     SKIP_BUILD="true"; shift ;;
+    --reserved-concurrency) RESERVED_CONCURRENCY="$2"; shift 2 ;;
+    -h|--help)        usage; exit 0 ;;
+    *) echo "Unknown flag: $1" >&2; exit 1 ;;
+  esac
+done
+
+# Export AWS_REGION + AWS_PROFILE so `aws` and `sam` inherit them via the
+# standard env-var chain. AWS_PROFILE may be empty — that lets the CLI's
+# default resolution (env → ~/.aws/config → IMDS) take over without us
+# having to pass `--profile` flags everywhere.
+#
+# AWS_DEFAULT_REGION is also set because SAM CLI honours it as a higher-
+# priority signal than AWS_REGION; without it, sam will read the region
+# from the active profile's samconfig.toml or ~/.aws/config and ignore
+# whatever AWS_REGION points at.
+export AWS_REGION
+export AWS_DEFAULT_REGION="$AWS_REGION"
+if [ -n "$AWS_PROFILE" ]; then
+  export AWS_PROFILE
+fi
+
+# ── Cleanup helper (defined early so the failure paths below can call it) ─
+BUCKET=""
+
+cleanup_and_exit() {
+  local exit_code="${1:-0}"
+  # The EXIT trap re-enters cleanup_and_exit on the way out; disarm it
+  # so we don't recurse if a teardown step trips set -e.
+  trap - EXIT
+  if [ "$KEEP_STACK" = "true" ]; then
+    echo "→ Keeping stack (--keep-stack); inspect at:"
+    echo "    aws cloudformation describe-stacks --stack-name $STACK_NAME"
+    if [ -n "$BUCKET" ]; then
+      echo "    aws s3 ls s3://$BUCKET/"
+    fi
+  else
+    echo "→ Tearing down stack $STACK_NAME"
+    if [ -n "$BUCKET" ]; then
+      aws s3 rm "s3://$BUCKET" --recursive >/dev/null 2>&1 || true
+      aws s3 rb "s3://$BUCKET" --force >/dev/null 2>&1 || true
+    fi
+    (cd "$SAM_DIR" && sam delete \
+      --stack-name "$STACK_NAME" \
+      --no-prompts) >/dev/null 2>&1 || true
+  fi
+  exit "$exit_code"
+}
+
+# Trap unexpected failures (set -e trips, SIGINT, etc.) so we don't leak
+# the deployed stack + bucket on a non-routed error path. Explicit
+# cleanup_and_exit calls disarm the trap first so teardown runs once.
+trap 'cleanup_and_exit $?' EXIT
+
+# ── Pre-flight checks ─────────────────────────────────────────────────────
+for cmd in aws sam bun ffmpeg jq zip; do
+  if ! command -v "$cmd" >/dev/null 2>&1; then
+    echo "ERROR: '$cmd' not found on PATH." >&2
+    exit 1
+  fi
+done
+
+FIXTURE_DIR="$REPO_ROOT/packages/producer/tests/distributed/$FIXTURE"
+BASELINE_MP4="$FIXTURE_DIR/output/output.mp4"
+if [ ! -d "$FIXTURE_DIR" ] || [ ! -f "$FIXTURE_DIR/src/index.html" ]; then
+  echo "ERROR: fixture not found or malformed: $FIXTURE_DIR" >&2
+  exit 1
+fi
+if [ ! -f "$BASELINE_MP4" ]; then
+  echo "ERROR: baseline mp4 missing: $BASELINE_MP4" >&2
+  echo "       (this is git-LFS tracked; run 'git lfs pull' to fetch it)" >&2
+  exit 1
+fi
+
+# Verify AWS credentials before building anything heavy. We don't print
+# the profile name in error text — operators are expected to know which
+# credentials they configured.
+echo "→ Pre-flight: verifying AWS credentials (region=$AWS_REGION${AWS_PROFILE:+, profile=$AWS_PROFILE})"
+if ! aws sts get-caller-identity --output text >/dev/null 2>&1; then
+  echo "ERROR: aws sts get-caller-identity failed." >&2
+  echo "       Configure AWS credentials (env vars, ~/.aws/credentials, SSO, IMDS) or set AWS_PROFILE." >&2
+  exit 1
+fi
+
+mkdir -p "$ARTIFACT_DIR/renders"
+
+# ── 1. Build the handler ZIP ──────────────────────────────────────────────
+if [ "$SKIP_BUILD" = "false" ]; then
+  echo "→ Building handler ZIP"
+  if ! bun run --cwd "$REPO_ROOT/packages/aws-lambda" build:zip; then
+    echo "ERROR: handler ZIP build failed." >&2
+    exit 2
+  fi
+  bun run --cwd "$REPO_ROOT/packages/aws-lambda" verify:zip-size
+else
+  echo "→ Skipping ZIP build (--skip-build)"
+fi
+ls -lh "$REPO_ROOT/packages/aws-lambda/dist/handler.zip"
+
+# ── 2. SAM validate + deploy ──────────────────────────────────────────────
+echo "→ SAM validate"
+(cd "$SAM_DIR" && sam validate --lint --region "$AWS_REGION")
+
+echo "→ SAM deploy (stack=$STACK_NAME, region=$AWS_REGION)"
+# ProjectName is intentionally NOT set to $STACK_NAME — the template
+# uses ProjectName only for the function/state-machine human-facing
+# names, and forcing it long here doesn't help. The BucketName is
+# auto-generated by CloudFormation per stack so concurrent smoke runs
+# don't collide. Pass --region explicitly here even though
+# AWS_DEFAULT_REGION is set, so a stray samconfig.toml in the working
+# directory can't override the script's choice.
+if ! (cd "$SAM_DIR" && sam deploy \
+        --stack-name "$STACK_NAME" \
+        --region "$AWS_REGION" \
+        --resolve-s3 \
+        --capabilities CAPABILITY_IAM \
+        --no-confirm-changeset \
+        --no-fail-on-empty-changeset \
+        --parameter-overrides \
+          ChromeSource=sparticuz \
+          "ReservedConcurrency=$RESERVED_CONCURRENCY"); then
+  echo "ERROR: sam deploy failed; tearing down rollback'd stack..." >&2
+  cleanup_and_exit 3
+fi
+
+# ── 3. Read stack outputs ─────────────────────────────────────────────────
+BUCKET=$(aws cloudformation describe-stacks \
+  --stack-name "$STACK_NAME" \
+  --query "Stacks[0].Outputs[?OutputKey=='RenderBucketName'].OutputValue" \
+  --output text)
+STATE_MACHINE_ARN=$(aws cloudformation describe-stacks \
+  --stack-name "$STACK_NAME" \
+  --query "Stacks[0].Outputs[?OutputKey=='RenderStateMachineArn'].OutputValue" \
+  --output text)
+echo "→ Stack outputs: bucket=$BUCKET state_machine=$STATE_MACHINE_ARN"
+
+# ── 4. Upload fixture as a project tarball ────────────────────────────────
+# tar.gz (not zip): Lambda's Node 22 base image ships GNU `tar` but not
+# `unzip` in /usr/bin. See packages/aws-lambda/src/handler.ts for the
+# matching untar call on the Lambda side.
+echo "→ Uploading fixture to s3://$BUCKET/projects/$FIXTURE.tar.gz"
+TMP_ARCHIVE=$(mktemp -d)
+tar -czf "$TMP_ARCHIVE/project.tar.gz" -C "$FIXTURE_DIR/src" .
+aws s3 cp "$TMP_ARCHIVE/project.tar.gz" "s3://$BUCKET/projects/$FIXTURE.tar.gz"
+rm -rf "$TMP_ARCHIVE"
+
+# ── 5. Render at each chunk count ─────────────────────────────────────────
+FIXTURE_META="$FIXTURE_DIR/meta.json"
+BASE_FPS=$(jq -r '.renderConfig.fps // 30' "$FIXTURE_META")
+BASE_W=$(jq -r '.renderConfig.width // 640' "$FIXTURE_META")
+BASE_H=$(jq -r '.renderConfig.height // 360' "$FIXTURE_META")
+
+RESULTS_JSON="$ARTIFACT_DIR/results.json"
+echo "[]" > "$RESULTS_JSON"
+
+IFS=',' read -ra COUNTS <<< "$CHUNK_COUNTS"
+for N in "${COUNTS[@]}"; do
+  EXEC_NAME="smoke-N$N-$(date +%s)"
+  OUTPUT_KEY="renders/$EXEC_NAME/output.mp4"
+  INPUT_JSON=$(jq -n \
+    --arg project "s3://$BUCKET/projects/$FIXTURE.tar.gz" \
+    --arg prefix "s3://$BUCKET/renders/$EXEC_NAME/" \
+    --arg output "s3://$BUCKET/$OUTPUT_KEY" \
+    --argjson n "$N" \
+    --argjson fps "$BASE_FPS" \
+    --argjson w "$BASE_W" \
+    --argjson h "$BASE_H" \
+    '{
+      ProjectS3Uri: $project,
+      PlanOutputS3Prefix: $prefix,
+      OutputS3Uri: $output,
+      Config: {
+        fps: $fps,
+        width: $w,
+        height: $h,
+        format: "mp4",
+        maxParallelChunks: $n,
+        runtimeCap: "lambda"
+      }
+    }')
+
+  echo
+  echo "================== N=$N =================="
+  echo "$INPUT_JSON" | jq .
+
+  START_MS=$(date +%s%3N)
+  EXEC_ARN=$(aws stepfunctions start-execution \
+    --state-machine-arn "$STATE_MACHINE_ARN" \
+    --name "$EXEC_NAME" \
+    --input "$INPUT_JSON" \
+    --query executionArn --output text)
+  echo "Started: $EXEC_ARN"
+
+  STATUS="RUNNING"
+  for _ in $(seq 1 300); do
+    sleep 5
+    STATUS=$(aws stepfunctions describe-execution \
+      --execution-arn "$EXEC_ARN" --query status --output text)
+    if [ "$STATUS" != "RUNNING" ]; then break; fi
+  done
+  END_MS=$(date +%s%3N)
+  WALL_MS=$((END_MS - START_MS))
+
+  if [ "$STATUS" != "SUCCEEDED" ]; then
+    echo "ERROR: N=$N execution did not succeed ($STATUS)." >&2
+    aws stepfunctions describe-execution \
+      --execution-arn "$EXEC_ARN" \
+      > "$ARTIFACT_DIR/renders/N$N-execution.json"
+    aws stepfunctions get-execution-history \
+      --execution-arn "$EXEC_ARN" --max-results 200 \
+      > "$ARTIFACT_DIR/renders/N$N-history.json" || true
+    cleanup_and_exit 4
+  fi
+
+  aws stepfunctions get-execution-history \
+    --execution-arn "$EXEC_ARN" --max-results 1000 --output json \
+    > "$ARTIFACT_DIR/renders/N$N-history.json"
+
+  OUTPUT_LOCAL="$ARTIFACT_DIR/renders/N$N-output.mp4"
+  aws s3 cp "s3://$BUCKET/$OUTPUT_KEY" "$OUTPUT_LOCAL"
+
+  PSNR_LOG=$(mktemp)
+  # ffmpeg's psnr filter prints per-frame stats `psnr_avg:X.XX` to its
+  # stats_file. We average those across frames to get the rendering's
+  # overall PSNR vs the baseline. The filter also prints a final summary
+  # line `PSNR ... average:X.XX ...` to stderr; we'd rather compute from
+  # per-frame data because the summary line is missing on some ffmpeg
+  # builds when the stream is too short.
+  ffmpeg -nostdin -v error \
+    -i "$OUTPUT_LOCAL" -i "$BASELINE_MP4" \
+    -lavfi "psnr=stats_file=$PSNR_LOG" -f null - 2>/dev/null || true
+  PSNR_AVG=$(awk '
+    /psnr_avg:/ {
+      for (i = 1; i <= NF; i++) {
+        if ($i ~ /^psnr_avg:/) {
+          split($i, kv, ":")
+          sum += kv[2]; count++
+        }
+      }
+    }
+    END { if (count > 0) printf("%.2f", sum / count); else print "0" }
+  ' "$PSNR_LOG")
+  rm -f "$PSNR_LOG"
+
+  echo "N=$N  wall=${WALL_MS}ms  psnr=${PSNR_AVG} dB"
+  jq --argjson n "$N" \
+     --argjson wall "$WALL_MS" \
+     --arg psnr "$PSNR_AVG" \
+     '. += [{chunkCount: $n, wallClockMs: $wall, psnrAvgDb: ($psnr|tonumber), output: "renders/N\($n)-output.mp4", history: "renders/N\($n)-history.json"}]' \
+     "$RESULTS_JSON" > "$RESULTS_JSON.tmp" && mv "$RESULTS_JSON.tmp" "$RESULTS_JSON"
+done
+
+# ── 6. Gate on PSNR threshold ─────────────────────────────────────────────
+FAILED=0
+while read -r row; do
+  N=$(echo "$row" | jq -r .chunkCount)
+  P=$(echo "$row" | jq -r .psnrAvgDb)
+  if awk -v p="$P" -v t="$PSNR_THRESHOLD" 'BEGIN{exit !(p<t)}'; then
+    echo "FAIL: N=$N PSNR=$P dB below threshold $PSNR_THRESHOLD" >&2
+    FAILED=$((FAILED + 1))
+  fi
+done < <(jq -c '.[]' "$RESULTS_JSON")
+
+# ── 7. Summary ────────────────────────────────────────────────────────────
+echo
+echo "================ RESULTS ================"
+printf '%-10s %-12s %-10s\n' "ChunkCount" "WallMs" "PSNR (dB)"
+jq -r '.[] | [.chunkCount, .wallClockMs, .psnrAvgDb] | @tsv' "$RESULTS_JSON" \
+  | awk -F'\t' '{printf "%-10s %-12s %-10s\n", $1, $2, $3}'
+echo
+echo "Artifacts: $ARTIFACT_DIR"
+
+if [ "$FAILED" -gt 0 ]; then
+  echo "FAILED ($FAILED renders below PSNR threshold)" >&2
+  cleanup_and_exit 5
+fi
+
+echo "PASS"
+cleanup_and_exit 0

examples/aws-lambda/template.yaml

@@ -0,0 +1,503 @@
+AWSTemplateFormatVersion: "2010-09-09"
+Transform: AWS::Serverless-2016-10-31
+Description: >-
+  HyperFrames distributed rendering — Step Functions standard workflow with
+  one Lambda function handling Plan, RenderChunk (fan-out via Map state),
+  and Assemble. One S3 bucket, alarms for runaway concurrency, Lambda
+  errors, and Step Functions execution failures.
+
+  Built from the handler ZIP at packages/aws-lambda/dist/handler.zip.
+
+  See:
+    - packages/aws-lambda/README.md (handler architecture)
+    - examples/aws-lambda/README.md (this directory's deploy guide)
+
+Parameters:
+  ProjectName:
+    Type: String
+    Default: hyperframes
+    Description: Name prefix applied to all created resources.
+
+  LambdaMemoryMb:
+    Type: Number
+    Default: 10240
+    AllowedValues: [2048, 3072, 4096, 5120, 6144, 7168, 8192, 9216, 10240]
+    Description: >-
+      Lambda memory in MB. Render workloads are CPU-bound; bumping memory
+      proportionally bumps the CPU share Lambda gives the function. 10 GB
+      (the max) is recommended for 1080p renders.
+
+  LambdaTimeoutSec:
+    Type: Number
+    Default: 900
+    MinValue: 60
+    MaxValue: 900
+    Description: >-
+      Per-invocation Lambda timeout. Render chunks at the default
+      chunkSize=240 frames complete in seconds; 15 minutes is the Lambda
+      hard ceiling and the default here to absorb cold-start variance.
+
+  ReservedConcurrency:
+    Type: Number
+    Default: -1
+    Description: >-
+      Lambda reserved concurrency cap. Set to a positive integer to bound
+      simultaneous chunk renders (e.g. 50 to limit cost). -1 means
+      unreserved (account default).
+
+  ChromeSource:
+    Type: String
+    Default: sparticuz
+    AllowedValues: [sparticuz, chrome-headless-shell]
+    Description: >-
+      Which Chrome runtime the bundled ZIP was built with. Must match the
+      `--source=` flag passed to `build-zip.ts`. The handler reads this
+      via the HYPERFRAMES_LAMBDA_CHROME_SOURCE env var at boot.
+
+  ChunkInvocationAlarmThreshold:
+    Type: Number
+    Default: 1000
+    Description: >-
+      CloudWatch alarm threshold for total RenderChunk invocations per
+      hour. The runaway-Map state pathology would fan out far more
+      chunks than expected; an alarm at 10× the typical workload
+      protects against billing surprises.
+
+Conditions:
+  HasReservedConcurrency: !Not [!Equals [!Ref ReservedConcurrency, -1]]
+
+Globals:
+  Function:
+    Runtime: nodejs22.x
+    MemorySize: !Ref LambdaMemoryMb
+    Timeout: !Ref LambdaTimeoutSec
+    # x86_64 is required for @sparticuz/chromium — its prebuilt
+    # Chromium ships x86_64-only. Adopters who switch to a custom
+    # ARM-built chrome-headless-shell can change this to `arm64`, but
+    # the default ZIP build will fail to launch on Graviton.
+    Architectures: [x86_64]
+    # Lambda function-level X-Ray tracing. The state machine already
+    # has Tracing.Enabled: true; without this, X-Ray traces would
+    # terminate at the Step Functions → Lambda boundary instead of
+    # following into per-function spans.
+    Tracing: Active
+    # Cost-allocation tags. Setting these at the Globals level applies
+    # to every AWS::Serverless::Function in the template — there's
+    # only one today, but the contract is portable to multi-function
+    # variants. Bucket + state-machine carry the same tags resource-
+    # locally because Globals only covers functions.
+    Tags:
+      Project: !Ref ProjectName
+      HyperFramesComponent: lambda-renderer
+    Environment:
+      Variables:
+        NODE_OPTIONS: "--enable-source-maps"
+        HYPERFRAMES_LAMBDA_CHROME_SOURCE: !Ref ChromeSource
+
+Resources:
+  # ── S3 bucket for plan tarballs, chunk outputs, and final renders ───────
+  RenderBucket:
+    Type: AWS::S3::Bucket
+    DeletionPolicy: Retain
+    UpdateReplacePolicy: Retain
+    Properties:
+      # BucketName omitted — CloudFormation generates a unique name like
+      # "<stack-name>-renderbucket-<random>". S3 bucket names are capped at
+      # 63 chars; a static !Sub expression including ProjectName +
+      # AWS::AccountId + AWS::Region trips that limit when ProjectName
+      # carries a timestamp (e.g. the smoke script's per-run stack name).
+      PublicAccessBlockConfiguration:
+        BlockPublicAcls: true
+        BlockPublicPolicy: true
+        IgnorePublicAcls: true
+        RestrictPublicBuckets: true
+      VersioningConfiguration:
+        # `Suspended` keeps storage costs flat — versions are not
+        # retained on overwrites. Tradeoff: if an adopter writes their
+        # final rendered mp4 to this bucket and a re-render overwrites
+        # the same key, the prior version is gone. Adopters who treat
+        # the final mp4 as user-keepable should set this to `Enabled`
+        # (intermediates under `renders/` still expire via the
+        # lifecycle rule below regardless).
+        Status: Suspended
+      LifecycleConfiguration:
+        Rules:
+          - Id: ExpireIntermediates
+            Status: Enabled
+            Prefix: renders/
+            # Plan tarballs and chunk outputs are intermediate artifacts.
+            # Users keep the final mp4 (different key prefix); the rest
+            # can age out after a week to keep storage costs flat.
+            ExpirationInDays: 7
+      Tags:
+        - Key: Project
+          Value: !Ref ProjectName
+        - Key: HyperFramesComponent
+          Value: lambda-renderer
+
+  # ── Single Lambda function handling all three roles ──────────────────────
+  RenderFunction:
+    Type: AWS::Serverless::Function
+    Properties:
+      FunctionName: !Sub "${ProjectName}-render"
+      Description: >-
+        HyperFrames distributed render handler. Dispatches on event.Action.
+      Handler: handler.handler
+      # Local path is resolved by `sam build` + `sam deploy --resolve-s3`
+      # (or `--s3-bucket`); the resulting CodeUri rewrites to s3://.
+      CodeUri: ../../packages/aws-lambda/dist/handler.zip
+      PackageType: Zip
+      ReservedConcurrentExecutions: !If
+        - HasReservedConcurrency
+        - !Ref ReservedConcurrency
+        - !Ref AWS::NoValue
+      EphemeralStorage:
+        Size: 10240
+      Environment:
+        Variables:
+          # Lambda's Node 22 runtime sets these by default; explicit for
+          # clarity + so users can override during local SAM invoke.
+          TMPDIR: /tmp
+      Policies:
+        - S3CrudPolicy:
+            BucketName: !Ref RenderBucket
+      # CloudWatch Logs perms are covered by SAM's default
+      # AWSLambdaBasicExecutionRole — explicit `CloudWatchLogsFullAccess`
+      # would be overscope (`logs:*` on `*`, including DeleteLogGroup +
+      # CreateExportTask). Reference templates shouldn't leak overbroad
+      # IAM into adopters' accounts.
+
+  # ── CloudWatch log group for the state machine ──────────────────────────
+  # SAM doesn't auto-create one when `LoggingConfiguration` is set, so we
+  # define it explicitly — that way the IAM grant on the state-machine
+  # role has a destination to write to.
+  RenderStateMachineLogGroup:
+    Type: AWS::Logs::LogGroup
+    Properties:
+      LogGroupName: !Sub "/aws/states/${ProjectName}-render"
+      RetentionInDays: 30
+
+  # ── Step Functions state machine: Plan → Map(N) RenderChunk → Assemble ──
+  RenderStateMachine:
+    Type: AWS::Serverless::StateMachine
+    Properties:
+      Name: !Sub "${ProjectName}-render"
+      Type: STANDARD
+      Tracing:
+        Enabled: true
+      Logging:
+        # Without this, the `WriteCloudwatchLogs` grant on the state
+        # machine role would be unused — operators would see zero
+        # execution history outside the Step Functions console.
+        # `Level: ERROR` keeps log volume low; bump to `ALL` for
+        # heavy debugging.
+        Level: ERROR
+        IncludeExecutionData: false
+        Destinations:
+          - CloudWatchLogsLogGroup:
+              LogGroupArn: !GetAtt RenderStateMachineLogGroup.Arn
+      Definition:
+        Comment: >-
+          HyperFrames distributed render orchestration: Plan → Map(N)
+          RenderChunk → Assemble.
+        # Defensive 1-hour ceiling on the whole choreography. The
+        # individual states already have retries + per-task timeouts;
+        # this catches pathological runaways (Plan-retry storm,
+        # stuck-state-machine bugs) at the top before per-task budgets
+        # compound into a multi-hour execution. The longest legitimate
+        # render observed in PR 880's eval was ~3 minutes.
+        TimeoutSeconds: 3600
+        StartAt: Plan
+        States:
+          Plan:
+            Type: Task
+            Resource: arn:aws:states:::lambda:invoke
+            Parameters:
+              FunctionName: !GetAtt RenderFunction.Arn
+              Payload:
+                Action: plan
+                ProjectS3Uri.$: "$.ProjectS3Uri"
+                PlanOutputS3Prefix.$: "$.PlanOutputS3Prefix"
+                Config.$: "$.Config"
+            ResultSelector:
+              PlanS3Uri.$: "$.Payload.PlanS3Uri"
+              PlanHash.$: "$.Payload.PlanHash"
+              ChunkCount.$: "$.Payload.ChunkCount"
+              Format.$: "$.Payload.Format"
+              HasAudio.$: "$.Payload.HasAudio"
+              AudioS3Uri.$: "$.Payload.AudioS3Uri"
+            ResultPath: $.Plan
+            Retry:
+              - ErrorEquals:
+                  # These error names are thrown by the producer's plan
+                  # stage when retrying can never help — version skew,
+                  # determinism violations, GPU misconfiguration, font
+                  # fetch failures, plan-size cap, unsupported format.
+                  # Fail fast rather than burning ~120s of retry budget.
+                  - FFMPEG_VERSION_MISMATCH
+                  - PLAN_HASH_MISMATCH
+                  - BROWSER_GPU_NOT_SOFTWARE
+                  - FONT_FETCH_FAILED
+                  - PLAN_TOO_LARGE
+                  - FORMAT_NOT_SUPPORTED_IN_DISTRIBUTED
+                MaxAttempts: 0
+              - ErrorEquals: [States.ALL]
+                IntervalSeconds: 2
+                MaxAttempts: 4
+                BackoffRate: 2
+                MaxDelaySeconds: 60
+            Next: BuildChunkList
+
+          BuildChunkList:
+            # Translate ChunkCount into an array `[0, 1, ..., N-1]` so the
+            # Map state below has something to iterate. Range is the
+            # idiomatic Step Functions intrinsic for this; no Lambda call
+            # required.
+            Type: Pass
+            Parameters:
+              ChunkIndexes.$: "States.ArrayRange(0, States.MathAdd($.Plan.ChunkCount, -1), 1)"
+            ResultPath: $.Iterator
+            Next: AssertChunkCount
+
+          AssertChunkCount:
+            # Defensive gate: `resolveChunkPlan` guarantees ChunkCount ≥ 1,
+            # but if some future regression let a zero-chunk plan through,
+            # `RenderChunks` (Map state) would iterate zero times and
+            # `Assemble` would receive an empty `ChunkS3Uris` array — silently
+            # producing an empty output. Fail fast instead.
+            Type: Choice
+            Choices:
+              - Variable: $.Plan.ChunkCount
+                NumericGreaterThan: 0
+                Next: RenderChunks
+            Default: PlanProducedZeroChunks
+
+          PlanProducedZeroChunks:
+            Type: Fail
+            Error: PLAN_TOO_LARGE
+            Cause: Plan returned ChunkCount=0 — non-retryable producer-side invariant violation.
+
+          RenderChunks:
+            Type: Map
+            ItemsPath: $.Iterator.ChunkIndexes
+            ItemSelector:
+              ChunkIndex.$: "$$.Map.Item.Value"
+              PlanS3Uri.$: "$.Plan.PlanS3Uri"
+              PlanHash.$: "$.Plan.PlanHash"
+              ChunkOutputS3Prefix.$: "$.PlanOutputS3Prefix"
+              Format.$: "$.Plan.Format"
+            # Map fan-out cap derives from the Plan's chunkCount so
+            # caller-supplied `Config.maxParallelChunks` (which
+            # `plan()` honours when sizing the chunk list) is the
+            # single source of truth. A hardcoded value here would
+            # silently throttle adopters who scale up the chunk count
+            # in their event payload.
+            MaxConcurrencyPath: $.Plan.ChunkCount
+            ResultPath: $.Chunks
+            ItemProcessor:
+              ProcessorConfig:
+                Mode: INLINE
+              StartAt: RenderChunk
+              States:
+                RenderChunk:
+                  Type: Task
+                  Resource: arn:aws:states:::lambda:invoke
+                  Parameters:
+                    FunctionName: !GetAtt RenderFunction.Arn
+                    Payload:
+                      Action: renderChunk
+                      ChunkIndex.$: "$.ChunkIndex"
+                      PlanS3Uri.$: "$.PlanS3Uri"
+                      PlanHash.$: "$.PlanHash"
+                      ChunkOutputS3Prefix.$: "$.ChunkOutputS3Prefix"
+                      Format.$: "$.Format"
+                  ResultSelector:
+                    ChunkS3Uri.$: "$.Payload.ChunkS3Uri"
+                    ChunkIndex.$: "$.Payload.ChunkIndex"
+                    Sha256.$: "$.Payload.Sha256"
+                  Retry:
+                    - ErrorEquals:
+                        - FFMPEG_VERSION_MISMATCH
+                        - PLAN_HASH_MISMATCH
+                        - BROWSER_GPU_NOT_SOFTWARE
+                      MaxAttempts: 0
+                    - ErrorEquals: [States.ALL]
+                      IntervalSeconds: 2
+                      MaxAttempts: 4
+                      BackoffRate: 2
+                      MaxDelaySeconds: 60
+                  End: true
+            Next: Assemble
+
+          Assemble:
+            Type: Task
+            Resource: arn:aws:states:::lambda:invoke
+            Parameters:
+              FunctionName: !GetAtt RenderFunction.Arn
+              Payload:
+                Action: assemble
+                PlanS3Uri.$: "$.Plan.PlanS3Uri"
+                ChunkS3Uris.$: "$.Chunks[*].ChunkS3Uri"
+                AudioS3Uri.$: "$.Plan.AudioS3Uri"
+                OutputS3Uri.$: "$.OutputS3Uri"
+                Format.$: "$.Plan.Format"
+            ResultSelector:
+              OutputS3Uri.$: "$.Payload.OutputS3Uri"
+              FramesEncoded.$: "$.Payload.FramesEncoded"
+              FileSize.$: "$.Payload.FileSize"
+            ResultPath: $.Output
+            Retry:
+              - ErrorEquals:
+                  # Same non-retryable error names as the Plan state's
+                  # gate — these surface at assemble time too because
+                  # ffmpeg-driven concat picks up version drift and we
+                  # re-verify plan hash + format at assemble. Skip the
+                  # retry storm; fail fast.
+                  - FFMPEG_VERSION_MISMATCH
+                  - PLAN_HASH_MISMATCH
+                  - FORMAT_NOT_SUPPORTED_IN_DISTRIBUTED
+                MaxAttempts: 0
+              - ErrorEquals: [States.ALL]
+                IntervalSeconds: 2
+                MaxAttempts: 4
+                BackoffRate: 2
+                MaxDelaySeconds: 60
+            End: true
+      Role: !GetAtt RenderStateMachineRole.Arn
+
+  RenderStateMachineRole:
+    Type: AWS::IAM::Role
+    Properties:
+      AssumeRolePolicyDocument:
+        Version: "2012-10-17"
+        Statement:
+          - Effect: Allow
+            Principal:
+              Service: states.amazonaws.com
+            Action: sts:AssumeRole
+      Policies:
+        - PolicyName: InvokeRenderFunction
+          PolicyDocument:
+            Version: "2012-10-17"
+            Statement:
+              - Effect: Allow
+                Action: lambda:InvokeFunction
+                Resource: !GetAtt RenderFunction.Arn
+        - PolicyName: WriteCloudwatchLogs
+          PolicyDocument:
+            Version: "2012-10-17"
+            Statement:
+              - Effect: Allow
+                Action:
+                  - logs:CreateLogDelivery
+                  - logs:GetLogDelivery
+                  - logs:UpdateLogDelivery
+                  - logs:DeleteLogDelivery
+                  - logs:ListLogDeliveries
+                  - logs:PutResourcePolicy
+                  - logs:DescribeResourcePolicies
+                  - logs:DescribeLogGroups
+                Resource: "*"
+        - PolicyName: XRayTracing
+          PolicyDocument:
+            Version: "2012-10-17"
+            Statement:
+              - Effect: Allow
+                Action:
+                  - xray:PutTraceSegments
+                  - xray:PutTelemetryRecords
+                Resource: "*"
+
+  # ── CloudWatch alarm: runaway chunk invocations ─────────────────────────
+  RenderChunkInvocationAlarm:
+    Type: AWS::CloudWatch::Alarm
+    Properties:
+      AlarmName: !Sub "${ProjectName}-runaway-chunk-invocations"
+      AlarmDescription: >-
+        Fires if RenderChunk Lambda invocations exceed the configured
+        threshold in a 1-hour window. The Map state's MaxConcurrency cap
+        protects against simultaneous fan-out, but a runaway state
+        machine that triggers many sequential renders would still rack
+        up cost; this alarm catches that pattern.
+      Namespace: AWS/Lambda
+      MetricName: Invocations
+      Dimensions:
+        - Name: FunctionName
+          Value: !Ref RenderFunction
+      Statistic: Sum
+      Period: 3600
+      EvaluationPeriods: 1
+      Threshold: !Ref ChunkInvocationAlarmThreshold
+      ComparisonOperator: GreaterThanThreshold
+      TreatMissingData: notBreaching
+
+  # ── CloudWatch alarm: Lambda function errors ────────────────────────────
+  # Fires on any non-zero error rate. The invocation alarm above catches
+  # *too many calls*; this catches *calls that failed*. Without it,
+  # silent per-chunk failures (a non-retryable error inside the
+  # producer) would only surface by reading Step Functions execution
+  # history.
+  RenderFunctionErrorsAlarm:
+    Type: AWS::CloudWatch::Alarm
+    Properties:
+      AlarmName: !Sub "${ProjectName}-render-function-errors"
+      AlarmDescription: >-
+        Fires if the render Lambda reports any errors in a 5-minute
+        window. Set EvaluationPeriods=1 so a single failure pages.
+      Namespace: AWS/Lambda
+      MetricName: Errors
+      Dimensions:
+        - Name: FunctionName
+          Value: !Ref RenderFunction
+      Statistic: Sum
+      Period: 300
+      EvaluationPeriods: 1
+      Threshold: 1
+      ComparisonOperator: GreaterThanOrEqualToThreshold
+      TreatMissingData: notBreaching
+
+  # ── CloudWatch alarm: Step Functions execution failures ─────────────────
+  # Fires when a state-machine execution reaches a terminal failure
+  # state (typed non-retryable, retry-exhausted, or top-level timeout).
+  # Complementary to the Lambda Errors alarm: SFN failures include
+  # Choice-state Fail branches (PlanProducedZeroChunks) that bypass
+  # Lambda entirely, plus retry-exhaustion of transient errors that
+  # individual Lambda invocations counted as successful "retries".
+  RenderStateMachineFailedAlarm:
+    Type: AWS::CloudWatch::Alarm
+    Properties:
+      AlarmName: !Sub "${ProjectName}-render-state-machine-failed"
+      AlarmDescription: >-
+        Fires when the render state machine reports a failed
+        execution. Catches retry-exhaustion + typed non-retryable +
+        TimeoutSeconds cases that the Lambda Errors metric misses.
+      Namespace: AWS/States
+      MetricName: ExecutionsFailed
+      Dimensions:
+        - Name: StateMachineArn
+          Value: !Ref RenderStateMachine
+      Statistic: Sum
+      Period: 300
+      EvaluationPeriods: 1
+      Threshold: 1
+      ComparisonOperator: GreaterThanOrEqualToThreshold
+      TreatMissingData: notBreaching
+
+Outputs:
+  RenderBucketName:
+    Description: S3 bucket for plan tarballs, chunk outputs, and final renders.
+    Value: !Ref RenderBucket
+    Export:
+      Name: !Sub "${AWS::StackName}-RenderBucket"
+
+  RenderFunctionArn:
+    Description: ARN of the Lambda function. Pass to `aws lambda invoke` for local testing.
+    Value: !GetAtt RenderFunction.Arn
+    Export:
+      Name: !Sub "${AWS::StackName}-RenderFunctionArn"
+
+  RenderStateMachineArn:
+    Description: ARN of the Step Functions state machine. Pass to `aws stepfunctions start-execution`.
+    Value: !Ref RenderStateMachine
+    Export:
+      Name: !Sub "${AWS::StackName}-RenderStateMachineArn"