arah2/docs/KNOWN-LIMITATIONS.md

Known limitations

arah² 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 arah² does not do well — stated plainly, for two readers: a driver deciding whether arah² 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

arah² 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) resolve inside the plan; cross-metro routes (20–30 km) do not. 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. Workers Paid was rejected: it breaks the project's $0 mandate.

WHAT CHANGED (Phase 8, shipped 2026-10-25): the promised ALT landmark preprocessing was built — the ARG2 graph layout carries build-time landmark tables (L=24, quantum 0.1 s, coverage 0.980), the search steers with them, and optimality is verified: the D-03 gate reproduces the frozen pre-ALT record exactly (53/53 routed pairs within ±0.1%, max |Δ| 0.005%, verdict classes preserved — node routing/scripts/measure-optimality-gate.mjs).

What REMAINS — the CPU verdict measured over budget, so the degradation stands: the 25-route gate printed GATE FAIL: p95 152.788 ms exceeds the 8 ms budget and the 100-pair cross-metro verdict GATE FAIL: p95 185.692 ms exceeds the 8 ms budget (2026-10-25; the --landmarks 32 probe measured worse: 182.725 / 204.499 ms). The faster steering that would help is provably unsound here: the fromTable triangle bounds are one-directional Lipschitz (their u-side term needs the reverse edge, which a oneway does not provide), and the bidirectional search's shared potential is consistent only with two-sided families — the D-03 gate caught the four-family variant returning suboptimal routes (x038: 1234.6 s vs the 1214.8 s optimum) before it shipped. The honest escalation — direction-split potentials with a re-proven meet rule, Contraction Hierarchies, or Workers Paid — is open, documented in docs/BUDGETS.md's c3 section. Full-speed routing is NOT claimed; only that the measurement is printed and the gate decides.

The /cari command may be missing from the Telegram menu

Some drivers saw a command menu listing /help and /privacy but not /cari. ROOT CAUSE (found and FIXED 2026-10-25, 07-06 launch-gate canary): it was a bot-side script bug, not a Telegram defect — bot/scripts/register-commands.mjs sent the scope under the wrong parameter name (bot_command_scope; the Bot API field is scope), which Telegram silently ignores, so every registration call actually hit the default scope and the group-scope "clear" calls wiped the default set entirely. The correct parameter was verified against https://core.telegram.org/bots/api/methods/setmycommands, the script was fixed, and all private-chat scopes now read back help, privacy, cari via getMyCommands (verified 2026-10-25). What REMAINS: the Telegram client caches the menu — a device that opened the bot before the fix may keep showing the stale menu until the app restarts. The workaround: type /cari in the chat — the command itself has always worked; only its discoverability was 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. One of them — the ALT landmark layout — shipped in Phase 8; its measured outcome (optimality verified, CPU verdict still over budget) is recorded in the section above. The other two are not 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	Built (Phase 8, 2026-10-25): optimality verified; the CPU verdict measured over budget (p95 152.8/185.7 ms vs 8 ms) — the degradation stands
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.