chore(deps): @cloudflare/workers-types 5 upgrade tracker — workspace-wide migration from v4 #139

Umbrella tracker for the @cloudflare/workers-types 4.x → 5.x workspace-wide upgrade, mirroring the pattern used for #115 (Astro) and #120 (Vitest).

Why this needs a tracker

Dependabot filed #127 (@cloudflare/workers-types 4.20260417.1 → 5.20260810.1) on 2026-08-13. workers-types v5 is the workerd type surface split, not a straight number bump — it changes the shape of several ambient interfaces (Fetcher, DurableObjectState, Queue, KVNamespace, ExportedHandler) and drops the deprecated 4.x-shim types.

The bump touches 7 files across the workspace root and every consuming package's devDependencies. Landing it as a single Dependabot merge would risk silent any-widening in packages we care about, and would race with #100 / #64 (workerd boot crash fix landed 2026-04-20 — that codepath is exactly the surface v5 refactors).

Scope

• Root @cloudflare/workers-types bump
• Per-package devDependencies alignment (7 files per chore(deps-dev): bump @cloudflare/workers-types from 4.20260417.1 to 5.20260810.1 #127's changed-files count)
• Audit direct usages of ambient DO / KV / Queue / Fetcher types in:
  • packages/do/
  • packages/kv/
  • packages/queue/
  • packages/realtime/ (uses DO internally — see feat(@workkit/realtime): SSE-over-Durable-Objects broker + client helper #111)
  • packages/ratelimit/ (uses KV — see fixedWindow writes expirationTtl < 60s, rejected by Cloudflare KV #108)
  • packages/cache/
  • packages/mcp/ (see @workkit/mcp: implement DO-backed sessions #46 for DO-backed sessions)
• Confirm every packages/* still type-checks and passes bun test
• Confirm no bundle-size regressions

Blockers / coordination

• TypeScript 7 tracker (to be filed alongside this) — v5 targets newer TS features; ideally land after or with the TS 7 upgrade.
• @workkit/mcp: implement DO-backed sessions #46 DO-backed MCP sessions — do not want to be mid-implementation when the DO type surface shifts.

Action items

• Root bump @cloudflare/workers-types
• Fix any per-package type errors (diff-only, per constitution rule 8)
• Verify packages/do, packages/kv, packages/queue, packages/realtime, packages/ratelimit, packages/cache, packages/mcp still export their public API unchanged
• Confirm bundle sizes unchanged (bundle-size CI job)
• Close chore(deps-dev): bump @cloudflare/workers-types from 4.20260417.1 to 5.20260810.1 #127 (superseded by this tracker)

Dependabot handling (once accepted)

Extend the root bun ecosystem ignore: block in .github/dependabot.yml:

- dependency-name: "@cloudflare/workers-types"
  update-types:
    - version-update:semver-major

Follow the pattern established by #124 (dependabot config) and #137 (docs Astro-ecosystem ignore expansion).

Not covered here

• workerd runtime bumps — separate concern; feat(agent): createRequire(import.meta.url) at module init fails in workerd — blocks prod deploy #64 tracked the boot crash landing 2026-04-20.
• wrangler upgrades — orthogonal.