every.channel/evolution/proposals/ECP-0037-cross-os-determinism.md

ECP-0037: Cross-OS Determinism Testing (macOS + Linux)

Status: Draft Author: Codex Reviewers: founder@every.channel Created: 2026-02-07

Decision

Add an explicit cross-OS determinism test workflow for the CMAF ladder pipeline.

We will treat the determinism target as:

• identical output bytes for init.mp4 and segment_*.m4s for the same synthetic input,
• given the same ffmpeg/x264 build and the same every.channel version,
• across macOS and Linux.

Motivation

• Our core thesis depends on multiple independent nodes producing byte-identical artifacts.
• Without automated cross-OS checks, determinism will silently regress.

Scope

In scope:

• Keep an ignored Rust test that produces a deterministic synthetic TS and verifies:
  • bit-identical outputs across two runs on one host,
  • keyframe alignment at segment boundaries.
• Add a script that exports a canonical test input and compares outputs from two machines.

Out of scope:

• Perfect determinism across different ffmpeg/x264 versions.
• Hardware encoder determinism.

Implementation

• Local test: crates/ec-node/tests/determinism_cmaf_ladder.rs
• Cross-OS procedure:
  1. On macOS and Linux, run the same nix flake dev environment (pins ffmpeg).
  2. Run cargo test -p ec-node --test determinism_cmaf_ladder -- --ignored --nocapture.
  3. Emit a JSON summary of sha256s per variant (init + segments) into tmp/determinism/<os>.json.
  4. Compare the JSON across OS.

Notes

• Even with pinned ffmpeg, Apple vs Linux libc may still perturb behavior.
• If cross-OS byte equality fails but in-host determinism holds, we can treat it as:
  • still useful for availability (single-encoder determinism),
  • but not sufficient for multi-source "same bytes" dedupe.