Cf Compatibility Check

Cloudflare Compatibility Check

Review only the changed implementation and the context needed to prove its behavior. Report findings; do not edit unless the user also requests fixes.

Load the contract first

Before judging code, read completely:

1. the repository AGENTS.md;
2. docs/implemented/p3-0-cloudflare-runtime-compatibility.md;
3. docs/references/cloudflare-compatibility.md;
4. docs/references/p1-deviations.md;
5. packages/runtime/workerd.lock.json and the root package manifest when runtime or public types changed.

The active target is the stable tenant Worker programming surface for Workers runtime, Durable Objects, Queues, Workflows, R2, D1, and KV. Cloudflare management APIs, global edge topology, and other products are outside this review unless the user explicitly changes the scope.

Resolve the review scope

1. Use a user-specified base when provided.
2. Otherwise resolve the repository's default branch from a local refs/remotes/<remote>/HEAD symbolic ref and use its merge base with HEAD. Do not fetch or pull merely to establish a base.
3. If no default-branch ref exists, use a configured upstream only when it clearly represents the integration base. Do not guess main, master, or another branch name. Review the working tree immediately and state that committed branch history remains unreviewed until the base is known.
4. Inventory these scopes separately:
   • committed changes from the merge base through HEAD;
   • staged and unstaged tracked changes against HEAD;
   • untracked files from git ls-files --others --exclude-standard.
5. Inspect deleted code and changed consumers, not only added lines. Expand beyond the diff only to resolve call paths, persisted authority, generated assets, and tests needed to prove a candidate.

Do not report unrelated pre-existing incompatibilities. Report an older defect only when changed code activates, widens, or relies on it.

Use current primary sources

For every changed Cloudflare-visible behavior, retrieve current evidence instead of relying on memory:

1. fixed stable @cloudflare/workers-types declarations and the matching pinned workerd generated declarations;
2. official Cloudflare runtime or product documentation for semantics that types cannot express;
3. official compatibility-flags documentation and Workers changelog for current default behavior;
4. matching upstream workerd source and tests, then a verified stock workerd binary for executable behavior;
5. a portable real-Cloudflare differential only when the user explicitly authorizes its external writes and supplies the required account and credentials.

Use the third_party/workerd submodule, the workerd pin, and installed or locked npm artifacts before considering a network download. The fork checkout may differ from the formal pin: read types/generated-snapshot/index.d.ts and runtime source from the matching revision with git show, and report missing objects instead of substituting HEAD. Browse only official Cloudflare documentation and primary upstream sources for technical claims. Treat workers-sdk, Wrangler, Miniflare, WDL, and other reference projects as integration evidence, not as authority over Cloudflare docs, stable types, or stock workerd behavior.

When sources conflict, record the exact versions and block the compatibility claim. Do not invent a compromise API.

Review each changed surface

Map every changed tenant-visible behavior to a product, upstream declaration, runtime source, and local test. Read only the relevant sections of the surface checklist after identifying the changed domains.

Apply these gates:

Type gate

• Public Cloudflare runtime declarations must come directly from fixed @cloudflare/workers-types stable or from a reproducible matching workerd type generation.
• Generated per-deployment Env, Service RPC, and Durable Object stub types may compose upstream declarations from validated binding configuration.
• Flag handwritten, copied, narrowed, widened, or partially re-declared Cloudflare interfaces, including missing overloads, changed generics, optionality, readonly fields, return types, module declarations, and error types.
• The full upstream package may contain types for non-target products. Actual Env, runtime availability, capability/catalog state, and configuration rejection establish the product boundary; deleting upstream type names does not.
• Stable target members without runtime support are blocked, not unsupported. Experimental declarations are not part of the target unless explicitly added.

Runtime gate

• Trace the public entry point through validation, canonical descriptor, persisted authority, WorkerLoader/system Worker, stock workerd primitive, storage, and response/error mapping.
• Compare success, failure, overload dispatch, default values, limits, metadata, pagination, conditional operations, streams, structured clone, RPC, cancellation, retry, transaction, lifecycle, and restart behavior where applicable.
• A matching method name or a passing smoke test is not runtime compatibility. A stock workerd primitive is not enough when an open-compute facade changes inputs, outputs, errors, visibility, or durability.
• Accept a deviation only when it is caused directly by single-machine topology, preserves the API and security/data contract, has a stable deviation ID and official source, and is covered by positive, negative, and recovery tests.

Single-latest gate

• Tenant configuration must not select historical compatibility_date, date ranges, or compatibility-flag sets.
• The platform must use one reproducibly pinned effective compatibility date and only the internal flags required for the current stable contract.
• Flag old/new behavior branches, historical fallbacks, date-dependent persisted contracts, or claims based on a newer npm type surface than the pinned workerd/runtime can execute.

Scope and authority gate

• Do not require Cloudflare /client/v4, Dashboard, billing, account, or Wrangler management parity.
• Reject non-target binding configuration at the authority boundary, but do not confuse an external data-plane protocol with a management API.
• Preserve tenant isolation, immutable deployment identity, secret boundaries, transaction integrity, restart/crash recovery, and fail-closed validation. Self-host topology does not excuse violations of these properties.
• Reject scenario-specific production branches, test fixture literals, mock-only behavior, or a framework adapter used as proof of the generic platform contract.