test(producer): add cross-worker idempotency unit test

[jrusso1020]

Description

Phase 4 of the distributed rendering plan: test fixtures (see DISTRIBUTED-RENDERING-PLAN.md §11 Phase 4 + §10 test strategy). This is PR 4.6 of the Phase 4 remainder; PR 4.1 (#827) landed the harness mode and the Phase 3 follow-up fixes the harness surfaced.

This PR adds a cross-worker idempotency unit test at packages/producer/src/services/distributed/crossWorkerIdempotency.test.ts. The test plans a 5-frame composition once per format, renders chunk 0 twice into two distinct temp paths, and asserts the resulting bytes are identical — both via the engineered `ChunkResult.sha256` fingerprint and via explicit `Buffer.equals` comparison of every output file. Covers both SDR mp4 (BeginFrame + libx264 encode) and png-sequence (screenshot capture, no encoder) per §10.1 axis 2. Runs via `bun test`, no Docker required — soft-skips when the host's chrome-headless-shell stack can't render (the Docker harness covers the determinism contract against a known-good image).

The existing `renderChunk.test.ts` already pins the byte-identical-retry contract for png-sequence by comparing the sha256 fingerprint; this file complements it with (1) explicit byte-level verification (independent of the sha256 helper) and (2) the mp4 path that `renderChunk.test.ts` skips to dodge BeginFrame on dev hosts.

Testing

• `bun test packages/producer/src/services/distributed/crossWorkerIdempotency.test.ts` — both subtests pass on host (6.4s, 13 expect() calls)
• `bun test packages/producer/src/services/distributed/` — all 41 distributed unit tests pass (7.9s)
• `bunx oxlint` + `bunx oxfmt --check` clean
• `bunx tsc --noEmit` (producer package) clean

🤖 Generated with Claude Code

[jrusso1020]

• test(producer): add cross-worker idempotency unit test #844 👈 (View in Graphite)
• main

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

[miguel-heygen]

Cross-worker idempotency test — explicit byte-level verification + mp4 path coverage. Clean addition to the distributed test suite. LGTM.

[miguel-heygen]

Full Review: Cross-worker idempotency test

Well-written test. Exercises both rendering paths (png-sequence via screenshot capture, mp4 via BeginFrame + libx264) and verifies idempotency at two layers: ChunkResult.sha256 fingerprint and raw Buffer.equals on every output file. Frame-dir assertion also catches missing/extra frames.

Flaky risk: Low. Chrome dependency is soft-skipped via HOST_CHROME_FAILURE_PATTERNS, ffmpeg dependency likewise. 120s timeout is generous for cold Chrome starts. Temp dirs cleaned in afterAll.

Minor note: Soft-skip uses console.warn + return rather than a test framework skip API, so CI reports "pass" instead of "skip" when Chrome is unavailable. Consistent with renderChunk.test.ts pattern — acceptable, but test.skip() at runtime would improve visibility if bun:test adds it.

No changes requested. LGTM.

[vanceingalls]

Post-merge advisory review (already merged into main at 808b10cb). Findings flagged for follow-up, not gating. Prior coverage: @miguel-heygen's first review approved the diff and his second flagged the console.warn-vs-test.skip() visibility nit — additive review below.

Strengths

• crossWorkerIdempotency.test.ts:114-118 — explicit Buffer.equals after the sha256 equality assertion is the right shape. Comment honestly names the rationale ("if the sha256 helper ever regresses... this assertion still fails the test honestly"); that's the value-add over renderChunk.test.ts's sha-only path.
• crossWorkerIdempotency.test.ts:101-108 — assertBytesEqual in "frame-dir" mode compares readdirSync().sort() listings first, so missing/extra frames trip the assertion before the per-file bytes check. Cheap, complete.
• mp4-path coverage closes a real gap — renderChunk.test.ts only exercises png-sequence (it forces format: "png-sequence" to dodge BeginFrame), so without this file the BeginFrame + libx264 path had no byte-identity unit pin at all.

Findings

should-be-follow-up-ticket — producer unit tests don't run in CI. ci.yml:134 runs bun run --filter '!@hyperframes/producer' test, explicitly excluding @hyperframes/producer. windows-render.yml:398-400 does the same with a comment ("producer package is skipped because its tests require Docker"). Dockerfile.test's ENTRYPOINT is tsx src/regression-harness.ts, not bun test. Net: this file — and the 7 other .test.ts siblings in services/distributed/ (assemble, chunkBoundary, plan, planFormatBanlist, planSizeCap, publicExports, renderChunk) — are not invoked by any CI job on this repo. The PR's "Testing" section accurately reports the local bun test runs, but no CI gate enforces this on future PRs. This is pre-existing debt, not a regression introduced by #844, and the Docker harness exercises the determinism contract end-to-end against a known-good chrome+ffmpeg image — so the production property is still covered. But the unit assertions in this file (including the load-bearing Buffer.equals byte-identity check it's designed to add) will silently rot if a future PR breaks them. Worth a follow-up ticket: either (a) add a producer-unit-tests CI job that runs bun test packages/producer/src/services/distributed/ on hosts where Chrome can't render (the soft-skip already covers that case), or (b) wire these .test.ts files into the Docker harness.

important — chunk 0 only. crossWorkerIdempotency.test.ts:130, 178 — both subtests render renderChunk(planDir, 0, ...). The byte-identity contract is (planDir, chunkIndex) → bytes for every chunkIndex, and chunk 0 is the chunk most likely to be special-cased by the IDR + GOP-locking logic. A regression that broke determinism specifically for chunks N>0 (e.g. mishandled seek offset, wrong frame indexing into video-frames/) wouldn't trip either subtest. Cheap fix on a follow-up: parameterize over chunk index, run at least one non-zero chunk per format.

nit — soft-skip regex duplicated. crossWorkerIdempotency.test.ts:46-47 hoists HOST_CHROME_FAILURE_PATTERNS to a top-level const, but renderChunk.test.ts:184-186 keeps the same literal inline. They match exactly today; if one drifts, the soft-skip behavior diverges silently. Either lift both to a shared services/distributed/__test_utils__ module, or accept the duplication explicitly with a code comment pointing each file at the other.

nit — frame-dir mismatch reports differently from file mismatch. crossWorkerIdempotency.test.ts:97-108 — file mode uses expect().toBe(true), frame-dir mode throws a raw Error with custom byte-length detail. Both are useful info, but the inconsistency means failure ergonomics depend on which output kind the test is exercising. Pulling the frame-dir path through expect() (e.g. expect({ name, ok: a.equals(b) }).toEqual({ name, ok: true })) gets uniform bun-test failure framing.

nit — outDir asymmetry between subtests. :172 puts both mp4 outputs in a shared mp4-chunks/ dir; png-sequence uses two top-level dirs. Both are correct (mp4 outputs are files, png-sequence outputs are dirs); the symmetry break is cosmetic.

Verdict: COMMENT (post-merge: With fixes)
Reasoning: Test itself is well-shaped — explicit byte-level verification plus mp4-path coverage is a real gap-fill over renderChunk.test.ts. Two follow-ups worth tracking: (1) producer unit tests aren't wired into any CI job, so this file silently rots if it regresses; (2) chunk 0 only — extend to non-zero chunks on a follow-up.

Review by Vai