Cloudflare ships its JavaScript runtime every single day to code it did not write and cannot ask anyone to change. This guide reconstructs how that became possible, and what it costs, from the one file where the whole contract is written down, plus the package registries that date every step of the surrounding decade.
A shared execution environment, other people's code already running on it, and a release every day. The problem is not how to build the platform; it is how to keep changing it once you have lost the right to ask anyone to change with you.
The problem, stated without naming anything: you operate an environment that runs other people's programs, you release changes to it continuously, and you have no mechanism to make those programs change in step. Every hosted runtime, every database with a query planner, every long-lived API sits somewhere on this problem. What makes it hard is not the first change. It is the fiftieth, once the accumulated promises of the previous forty-nine are load bearing.
Five organisations have shipped an answer and left it in public. Cloudflare stamps every deployment with a date and freezes the semantics of that date forever. The Node.js project numbers its removals and does remove them: 206 deprecation codes, of which 131 are marked End-of-Life. Fastly swapped the entire JavaScript engine underneath its customers in one release and shipped a flag to turn the swap off. Vercel keeps a separate repository whose stated purpose is "Developing, testing, and defining the runtime Web APIs for Edge infrastructure", which is an admission that the APIs were not defined anywhere else. And the committee the runtime vendors formed for that purpose, WinterCG, moved itself out of the W3C and into Ecma in December 2024 because a Community Group cannot actually produce a standard.
This guide is about the Cloudflare instance, because it is the one where the contract is a
file you can read, count and date. That file is compatibility-date.capnp in the
workerd repository, and it is the most honest architecture document any of these
companies has published, precisely because nobody wrote it to be read as one. It contains
sentences like "We're worried that fixing this could break existing workers", attached to a
bug that has sat unfixed since the flag list began.
I expected the interesting artefact of Cloudflare's decade to be the Rust rewrite of the proxy. It is not. The interesting artefact is that the runtime's own record shows the opposite of a platform converging: the flag namespace grows faster every year, not slower. Four flags took a default date in 2021; 26 have taken one in the first nine months of 2026. Half the flags in the file, 97 of 187, have never been given a date at all, and 146 carry a permanent escape hatch that lets any customer pin the old behaviour indefinitely. The contract did not stabilise the platform. It made instability affordable, and the bill is a behaviour matrix that only ever gets wider.
Scope. This guide covers the tenant-facing behaviour contract of Cloudflare's developer platform between 2016 and 2026, the language and tooling decisions visible around it, and the comparable contracts at Fastly, Vercel, Node.js and WinterTC. It deliberately does not cover Cloudflare's network architecture, its configuration distribution plane, its pricing, or its published outage postmortems: the session that produced this page could reach code hosts and package registries only, so every claim here rests on repository and registry artefacts rather than on anybody's blog. Where that limit bites, the page says so.
Seven moving parts, six of which are in one Cap'n Proto schema file. The seventh is the rule that a flag must be documented before its date arrives.
The contract works like this. Every deployed Worker carries an immutable
compatibility_date chosen by its author, plus an optional list of named flags.
The runtime resolves that pair into a set of booleans and then branches on those booleans
wherever behaviour has ever changed. The runtime's own version number is a date:
v1.20260913.1 shipped on 13 September 2026, and the README states the property
plainly, "Updating workerd to a newer version will never break your JavaScript
code. workerd's version number is simply a date, corresponding to the maximum
compatibility date supported by that version."
What makes this more than a feature toggle system is the second direction. Nearly every flag is declared twice: an enable name for people who want the new behaviour early, and a disable name for people who need the old behaviour permanently. The file's own comment is careful about which is which: an enable flag is "used to enable the feature before it becomes the default, probably for testing purposes", while a disable flag is "used when a worker needs to keep long-term backwards compatibility with one bug but doesn't want to hold back everything else. This is hopefully rare! Most features should have a disable-flag defined." Those two sentences are in tension, and the count settles it: 146 of 187 flags carry a disable name. The rare case is the common case.
A deployment pins a date, never a runtime version. That inverts the usual dependency: the operator upgrades daily and the tenant never does, which is the only arrangement that scales to millions of deployments nobody can contact.
Stated at: workerd README
46 flags are declared as implied by another flag after a date, for example
nodeJsCompatV2 is implied by nodeJsCompat after 2024-09-23. The
mechanism exists because a date alone cannot express "new behaviour, but only for people
who already opted into this family".
Counted in: the flag file
39 flags are marked experimental and take no date. This is how the platform ships
unfinished surface without promising it, and it is also where flags go to be forgotten:
12 fields are now named obsoleteNN, retained as dead numbers because
removing a field would renumber the schema.
Counted in: the flag file
Two details raise this from a pattern to an architecture. The first is the documentation gate. The repository's contributor doc says compatibility flags "MUST be documented BEFORE their enable date", and puts the obligation on the author: "It is the responsibility of whoever introduces the flag to update the documentation at the same time as the flag." Each flag gets its own markdown file in the public docs repository. The contract is therefore enforced in three places, the schema, the docs tree, and upload validation, and a flag that exists in only one of them is a defect a reviewer can see.
The second is the global escape hatch, and how little it is used. One annotation,
compatEnableAllDates, turns a flag on for every date including the past. Its own
comment reads: "This is almost NEVER what you actually want because you're most likely
breaking back compat. Note that workers uploaded with the flag will fail validation, so this
will break uploads for anyone still using the flag." In 187 flags it has been used exactly
once, on the R2 public beta bindings. A mechanism that exists, is documented, and is used once
in five years is a good sign: the team wrote down the unsafe path so that taking it would be
a deliberate, reviewable act.
Where the reconstruction gets interesting is the eight flags annotated
neededByFl, which the schema describes as "A tag to tell us which fields we'll
need to propagate to FL on subrequests and responses." FL is the older proxy tier. Neither the
schema nor the README explains the relationship, but the flags that need propagating are the
ones about HTTP surface, Brotli content encoding, custom ports, cache-rule overrides and gRPC
conversion, and one of the oldest flags in the file is a 2021 note that the original
fetch() "happily sent any scheme to FL in the X-Forwarded-Proto
header". The inference, which neither document states, is that the new runtime never replaced
the old proxy: it was slotted in beside it, and per-request behaviour has to be negotiated
across that seam. If you are planning a rewrite, that seam is the part nobody budgets for.
Six forks visible in the record, with the condition that would flip each one for a team that is not Cloudflare.
Symbol.toStringTag, and reversed: "it turns out that was more breaking than expected"workerd was opened up in 2022 and Miniflare 3.0.0 (17 May 2023) rebuilt the local simulator on itThe fourth decision is the one most teams get wrong in the other direction. Cloudflare is the
company that put Rust in the network path: quiche on crates.io since 24 January
2019, boringtun since 22 March 2019, lol_html since 26 November
2019, pingora first published 7 December 2022 and opened to the public in 2024,
foundations since 23 January 2024. Its own README gives the rule: use Pingora if
"Security is your top priority: Pingora is a more memory safe alternative for services that
are written in C/C++". And yet the runtime is C++, because it is V8, and the CLI went the
other way entirely. Wrangler v1 was Rust, published as @cloudflare/wrangler from
1 June 2019; wrangler v2 is TypeScript, published as wrangler from 8 May 2022;
the v1 repository was archived on 3 August 2023 with the notice "This repository is for
Wrangler version 1, which is deprecated and no longer updated." The pattern is not "rewrite in
Rust". It is "put the language where its cost is paid": memory safety in the per-request path,
ecosystem gravity in the developer tool.
| Decision | Chosen | Rejected | Because | Flips when | Evidence |
|---|---|---|---|---|---|
| Runtime versioning | Date per deployment | Semver runtime | No tenant upgrade moment exists | You can schedule tenant upgrades | workerd README |
| Release cadence | Daily, version is the date | Batched releases | Freezing semantics decouples cadence from risk | Your rollback unit is bigger than a day | releases |
| Engine upgrades | 41 patches rebased onto each V8 | Forking V8 | Patches keep you on the upstream release train | Your patches stop rebasing cleanly | v8-updates.md |
| CLI language | TypeScript, from 2022-05-08 | Rust, 2019 to 2023 | The tool lives in the users' ecosystem | The CLI becomes a performance-critical daemon | wrangler-legacy |
| Node.js APIs | Default on from 2026-08-04 | A purely web-standard surface | Ecosystem cost exceeded the purity benefit | Your users' libraries do not assume Node | PR 6444 |
| Local development | Ship the runtime itself | Independent emulator | Two implementations means two behaviours | The runtime cannot leave your infrastructure | miniflare registry record |
The Node.js decision deserves its own paragraph, because the argument is public and it is
about exactly the thing this guide is about. On 27 March 2026 a Cloudflare engineer opened
PR 6444, "Enable nodejs_compat by
default", adding a date of 2026-04-14 to the nodeJsCompat flag. A reviewing
engineer listed the side effects: Buffer and process on the global
scope, setImmediate on the global scope, performance on the global
scope, and "setTimeout and setInterval returning an object rather than a number", which he
flagged as the one that "likely has the greatest potential for introducing problems". The PR
was closed unmerged on 17 April 2026. The flag carries a date today, 2026-08-04, four months
later than proposed. A platform that had no date mechanism would have had to choose between
shipping the break and never shipping it; this one could take the time to argue, then encode
the outcome as a date in a file.
Five failures, in three classes. None of them is the failure people expect, which is a customer's code breaking because the platform changed underneath it.
An evidence limit first, because it changes how you should read this section. Cloudflare's own incident postmortems are published on its blog, and the blog was not reachable from the environment this guide was researched in. Everything below comes from security advisories and issue threads on the code host, which are incident records of a narrower kind: they tell you what broke and what was patched, but not how long it lasted, how many tenants were affected, or what the team changed in its process afterwards. Treat the blast radius rows as the weakest claims on the page.
workerd to crash" for Workers handling WebSocket messages.Symbol.toStringTag on all runtime objects fixed several compliance bugs and broke deployed code that was type-sniffing. The remedy was a new flag whose comment says it plainly: "Unfortunately it turns out that was more breaking than expected."set_tostring_tag with do_not_set_tostring_tag, restoring the original behaviour below the date.url_standard with a date of 2022-10-31. A second flag had to follow for redirects, with the comment "the specCompliantUrl flag did not contemplate the redirect usage".response_redirect_url_standard, with its own disable name.Temporal API in the deployed runtime with its clock unvirtualised: "Temporal.Now.instant().epochMilliseconds returns 0 even at request time and after I/O, while Date.now() correctly returns real time." Code guarding a polyfill with typeof Temporal === 'undefined' silently stopped polyfilling, and issued JWTs stamped 1970 that "downstream verifiers correctly reject".workerd builds V8 without Temporal, so the two had diverged.Temporal.Now track Date.now().FormData instance exceeding 2^31 elements made forEach() "read from the wrong location in memory while iterating over elements", typically a crash, theoretically undefined behaviour.esi:include element as needing an end tag, which is wrong. The flag that fixes it, html_rewriter_treats_esi_include_as_void_tag, is the third entry in the file and carries no date. Its comment: "We're worried that fixing this could break existing workers."Group those six and three classes fall out. Class one, the default that pulls in more
than it says: the WebSocket compression date. Class two, the correctness fix that is a
behaviour change: toStringTag and the two URL flags, both repaired with more
flags. Class three, behaviour that enters from outside the contract: Temporal. Only
class two is the failure mode the contract was designed for, and it is the only one the
contract actually contained. That is the honest summary of what a compatibility date buys
you: it defends the surface you wrote, on the axis you anticipated, and nothing else.
There is a fourth class the public record cannot show, and naming it is the most useful thing this section can do. No published artefact describes what happens to a deployment that never moves its date. The ESI card above is the visible end of it: a bug nobody dares fix by default because the population that depends on it is unknown. Somewhere there are Workers running 2021 semantics on a runtime released today. Nobody has published how many, how they are monitored, or what would happen if a dependency forced that behaviour to change. If you adopt this pattern, that population is your real liability, and you should instrument it on day one.
Everything countable in the record, with what it was counted from and when. The counts are reproducible: fetch the file and run the same greps.
| Metric | Value | At | Context | As of | Source |
|---|---|---|---|---|---|
| Behaviour flags in the runtime | 187 | Cloudflare | Bool fields in the compatibility schema | 2026-09-13 | flag file |
| Flags with a default date | 90 | Cloudflare | The rest are opt-in only | 2026-09-13 | flag file |
| Flags with a permanent opt-out | 146 | Cloudflare | Disable names, kept after the date | 2026-09-13 | flag file |
| Dated flags per year | 4 / 11 / 10 / 17 / 20 / 26 | Cloudflare | 2021 through 2026 to date; the last is nine months, not twelve | 2026-09-13 | flag file |
| Flags forwarded to the older proxy | 8 | Cloudflare | neededByFl annotation | 2026-09-13 | flag file |
| Uses of the break-everyone escape hatch | 1 | Cloudflare | R2 public beta bindings | 2026-09-13 | flag file |
| Patches carried against V8 | 41 | Cloudflare | Rebased on every engine update | 2026-09-13 | patches/v8 |
| Node.js deprecation codes | 206 | Node.js | 131 End-of-Life, 23 runtime, 42 docs-only | 2026-09-13 | deprecations.md |
| Rust CLI lifetime | 2019-06-01 to 2023-08-03 | Cloudflare | First publish of @cloudflare/wrangler to repository archive | 2026-09-13 | wrangler-legacy |
| TypeScript CLI major versions | 2.0.0 / 3.0.0 / 4.0.0 | Cloudflare | 2022-05-08, 2023-05-17, 2025-03-13 | 2026-09-11 | npm registry |
| Local simulator, first to workerd-based | 2021-05-20 to 2023-05-17 | Cloudflare | Miniflare 0.1.0 to 3.0.0 | 2026-09-11 | npm registry |
| Rust in the network path, first publish dates | 2019-01-24 / 2019-03-22 / 2019-11-26 / 2022-12-07 / 2024-01-23 | Cloudflare | quiche, boringtun, lol_html, pingora, foundations | 2026-09-13 | crates.io |
| Pingora crate downloads | 9,176,279 | Cloudflare | Adoption of the framework, not of the proxy | 2026-09-13 | crates.io |
| Requests per second served by Pingora | 40,000,000+ | Cloudflare | Vendor claim in the project README, no independent measurement found | 2026-09-13 | pingora README |
Measured here: every flag count, the patch count and the publication dates, all taken from files fetched on 13 September 2026 and countable again in a minute. Claimed: the 40 million requests per second and the memory-safety framing around it are the project's own marketing, unverified by anything in this corpus. Derived: the per-year flag growth is my count of enable dates grouped by year, and 2026 is a partial year, so the trend is stronger than the table makes it look. Unknown: how many deployments sit on old dates, the size of the oldest cohort, and whether any published mechanism retires one. That gap is the single most important thing missing from the public record.
Every source behind this page, graded. Note the shape of it: this is a corpus of repository artefacts, because that is what the research environment could reach.
The whole contract in one schema: 187 flags, 90 with dates, 146 with permanent opt-outs, 39 experimental, 12 retired to dead field numbers, and a running commentary of admissions about bugs that could not be fixed outright.
The rule that makes the contract auditable: flags "MUST be documented BEFORE their enable date", and the author of the flag owns the docs change in the same window.
The twelve-step procedure for moving the engine underneath everyone, including rebasing the local patch series onto each new V8 and an automation script the doc says "has not been thoroughly tested".
41 patch files, including promise context tagging and cross-request promise resolution, which are the pieces that make one V8 isolate serve many tenants' requests safely.
A Cap'n Proto vulnerability reachable because WebSocket compression is on by default for compatibility dates from 2023-08-15. Production was patched before disclosure.
Integer overflow in FormData iteration reading from the wrong memory,
impractical to exploit on Cloudflare's own platform, patched in v1.20230419.0.
An engine upgrade exposed a new global whose clock bypassed the runtime's virtualised time, and feature detection in tenant code turned that into JWTs stamped 1970.
The argument in public: globals added, and "setTimeout and setInterval returning an object rather than a number" as the change with "the greatest potential for introducing problems". Closed 17 April 2026; the flag carries 2026-08-04 today.
The promise, "Updating workerd to a newer version will never break your JavaScript code", alongside a release every day whose version number is that day's date, and the warning that workerd alone "is not a hardened sandbox".
The Rust CLI, 2,775 commits and 3.2k stars, archived on 3 August 2023 with a deprecation notice pointing at the TypeScript rewrite.
Dates the reversal precisely: Rust CLI first published 1 June 2019 and last on 21 February 2023; the TypeScript line starts at 2.0.0 on 8 May 2022, so the two ran side by side for nine months.
0.1.0 on 20 May 2021, 3.0.0 on 17 May 2023 the same day as wrangler 3, and current builds versioned by calendar date, 5.20260911.0-alpha.
The Rust arc with dates: QUIC in January 2019, WireGuard in March 2019, the HTML rewriter in November 2019, the proxy framework in December 2022, the service library in January 2024.
The claim of more than 40 million requests per second, and the stated reason to adopt it: a memory-safe alternative for services written in C or C++.
"quiche powers Cloudflare edge network's HTTP/3 support", with the library also shipping on Android, which is the rare case of a vendor's infrastructure component becoming someone else's platform dependency.
The opposite contract, written down: 206 numbered deprecations with 131 already at End-of-Life, which is what becomes possible when the user chooses the runtime version.
"use StarlingMonkey by default, --disable-starlingmonkey flag": an entire JavaScript engine swapped under customer code in one release, with a named way back.
Why the runtime vendors' interoperability group left the W3C for Ecma: "technical standards development work will need to take place in a TC or WG, rather than a W3C CG".
Still active, 915 stars, describing itself as "Developing, testing, and defining the runtime Web APIs for Edge infrastructure": a third vendor maintaining a fourth definition of the same surface.
Each compatibility flag has its own markdown file in the public docs repository, which is the artefact the contributor rule in api-updates.md points at.
"Release 2026-09-13", "Release 2026-09-12", and so on, cut by an automation account between ordinary pull request merges from named engineers.
Python Workers carry their own annotation class, pythonSnapshotRelease, for
changes that break memory snapshots, and pin a Pyodide generation by flag, for example
python_workers_20250116 implied after 2025-09-29.
The C++ rules the runtime is held to: bounds and null checking enabled everywhere, raw references described as "incredibly dangerous", smart pointers required by default.
The service library the Rust components share: logging, tracing, metrics, memory profiling and seccomp sandboxing, published on crates.io since January 2024 and now a dependency of Pingora's own telemetry crate.
No conference talk, no peer-reviewed paper and no engineering blog post is cited on this page, and that is not because none exist. The research environment for this guide could reach code hosts and package registries only, so Cloudflare's own blog, the archive, the usual conference video hosts and the paper repositories were all out of reach. The upside is a corpus nobody wrote for an audience: schema comments, patch filenames, archive banners and registry timestamps. The downside is that motives and outcomes are inferred rather than reported, and none of Cloudflare's published outage postmortems could be consulted. If you extend this work, start with the blog posts named in the READMEs cited above.
Six rungs. The line between a toy and the real thing is rung four, where you stop being able to delete anything.
Take any service with a handler interface and add an immutable behaviour_date
to each deployed unit. Implement one behaviour change twice, old and new, selected by that
date.
Done when: two units deployed on the same binary produce different documented outputs for the same input. Teaches: semantics are per-deployment state, not per-release state.
Give the change an enable name and a disable name, and make deployment fail on any flag name the binary does not know, the way Cloudflare rejects uploads carrying retired flags.
Done when: a deployment with a typo in a flag name is refused at upload, not at request time. Teaches: the flag namespace is an API, so it needs validation and a deprecation story of its own.
Date implies a flag set; explicit names override; implication rules like "flag B is implied by flag A after date D" come last. Write a table-driven test over dates and flag combinations.
Done when: the test enumerates every flag against three dates and fails if a new flag is added without a case. Teaches: the resolution order is the part people get wrong, and the only defence is exhaustive tests.
Publish the interface to a second team, wait for them to deploy, then attempt to remove the oldest behaviour. Measure what you have to do to find out whether anyone depends on it.
Done when: you can answer "how many live deployments would this removal change" with a query rather than a guess. Teaches: the cost of the contract is not the branching, it is that removal now requires a census.
Upgrade an engine, library or kernel your behaviour is built on and enumerate every observable difference it introduces. Gate the ones your contract does not already cover.
Done when: the upgrade's new observable surface is listed in the changelog, and anything unflagged is a deliberate, recorded choice. Teaches: the Temporal failure, before it happens to you.
Emit the resolved date and flag set with every request, then build the distribution: oldest date in production, number of deployments more than two years behind, flags that only pre-2022 deployments still use.
Done when: a dashboard answers "what breaks if we retire behaviour X" in one query. Teaches: the liability of a compatibility contract is a population, and populations are only manageable once they are measured.
What actually worked here, in an environment where engineering blogs were unreachable and only code hosts and registries answered. The method transfers to any company with a public repository.
site:github.com <org> compatibility flag schemacurl https://raw.githubusercontent.com/<org>/<repo>/main/docs/api-updates.mdgrep -c 'compatEnableDate' compatibility-date.capnphttps://github.com/<org>/<repo>/pulls?q=is%3Apr+is%3Aclosed+is%3Aunmerged+<topic>https://github.com/<org>/<repo>/issues?q=is%3Aissue+regression+OR+broke+<feature>https://github.com/<org>/<repo>/security/advisoriescurl https://registry.npmjs.org/<package> | jq '.time | {created, "1.0.0", "2.0.0"}'curl https://crates.io/api/v1/crates/<crate> | jq '.crate.created_at'site:github.com <org> archived "no longer maintained"grep -n 'neededByFl\|Unfortunately\|worried' compatibility-date.capnphttps://github.com/<org>/<repo>/tree/main/patcheshttps://github.com/<org>/<repo>/commits/mainTwo habits did most of the work. First, read the comments rather than the code: "We're worried that fixing this could break existing workers" is a design position nobody would put in a blog post. Second, prefer artefacts with timestamps you did not have to trust: a registry publication date, an archive banner, a release tag. When the narrative sources are unavailable, the bookkeeping is still there, and the bookkeeping is harder to polish.