Skip to content

CONCEPT Cited by 1 source

Spec-compliant optimization

Spec-compliant optimization is the design discipline of removing allocations, scheduling hops, or work from an implementation within the observability constraints the spec imposes — i.e., preserving every spec-observable behaviour while cutting the cost the spec doesn't mandate.

The operating principle

A specification describes what an implementation must expose; it constrains the observable behaviour. Anything a well-behaved consumer could not distinguish by-construction is a free optimisation target.

Example (from the 2026-04-21 Vercel post): Web Streams read() must return a Promise. The spec does not say whether the Promise must be pending or pre-resolved — both produce the same await result in the consumer's next microtask. Returning Promise.resolve(result) when data is buffered is observationally equivalent to returning a pending Promise that resolves via the microtask queue. Implementation cost: the pending-Promise allocation + ReadableStreamDefaultReadRequest object. Spec observability: identical. This is the canonical concepts/synchronous-fast-path-streaming instance.

The operating failure mode

The naive version of this discipline is "my optimisation preserves the observable behaviour I can think of." The practitioner then ships an allocation-free read path that silently breaks cancellation-during-read, locked-stream error identity, or thenable interception.

Vercel describes running into exactly this (sources/2026-04-21-vercel-we-ralph-wiggumed-webstreams-to-make-them-10x-faster):

"We tried many shortcuts. Almost every one of them broke a Web Platform Test, and the test was usually right. The ReadableStreamDefaultReadRequest pattern, the Promise-per-read design, the careful error propagation: they exist because cancellation during reads, error identity through locked streams, and thenable interception are real edge cases that real code hits."

The missing piece: executable spec as oracle

Spec-compliant optimisation becomes tractable only with a machine-checkable spec oracle — typically a comprehensive conformance test suite. The spec text alone is insufficient because human reasoning about what's observable reliably misses edges. The oracle is the arbiter.

For Web Streams, that oracle is Web Platform Tests — 1,116 streams cases. Every shortcut that failed WPT pointed at a spec invariant the optimiser had broken. This is the load-bearing enabler for patterns/ai-reimplementation-against-conformance-suite: WPT is the reason AI-assisted reimplementation became possible at all.

Concrete spec-compliant optimisations from the 2026-04-21 disclosure

Optimisation Spec-observable? Mechanism
Return resolved Promise on buffered read No (microtask hop still fires) Skip request-object + pending-Promise allocation
Defer pipeThrough resolution until pipeTo() sink No (consumer reads happen at same logical time) Walk upstream link chain, single pipeline() call
Use LiteReadable for byte streams No (BYOB + read semantics preserved) Array-based dispatch vs EventEmitter
Patch Response.prototype.body to fast shell No (deferred chain resolves at read) Fast-stream wrapper allows chain fusion later

Spec-violating shortcuts that broke WPT

Per the 2026-04-21 post, things Vercel tried that broke WPT:

  • Using .call() to invoke user callbacks. WPT monkey-patches Function.prototype.call and verifies implementations don't use it. Reflect.apply is the only safe way. The spec says "call the function"; the test suite encodes "without using user-clobberable properties".
  • Replacing WHATWG pipeTo() universally with Node's stream.pipeline(). The goal was a single pipeline() call per chain. Reality: 72 WPT failures on error propagation, stream locking, and cancellation. Retreated to pipeline()-only-when-all- fast, falling through to spec-compliant pipeTo or native pipeThrough otherwise.
  • Not being careful with {value, done} allocation. WPT puts .then on read results to verify thenable handling; since Promise.resolve(obj) always checks .then, where the result object is created matters.

Sibling to the C/C++ "as-if" rule

Compiler writers have long worked under the "as-if" rule of the C and C++ standards — the implementation must behave as if the source program ran step-by-step, but any optimisation that preserves the observable behaviour is fair game. Spec-compliant optimisation is the same discipline applied at the API-implementation layer rather than the compilation layer — and WPT plays the role the compiler's correctness tests and sanitisers play for C/C++.

Seen in

Last updated · 476 distilled / 1,218 read