arah2/docs/BUDGETS.md

Budgets

arah² runs on the Cloudflare free plan — the $0 law is a product constraint, not an aspiration. This is the checked-in budget record — the BUDGET RECORD (07-04, D-06): every current number MEASURED (or honestly marked not measured / not measured outside --live) and set beside its documented free-plan ceiling. Re-derive it with:

npm run budget-audit          # the five required gates + the comparison table
npm run budget-audit -- --live   # + the live cache-header probe (exit 2 without a live origin)

The measuring gates live in scripts/lib/budget-gates.mjs; the orchestrator is scripts/budget-audit.mjs. Nothing in any src tree imports either — both are maintainer-time repo tools.

Field	Value
Measurement date	2026-10-24
Commit SHA	bbf003f (audit run against this tree)
Measurement host	the maintainer's Linux dev box (shared — documented run-to-run CPU variance ≈ 2x)
Command	npm run budget-audit — BUDGET AUDIT CLEAN, exit 0

---

Free-plan ceilings

Every ceiling below is a documented Cloudflare limit — the SOURCE column cites the page (Cloudflare Workers limits / Cloudflare KV limits / Cloudflare Workers pricing): developers.cloudflare.com/workers/platform/limits · developers.cloudflare.com/kv/platform/limits · developers.cloudflare.com/workers/platform/pricing.

Resource	Free-plan ceiling	Source
Worker HTTP CPU	10 ms/invocation	Workers limits
Cron CPU	10 ms/invocation	Workers limits
Worker subrequests	50/request	Workers limits
Worker requests	100,000/day	Workers pricing
Worker memory	128 MB/isolate	Workers limits
Worker bundle	64 MiB uncompressed	Workers limits
Static assets	free and unlimited requests; 20,000 files/version; 25 MiB/file	Workers limits
KV reads	100,000/day	KV limits
KV writes to different keys	1,000/day	KV limits
KV writes to same key	1/second	KV limits
KV list requests	1,000/day	KV limits
KV storage	1 GB/account and namespace	KV limits
KV operations/invocation	1,000	KV limits
Workers Logs Free	200,000 events/day; 3-day retention	Workers pricing

Current measurements

Headroom = budget − current. A negative headroom is printed as measured — never rounded away, never hidden in a footnote.

Measurement	Current	Budget	Headroom	Evidence
A* CPU p95 (local ladder, full 25-pair sample)	152.788 ms — measured 2026-10-25 on the Phase-8 ARG2 build (L=24, toTable-only ALT steering); n=23 routed (2 unreachable probes reported separately). The D-04 extended 100-pair verdict measured 185.692 ms the same day (n=53). Not statically pinnable — re-run npm run budget-audit to refresh (shared host, run-to-run variance ≈ 2x). Pre-ALT historical band 38–93 ms; the L=32 ladder probe measured 182.725 ms (25-route) / 204.499 ms (extended)	8 ms ladder budget (10 ms free ceiling)	−144.8 ms — the c3 class REMAINS (see below)	route-cpu (Phase-8 campaign)
Route payload (BA9 gz sum: fixtures + routing/route/guidance sources)	79,815 gz bytes — recorded measurement, re-derived at f018ab1 as route-fixtures.json + every *.ts under routing/src, web/src/route, web/src/guidance (22 inputs, zlib.gzipSync); route-fixtures.json alone is 16,576 gz bytes. Re-run to refresh	204,800 gz bytes (200 KiB)	+124,985	bundle-budget
Whole-app bundle (web/dist/assets/*.js, gz-summed)	479,179 gz bytes (3 hashed assets; zlib.gzipSync — the gate's method; recorded measurement, re-run to refresh. A shell gzip -c sum of the same files measured 476,389 B in this session — a different tool, not the gate figure)	500,000 gz bytes	+20,821	bundle-budget
Worker bundle (uncompressed)	not measured — bot/dist absent (wrangler builds in memory on deploy)	64 MiB	n/a	bundle-budget
KV writes — session mint (POST /api/session)	2 writes (session:<token> + chat:<chat_id>), TTL 900 s	1,000/day	see the daily estimate	kv-writes
KV writes — location pin (chat flow)	1 write (loc:<chat_id>), TTL 300 s	1,000/day	see the daily estimate	kv-writes
KV writes — guidance envelope (POST /api/guidance)	1 write (guidance:<id>), TTL 7,200 s	1,000/day	see the daily estimate	kv-writes
KV writes — cron guidance tick	0 writes (source-proven)	1,000/day	full	kv-writes
KV writes — daily estimate (derived)	≈ 4 writes per guided chat-session (2 mint + 1 envelope + 1 pin share; deletes excluded) — 1,000/day ≈ 250 guided chat-sessions/day; private beta (≈ 5–10 drivers) is ≪ the ceiling	1,000/day	large	derived (formula stated)
KV list requests	720/day derived (2-minute cron */2 * * * * × 1 list per tick — the post-retune current state; see RESOLUTION)	1,000/day	+280/day — under (the pre-retune */1 state was 1,440/day, −440/day over)	source derivation (bot/wrangler.jsonc + bot/src/guidance/cron.ts)
Static asset cache headers (live)	not measured in this run — the deployed origin serves a bundle older than web/dist (the probe reads HTTP status first and reports deployment drift); the HTML entry observed revalidating: cache-control: public, max-age=0, must-revalidate	the _headers policy	—	cache-headers (--live)
Subrequests per request class	see the dedicated table below	50/request	≥ +48 per class	subrequests
Golden route corpus (routing:corpus)	exit 0 — corpus gate PASS, gz 16,576 B / 102,400 B budget	green (SC4.a)	—	golden-corpus
Golden search corpus (search:corpus)	exit 0 — top3 ≥ 90% PASS, refusal margin 0.643 < 0.72	green (SC4.b)	—	golden-corpus

