0003. The sandbox targets workerd's surface

• Status: superseded by 0008
• Date: 2026-07-20

Context

This executor is a drop-in replacement for one that runs generated code on workerd. Code a model wrote against the platform executor has to run here unchanged. So the API surface inside the isolate is a compatibility question, not a question of taste. Bare V8 isolates carry the ECMA-262 language and no more. So the surface is entirely a choice. Without a named target the choice becomes a series of guesses about what generated code will reach for, and every one of those guesses is unfalsifiable.

Decision

Inside the isolate, the web-standard API surface matches workerd’s documented Web Standards list. That list is the target. Proof comes from the differential suite diffing this isolate against a real workerd instance, per 0005.

How a given API arrives follows the cost of the specification:

• Reference implementations in pure JavaScript are taken where one exists, such as whatwg-url for URL. Streams are committed to web-streams-polyfill on the same grounds.
• Thin facades are written inside the sandbox where the specification itself is thin, such as fetch, Request and Headers.
• Host bridges are built only where the API needs a real privilege the isolate does not have: timers, outbound network, crypto.

Where a probe against the real runtime shows an observable string, that string is adopted verbatim and pinned by a test. Error texts for calling a timer with a non-function are workerd’s own.

Consequences

Delivery is capability by capability under 0004, never in one sweep, and each capability arrives with tests pinning its observable behaviour. Divergences are recorded, never tolerated in silence. Every known one lives as a case in the compatibility catalogue: timer functions expose a different Function.length and a different toString source, header iteration is insertion-ordered where workerd sorts, and a few Request properties sit on the instance where the standard puts getters on the prototype.

But some of the list stays out of scope on purpose. Three of them are not targets at all: the Cache API, HTMLRewriter and EventSource. CompressionStream and DecompressionStream and WebSocket are host-backed work, each large enough to need a delivery of its own. Dependency weight is accepted where the standard demands it. whatwg-url ships large IDNA tables because the URL Standard requires them, and it is the same standard that workerd’s own URL implements.