arah2/docs/KNOWN-LIMITATIONS.md

<!-- generated-by: gsd-executor (07-05, D-08) -->

# Known limitations

araharah is a turn-by-turn navigator for the Kuala Lumpur metro, delivered inside
Telegram: you search a destination with the bot (`/cari KLCC`), open the Mini App,
and follow live route guidance built on OpenStreetMap data. It works today for real
drivers, and it has real limits. This page lists what araharah does **not** do well —
stated plainly, for two readers: a driver deciding whether araharah fits today's trip,
and a fork deciding what they are inheriting. Nothing here is a hidden defect; every
claim names its evidence, and none of it is fixed by asking harder.

## Data coverage

araharah routes over a snapshot of OpenStreetMap, and inherits OSM's gaps honestly:

- **No traffic awareness.** There is no live traffic feed; the ETA is a
  distance-and-speed estimate from the route model, not a prediction.
- **No lane guidance.** There is no lane-level arrow guidance; the maneuver glyph
  names the turn, not the lane.
- **Speed limits appear only where OSM maps them.** Many KL roads carry no
  `maxspeed` tag in OSM, so no limit is shown on those roads.
- **Turn restrictions and one-ways** are only as good as the OSM snapshot the road
  graph was built from; a restriction edited in OSM last week may not be reflected
  until the next graph build.
- **The road graph is a build-time artifact** (`routing/data/kl-roadgraph.v1.bin`),
  rebuilt by a maintainer — forks rebuild their own (`docs/ROAD-GRAPH.md`).

## Cross-metro routes may not resolve

Route computation runs inside Cloudflare Workers' free plan, whose per-request CPU
allowance is small. On the real KL road graph, short product routes (2–8 km — the
common search-and-reroute trip) measure 2–8 ms of Worker CPU and resolve inside the
plan. Cross-metro routes (20–30 km) measured p95 38–93 ms against the same graph
(`routing/scripts/measure-route-cpu.mjs`, LADDER HISTORY; Phase 6 plan summary), which
is beyond what the free plan permits. Those trips therefore degrade honestly: the app
shows the router-pending card — "the router is not ready for this trip" — instead of
freezing or drawing a wrong line. The committed upgrade lever is ALT landmark
preprocessing (a build-time graph layout that cuts A* steering cost); it is a
next-milestone item and is **not** in this release. Workers Paid was rejected: it
breaks the project's $0 mandate.

## The /cari command may be missing from the Telegram menu

Some drivers see a command menu listing `/help` and `/privacy` but **not** `/cari`.
This is a Telegram `setMyCommands` scope-resolution behaviour, not a bot bug:
Telegram resolves a chat's menu from the narrowest scope that has ANY commands set,
so a stale non-default scope (for example an old `all_private_chats` set recorded
before `/cari` existed) shadows the default scope's fuller menu. The bot re-arms
every such scope (`bot/scripts/register-commands.mjs`), but the Telegram client may
keep showing the cached menu until the app restarts. **The workaround: type `/cari`
in the chat** — the command itself has always worked; only its discoverability is
affected.

## Beta quality

This is a private beta with a handful of drivers in Kuala Lumpur, not a finished
product. The device matrix was walked on real Android and iOS phones, Telegram
Desktop, and a plain browser; battery drain is a measured number, not an estimate —
one Android guidance run of at least 30 screen-on minutes with battery percentage
read at start and end, the method and caveats recorded in the launch-gate file
(`07-LAUNCH-GATE.md`) before the first driver is onboarded. Fullscreen and
orientation behaviour varies by Telegram client version; where the platform refuses
a fullscreen request the app degrades to a usable portrait/landscape layout rather
than failing. Known limits that are milestones, not defects: no voice guidance, no
live trip sharing, no toll toggle, no traffic-aware ETA — all are post-validation
items on the roadmap.

## What is being worked on next

Three tracks target the limits above; none of them are in this release.

| Track | What it fixes | Honest status |
| --- | --- | --- |
| WASM-router | A client-side router compiled to WebAssembly — the static-hosted endgame where routing cost leaves the Worker entirely | Committed direction, not built |
| ALT landmark preprocessing | The cross-metro CPU degradation (the section above) — build-time landmark layout cuts A* steering cost at $0 runtime | Next-milestone item, not built |
| Engine B | A fully client-side webview router — routing runs in the browser, the Worker serves only data | Future track, not built |

## Privacy in one paragraph

Your coordinates live only in memory and in TTL-expiring KV records: sessions expire
in about 15 minutes, location pins in 5 minutes, guidance envelopes in about 2 hours;
there is no location history, no profile, and nothing retained past those TTLs. There
is NO telemetry of any kind in this release — no analytics, no crash reporting, no
usage tracking. The shipped bundle contacts only the map tile host, the Telegram API,
and the app's own Worker. `docs/PRIVACY-AUDIT.md` holds the full record, including
how each claim was verified.

## How to run the audit yourself

Forks inherit the audit tools — run both before your first driver:

- `npm run privacy-audit` — greps every source tree for storage-API writes outside
  the platform allowlist, coordinate/payload logging, and telemetry in the shipped
  bundle, and probes the live KV namespaces. **Exit 0 = every gate passed; exit 2 =
  environment drift — investigate, never a pass.**
- `npm run budget-audit` — re-measures Worker CPU, bundle sizes, KV write classes,
  and cache headers against the documented free-tier ceilings, and re-runs the golden
  route and search corpora. **Exit 0 = every budget held; exit 2 = environment drift
  — investigate, never a pass.**