feat(producer): freezePlan snapshots PRODUCER_RUNTIME_* env vars

[jrusso1020]

What

Adds snapshotRuntimeEnv(env = process.env) and RUNTIME_ENV_SNAPSHOT_PREFIXES to packages/producer/src/services/render/stages/freezePlan.ts. The helper captures process.env keys matching PRODUCER_RUNTIME_ or PRODUCER_RENDER_ prefixes into a fresh Record<string, string>, ready to be embedded in LockedRenderConfig.runtimeEnv.

Why

Part of Phase 2, §4.3 (LockedRenderConfig.runtimeEnv) and §5.2 (RENDER_SEEK_MODE row).

fileServer.ts reads several PRODUCER_RUNTIME_* / PRODUCER_RENDER_* env vars at module-load time (RENDER_SEEK_MODE, RENDER_SEEK_STEP, RENDER_SEEK_OFFSET_FRACTION, …) and bakes them into the served HTML's RENDER_MODE_SCRIPT. Distributed chunk workers are separate processes that may inherit a different environment; without a snapshot, two chunks of the same plan could serve different HTML and produce divergent output. The plan freezes the controller's env so Phase 3's renderChunk() can materialize it back into the worker's process.env before launching its file server.

How

• Helper iterates Object.keys(env), retains entries whose key starts with one of the prefixes, skips entries whose value is undefined, and returns a NEW object each call (so subsequent env mutations don't retroactively change a frozen plan).
• Exported RUNTIME_ENV_SNAPSHOT_PREFIXES so the Phase 3 worker side can apply the same filter (asymmetric handling would leak stale controller env into worker behavior).
• The freezePlan() function body remains a skeleton — Phase 3 owns the full implementation. The snapshot helper is exported on its own so this gate is testable without that body.

Test plan

• Unit tests added: freezePlan.test.ts (9 cases) covers PRODUCER_RUNTIME_* capture, PRODUCER_RENDER_* capture, both-prefix mix, ignored unrelated keys, off-by-one prefix variants (PRODUCER_RUNTIM_, PRODUCER_RENDR_, PRODUCER_DEBUG_), undefined-value skip, fresh-object contract, default-to-process.env, and the exported prefix list assertion.
• No caller invokes snapshotRuntimeEnv yet — Phase 3's freezePlan body will.
• bun run --cwd packages/producer typecheck clean.
• bunx oxlint + bunx oxfmt --check clean.

This is part of a stack of 10 PRs; this is PR 5 of 10. Stacked on top of #769.

🤖 Generated with Claude Code

[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

• feat(producer): fail-closed font fetch flag in deterministicFonts #775
• feat(producer): plan-time validator — reject system fonts #774
• feat(producer): plan-time validator — reject GPU encode #773
• feat(producer): audio post-pad/trim helper for assemble #772
• feat(engine): first-frame warmup capture helper for distributed chunks #771
• feat(producer): freezePlan snapshots PRODUCER_RUNTIME_* env vars #770 👈 (View in Graphite)
• feat(producer): seedable Math.random / crypto.getRandomValues shim, gated #769
• refactor(engine): clamp warmupTicks to fixed iteration count, gated #768
• feat(engine): assertSwiftShader chrome://gpu validator #767
• feat(engine): add lockGopForChunkConcat option to buildEncoderArgs #766
• main

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

[miguel-heygen]

Clean, focused utility. The separation into runtimeEnvSnapshot.ts (standalone, no freeze-pipeline deps) with a re-export from freezePlan.ts is the right call — chunk workers need the snapshot helper at boot without importing the entire freeze pipeline.

Key correctness checks:

• Fresh object each call (Object.keys + new Record) — prevents live-reference mutation from leaking across plan snapshots.
• typeof value !== "string" guard handles the undefined slots in Record<string, string | undefined> cleanly.
• Exported RUNTIME_ENV_PREFIXES keeps capture and re-apply sides in sync — the test asserts the exact prefix list, which is a good regression anchor.
• Off-by-one prefix variants in tests (PRODUCER_RUNTIM_, PRODUCER_RENDR_, PRODUCER_DEBUG_) are exactly the edge cases that catch startsWith bugs.

The freezePlan() body staying a skeleton is fine — it's Phase 3 scope and the error message update (dropping the plan-doc reference) is a minor cleanup.

LGTM.

— Magi

[vanceingalls]

Strengths:

• Clean separation: runtimeEnvSnapshot.ts is a standalone utility with no dependency on the freeze pipeline (runtimeEnvSnapshot.ts:14-16) — chunk workers can re-apply the snapshot without dragging in the planner. Right call.
• RUNTIME_ENV_PREFIXES exported for the worker side (runtimeEnvSnapshot.ts:24) is the single source of truth that prevents capture/replay asymmetry — pinned by the "exports the prefix list for chunk-worker materialization" test (runtimeEnvSnapshot.test.ts:96).
• Fresh-object contract pinned via the mutate-after-snapshot test (runtimeEnvSnapshot.test.ts:77-85) — guards against accidental return env pass-through.
• Off-by-one prefix variants explicitly negative-tested (runtimeEnvSnapshot.test.ts:48-50 — PRODUCER_RUNTIM_, PRODUCER_RENDR_, PRODUCER_DEBUG_) — catches typo-prefix mistakes.

Findings:

important: PR description claims snapshotRuntimeEnv and RUNTIME_ENV_SNAPSHOT_PREFIXES live in freezePlan.ts, but the actual diff puts them in a new file runtimeEnvSnapshot.ts and names the const RUNTIME_ENV_PREFIXES (without _SNAPSHOT_). The re-export at freezePlan.ts:97 preserves backward-compat for any caller that already imports from freezePlan — but the description should match the diff so reviewers and future spelunkers find the right file. Not a code issue, just a description-vs-diff drift. (Rule 3 cross-check: no other reviewers caught this yet — surfacing as the first reviewer.)

important: runtimeEnvSnapshot.ts:42 filters typeof value !== "string" — but process.env only ever returns string | undefined in Node, never numbers/booleans. The defensive guard is fine, but the test at runtimeEnvSnapshot.test.ts:56 only covers undefined. If a worker materializes the snapshot back via Object.assign(process.env, snapshot), all process.env reads will return strings — no breakage. But: when freezing the plan, if a caller passes a non-string-only env object (e.g. a test fixture using Record<string, unknown>), the silent skip means the snapshot is incomplete and the failure surfaces only at chunk-worker time. Consider: either widen the input type to Record<string, unknown> and explicitly throw on non-string for matched-prefix keys, or narrow the input type to Record<string, string | undefined> (what's there now) and rely on the type system. Currently it's a soft-skip — easy to miss in CI.

nit: runtimeEnvSnapshot.ts:24 as const on the array is fine but readonly string[] is a wider type than readonly ["PRODUCER_RUNTIME_", "PRODUCER_RENDER_"]. If you want callers (e.g. chunk workers) to pattern-match exhaustively, the tuple form is more useful. Minor.

Verdict: APPROVE
Reasoning: Helper is correctly shaped (fresh-object, prefix-shared, no live process.env ref). Description drift is doc-only and the input-type concern is a follow-up.

— Vai