# arah² — Architecture ## System Overview arah² is a Telegram-first GPS navigator: a grammY bot (`arah2bot`) running as a single Cloudflare Worker serves both the Telegram webhook **and** the static Mini App bundle served from the same origin. The Mini App (`@araharah/web`, a Vite + MapLibre GL application) authenticates with the Worker by posting its verbatim `Telegram.WebApp.initData` to `POST /api/session`, receives a short-lived opaque bearer token, and then acquires a position through a three-link chain (Telegram `LocationManager` → WebView `navigator.geolocation` → chat-relayed pin). Searching a destination and routing to it are real today: `@araharah/search` is the in-Worker gazetteer (search backend #1 of the D-01 ladder), and `@araharah/routing` is the routing data plane — its CSR road-graph codec, snapper, and A\* power **engine A**, the Worker-side router (`bot/src/routing/worker-router.ts`) that routes over a ROAD_GRAPH R2-hosted KL road-graph binary through `POST /api/route`. Guidance is end-to-end: a turn-card cron (the repo's first Cron Trigger, `*/2 * * * *`) pushes turn-cards into the chat from a TTL-only guidance envelope, statelessly. All durable state is TTL-only — one Cloudflare KV namespace (`chat_sessions`, plus `guidance:*` envelopes in it) — so the system has no database, no persistent storage, and no analytics. `@araharah/theme` is the shared design-token package: it compiles Tailwind v4 CSS consumed by the web app and is the derivation source for the Rams basemap style the map renders. Architecturally this is a **five-workspace npm monorepo in a layered/hexagonal arrangement**: a stateless edge worker with a KV repository layer and an embedded search index plus A\* router, a framework-free TypeScript client with its own repository, adapter, route, and guidance layers, and two pure V8-native data-plane packages (search, routing) that both the worker and the client import — and a pure build-time token/cartography package underneath. ```mermaid graph TD classDef client fill:#EB8008,stroke:#8A4C00,stroke-width:2px,color:#1A1A1A classDef worker fill:#D9D2C6,stroke:#736B1E,stroke-width:2px,color:#1A1A1A classDef store fill:#ED3F1C,stroke:#8C1F0A,stroke-width:2px,color:#FFFFFF classDef build fill:#1A1A1A,stroke:#000000,stroke-width:2px,color:#FFF8F0 classDef plane fill:#736B1E,stroke:#4A440F,stroke-width:2px,color:#FFF8F0 A["Telegram client
chat + Mini App webview"]:::client B["@araharah/bot Worker
src/webhook.ts"]:::worker C["grammY handlers
commands + /cari + fallbacks"]:::worker D["Security
initdata.ts HMAC"]:::worker E[("KV chat_sessions
session:* 900s · chat:*
loc:* 300s · guidance:* 7200s")]:::store R[("R2 ROAD_GRAPH
kl-roadgraph.v1.bin")]:::store Q["scheduled()
*/2 turn-card cron"]:::worker F["@araharah/web Mini App
src/main.ts"]:::client G["Session client + store
src/session/"]:::client H["Location chain
src/location/"]:::client I["MapLibre map + UI
src/map/, src/ui/"]:::client RT["Route controller + guidance
src/route/, src/guidance/"]:::client S["@araharah/search
gazetteer SearchSource"]:::plane U["@araharah/routing
graph · snap · A*"]:::plane J["@araharah/theme
dist/rams.css + basemap"]:::build A -->|"POST /telegram/webhook"| B A -->|"loads Mini App"| B B --> C B --> D B --> E B --> R Q --> E Q --> R C --> E C --> S C -->|"sendPhoto turn-cards"| A F -->|"POST /api/session initData"| B F -->|"GET /api/location Bearer"| B F -->|"POST /api/location-fallback"| B F -->|"POST /api/route Bearer"| B F -->|"POST|GET|DELETE /api/guidance"| B F -->|"build-time imports"| S F -->|"build-time imports"| U G --> F H --> G F --> H H --> I RT -->|"reroute"| B J -->|"compiled CSS + inlined style JSON"| F ``` ## Component Diagram ```mermaid graph LR classDef ws fill:#EB8008,stroke:#8A4C00,stroke-width:2px,color:#1A1A1A classDef wsfill fill:#FFF8F0,stroke:#EB8008,stroke-width:2px,color:#1A1A1A classDef botfill fill:#F5EDE0,stroke:#736B1E,stroke-width:2px,color:#1A1A1A classDef plane fill:#736B1E,stroke:#4A440F,stroke-width:2px,color:#FFF8F0 classDef store fill:#ED3F1C,stroke:#8C1F0A,stroke-width:2px,color:#FFFFFF classDef ext fill:#E0D9CD,stroke:#564335,stroke-width:2px,color:#1A1A1A subgraph ROOT["root — npm workspaces"] direction TB subgraph THEME["theme · @araharah/theme"] direction TB T1["src/tokens.css
@theme static, 55 colors"]:::wsfill T2["src/components.css"]:::wsfill T3["basemap/build.mjs"]:::wsfill T4["dist/rams.css"]:::wsfill T5["basemap/liberty-rams.json"]:::wsfill T1 --> T4 T2 --> T4 T1 -->|"derives roles"| T3 T3 --> T5 end subgraph WEB["web · @araharah/web"] direction TB W1["src/main.ts"]:::wsfill W2["src/session/"]:::wsfill W3["src/location/"]:::wsfill W4["src/map/"]:::wsfill W5["src/ui/ + src/telegram/"]:::wsfill W6["src/search/ + src/route/
+ src/guidance/"]:::wsfill W7["dist/ (served)"]:::wsfill W1 --> W2 W1 --> W3 W1 --> W4 W1 --> W5 W1 --> W6 W1 --> W7 W4 --> W7 W5 --> W7 W6 --> W7 end subgraph BOT["bot · @araharah/bot"] direction TB B1["src/webhook.ts"]:::botfill B2["src/security/initdata.ts"]:::botfill B3["src/bot/ + src/guidance/cron.ts"]:::botfill B4["src/kv/"]:::botfill B5["src/routing/worker-router.ts"]:::botfill B6["src/config.ts Env"]:::botfill B1 --> B2 B1 --> B3 B1 --> B4 B1 --> B5 B1 --> B6 end subgraph SEARCH["search · @araharah/search"] direction TB S1["src/gazetteer.ts
lazy memoized index"]:::plane S2["src/source.ts
SearchSource #1"]:::plane S3["src/score.ts + normalize.ts"]:::plane S1 --> S2 S3 --> S2 end subgraph ROUTING["routing · @araharah/routing"] direction TB R1["src/graph.ts
CSR codec"]:::plane R2["src/snap.ts + astar.ts"]:::plane R3["src/fixture-source.ts
#1 · http-source.ts
engine-A client seam"]:::plane R1 --> R2 R1 --> R3 R2 --> R3 end KV[("KV chat_sessions")]:::store R2B[("R2 ROAD_GRAPH
araharah-graphs")]:::store CRON["Cron Trigger
*/2 * * * *"]:::ext TG["Telegram Bot API"]:::ext OFM["OpenFreeMap tiles"]:::ext end WEB -->|"workspace deps @araharah/{theme,search,routing}"| THEME WEB --> SEARCH WEB --> ROUTING BOT -->|"deps @araharah/{search,routing}"| SEARCH BOT --> ROUTING BOT -->|"assets binding ../web/dist"| WEB B1 --> KV B4 --> KV B5 --> R2B B3 --> KV CRON --> B1 B1 <-->|"webhookCallback / sendMessage"| TG W3 <-->|"chat pin"| TG W4 --> OFM ``` ## Workspaces Dependency Graph ```mermaid graph TD classDef pkg fill:#EB8008,stroke:#8A4C00,stroke-width:2px,color:#1A1A1A classDef dep fill:#736B1E,stroke:#4A440F,stroke-width:2px,color:#FFF8F0 classDef out fill:#D9D2C6,stroke:#736B1E,stroke-width:2px,color:#1A1A1A ROOT["araharah (private root)"]:::out TH["@araharah/theme"]:::pkg SE["@araharah/search"]:::pkg RO["@araharah/routing"]:::pkg BT["@araharah/bot"]:::pkg WB["@araharah/web"]:::pkg KVS[("KV chat_sessions")]:::dep R2S[("R2 ROAD_GRAPH")]:::dep TGAPI["Telegram Bot API"]:::dep ROOT -->|"workspaces"| TH ROOT -->|"workspaces"| SE ROOT -->|"workspaces"| RO ROOT -->|"workspaces"| BT ROOT -->|"workspaces"| WB WB -->|"dependencies: @araharah/theme *"| TH WB -->|"dependencies: @araharah/search *"| SE WB -->|"dependencies: @araharah/routing *"| RO BT -->|"dependencies: @araharah/search *"| SE BT -->|"dependencies: @araharah/routing *"| RO BT -->|"static assets ../web/dist"| WB BT --> KVS BT --> R2S BT --> TGAPI WB -->|"api routes"| BT ``` `@araharah/search` and `@araharah/routing` are the shared V8-native data planes: the **bot Worker** imports them at runtime (gazetteer search, graph decode, snap, A\*), the **web app** imports the same sources at build time (destination resolution, the `RoutingSource` ladder, polyline decoding). Neither data plane reads the environment, the network, or storage. `@araharah/theme` stays web-only (`"@araharah/theme": "*"` in `web/package.json` — `dist/rams.css` in `web/src/shell.css`, `basemap/liberty-rams.json` in `web/src/map/map.ts`). The bot has no workspace dependency on theme or web; its coupling to web is a **build-order coupling only** — the root `build` script builds theme then web, and the Worker's `[assets]` binding points at `../web/dist`. Both data-plane packages have **no `exports`/`main` field** — consumers import the explicit subpath with extension, e.g. `@araharah/search/src/index.ts` and `@araharah/routing/src/index.ts`. A bare package specifier resolves to nothing. ## Data Flow ### 1. Telegram command surface (bot → chat) Telegram delivers an update to `POST /telegram/webhook`. The Worker first fails closed if `WEBHOOK_SECRET` is unset, then hands the request to grammY's `webhookCallback(bot, "cloudflare-mod", …)`, which constant-time-compares the `X-Telegram-Bot-Api-Secret-Token` header. `createBot(env)` is instantiated **per request** (the token only arrives with `env`), registers the command stack, and grammY dispatches: ``` POST /telegram/webhook → webhookCallback (secret check) → createBot(env) → registerStart / registerHelp / registerPrivacy → pickLocale(language_code) → ctx.reply(plain text, link_previews disabled) ``` `createBot` also builds ONE memoized gazetteer `SearchSource` (backend #1) shared between the `/cari` + `/search` command surface (`bot/src/bot/commands/cari.ts`) and the alternates switcher (`bot/src/bot/handlers/search-alternate.ts`): `/cari` renders a venue card whose OPEN button deep-links `/?dest=` (origin from the configured `MINI_APP_URL` var, never user input), and the alternates handler swaps the selected entry via a callback. The venue card's inline buttons and the location-fallback reply keyboard are the two documented exceptions to the plain-text-only command rule. All user-facing copy comes from `bot/src/i18n/strings.ts`; `bot/scripts/register-commands.mjs` derives the persistent `/setMyCommands` menu descriptions from the same `helpMenu` lines, so menu and reply cannot drift. ### 2. Mini App boot (session handshake) ```mermaid sequenceDiagram participant WA as WebApp webview participant MAIN as web/src/main.ts participant SESS as session/client.ts participant WK as Worker /api/session participant ID as security/initdata.ts participant KV as KV chat_sessions MAIN->>MAIN: applySafeArea(resolveSafeInsets(wa)) MAIN->>MAIN: bootMap() mounts MapLibre FIRST MAIN->>MAIN: register strip, cards, recenter MAIN->>SESS: createSession(wa.initData) [verbatim string] SESS->>WK: POST /api/session, body = initData (≤ 4 KB) WK->>ID: validateInitData(raw, BOT_TOKEN) ID-->>WK: ok | malformed | tampered | stale WK->>KV: mintSession(chat_sessions, claim) KV-->>WK: opaque UUID token WK-->>SESS: 200 { token } SESS->>SESS: setSession(token) [module scope only] ``` The HMAC path: `dataCheckString` = all initData fields **minus `hash` only**, sorted by field name, joined with `\n`; secret key = `HMAC-SHA256(key="WebAppData", message=botToken)`; check = `HMAC-SHA256(key=secretKey, message=dataCheckString)` compared in constant time against `hash`. `signature` participates in the check. `auth_date` older than 900 s is rejected as `stale`. ### 3. Location acquisition chain ```mermaid flowchart TD classDef s fill:#EB8008,stroke:#8A4C00,stroke-width:2px,color:#1A1A1A classDef ok fill:#F5EDE0,stroke:#736B1E,stroke-width:2px,color:#1A1A1A classDef no fill:#ED3F1C,stroke:#8C1F0A,stroke-width:2px,color:#FFFFFF START["acquireFix(deps, lastAccepted)"]:::ok L1{"telegramLocationSupported
isVersionAtLeast 8.0"}:::ok NUDGE{"looksStale(prev, fix)
haversine < 0.01 m"}:::ok L2{"webviewLocationSupported"}:::ok L3{"getToken() !== null"}:::ok LIVE["return { fix, state: live }"]:::s DEN1["denied / timeout"]:::no DEN2["denied / no-permission"]:::no START --> L1 L1 -->|"yes"| NUDGE NUDGE -->|"no"| LIVE NUDGE -->|"yes: discarded webview read"| L1 L1 -->|"no"| L2 L2 -->|"yes + fix"| LIVE L2 -->|"no fix"| L3 L3 -->|"yes: bounded 60s poll"| LIVE L3 -->|"poll expired"| DEN1 L3 -->|"no token"| DEN2 ``` Link 1 (`telegram.ts`) calls `LocationManager.init()` then `getLocation()`, with a hard 8 s wrapper timeout because the API documents no timeout. A byte-identical fix to the last accepted one routes to the nudge: one **discarded** webview read refreshes the Android native cache, then telegram is retried. Link 2 (`webview.ts`) calls `navigator.geolocation.getCurrentPosition` with `maximumAge: 0`. Link 3 (`chat-pin.ts`) polls `GET /api/location` every 2 s for at most 60 s. ### 4. Chat-pin relay (the Desktop-Telegram path) ```mermaid sequenceDiagram participant U as User (chat) participant B as Bot handler participant KV as KV loc:chat_id participant MA as Mini App participant W as Worker MA->>W: POST /api/location-fallback (Bearer token) W->>W: getClaimByToken → claim.chat_id W->>B: requestLocationFallback(bot, chat_id, locale) B->>U: reply keyboard, request_location: true U->>B: taps button, native location picker B->>KV: writePin(kv, chat_id, { lat, lng, acc }) expirationTtl 300 loop every 2 s, bounded 60 s MA->>W: GET /api/location (Bearer token) W->>KV: getPin(chat_sessions, claim.chat_id) KV-->>W: LocationPin | null W-->>MA: { pin } (200) or { pin: null } end ``` Both `/api/location` and `/api/location-fallback` derive the target `chat_id` from the **resolved session claim**, never from client input, and derive locale from `claim.language_code`. Telegram has no push channel from chat to webview, so this poll is server-mediated by necessity. ### 5. Destination deep-link (search, both carriers) The destination id is a **plain public gazetteer slug** — no crypto, no token anywhere on this path. `web/src/search/resolve-destination.ts` reads it from TWO carriers in a fixed order with ONE shared validation (`[A-Za-z0-9_-]{1,64}`, optional `dest_` wire prefix): 1. **PRIMARY — the URL query string** (`?dest=`): the `/cari` OPEN inline-button path; Telegram opens the button's URL verbatim in the webview. 2. **SECONDARY — `start_param` inside the SIGNED initData string**: the documented direct-link (`t.me/?startapp=`) and home-screen-shortcut path, treated as an untrusted exact-lookup key. The id resolves against the webview's **own build-time copy of the shared gazetteer** (`@araharah/search` inlined by Vite). A hit renders the destination card with a START-route action; a miss renders the honest "destination unavailable" card and the boot continues staged — never a blank map. The resolved entry lives in module scope (memory only); nothing persists. ### 6. Route consult (engine A over R2) ```mermaid sequenceDiagram participant MAIN as main.ts (auto-consult, once per boot) participant CTRL as route/route.ts participant HTTP as http-source.ts (backend #2 seam) participant W as Worker /api/route participant G as loadGraph (R2 ROAD_GRAPH) participant A as snapToGraph + routeAstar MAIN->>CTRL: route { origin: fix, destinationId } CTRL->>HTTP: POST endpoint (injected), bearer = memory token HTTP->>W: { origin, destinationId } (≤ 4 KB) W->>W: getClaimByToken — Bearer claim gate W->>G: R2 GET kl-roadgraph.v1.bin (ONE per cold isolate, memoized) G-->>W: RoadGraph | null W->>A: bbox-check origin → snap origin → snap destination → A* A-->>W: RouteResult | null W-->>HTTP: 200 { result } | 200 JSON null HTTP-->>CTRL: RouteResult | null (fail-honest) ``` `bot/src/routing/worker-router.ts` is engine A's whole server surface: the decoded graph memoizes per isolate (`loadGraph` — the ONLY R2 loader, shared with the cron arm), the origin is bbox-checked against `graph.bbox` before any snap/A\* work, and **every miss class answers `200 null`** — unknown destination, snap miss, unreachable pair, absent/corrupt graph — the honest router-pending state (never a 500, never a fake route). Alternatives generation is prohibited on this path: exactly one best route. The client composes the ladder at the import site — `createFixtureRoutingSource` (backend #1, the 15-pair golden corpus) followed by `createHttpRoutingSource` (engine A) — with the null contract end to end. ### 7. Guidance (mint → resume → cron push) ```mermaid sequenceDiagram participant MA as Mini App participant W as Worker /api/guidance participant KV as KV guidance:id (7200s) participant C as scheduled() every 2 min MA->>W: POST /api/guidance (Bearer) — six-field route snapshot W->>W: getClaimByToken → chat_id minted from the CLAIM (body chat_id structurally ignored) W->>KV: mintGuidanceSession — inline snapshot, expirationTtl 7200 KV-->>W: envelope (uuid id) W-->>MA: 201 { id } Note over MA: webview killed / phone locked MA->>W: GET /api/guidance?id= — resume carrier ?g= W->>KV: getGuidanceSession — foreign or absent are indistinguishable 404s KV-->>MA: envelope → straight into the live trip loop every 2 min (stateless — zero KV writes) C->>KV: list prefix guidance: → getGuidanceSession per key C->>C: projectTurnCards(envelope, nowSec, streetAt(loadGraph)) C->>MA: sendPhoto glyph + OPEN (?g=) — due cards only, cadence 240 s end ``` The envelope is the **frozen Phase 5 contract**: exactly four fields (`id`, `chat_id`, `route_snapshot`, `created_at`); the snapshot is INLINE (one key, one TTL) with six fields (`destinationId`, `destinationName`, `distanceM`, `durationS`, `geometry` polyline6, `startedAtSec`). Every write carries `expirationTtl: 7200` on the same call line — the PG1 TTL law covers this file. On the web side, `web/src/guidance/guidance.ts` is the pure reroute state machine (`idle → on_route → off_route → resuming/rerouting → arrived`, accuracy-aware threshold, 20 s storm guard) and `web/src/guidance/watch.ts` is the throttled `watchPosition` stream (guidance work runs on ≥ 10 m moved or ≥ 5 s elapsed — fixes are consumed in the caller's frame and never transmitted). ### 8. Worker routing table | Method | Path | Handler in `bot/src/webhook.ts` | Purpose | | --- | --- | --- | --- | | POST | `/telegram/webhook` | inline in `fetch()` | grammY webhook adapter + secret-token compare | | POST | `/api/session` | `handleSession` | initData → one-time opaque session token | | GET | `/api/location` | `handleLocation` | Bearer-authenticated chat-pin relay | | POST | `/api/location-fallback` | `handleLocationFallback` | Ask the bot to send the reply keyboard | | POST/GET/DELETE | `/api/guidance` | `handleGuidance` | Mint / resume / delete the 7200 s guidance envelope | | POST | `/api/route` | `handleRoute` (in `src/routing/worker-router.ts`) | Bearer-gated engine-A routing over the R2 road graph | | * | anything else | — | 404 | `run_worker_first: ["/api/*", "/telegram/*"]` guarantees the Worker's `fetch` owns these paths before the static asset fallback runs; every other path resolves to the `web/dist` bundle. The same `fetch` handler also exports `scheduled()` — the `*/2` cron that runs the turn-card push (flow 7). ## Build & Deploy Topology ```mermaid graph LR classDef step fill:#1A1A1A,stroke:#000000,stroke-width:2px,color:#FFF8F0 classDef art fill:#D9D2C6,stroke:#736B1E,stroke-width:2px,color:#1A1A1A classDef cloud fill:#EB8008,stroke:#8A4C00,stroke-width:2px,color:#1A1A1A classDef store fill:#ED3F1C,stroke:#8C1F0A,stroke-width:2px,color:#FFFFFF T1["theme: tailwindcss -i src/theme.css -o dist/rams.css --minify"]:::step T2["theme: basemap/build.mjs
fetch liberty → derive roles → liberty-rams.json"]:::step W1["web: vite build → dist/"]:::step W2["web: vite build --mode harness → dist-harness/"]:::step B1["bot: wrangler deploy"]:::step B2["bot: scripts/set-webhook.mjs"]:::step RG["routing: build-road-graph.mjs
→ kl-roadgraph.v1.bin"]:::step RU["routing: upload-road-graph.mjs
→ R2 (fork contract)"]:::step AR1["theme/dist/rams.css + fonts"]:::art AR2["web/dist (index.html, hashed assets,
inlined liberty-rams style, public/glyphs)"]:::art AR3["web/dist-harness (never deployed)"]:::art EDGE["Cloudflare Worker araharah-bot
[assets] ../web/dist + cron */2"]:::cloud KVS[("KV chat_sessions")]:::store R2B[("R2 ROAD_GRAPH")]:::store T1 --> W1 T2 --> W1 T1 --> AR1 W1 --> AR2 W2 --> AR3 AR2 --> EDGE B1 --> EDGE B1 --> B2 RG --> RU RU --> R2B EDGE --> KVS EDGE --> R2B ``` The root scripts encode the ordering: `npm run build` = `build -w theme && build -w web`; `npm run deploy` = `npm run build && npm run deploy -w bot` (which is `wrangler deploy && node scripts/set-webhook.mjs`). `bot/wrangler.jsonc` binds `assets.directory` to `../web/dist`, so `web/dist` must exist before a bot deploy. The road-graph binary is a separate provisioning track (never a build prerequisite): `routing/scripts/build-road-graph.mjs` writes `routing/data/kl-roadgraph.v1.bin` (~15 MB, a build artifact that is NOT committed) and `routing/scripts/upload-road-graph.mjs` puts it on R2 — the fork contract is `docs/ROAD-GRAPH.md`. The two web builds never share an outDir: `vite.config.ts` sets `outDir: "dist-harness"` only under `--mode harness` and defines `__ARAHARAH_HARNESS__` to `true` there and `false` everywhere else, so the mock installer and the `fetch` stubs in `web/index.html` are dead-code-eliminated from production. `web/test/build-artifact.test.mjs` (BA1–BA10) proves the shipped bundle references no third-party CDN, self-hosts the woff2 fonts, contains the inlined Rams style, and carries neither `installMockWebApp` nor `__ARAHARAH_MOCK__`. The turn-card glyphs (`web/public/glyphs/*.png`, rendered by `routing/scripts/build-glyphs.mjs`) are static assets the cron references as `${MINI_APP_URL}/glyphs/.png`. ## Key Abstractions ### `@araharah/bot` | Abstraction | File | Description | | --- | --- | --- | | `Env` | `bot/src/config.ts` | Typed contract: `BOT_TOKEN`, `WEBHOOK_SECRET` (non-empty — the webhook fails closed without it), `chat_sessions: KVNamespace`, `ROAD_GRAPH: R2Bucket` (first R2 binding), `MINI_APP_URL` (public deep-link origin). | | `createExportedHandler(opts)` | `bot/src/webhook.ts` | The `ExportedHandler` factory — six fetch routes plus `scheduled()`; 404 otherwise. Production passes nothing; offline tests inject a recording `baseFetch`. | | `validateInitData(raw, botToken, opts)` | `bot/src/security/initdata.ts` | Pure HMAC-SHA256 validation of Telegram WebApp initData. Depends only on `crypto.subtle`, so it runs unchanged in Workers and bare Node. Returns `InitDataResult`. | | `SessionClaim` / `mintSession` / `getClaimByToken` / `getTokenForChat` | `bot/src/kv/sessions.ts` | TTL-only session layer. `SESSION_TTL_SECONDS = 900`. Key scheme `session:` → claim, `chat:` → current token. Rotate-on-new with a best-effort reconciliation sweep. | | `LocationPin` / `writePin` / `getPin` / `clearPin` | `bot/src/kv/location-pin.ts` | TTL-only pin layer. `PIN_TTL_SECONDS = 300`. Key `loc:`. `getPin` range-validates on read. | | `GuidanceSessionEnvelope` / `GuidanceRouteSnapshot` / `mint/get/deleteGuidanceSession` / `GUIDANCE_KEY_PREFIX` | `bot/src/kv/guidance-sessions.ts` | The frozen four-field envelope (six-field inline snapshot), `GUIDANCE_SESSION_TTL_SECONDS = 7200`, key `guidance:`. Defensive reads (garbage → null); ids UUID-guarded before any KV touch. | | `handleRoute` / `loadGraph` | `bot/src/routing/worker-router.ts` | Engine A's server surface: Bearer claim gate, 4 KB body cap, bbox pre-check, snap → A\* over the R2-hosted graph, `200 null` for every miss. `loadGraph` is the ONLY R2 loader — one memoized GET per cold isolate, shared with the cron arm. | | `projectTurnCards` / `makeStreetAt` | `bot/src/guidance/cron.ts` | The PURE projection over the frozen snapshot — when a card is due (`nowSec % CARD_CADENCE_S < SCAN_TICK_S`), glyph + caption composition, street reconstruction from the graph. `CARD_CADENCE_S = 240`; the cron is stateless (zero KV writes). | | `createBot(env, opts)` | `bot/src/bot/bot.ts` | grammY factory; wires `/start` + `/mula`, `/help`, `/privacy` + `/privasi`, `/cari` + `/search`, the alternates switcher, and the location-fallback handler. Builds one shared gazetteer `SearchSource`. | | `registerCari(bot, source, origin)` | `bot/src/bot/commands/cari.ts` | The search command surface: venue card with OPEN deep link (`?dest=`) and alternates callbacks — the second documented exception to the text-only rule. | | `requestLocationFallback(bot, chatId, locale)` | `bot/src/bot/handlers/location-fallback.ts` | Sends the `request_location` reply keyboard. Single caller: `handleLocationFallback`. | | `strings` / `pickLocale` | `bot/src/i18n/strings.ts` | The bot's entire copy surface (`en`, `ms`). `pickLocale` maps an `ms`/`ms-*` language code to Malay, everything else to English. | | `KvLike` | `bot/src/kv/*.ts` | Structural KV interface (module-private, not exported — the derived `MintSessionKv`/`LocationPinKv`/`GuidanceSessionKv` are the public surface) — lets tests pass a fake without depending on Workers types. | ### `@araharah/search` | Abstraction | File | Description | | --- | --- | --- | | `SearchSource` | `search/src/types.ts` | The pluggable search seam: async `search(q)` + synchronous `byId(id)`. The documented ladder is backend #1 (gazetteer, shipped) with later rungs slotted at the import site — no env read, no registry. | | `createGazetteerSource()` | `search/src/source.ts` | Backend #1. The refusal contract is load-bearing: an EMPTY array means "not in the v1 area" — never a fabricated pin. Ranking is score-band DESC then entry-id ASC (deterministic tie-break). | | `search(text, limit)` | `search/src/source.ts` | The synchronous scoring path — shared by the bot, the Mini App, and the corpus runner: the measured quality IS the shipped quality. | | `getEntries` / `getEntryById` / `getIndex` | `search/src/gazetteer.ts` | The lazy, memoized index over a static JSON import (`data/kl-gazetteer.json`, ODbL notice inside). Three laws: lazy + memoized (never module-scope work), survives three environments (Worker bundle, Vite bundle, bare Node), no logging/storage. | | `scoreCandidate` / `TIER` / `FUZZY_ADMIT_SIMILARITY` | `search/src/score.ts` | Tiered admission — EXACT / ALIAS_EXACT / PREFIX / TOKEN_SET bands always admitted; FUZZY only at similarity ≥ 0.72. `normalize` (with `rules/abbreviations.ts`) canonicalizes both sides of every comparison. | | `GazetteerEntry` | `search/src/types.ts` | `id` (slug), `name`, `aliases`, coordinates, category — the entry shape every carrier (bot card, webview resolver, guidance snapshot) reduces to. | ### `@araharah/routing` | Abstraction | File | Description | | --- | --- | --- | | `RoutingSource` | `routing/src/types.ts` | The pluggable routing seam: `route(req) → RouteResult \| null`. Backend ladder: #1 `"fixture"` → #2 `"engine-a"` (LIVE, via `/api/route`) → engine B (client-side webview router, documented post-v1). Selection happens at the import site in code — no env read, no registry. | | `RouteResult` / `RouteOption` / `RouteStep` / `RouteGeometry` | `routing/src/types.ts` | Day-one contract: options 1..3 (index 0 = best), `cumulativeDistanceM` parallel to points (the guidance projection contract), polyline6 `geometry`, optional `kind` maneuver tags. Fixture-world steps are empty arrays — honest "not wired". | | `RoadGraph` / `encodeGraph` / `decodeGraph` | `routing/src/graph.ts` | The CSR road-graph binary codec (`GRAPH_MAGIC`, `GRAPH_VERSION`) — the on-disk form of `kl-roadgraph.v1.bin`. V8-native, dependency-free, no network. | | `snapToGraph` / `SnapResult` | `routing/src/snap.ts` | Snaps a raw fix onto the graph (bbox-margined); the origin of every route computation and of the cron's street reconstruction. | | `routeAstar` / `deriveSteps` / `classifyTurn` | `routing/src/astar.ts` | The A\* engine plus the maneuver classifier (`depart`/`left`/…/`arrive`) that feeds both the webview guidance machine and the cron's turn cards. | | `createFixtureRoutingSource` | `routing/src/fixture-source.ts` | Backend #1: the committed 15-pair golden KL corpus (`data/route-fixtures.json` + `test/fixtures/golden-pairs.json`). Demo-grade by design; the tolerance gate is `npm run routing:corpus`. | | `createHttpRoutingSource(options)` | `routing/src/http-source.ts` | Engine A's client seam: injected `endpoint` + `bearer` getter, defensively validates every response field, resolves null on any failure (the null contract crossing HTTP). Never holds or persists the token. | | `decodePolyline6` / `encodePolyline6` / `haversineM` / `deriveCumulativeDistanceM` | `routing/src/polyline.ts`, `routing/src/geo.ts` | The storage geometry format and the ONE distance authority — every distance in the system flows through `geo.ts`. | ### `@araharah/web` | Abstraction | File | Description | | --- | --- | --- | | `Fix` | `web/src/location/types.ts` | The single normalized position shape every source reduces to: `lat`, `lng`, `accuracyM`, `headingDeg`, `ts`, `source`. Freshness lives in the fix. | | `LocationState` | `web/src/location/types.ts` | Discriminated union: `idle` / `validating` / `acquiring` / `awaiting-pin` / `live` / `stale` / `denied`. | | `acquireFix(deps, lastAccepted)` | `web/src/location/chain.ts` | The three-link state machine. Pluggable cadence — no `setInterval`, no `watchPosition`. | | `isFixStale(fix, nowMs)` / `fixAgeSeconds` | `web/src/location/chain.ts` | The 45 s signal-lost threshold and the `FIX Ns AGO` telemetry helper. | | `readDestinationId` / `resolveDestination` / `setDestination` | `web/src/search/resolve-destination.ts` | The two-carrier deep-link resolver (`?dest=` URL, then signed initData's `start_param`), one shared slug validation, memory-only result, honest-null on miss. | | `buildDestinationCard` / `buildDestinationUnavailableCard` | `web/src/search/destination-card.ts` | The search surface's Rams cards (destination confirmed / honest unavailable). | | `createRouteController` | `web/src/route/route.ts` | The consult/select/walk-back state machine and the guidance pump: auto-consults once per boot, draws the selected line (`setData` on the `route` source), starts the guidance watch, delegates every guidance decision. Touches no DOM/map directly — everything injected. | | `installRouteLayers(m)` | `web/src/route/route-layers.ts` | Installs the `route` / `route-alt` map sources inside map.ts's ONE load handler; a drawn route is static furniture (only selection changes it). | | `createGuidanceSession` / `stepGuidance` | `web/src/guidance/guidance.ts` | The pure reroute state machine: `idle → on_route → off_route → resuming/rerouting`, accuracy-aware threshold (`max(35, 2×accuracy)` capped 100), 3-fix + 8 s grace, 20 s storm guard. A pure reducer — replay-verifiable in Node. | | `createGuidanceWatch(geo, onFix)` | `web/src/guidance/watch.ts` | The gated position stream: `watchPosition` high-accuracy, throttled to ≥ 10 m moved or ≥ 5 s elapsed. Fixes are consumed in the caller's frame — never stored, logged, or transmitted. | | `TelegramWebAppLike` | `web/src/telegram/webapp.ts` | Hand-rolled ~20-member contract for `window.Telegram.WebApp`. `getWebApp()` may honestly return `null` off-Telegram. | | `createSession(initData)` | `web/src/session/client.ts` | POSTs the verbatim initData string; returns `{ ok: true, token }` or a `malformed`/`tampered`/`stale`/`network` reason. | | `setSession` / `getSession` / `isSessionStale` / `clearSession` | `web/src/session/store.ts` | Module-scope token holder. No persistence call anywhere in the file. | | `bootMap(container)` | `web/src/map/map.ts` | MapLibre v6 bootstrap with the build-time-inlined Rams style. Returns `null` on `GPUInitializationError`. | | `createPositionMarker()` | `web/src/map/marker.ts` | SVG accuracy circle + 20 px dot + heading cone. Cone hidden entirely when heading is `null`. | | `createFollowController(map, onModeChange)` | `web/src/map/follow.ts` | following/free camera. Only a user gesture (`movestart` with `originalEvent`) flips to free. | | `createStatusStrip(host)` | `web/src/ui/strip.ts` | The status band — state lamp + state word on the left, telemetry on the right. | | `buildBootCard` / `buildDeniedCard` / `buildSignalLostCard` | `web/src/ui/cards.ts` | Rams card surfaces composed from theme component classes; zero inline copy. | | `createRecenterControl(host, locale, onRecenter)` | `web/src/ui/recenter.ts` | 40×40 follow plate with three instant notch states. | | `watchTheme(wa)` / `resolveBranch` | `web/src/telegram/theme.ts` | The theme-slot machine: Telegram light/dark (or `header_bg_color` luminance fallback) selects between two Rams token pairs — `applyTheme`'s ONLY statement is the `data-tg-theme` attribute set; MapLibre is deliberately absent (the map style is never re-set). Pinned by `web/test/theme.test.mjs`. | | `resolveSafeInsets` / `applySafeArea` | `web/src/telegram/safe-area.ts` | Union of CSS `env()` and `WebApp.safeAreaInset`, max per edge, emitted as CSS custom properties. | | `wireBackButton(wa, hasOverlay)` | `web/src/telegram/backbutton.ts` | Total function — the context-aware resolver (guidance → confirm; confirm → CONTINUE; ended → search-root walk; route → Phase 5 walk; root → close) and the wire's per-state `sync()`. | | `wireHomeScreen(wa, locale)` | `web/src/telegram/homescreen.ts` | The ONBD-03 home-screen affordance behind the Bot API 8.0 capability guard — Telegram-native methods only. | | `installMockWebApp(options)` | `web/src/mock/telegram-mock.ts` | Harness-only fake `window.Telegram.WebApp` with a dev-signed initData. Excluded from `web/dist`. | | `localeFromInitData(raw)` | `web/src/i18n/strings.ts` | Parses the locale out of the raw initData string — the session response carries only `{ token }`. | ### `@araharah/theme` | Abstraction | File | Description | | --- | --- | --- | | `@theme static` block | `theme/src/tokens.css` | 55 `--color-*` tokens plus spacing and typography. `static` forces every token into the compiled CSS so the package is consumable as plain custom properties. | | `theme/src/theme.css` | `theme/src/theme.css` | Entry stylesheet — `@import`s tailwindcss, tokens, components; declares seven self-hosted `@font-face` rules; defines the `--shell-bg` / `--shell-on-surface` theme slots (the two Rams token pairs the slot switch flips). | | Component classes | `theme/src/components.css` | `.card`, `.btn-primary`, `.btn-secondary`, `.chip-*`, `.maneuver-*`, `.text-*`, `.toggle*`, `.input-field`, `.checkbox`. | | `build.mjs` | `theme/basemap/build.mjs` | Forks OpenFreeMap `liberty`, deriving every cartographic color from `tokens.css` via `desaturate(tokenHex, satMultiplier, lightnessPerRole)` with saturation clamped to `[0.06, 0.12]`. | | `liberty-rams.json` | `theme/basemap/liberty-rams.json` | The generated style. Accent guard fails the build if `#EB8008` / `#ED3F1C` / `#736B1E` leak into any layer. `building-3d` is removed (faux 3D). | ## Directory Structure Rationale ``` araharah/ ├── package.json # private root; workspaces + script passthroughs ├── bot/ # @araharah/bot — the Cloudflare Worker │ ├── src/ │ │ ├── webhook.ts # the single fetch handler; six routes + scheduled() │ │ ├── config.ts # Env contract (KV, R2, MINI_APP_URL) │ │ ├── bot/ # grammY factory, commands/, handlers/ (incl. /cari) │ │ ├── security/ # initdata.ts — pure, isolation-free crypto │ │ ├── kv/ # sessions.ts, location-pin.ts, guidance-sessions.ts — TTL-only repos │ │ ├── routing/ # worker-router.ts — engine A's server surface │ │ ├── guidance/ # cron.ts — the pure turn-card projection │ │ └── i18n/strings.ts # every user-facing bot string │ ├── scripts/ # set-webhook, register-commands, set-menu-button │ ├── test/ # hand-rolled zero-dependency runner + suites │ └── wrangler.jsonc # worker name, assets binding, run_worker_first, R2, cron ├── web/ # @araharah/web — the Mini App │ ├── src/ │ │ ├── main.ts # boot choreography (order is load-bearing) │ │ ├── session/ # client.ts (network), store.ts (memory) │ │ ├── location/ # chain.ts + telegram/webview/chat-pin sources │ │ ├── search/ # resolve-destination.ts, destination-card.ts │ │ ├── route/ # route.ts controller, card, markers, layers │ │ ├── guidance/ # guidance.ts machine, watch.ts, banner, eta, camera, haptics │ │ ├── telegram/ # webapp, theme, backbutton, safe-area, homescreen │ │ ├── map/ # map.ts, marker.ts, follow.ts │ │ ├── ui/ # strip.ts, cards.ts, recenter.ts │ │ ├── mock/ # harness-only Telegram fake │ │ ├── i18n/strings.ts # every user-facing shell string │ │ └── shell.css # Rams chrome; imports @araharah/theme/dist/rams.css │ ├── public/glyphs/ # turn-card PNGs the cron deep-links │ ├── test/ # runner + gate suites (copy, storage, artifact, chain, guidance) │ ├── scripts/capture.mjs # screenshot capture │ └── vite.config.ts # dual-build dist/ vs dist-harness/ ├── search/ # @araharah/search — the gazetteer data plane │ ├── src/ # gazetteer.ts, source.ts, score.ts, normalize.ts, types.ts │ ├── src/data/ # kl-gazetteer.json (committed, ODbL notice inside) │ ├── scripts/ # gazetteer-corpus.mjs, json-to-sqlite.mjs, overpass-topup.mjs │ └── test/ # runner + suites + golden corpus fixtures ├── routing/ # @araharah/routing — the routing data plane │ ├── src/ # graph.ts, snap.ts, astar.ts, polyline.ts, geo.ts, │ │ # fixture-source.ts, http-source.ts, types.ts, index.ts │ ├── data/ # kl-roadgraph.v1.bin — BUILD ARTIFACT, not committed │ ├── scripts/ # build-road-graph.mjs, upload-road-graph.mjs, │ │ # build-glyphs.mjs, route-corpus.mjs, fetch-route-fixtures.mjs │ └── test/ # runner + suites + mini-graph fixtures ├── theme/ # @araharah/theme — design tokens + cartography │ ├── src/ # tokens.css, components.css, theme.css, sheet.html │ ├── fonts/ # self-hosted Geist + Space Grotesk woff2 │ ├── basemap/ # build.mjs + generated liberty-rams.json │ ├── scripts/ # audit.mjs (token audit), screenshot.mjs │ └── dist/rams.css # compiled output ├── scripts/ # root audits — privacy-audit.mjs, budget-audit.mjs, │ │ # lib/ (source-gates, bundle-gates, budget-gates, │ │ # cloudflare-probes), test/ (their suites) ├── stitch_minimalist_route_navigator/ # read-only design reference (mockups) └── docs/ ``` Rationale for the boundaries: - **`bot/src/webhook.ts` owns routing; nothing else dispatches.** The Worker is the only place that decides which path runs, so `run_worker_first`, the secret-token gate, the body caps, and the cron tick all apply uniformly. - **`bot/src/security/`, `bot/src/kv/`, and the two data-plane packages are dependency-light on purpose.** `initdata.ts` imports nothing from grammY and runs in both Workers and bare Node; `kv/*.ts` take a structural `KvLike` so the suites pass fakes; `@araharah/search` and `@araharah/routing` are V8-native with zero runtime dependencies, no env reads, and no network — the same sources run inside the Worker bundle, the Vite bundle, and the Node corpus runners. - **The backend ladders are constructed in code, not configured.** Search and routing each expose a seam (`SearchSource`, `RoutingSource`) whose backend selection happens at the import site — no env read, no config read, no dynamic registry. Swapping a backend is an import-site change. - **`bot/src/i18n/strings.ts` is the single copy source.** The commands register script derives its menu text from the same `helpMenu` lines, and `bot/test/commands.test.mjs` gates that the `/privacy` copy still names the four never-stored facts (location, routes, trip history, profile) and keeps the ~15-minute TTL wording, in both locales. - **`web/src/location/` separates sources from the chain.** Each source is a small module that normalizes to `Fix` and answers `null` for denial; `chain.ts` owns ordering and knows nothing about any single source's API. - **`web/src/route/` + `web/src/guidance/` split wiring from decisions.** `route.ts` only wires (consult once, draw, start the pump); `guidance.ts` is the pure state machine that decides every guidance behavior; `watch.ts` owns the throttle; the view modules (banner, eta, camera, haptics) each own one concern. Node-testable with injected DOM/map/geo. - **`web/src/session/` splits network from state.** `client.ts` owns fetch and error vocabulary; `store.ts` owns the in-memory token and the 900 s staleness rule. Neither ever touches storage. - **`web/src/telegram/` is the only place that touches `Telegram.WebApp`.** Every other module takes the narrow `TelegramWebAppLike` interface, which is what lets the mock, the test fakes, and real clients satisfy the same contract. - **`theme/` is pure build-time.** It exports no runtime code — a CSS bundle and a JSON style. That is why `web` can depend on it without pulling a bundler into the token package. - **`scripts/` is the audit layer, not product code.** `privacy-audit.mjs` and `budget-audit.mjs` are maintainer-time gates that import from `scripts/lib/`; nothing in `bot/src`, `web/src`, `routing/src`, or `search/src` imports them. - **`routing/data/` is a build artifact by law.** The 15 MB graph binary is gitignored; forks build and upload their own (`docs/ROAD-GRAPH.md` is the fork contract). - **`stitch_minimalist_route_navigator/` is `@source`-scanned, never edited.** The theme compiles every class the four mockups use so the design vocabulary stays provable against the shipped CSS. ## Cross-Cutting Concerns ### Privacy by construction — the gate lineage Two layers of gates pin this rather than documenting it: **The consolidated maintainer audit** — `npm run privacy-audit` (`scripts/privacy-audit.mjs`), five static gates in `scripts/lib/source-gates.mjs` and `scripts/lib/bundle-gates.mjs`, plus `--live` probes in `scripts/lib/cloudflare-probes.mjs`: | Gate id | Rule | | --- | --- | | `storage-api` | The memory-only law, repo-wide (the no-storage suite generalized). | | `kv-ttl` | The PG1 same-line TTL law, repo-wide — every `.put(` line in `bot/src` carries `expirationTtl` as a named constant. | | `log-vocabulary` | The D-14 category-only log law — no coordinate, payload, user id, or timestamp in any log line. | | `runtime-hosts` | The POSITIVE fetch-host allowlist — no fetch to any host outside it. | | `bundle-telemetry` | The PRODUCTION `web/dist` scan — no analytics, no beacon, no telemetry in the shipped artifact. | | `kv-expiry` / `asset-headers` (with `--live`) | Live expiry metadata and cache-header verification — a skipped probe is never mistaken for a pass (exit 2 = NOT RUN). | Exit codes: `0` clean, `1` violations, `2` NOT RUN (environment drift) — no silent passes. The audit doubles as the fork onboarding check. `docs/PRIVACY-AUDIT.md` is the human record. **The in-suite gates** (the same laws asserted where the code lives): - `bot/test/privacy.test.mjs` — the PG1/PG2 lineage: every `put` on `chat_sessions` (now spanning `sessions.ts`, `location-pin.ts`, `guidance-sessions.ts`, and `webhook.ts`) must carry an explicit `expirationTtl` on the same call line, as a named `SCREAMING_SNAKE` constant. No write path can persist without a TTL. - `web/test/no-storage.test.mjs` — comments stripped, every `web/src` file scanned; zero occurrences of `localStorage`, `sessionStorage`, `indexedDB`, `caches`, `document.cookie`, `WebApp.DeviceStorage`, `WebApp.SecureStorage`, `WebApp.CloudStorage`, or any service-worker registration. - `bot/test/route-privacy.test.mjs` — the route handler's structural proof: the only persisted surface is the guidance envelope; the route request's origin never touches storage or a log line. The persisted surface is exactly `SessionClaim` (user_id, chat_id, issued_at, language_code) for 900 s, `LocationPin` (latitude, longitude, horizontal_accuracy) for 300 s, and the `GuidanceSessionEnvelope` for 7200 s — all in ONE KV namespace. On the web side, guidance on-route fixes never leave the device; the ONLY network-bound position is a reroute's origin (one point, on a real excursion, snapped server-side). The client holds the token, the destination, and the last fix in module scope only. ### TTL-only storage law Every KV write carries an explicit TTL; nothing survives past it: | Key family | TTL | Constant | | --- | --- | --- | | `session:` / `chat:` | 900 s (~15 min) | `SESSION_TTL_SECONDS` | | `loc:` | 300 s | `PIN_TTL_SECONDS` | | `guidance:` | 7200 s (~2 h) | `GUIDANCE_SESSION_TTL_SECONDS` | The R2 bucket (`ROAD_GRAPH`) is a read-only binary host, not a persistence surface. Exactly ONE `kv_namespaces` entry is the law (`GE5`) — a new KV family is a design change, not a refactor. ### Access control Every chat-scoped route (`/api/location`, `/api/location-fallback`, `/api/guidance`) resolves the `chat_id` from the Bearer session claim, never from client input; locale comes from `claim.language_code`. The location-fallback request body is never read; a guidance POST's `chat_id` field is structurally dropped (`validateSnapshot` builds the new object field-by-field); GET/DELETE compare `envelope.chat_id === claim.chat_id` so foreign and absent are indistinguishable 404s (no existence oracle for cross-chat probing). `/api/route` uses the claim purely as an identity gate — routing itself is chat-agnostic and nothing about the caller is stored, logged, or echoed. ### Honest degradation Every degradation is a labeled state, never a silent one or a fabricated value: `bootMap()` returning `null` renders the shell over `--color-surface-dim` with `data-map="absent"`; a null heading hides the marker cone rather than guessing an orientation; `getPin` range-validates so a corrupt record cannot fly the camera to null island; the poll is bounded at 60 s so `AWAITING PIN` cannot persist; every source timeout resolves `null` so the chain always advances; **the route null contract** — every `/api/route` miss class answers `200 null` and the client renders the pending card; a null road graph degrades the cron card to the bare-verb street-less composition — the send still fires; guidance deviation becomes a labeled off-route state with a storm-guarded reroute, never a silent camera jump. ### Category-only logging The Worker's only log statements are categories — `[webhook] rejected: misconfigured`, `[initdata] rejected: malformed|tampered|stale`, `[location]`/`[location-fallback]`/ `[guidance]`/`[route] rejected: unauthorized|malformed`, `[guidance-cron] skipped: unconfigured|malformed`, `[guidance-cron] send failed`, `[location-fallback] failed: telegram-send`. Never raw payloads, never user ids, never chat ids, never coordinates, never timestamps. Rejection responses carry the category only. The web app's console lines are state tokens (`ARAHARAH-ROUTE`, `ARAHARAH-GUIDE`, `RAMS-BASEMAP-READY`, `ARAHARAH-LIVE`) — never coordinates. The audits (`log-vocabulary` gate) prove this mechanically. ### The budget law `npm run budget-audit` (`scripts/budget-audit.mjs`) measures the free-tier posture instead of assuming it: route CPU (the A\* ladder, child-process), bundle size, KV write classes (the cron's ZERO-writes law), subrequest classes, and the golden corpora; `--live` adds observed cache headers. The record is `docs/BUDGETS.md`. The cron's cadence is tuned to it: `*/2 * * * *` × one KV list-op per tick = 720 list-ops/day, inside the free plan's 1,000/day KV-list ceiling, and each tick performs zero KV writes (stateless projection over the 7200 s envelopes). ### Testing Five workspaces, one test idiom: `bot/test`, `web/test`, `search/test`, and `routing/test` each use the same hand-rolled zero-dependency runner (`runner.mjs` + `harness.mjs`), auto-discovering `*.test.mjs`; `theme` runs `scripts/audit.test.mjs` in the same shape, and `scripts/test/` holds the audit tools' own suites. Gates are grep/introspection assertions against source and build artifacts, not just behavioral assertions. The corpus suites (`search/test/corpus.test.mjs`, `routing/test/corpus.test.mjs`) assert the same measurements the standalone corpus runners print — measured quality and shipped quality cannot drift. ## What Is Not Built Yet The following are documented targets, **not** in the codebase: **engine B** (the fully client-side webview router — graph on the phone; engine A's documented post-v1 evolution; the Valhalla-to-JS port was ruled infeasible and geojson-path-finder was rejected — recorded so neither is re-proposed), Valhalla-on-VPS (the documented provision path, not shipped), Neon/Postgres, RabbitMQ, Prometheus/Grafana, Resend, opt-in telemetry (v1 carries zero telemetry — there is nothing to opt into yet), and the Maptiler tile provider (the basemap today is the OpenFreeMap `liberty` fork). Alternatives generation on `/api/route` is prohibited by design, not deferred. Search backend #1 (gazetteer) and routing backends #1/#2 are the only ladder rungs implemented; later rungs slot in at the import site without a client rewrite.