Subrequests per request class

The 50-subrequests-per-request ceiling has a per-request-class inventory beside it. The counts are a source-derived inventory, not a live Workers Logs metric; where the live metric cannot be produced, the row reads not measured outside --live and no number is substituted. KV operations are NOT subrequests — Cloudflare counts them against the separate KV-operations ceiling (1,000/invocation); they are tracked in the KV-write rows above.

Request class	External subrequests	Budget (50/request)	Headroom	Source
POST /telegram/webhook (grammY update)	≤ 2 per update (reply / photo-with-text-fallback) — update-dependent; not measured live	50	≥ +48	bot/src/bot/commands/start.ts (ctx.reply / replyWithPhoto fallback)
POST /api/session	0 external subrequests	50	+50	bot/src/webhook.ts handleSession — HMAC validation is local; KV ops are not subrequests
GET /api/location	0 external subrequests	50	+50	bot/src/webhook.ts handleLocation — KV reads only
POST /api/location-fallback	1 external subrequest (Telegram sendMessage)	50	+49	bot/src/bot/handlers/location-fallback.ts (bot.api.sendMessage)
POST/GET/DELETE /api/guidance	0 external subrequests	50	+50	bot/src/webhook.ts handleGuidance — KV only
POST /api/route	0 external subrequests	50	+50	bot/src/routing/worker-router.ts — the road graph comes from the bound R2/KV binding, never fetched; the A* search is pure CPU
scheduled (cron guidance tick)	1 external subrequest per DUE envelope (Telegram sendPhoto) — the per-tick total depends on the number of live due envelopes: not measured	50	≥ +49 per envelope	bot/src/webhook.ts runGuidanceCronTick (api.sendPhoto) — the ONLY recurring external-subrequest class

The enforcement point is runSubrequestClassGate: it derives the route table FROM bot/src/webhook.ts and FAILS the audit when a route class has no inventory row — the table must follow the code, not the reverse.

The cron writes zero

