0005. Compatibility is proven by a differential suite

• Status: accepted
• Date: 2026-07-19

Context

This executor plugs into @cloudflare/codemode as a replacement for the executor that ships with it. “Compatible” has to mean something checkable, or every upstream release becomes a risk nobody can size. One answer is to pin this executor’s behaviour against upstream internals, copying their helpers and asserting on their private shapes. That freezes the project on one version and turns every upstream refactor into a break. Another states compatibility as an observable contract and measures it against the real runtime.

Parity against internals was rejected on both counts. It is fragile. And it fills the repository with code written in someone else’s style that nobody here can own.

Decision

Compatibility is a contract stated as a catalogue. Every contact point with the upstream package gets a case, and every case runs twice, once against this executor and once against a reference worker running the real upstream executor on workerd. Both results are diffed. That catalogue runs over a version matrix, the same reference worker bundled against several upstream lines including the newest release. The upstream package is never a pinned dependency: the supported range follows upstream releases, and the latest release is a first-class column in the matrix. One dedicated CI job runs the suite as a required check.

Where a duty falls to this executor that upstream also performs, it is written here as its own module in this repository’s style. Studying upstream is expected. But transplanting their code, or pinning tests to their internals, is not. The suite proves the behaviour end to end: a consumer depends on no other part.

Consequences

Upstream releases become a version bump plus a diff. Either the catalogue stays green or it names the exact case that moved. Every case carries an explicit reason when it cannot run, so a gap is never silent. A case the reference genuinely cannot express is marked unavailable to it. On the versions outside the boundary where upstream behaviour itself changed, a case is skipped. Cases held by a known defect are blocked, and the defect is named where the block is.

Divergences the suite finds are closed by delivering the full behaviour, not by documenting the difference. Binary payload encoding and input normalization both surfaced this way, and both became modules here. The supported range keeps an upper bound. Any unbounded range would assert compatibility the suite has not run.