Skip to main content

Decision and current state

Oxfmt 0.74.0 and Oxlint 1.89.0 are the canonical repository tools. Run bun format and bun lint for checks, or bun ff for safe lint fixes followed by formatting. CI runs oxfmt --check . and oxlint --deny-warnings --threads 2 .. Editor integrations use the local tools. Markdown, MDX and YAML remain outside Oxfmt formatting; generated byte-freshness artifacts retain their owning generators. CSS overrides use double quotes to retain stylesheet and source-registration contracts; JavaScript and TypeScript retain single quotes. Generated route trees, bridge registries, generated API clients, vendored skill catalogs and paused runtimes remain outside traversal. The Security Checks workflow retains its reviewed bytes and is excluded from formatting; its byte seal remains unchanged. Wrangler usage digests require an explicit formatting-only PR admission. Oxc formatting is independent of Cloudflare runtime adoption. Vite+ consolidates tooling; it does not translate routes, server components or server actions. Lint parity is approximate: the configuration retains the correctness preset with explicit exclusions for React Compiler diagnostics, dependency analysis and rules whose semantics exceed the repository baseline. The explicit react/no-danger error preserves the unsafe-HTML guard. Sanitized HTML exceptions are individual line suppressions tied to a reviewed sanitizer. Type checks remain required. CSS lint rules and import organization do not have automatic parity; review these separately. The pinned configuration is the executable rule inventory.

Formatting conflicts in open pull requests

