2026-05-02 — Reconcile wrangler.toml to Workers SOP §02

2026-05-02 — Reconcile wrangler.toml to Workers SOP §02

Status

Accepted

Context

wrangler.toml was scaffolded during the initial Phase 4 build with the dev environment isolated under [env.dev] and a bare top-level block (name only, no bindings). Adventive Workers SOP §02 requires the top-level block to be the dev environment — bindings, vars, and routes declared at the top, not under an explicit [env.dev] block.

A review of the file against SOP §02 found five deviations (D1–D5):

ID	Deviation	SOP §02 requirement
D1	Top-level name = "adv-svc-public-api" — missing -dev suffix	Top-level name must be the dev Worker name per §01 naming convention
D2	All dev bindings/vars/routes lived under [env.dev]	Top-level = dev defaults; no [env.dev] block
D3	workers_dev = true in dev block	workers_dev = false for anything customer-facing; *.workers.dev bypasses WAF
D4	account_id hardcoded in file	Rely on CLOUDFLARE_ACCOUNT_ID env var; do not commit account IDs unnecessarily
D5	[env.stg] / [env.prd] blocks lacked workers_dev = false and routes; env block keys were stg/prd instead of staging/production	SOP §01 note: Wrangler env block keys use full words (staging, production); deployed Worker names still end in -stg/-prd via the name override

An additional gap from SOP §02 was found during sweep:

ID	Gap	SOP §02 requirement
D7	No [observability] block	Required for every Worker — needed for production incident debugging

Decision

1. Rename [env.dev] → top-level. All dev bindings, vars, and routes moved up. Delete [env.dev] block.
2. Set name = "adv-svc-public-api-dev" at top-level.
3. Set workers_dev = false at top-level (and add it to [env.staging] and [env.production]).
4. Remove account_id line.
5. Rename env blocks to [env.staging] / [env.production]. Add workers_dev = false and routes to both. Zone IDs for adventivestg.com and adventive.com are not yet recorded; zone_name is used (avoids needing the zone ID, resolves at deploy time).
6. Add [observability] enabled = true, head_sampling_rate = 1.
7. Add size/performance limit comment block in file header (SOP §02 §“Size and performance limits”).

Test infrastructure side-effect

Promoting Hyperdrive and service bindings to top-level caused vitest-pool-workers (which reads wrangler.toml without --env) to see those bindings and fail miniflare init. All tests mock at the Hono / class layer and need no actual binding resolution. Fix: introduce wrangler.test.toml (bare-minimum config, no infra bindings) and point vitest.config.ts at it. This matches the pre-change behavior where the test config had no bindings at top-level.

Consequences

• Deploy commands change: wrangler deploy (dev), wrangler deploy --env staging, wrangler deploy --env production.
• The legacy adv-svc-public-api Worker (created before this rename) is now an orphan in Cloudflare. It should be deleted from the dashboard after confirming adv-svc-public-api-dev is live and healthy.
• No business logic, binding names, Hyperdrive IDs, or compatibility_date changed.
• npm run test gate passes (94/94).
• All three wrangler deploy --dry-run gates pass.