Codex Rules for Cloudflare Workers

# Cloudflare Workers Rules

## Runtime constraints — READ FIRST
- This project runs on the Cloudflare Workers runtime (V8 isolate), NOT Node.js.
  Node.js built-ins (`fs`, `path`, `crypto` from `node:crypto` pre-Workers-crypto,
  `child_process`, `net`, `dgram`) are NOT available unless explicitly listed as
  available in the wrangler compatibility flags.
- Allowed globals: `fetch`, `Request`, `Response`, `Headers`, `URL`, `URLSearchParams`,
  `ReadableStream`, `WritableStream`, `TransformStream`, `TextEncoder`, `TextDecoder`,
  `crypto` (Web Crypto API), `caches` (Cache API), `setTimeout`, `clearTimeout`.
- Do NOT use `process.env`. Environment variables and secrets are accessed via the
  `Env` bindings object passed to the `fetch` handler as the second argument.
- Do NOT import `node:*` modules unless `nodejs_compat` is set in `wrangler.toml`
  and you have confirmed the specific module is available in that compat mode.

## Bindings pattern
- All KV, R2, D1, Durable Object, Queue, and AI bindings are declared in
  `wrangler.toml` and typed in `src/types/env.d.ts` (or `worker-configuration.d.ts`).
- Access bindings only through the `env` parameter of the `ExportedHandler` fetch
  method: `export default { async fetch(req, env, ctx) { ... } }`.
- Never instantiate KV or R2 clients manually — use the env binding directly.
- Run `wrangler types` after adding a new binding to regenerate the TypeScript types.

## Request/Response handling
- Always return a `Response` object from the `fetch` handler. Never `throw` outside
  a try/catch at the handler boundary — unhandled errors surface as opaque 500s.
- Use `ctx.waitUntil()` for fire-and-forget async work (logging, analytics writes)
  so the isolate is not terminated before the side effect completes.
- Stream large responses with `ReadableStream` rather than buffering them entirely
  in memory — Workers have a 128 MB memory limit per isolate.

## Build and deploy
- Use `wrangler dev` for local development (not `node server.js` or any other runner).
- Test with `wrangler dev --remote` before deploying to catch binding resolution
  issues that only appear against real Cloudflare infrastructure.
- Deploy with `wrangler deploy`. Never edit the production worker via the Cloudflare
  dashboard directly — it diverges from the codebase.
- Bundle size must stay under 1 MB (compressed). Run `wrangler deploy --dry-run`
  and check the reported bundle size before merging large dependency additions.

## TypeScript conventions
- Strict mode enabled. No `any`. Use `unknown` for untrusted external data and
  narrow it with Zod or manual type guards before use.
- The `Env` interface must be in sync with `wrangler.toml`. If you add a binding
  in `wrangler.toml`, add the corresponding property to `Env` in the same PR.
- Use `satisfies ExportedHandler<Env>` on the default export to catch binding
  type mismatches at compile time.

## Definition of done
- `wrangler check` (or `tsc --noEmit`) passes with zero errors.
- `wrangler dev` starts without warnings.
- `wrangler deploy --dry-run` reports bundle size under 1 MB.
- No `process.env` references in source. No `node:*` imports unless compat flag is set.