From 78482ab2093acac8b46a37c4da5329c708da1bc3 Mon Sep 17 00:00:00 2001 From: araharah-executor Date: Sun, 25 Oct 2026 04:46:02 +0800 Subject: [PATCH] feat(07-05): the known-limitations document (D-08) + the /help pointer line (en+ms) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - docs/KNOWN-LIMITATIONS.md — new, for drivers AND forks: OSM data gaps, the c3 cross-metro CPU degradation (2-8 ms short / p95 38-93 ms cross-metro, measure-route-cpu.mjs LADDER HISTORY as evidence, ALT as the committed lever, Workers Paid rejected on the $0 mandate), the /cari menu defect + the type-the-command workaround, the beta-quality statement, the roadmap pointers (WASM-router / ALT / engine B — none in this release), the privacy paragraph, and the fork-facing audit commands - strings.ts helpMenu (en+ms): ONE pointer line each, not /-prefixed so the CS5 menu parse ignores it; URL is the repo's actual remote deep link (http://gitmirah:3000/c-fu/arah2/src/branch/main/docs/KNOWN-LIMITATIONS.md), identical in both locales — single-copy law (D-05) - suite 126/126, CS5 green --- bot/src/i18n/strings.ts | 4 +- docs/KNOWN-LIMITATIONS.md | 100 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 102 insertions(+), 2 deletions(-) create mode 100644 docs/KNOWN-LIMITATIONS.md diff --git a/bot/src/i18n/strings.ts b/bot/src/i18n/strings.ts index 8a0bb80..d9e1376 100644 --- a/bot/src/i18n/strings.ts +++ b/bot/src/i18n/strings.ts @@ -92,7 +92,7 @@ export const strings: Record = { privacyNotStored: "What araharah never keeps: your location, your routes, your trip history, any profile about you.", helpMenu: - "Commands:\n/help — How araharah works and what it keeps\n/privacy — What araharah stores and never stores\n/cari — Search for a destination in the KL metro", + "Commands:\n/help — How araharah works and what it keeps\n/privacy — What araharah stores and never stores\n/cari — Search for a destination in the KL metro\nKnown limits: http://gitmirah:3000/c-fu/arah2/src/branch/main/docs/KNOWN-LIMITATIONS.md", awaitingPin: "Send me a pin in this chat and I'll use it as your starting point.", shareLocationButton: "Share my location", pinReceived: "Got it — your starting point is set.", @@ -130,7 +130,7 @@ export const strings: Record = { privacyNotStored: "Yang araharah tidak pernah simpan: lokasi anda, laluan anda, sejarah perjalanan anda, apa-apa profil tentang anda.", helpMenu: - "Arahan:\n/help — Cara araharah berfungsi dan apa yang ia simpan\n/privacy — Apa yang araharah simpan dan tidak pernah simpan\n/cari — Cari destinasi di kawasan KL", + "Arahan:\n/help — Cara araharah berfungsi dan apa yang ia simpan\n/privacy — Apa yang araharah simpan dan tidak pernah simpan\n/cari — Cari destinasi di kawasan KL\nHad panduan: http://gitmirah:3000/c-fu/arah2/src/branch/main/docs/KNOWN-LIMITATIONS.md", awaitingPin: "Hantar saya pin dalam chat ini dan saya akan gunakannya sebagai titik mula anda.", shareLocationButton: "Kongsi lokasi saya", pinReceived: "Baik — titik mula anda sudah ditetapkan.", diff --git a/docs/KNOWN-LIMITATIONS.md b/docs/KNOWN-LIMITATIONS.md new file mode 100644 index 0000000..71dbdb2 --- /dev/null +++ b/docs/KNOWN-LIMITATIONS.md @@ -0,0 +1,100 @@ + + +# 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.**