refactor(producer): unify render requests

[jrusso1020]

What

Define one serializable RenderRequest and normalize environment input at the boundary.

Why

CLI, Docker, server, and distributed adapters copied option bags and silently dropped fields.

How

Add a shared request schema, explicit adapters, round-trip validation, and thread it through local/server/distributed entry points.

Test plan

• render request round-trip, server parsing, CLI Docker, and distributed validation tests
• Stack-wide lint, format, build, typecheck, and relevant integration gates

[jrusso1020]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• refactor(repo): resolve changed-code audit #2174
• test(engine): isolate peer abort regression #2173
• refactor(cli): decompose render phases #2172
• refactor(cli): centralize process lifecycle #2171
• fix(cloudrun): publish adapter contract #2170
• test(repo): execute packed subpaths #2169
• refactor(repo): centralize package subpaths #2168
• refactor(core): own edit protocol contract #2167
• test(compiler): enforce preview render parity #2166
• refactor(studio): gate SDK operation families #2165
• refactor(studio): gate Acorn writer migration #2164
• refactor(producer): make capture plans immutable #2163
• refactor(producer): unify render requests #2162 👈 (View in Graphite)
• refactor(engine): type capture failures #2161
• refactor(engine): manage child process lifecycles #2160
• refactor(engine): add fingerprinted browser leases #2159
• refactor(render): centralize execution ownership #2158
• refactor(core): unify composition contract #2157
• fix(studio): enforce optimistic file concurrency #2156
• fix(studio): make sdk cutover transactional #2155
• fix(render): publish artifacts atomically #2154
• fix(render): surface structured outcomes #2153
• fix(player): own connection and media resources #2152
• fix(core): preserve runtime transport contract #2151
• fix(player): version runtime protocol #2150
• test(repo): verify packed consumers #2149
• test(repo): enforce workspace contracts #2148
• fix(core): enforce strict runtime safety #2147
• test(producer): gate source tests by execution lane #2146
• fix(core): make timing masks safe for source loaders #2145
• chore(repo): forbid tracked generated artifacts #2144
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[jrusso1020]

🤖 Automated code-review pass — LGTM, no blocking issues found.

Reviewed the incremental diff (new renderRequest.ts + CLI local/Docker, server, and distributed plan.ts wiring). Traced every producer of the old option-bag shape into the unified RenderRequest; field mappings are complete and consistent.

Verification notes (things that looked risky but check out):

• CLI renderLocal maps all prior createRenderJob fields (fps/quality/format/gifLoop/workers/useGpu/hdrMode/crf/videoBitrate/videoFrameFormat/variables/entryFile/outputResolution/debug/strictness + producerConfig→engineConfig, logger via runtime). Nothing dropped.
• Docker forwards --protocol-timeout/--player-ready-timeout verbatim as ms (no /1000), which is correct: both CLI flags are documented in ms, unlike --browser-timeout which is seconds. render.ts:652-653.
• buildRenderJobConfig(input, absoluteOutputPath, log) — absoluteOutputPath is in scope at both call sites (server.ts:621, server.ts:697). Server RenderInput.fps is always a {num,den} rational (parseServerFps), so the new assertPositiveFps won't reject valid server requests; format is defaulted to "mp4".
• plan.ts:728/746: switching producerConfig: config.producerConfig → producerConfig: cfg actually strengthens the invariant — the synthetic plan job now always pins browserGpuMode:"software" + forceScreenshot:false instead of potentially leaking env-derived values when producerConfig was undefined.
• engineConfig added to DistributedRenderConfig is intentionally NOT omitted from SerializableDistributedRenderConfig (it's the JSON-safe replacement for the runtime-only producerConfig) and is now walked by validateDistributedRenderConfig for injection safety. Consistent.

Non-blocking nits (no need to gate on these):

• packages/producer/src/renderRequest.ts:70-71 — (fps.num as number) / (fps.den as number) casts. Repo CLAUDE.md says "avoid as T assertions; prefer type guards." Defensible here since Number.isInteger() already runtime-guards, but a typeof fps.num === "number" narrowing would satisfy the convention without the cast. [PLAUSIBLE]
• distributedConfigFromRequest, renderRequestFromDistributedConfig, and serialize/parseRenderRequest are exported and tested but have no production caller yet (only createRenderRequest/renderConfigFromRequest are wired into CLI + server). Expected for a stacked refactor — flagging only so a later PR in the stack actually threads them through the distributed entry point. [PLAUSIBLE]