Manually merge main into the PR branch first. From the repository root, run node scripts/resolve-format-conflicts.js --main origin/main for a dry run, then repeat with --apply. The selected ref must equal MERGE_HEAD. The helper only considers unmerged JS/TS files changed on the PR and proves that normalized base and incoming-main blobs match using the pinned formatter. It retains the PR blob and formats it. Real semantic changes, manual conflict edits, unsupported paths, symlinks, binary content and add/delete/rename conflicts are refused before writes. Targets are opened with no-follow flags before inspecting their descriptor metadata; no pathname precheck authorizes access. Checked regular-file descriptors retain device/inode identity for reads and writes. Nonblocking open rejects non-regular targets without waiting on FIFO peers. Parent containment and identity are rechecked; path replacement refuses without following the replacement. The helper is not a crash-atomic multi-file writer. Only ordinary merge conflict markers are supported; diff3/zdiff3 conflicts need manual resolution. Files with no conflicts are left alone. No index update, commit, merge or push occurs. Inspect the diff and stage resolutions manually. Regression coverage: node --test scripts/resolve-format-conflicts.test.js. Lettin and Parley already have Next.js/OpenNext Worker deployments. Their next architecture milestone is the same per-app TanStack Start + Void + Vite+ Worker runtime as the other web apps, reaching next/* only through @tuturuuu/start-bridge and preserving existing contracts. See the native Start migration runbook. The retired apps/tanstack-web is not revived.

Platform-wide target and daily checkpoints

The ultimate target is every active application using Vite+, hosted on Cloudflare, with Oxc linting/formatting. Work proceeds incrementally alongside the product backlog; the initial Worker inventory below is the first wave, not a limit on the program. Retained paused applications remain excluded until resumed. Mobile continues to use its native Flutter toolchain; shared services and web surfaces follow the platform target without implying a rewrite of native UI. Keep per-app ownership, prerequisites and exact-head receipts in the private request backlog and coordination board. Checkpoint reviewable PRs as each unit finishes. Separate implemented, CI-verified, runtime-accepted and production-delivered states. A merge does not establish hosting cutover. Capture new Worker/app scope and compatibility findings before dispatching the next unit; avoid competing migration and product owners in the same files.

Complete Worker migration scope

The migration includes every active Worker-backed app/service, not only Lettin and Parley. Framework replacement applies to Next/OpenNext web apps; native Workers retain their fetch/email/scheduled/RPC entrypoints while adopting Vite+ and Oxc tooling. A backend service does not need React or a router to qualify. This inventory follows active checked-in Wrangler configurations. Existing apps/backend and apps/tanstack-web Wrangler files are retained paused artifacts, not migration targets. New active Worker configurations must join the inventory. Deployment existence and canonical health still require live evidence. Begin with the portable session core and the already Vite-native Colab toolchain, then use the same verified conventions for native service workers. Meet, Parley and Lettin require the shared framework-adapter work before full web replacement. Each app retains its own exact-commit test/type/lint/build and Worker acceptance receipts; one green app cannot establish another app’s readiness.

cf CLI adoption alongside Vite+

Prefer Cloudflare’s cf CLI over Wrangler as each operation proves compatible. The per-operation verdicts, native Worker template, guard and cutover checklist live in cf CLI and Void over Wrangler. This is a phased tooling decision, separate from framework migration and production promotion. Existing Wrangler commands/configurations remain authoritative until that scope passes its replacement gates. Cloudflare’s launch announcement introduces cf in open beta, with JSON output and a generated API command surface. Vite-built Workers can migrate to typed cloudflare.config.ts; configuration uses Vite modes, whose semantics differ from Wrangler environments. cf still delegates some development/deployment paths to Wrangler. Recheck upstream support before implementing a scope; the announcement is not evidence of repository compatibility.
  1. Read-only discovery first. Pin a reviewed cf version through the owning workspace’s package manager. Verify help/schema, authentication and selected account independently; existing Wrangler login does not establish cf access. Exercise bounded inventory/observability queries and record supported command mappings. Filter JSON to required fields and keep raw logs/credentials private.
  2. Pilot a Vite-native Worker. Coordination or Colab is a candidate after its Vite+ artifact gates pass. Review migration output in an isolated worktree; do not run a repository-wide migrator. Verify compatibility with the pinned Vite+ core, Cloudflare plugin and test runner before adopting typed configuration.
  3. Prove configuration and artifact parity. Compare resolved settings for every used mode: account/name, routes/domains, compatibility date/flags, assets, service bindings, Durable Object names/classes/migrations, storage identifiers, triggers, secrets and observability. Preserve resource identity; never infer that a similarly named mode selects the same deployed environment. Select one authoritative configuration per scope, with an explicit fallback procedure.
  4. Replace operations separately. Map local development, type generation, tests, CI bundling, validation upload, tail, version inspection, deployment and rollback individually. Unsupported or unverified operations retain Wrangler. CI must exercise the final emitted artifact and preserve exact-SHA and target identity checks; a CLI rename or dry run alone cannot establish runtime health.
  5. Roll out per owner. Update scripts, workflow permissions, runbooks and skill references together after focused tests and exact-commit CI pass. Production commands change only with separately authorized promotion, bounded scope and verified rollback. Keep paused runtimes excluded.

Discovery runtime and authentication

Use Node.js 22.18 or later to execute cf. Installing a dependency with Bun does not mean the CLI should run on Bun: Cloudflare documents that commands loading cloudflare.config.ts fail on the Bun runtime. Verify the executor separately from the package manager. See installation and authentication. For capability discovery before project adoption, run a reviewed, exact cf version through npm exec --yes --package=cf@<reviewed-version> -- cf --help from a private scratch directory outside app configuration and .env ancestry. This avoids a global install or repository dependency change. Use an anonymous cf cli search query describing the operation, then inspect that command’s help/schema. Discovery proves command availability, not authenticated operation or Worker artifact parity. Parse cf auth whoami JSON and require authenticated === true; exit status zero alone does not establish authentication. An unauthenticated result can return authenticated: false and an error with a successful process exit. Preserve that failure instead of proceeding to API calls. cf uses separate credentials from Wrangler; do not copy credential files or assume a prior Wrangler login applies. API commands can remember selected accounts in project-local cache files. Use explicit target identity and isolate discovery before touching app worktrees; review any resulting local files. Neither command discovery nor --dry-run authorizes migration, configuration mutation, resource creation or deployment. Cron Control, Devbox Control and Coordination pin cf@1.0.0-beta.20 and use cloudflare.config.ts, vp dev and cf workers types. Their existing per-service CI checks qualify configuration and emitted output; this does not qualify legacy Void or OpenNext configuration consumers. See the operation matrix for retained publication gaps. The package pin requires Node ^22.23 || ^24.22 || ^26.12; the older Node 22.18 discovery minimum does not satisfy that package’s engines. Do not replace wrangler types --config <emitted-config> with a bare cf command: type generation must read the same Worker identity and preserve the declarations consumed by the app. Retain legacy local dev, D1 migration and tail commands until their exact configuration, persistence and output contracts pass independently. Calendar is the first emitted-config type-generation profile: its existing validator admits only ASSETS, and the adapter runs the pinned cf CLI on a supported Node executor. CI compares exact binding keys/requiredness/types against the existing producer, verifies unchanged artifact bytes and retains a receipt. Its self-contained declaration does not require shipping a generated config. Other resource and framework profiles still require separate qualification. Calendar’s build-output comparison copies sealed ESM/assets into the cf format and verifies the same bytes after restore. It retains the publisher because secondary upload-module names and asset/runtime semantics need separate proof. Track CLI capability gaps independently from app migration so an unsupported operation does not block portable libraries or Oxc adoption.

Qualify dependency resolution

Reconcile workspace requests with Bun’s generated lockfile using the repository’s pinned Bun version. A manifest-only update can leave frozen installation blocked before any type checking runs. Keep lifecycle scripts disabled during local dependency inspection; require the normal exact-commit CI installation and builds. Review effective tool dependencies as well as changed lock rows. Oxlint and Oxfmt have optional Vite+ peers, so a Vite+ update can change their selected peer without changing either tool’s own row. Static scoped placements and a successful frozen lockfile check do not prove the installer uses those placements. Resolve packages from each owning app and tool after installation, record intentional peer changes, and retain CI and emitted-runtime gates for the affected apps.

Use the tooling foundation

From the repository root, pass explicit files you own:
Lint fails on warnings/errors. Format checks do not write; oxc:write explicitly applies formatting. The wrapper rejects empty selections, flags, globs, directories, symlinks resolving outside the permitted source, build/dependency trees and paused runtimes. Installed tools run with two threads, without Turbo or builds. Tests cover scope rejection, debugger linting, read-only formatting and idempotence. The baseline uses correctness rules with explicit exclusions, TypeScript/React/ accessibility plugins, and two-space, 80-column, single-quote, semicolon, LF, ES5-trailing-comma formatting. This is not Oxc rule parity. Manifest sorting is disabled; import and Tailwind sorting are not enabled.

Rule parity follow-up

The root configuration lists every disabled rule. React Compiler rules and react-hooks/exhaustive-deps need a separate behavioral adoption. Accessibility rules need component-aware parity with existing intentional exceptions. Unused variable and expression checks need matching TypeScript/test semantics. Arithmetic and control-regex rules need fixture review before enabling. Next.js domain rules, CSS linting, import organization and Tailwind sorting require dedicated parity coverage; format success alone does not establish it. Keep type, accessibility, security and runtime validation independent.

First-party portability contract

Maintain domain rules and application services as ordinary TypeScript modules. Reusable React components may depend on React and framework-independent UI primitives; they receive navigation, translated labels and data through typed props or a small explicitly scoped provider. React Server Components are an optional adapter surface, never a prerequisite for consuming the domain package. Prefer existing first-party packages and narrow public subpath exports over a new universal framework wrapper. Keep Next-specific compatibility entrypoints stable while adding portable ones. Do not call an entire package framework-agnostic just because one file is pure: consumers must resolve its entrypoint without transitively loading Next/OpenNext or Cloudflare. Validate import graphs and consumer builds in CI. Runtime-specific optional adapters must have explicit entrypoints/dependencies. Use standard Request, Response, Headers, URLs and AbortSignal at HTTP boundaries where appropriate. Pass request context per invocation; never store actors or bindings in process-wide mutable state. Inject verified identity rather than accepting browser-provided user IDs as authority. Preserve audience, expiry, MFA, consent, membership and revocation checks in reusable policy services. Current seams include Lettin’s Actor/Store context and SQL permission fences, with bindings/identity/HTTP as framework adapters. Parley/Meet domain contracts can remain shared while routes, session lookup and meeting UI adapters are extracted. A package can support Next.js, TanStack Start or other React hosts by implementing these small adapters; support for every framework is a goal requiring consumer verification, not an automatic guarantee.

Vite-native Worker acceptance gates

Compare emitted compatibility flags against each service’s source configuration; Devbox Control currently has no flags, so its verifier must not require nodejs_compat simply because another Worker uses it. Prove a small authenticated vertical slice before replacing the complete app. Document fixture boundaries and hosted dependencies: local Durable Objects do not validate Cloudflare SFU/TURN. Hosting adoption does not imply migrating every store to D1 or replacing Supabase. Database changes, schedules, secrets and canonical traffic each need a bounded plan. Pin the promotion range, retain a rollback artifact and verify schema/binding compatibility and health before promotion.

Runaway-work and cost acceptance

Every migration or change that adds or amplifies billable work must include a cost-safety review. The reported runaway Durable Object alarm incident is a warning about self-sustaining work, not an independently verified account of provider usage. Do not rely on future refunds, billing notifications or a per-invocation CPU limit to cap total storage, requests, retries or downstream spend. Durable Object alarms are at-least-once and automatically retry thrown errors. Explicit rescheduling can create another chain beyond those retries. Ingress rate limits cannot stop work that an alarm, queue consumer or cron trigger already owns. Require regressions for empty queues, expired state, duplicate execution, restart, clock/deadline boundaries, persistent downstream failure, no progress and stop-versus- reschedule races. Count storage/downstream calls as well as final return values; prove bounds under repeated wakes in isolated fixtures and the real local Worker. Exact-commit CI must exercise the emitted artifact. Keep live account settings, alert delivery and hosted shutdown verification as separate production evidence. Cron Control’s default-off checkout Worker uses a 5,000-item combined active and quarantine bound, pre-expiry capacity checks, three durable attempts per item, per-workspace invalidation receipts and a 240-second whole-run deadline. Stop is checked before each expiry batch and invalidation chunk. See the processor runbook for counted operation bounds, restart/deadline/poison regressions and remaining hosted stop and cache-freshness evidence. Source and mocked requests do not establish billed usage or crash-atomic database-to-ledger persistence. Cron Control’s default-off database history job adds one RPC per enabled ten-minute slot, deleting at most 1,000 completed rows per table. It has no in-slot retry or drain loop; the existing durable slot claim, pre-delete stop fence and five-failure budget survive ledger restarts. Counted dispatch/stop regressions and full-chain pgTAP cover the bounds and seven-day cutoff. The history retention runbook records the daily operation envelope and stop procedure. Hosted scheduled execution, independent operator-stop acceptance and billed usage remain rollout evidence. The abuse-guard store Worker (apps/abuse-guard) keeps its bounded-work and stop-fence evidence in the abuse-guard store runbook. It carries a few accounting limits:
  • Its daily budget counts admitted commands, not billed rows. One win.hit writes up to four window rows plus a dedupe record, and one res.reserve writes up to three rows plus a dedupe record.
  • Replay/password command admission now checks durable source/principal quotas and charges family usage in one control-object transaction. Each identity gets at most 5% of the family share per UTC day. Denied subject commands and success refunds count; cache eviction/restart never resets the quota.
  • Fair admission adds one control DO request per cache miss and up to two quota rows plus a control-state write on admission. Rejected probes do not spend subject commands, but their request billing remains unbounded without accepted ingress controls. The command budget is not a total dollar cap. Hosted request sizing and partition capacity remain activation holds.
  • Other families reserve the entire batch in a durable control transaction before executing subjects. Each admitted batch adds a control request and a control-state row read/write. Interrupted and skipped work remains charged. The workerd restart-before-flush regression replaces the runtime between admissions and verifies that reservations survive and the family budget cannot be bypassed. Operator stops reject new admissions; request billing remains an activation hold.
  • The theoretical storage ceiling is 2 KiB × 120-day retention × the daily budget. Only replay fences use long TTLs, and their values are tiny.
CPU limits constrain an invocation, not the number of invocations or all billable services. Usage notifications are detection, not an automatic spending cutoff. Choose service-specific limits with measured workloads; do not silently apply an arbitrary global value that breaks realtime or recovery behavior. See current Workers pricing and custom CPU limits and available billing alerts. Any automatic circuit breaker must itself perform bounded work and fail safely without deleting original data or retrying indefinitely. Existing tests and code must be inspected per service; this foundation establishes review gates and does not assert that every deployed alarm is protected or that account alerts are configured.

Hive maintenance and native migration

The Hive maintenance module (apps/hive/maintenance/worker.mjs) returns one fixed response per request with zero upstream calls, bindings, body reads or background jobs. Focused tests cover HTTP methods, WebSocket rejection and zero external work. Request volume can still incur charges. Hosted route removal and script deletion are its durable stop procedure; that control-plane rehearsal is pending separately approved staging access, not proven by source tests. See the maintenance runbook. The native migration plan requires persisted budgets and generation/stop fences before simulation, queues, alarms or model calls can be enabled. Operation-count, crash/restart and stop-versus- reschedule evidence remains pending implementation. No Hive native scheduler or paid storage/AI resource is enabled by this plan.

Wave-1 staging publishers: publication and serving envelope

Calendar, Mail and Apps staging publishers require an exact owner-reviewed source/artifact admission and authenticated D1 consumption state. PR GitHub tokens cannot write that staging-account ledger; missing/deleted/invalid state fails closed. Seven bounded D1 queries persist/read back three transitions on a fresh success; there is one upload invocation, no application retry and no automatic admission renewal. The real-entrypoint stop-fence negative control, forged/deleted-state fixtures and SQLite conditional-update races live in scripts/ci/wave1-native-*.test.js. Staging configs disable workers.dev and preview URLs and have no public routes, including Meet’s prepared profiles. This removes public request amplification; rate limits, CPU caps and the publication flag alone would not cap serving costs. The owner must verify hosted topology before enablement. Disable publication and delete/disable only the staging Worker to stop unexpected execution, preserving consumption evidence. The publisher runbook owns provisioning, HMAC/token rotation, finite counts and the stop procedure. Hosted credential scope, private runtime acceptance and actual serving state remain separate release evidence. Production publication stays held for all four apps.

Turbo remote cache: R2 operation envelope

apps/turbo-cache ships with TURBO_CACHE_MODE=off, which performs no R2 or DO operations on artifact paths. budget-v2 in the global Durable Object is the authoritative fence/counters. Every reservation and admin mutation uses a storage transaction, committed before allowance. Missing/corrupt/unavailable state fails closed. Denials and repeated unchanged admin actions do not write; unknown reservation outcomes are denied without retry or refund. Native DO storage/output gates preserve charges and fences across restart. There are zero R2 control writes, including initialization, admin actions and bursts. _control/budget-v1 is read only on explicit first initialization to import prior usage; it is never an admission source or live checkpoint. Delayed legacy writes cannot overwrite migrated DO state. Disable/drain the old revision and reconcile unresolved writes before import. No periodic job, alarm or retry loop exists; each request has at most one admission transaction. The maximum batch is 50 hashes × four scopes (200 HEADs). Including DO and rate-limit calls, its conservative operation count is 202 under the configured 208 ceiling. apps/turbo-cache/src/stop-regression.test.ts and budget-integrity.test.ts cover counts, failed/unknown transactions, concurrent reservations, delayed legacy completion after stop and restart, a 600-request burst with simulated control-write 429s, migration and coalesced admin actions. The workerd script verifies actual transactional initialization and fence/restart. Exact-commit build/runtime CI remains required. DO requests/storage and denied or status ingress remain traffic-dependent costs outside R2 admission counters; there is no fixed total-spend guarantee. Set mode off to stop artifact storage/DO calls or disable the Worker route to stop invocations. The runbook owns migration, pricing review and stop.

Incident evidence

Correlate scoped failing requests with authenticated Worker tail exceptions and the deployed revision. A hung-request cancellation establishes a runtime failure; nearby framework warnings are clues, not root-cause proof. Offline artifact replay can isolate middleware/server boundaries, but missing modules or post-build config patches do not establish a valid replacement release. Keep raw logs private. Build success alone does not establish request health. Follow active runtime ownership and the delivery runbook. Release builds remain in CI; a migration direction does not authorize production cutover.

Upstream references