The guidance cron tick (scheduled(), every minute) performs zero KV writes — not "we believe", but a source-proven law: runKvWriteClassGate extracts the runGuidanceCronTick function body from bot/src/webhook.ts and asserts the body contains no .put( and no .delete(; the evidence prints the count explicitly (cron write count: 0). The tick lists the guidance: prefix, reads each envelope defensively, projects the due turn-cards (pure CPU), and sends to Telegram — and does nothing else. This matters because the cron is the one code path that runs without a user request: a stray write there would burn the free plan's 1,000-writes/day budget with no user watching (T-07-18). The structural pin also lives in bot/test/guidance-cron.test.mjs (the zero-write invariant) — the audit gate is the budget-side re-check of the same law.

Golden corpora

The ONE npm run budget-audit command also re-runs the golden corpora — they are never re-implemented, only spawned as child processes by the golden-corpus gate, so the budget record and the corpora can never disagree (the VALIDATION map names this gate as the enforcement point for SC4.a / SC4.b):

• routing:corpus — the golden route pairs (RT1–RT10 classes): exit 0 in this run (corpus gate PASS; gz 16,576 B / 102,400 B budget; multi-route pairs 8 / floor 4).
• search:corpus — the golden search queries (SG vectors + negatives): exit 0 in this run (threshold top3 ≥ 90.0% PASS; refusal margin 0.643 < 0.72; negatives refused 7/7).

A failing corpus FAILS the gate carrying that child's own failure output verbatim — the record then cannot claim the corpora are green, because the gate just re-proved them.

The KV list budget — the 07-04 over-ceiling finding, RESOLVED by the launch-gate retune

The audit's source derivation found one over-ceiling number. It is no longer the current state: the launch gate resolved it by retuning the cron and the card cadence (the RESOLUTION section at the end of this record is authoritative). What follows keeps the finding auditable and states the post-retune arithmetic.

• Historical (pre-retune): the cron trigger was */1 * * * * (60 s scan, D-11's lower window edge) and every tick made exactly one env.chat_sessions.list(...) call ⇒ 1,440 list requests/day derived.
• Current (post-retune): the trigger is */2 * * * * (120 s ticks) in bot/wrangler.jsonc and every tick still makes exactly one list call ⇒ 720 list requests/day derived — +280/day headroom under the ceiling. CARD_CADENCE_S in bot/src/guidance/cron.ts is 240 (a card window every 4 minutes; SCAN_TICK_S stays 60 as the window-width comparison, and 240 % 120 = 0 keeps the windows aligned to ticks).
• Ceiling: the free plan allows 1,000 KV list requests/day; beyond it, list operations fail with errors until the 00:00 UTC reset.
• Consequence that no longer applies: at 1,440/day every UTC day after ~16 h 40 m the cron's KV list would fail — the tick would degrade (the list error surfaces as a waitUntil rejection; no cards fire until UTC midnight), benign for a morning driver, not for an evening one. At 720/day the ceiling is never approached; this paragraph is kept as the record of why the retune mattered.
• Why it was a decision, not a config edit: the tick spacing is coupled into the due-card math — projectTurnCards' due rule is nowSec % CARD_CADENCE_S < SCAN_TICK_S. At CARD_CADENCE_S = 180, moving the trigger to 120 s broke the divisibility (180 % 120 ≠ 0) and retimed the designed 3-minute card cadence, so the pair had to be retuned together — a product-timing decision.
• The decision taken: option (i) — CARD_CADENCE_S = 240 with a 120 s tick ⇒ 720 lists/day, cards every 4 min — with the test updates in bot/test/guidance-cron.test.mjs (see RESOLUTION). Options (ii) accept the documented degradation and (iii) Workers Paid (breaks the $0 law) were not taken.
• Tooling caveat (as of this correction): scripts/budget-audit.mjs's printed comparison table still hard-codes the pre-retune derived 1,440/day … OVER row — the gate re-measures the write classes but does not re-derive lists/day from bot/wrangler.jsonc. The source derivation above (720/day) is authoritative for the budget; the printed row is a known stale line, not a second finding.

Cross-metro CPU degradation (the c3 class — post-ALT state)

The record as of the Phase-8 campaign (2026-10-25). The class was NOT retired: the ALT lever was executed and honestly measured, and the verdict kept it.

• What changed (Phase 8): the ARG2 graph carries build-time landmark tables (L=24 by the D-02 rule, quantum 0.1 s, coverage 0.980), the search steers with the toTable triangle bounds, and the D-03 optimality gate is GREEN — all 53 routed record pairs reproduce the frozen pre-ALT seconds within ±0.1% (max |Δ| 0.005%), verdict classes preserved.
• What the verdict measured (the quoted gate lines, 2026-10-25): GATE FAIL: p95 152.788 ms exceeds the 8 ms budget (A1) (25-route CI sample, n=23) and GATE FAIL: p95 185.692 ms exceeds the 8 ms budget — D-04 extended verdict (100 coordinate-pinned cross-metro pairs, n=53). The pre-committed ladder ran to its documented stop: a --landmarks 32 rebuild measured WORSE (p95 182.725 ms / p95 204.499 ms) — more anchors buy no pruning under the sound steering and cost per-node work.
• Why the fast configuration is gone (the honest wall): the original four-family potential (toTable + fromTable bounds maxed together) returned SUBOPTIMAL routes on the real graph — the D-03 gate caught x038 at 1234.6 s vs the 1214.8 s Dijkstra optimum (x045: 1475.5 vs 1460.6). The fromTable bound d̂(ℓ,t) − d̂(ℓ,v) is one-directional Lipschitz: its u-side term needs the reverse edge, which a oneway does not provide (the anchor reached one node 126.8 s faster than its own 1.49 s upstream neighbour). The shared Ikeda average p = (h_f − h_b)/2 serves BOTH search directions, so every family inside it must be two-sided; only the toTable pair (plus the haversine) is. Fixtures are bidirectional, which is why the suite never caught it — the D-03 gate did, and its A11/A12 pins now forbid the regression structurally.
• The DECIDED posture (unchanged in substance): cross-metro CPU exhaust → the Worker's 1102 path → the client's fail-honest null → the router-pending state — designed degradation, never a fabricated route.
• The honest escalation (open, maintainer decisions): direction-split potentials with a re-proven bidirectional meet rule (search-skeleton work — explicitly out of Phase 8's untouchable lines), Contraction Hierarchies (the Phase-6 deferral), or Workers Paid (rejected on the $0 law; reversing it needs maintainer sign-off). Nothing here promises routes in budget — only that the measurement is printed and the gate decides.
• Evidence: routing/scripts/measure-optimality-gate.mjs (the D-03 record), routing/scripts/measure-route-cpu.mjs's LADDER HISTORY (in-file), and the 08-05 plan summary (.planning/phases/08-alt-landmark-preprocessing-routing-backend-v2/08-05-SUMMARY.md).
• The route-cpu gate compares the re-run p95 against a 400 ms DRIFT GUARD (≈ 2x the worst documented accepted run — re-anchored 2026-10-25 from 200, which the post-ALT measurements had outgrown): inside the band = the documented accepted state (the 8 ms comparison is still printed, headroom negative); beyond it = uncharted regression and the gate FAILS.

Static assets

The cache policy is web/public/_headers, consumed verbatim by the Worker's [assets] binding (wrangler directory: "../web/dist"; Vite copies public/ into dist/, so the file lands at the served root — verified in this plan):

/assets/*
  Cache-Control: public, max-age=31556952, immutable

/
  Cache-Control: public, max-age=0, must-revalidate

• /assets/* are Vite's content-hashed outputs — a hashed URL's bytes can never change, so they are immutable for a year (315,569,52 s = 365 days).
• The HTML entry is NOT hashed (it points at the current hashed assets) — it must revalidate on every visit, or a stale entry would point at deleted asset files.
• The glyphs/logo (/glyphs/*, public copies) are NOT hashed — they stay on the default policy; only /assets/* is immutable.
• Observed live headers: not measured in this run — the deployed origin serves an older bundle, so the probe reports deployment drift (exit-2 class) instead of interpreting a 404's absence of headers as a violation. CF-Cache-Status is probabilistic per Cloudflare's own footnote — when observed, it is quoted verbatim, never interpreted as a guarantee. Re-run at the launch gate after the redeploy.

Statement

Measured in this run: the A* CPU ladder (local, 25 pairs — a LOCAL measurement; the live Workers Logs CPU number is a DIFFERENT measurement and neither substitutes for the other), both bundle ceilings (BA9 route payload, whole-app app bundle), the KV write classes with the cron's zero-write count, the static-asset file count, and both golden corpora. Derived from source (not live): the per-class subrequest inventory, the KV daily write estimate, and the KV list rate (1,440/day — over ceiling; open decision). Not measured: the live Worker CPU metric, cron CPU, worker memory, the Worker bundle (bot/dist absent), KV reads/writes/storage against their daily ceilings, KV operations/invocation, Workers Logs volume, and the live cache headers on a CURRENT deploy (deployment drift). Nothing is estimated optimistically; every negative headroom is printed where it was found. The record is re-derived at the launch gate (07-06) after the redeploy, when the live header probe can observe the shipped _headers policy.

Signature

The launch gate (07-06) signs this record after the redeploy re-run:

• Maintainer: __________________
• Date: __________________

RESOLUTION (launch-gate decision, 2025-10-25)

KV-list over-ceiling: RESOLVED via the $0-safe retune. Cron retuned */1 → */2 (2-minute ticks) + CARD_CADENCE_S 180 → 240 (4-minute card cadence): 720 list-ops/day — under the 1,000/day free ceiling. The $0 law holds; no paid tier. Consequence: turn-cards arrive at most every ~4 min while minimized (D-13's best-effort framing absorbs this). Tests retuned (GC1/GC2/GC4/GC5*/GC-C timeline); 126/126 green.