From f33bc767791e75704bfe5ba0c12cb5bf26b5250d Mon Sep 17 00:00:00 2001 From: araharah-executor Date: Sat, 24 Oct 2026 01:46:39 +0800 Subject: [PATCH] =?UTF-8?q?docs(04-04):=20complete=20webview=20deep-link?= =?UTF-8?q?=20hand-off=20plan=20=E2=80=94=20two-carrier=20resolver=20+=20O?= =?UTF-8?q?NBD-03=20hooks=20+=20device=20gate=20escalated?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../04-04-SUMMARY.md | 244 ++++++++++++++++++ 1 file changed, 244 insertions(+) create mode 100644 .planning/phases/04-destination-search-kl-gazetteer/04-04-SUMMARY.md diff --git a/.planning/phases/04-destination-search-kl-gazetteer/04-04-SUMMARY.md b/.planning/phases/04-destination-search-kl-gazetteer/04-04-SUMMARY.md new file mode 100644 index 0000000..8911510 --- /dev/null +++ b/.planning/phases/04-destination-search-kl-gazetteer/04-04-SUMMARY.md @@ -0,0 +1,244 @@ +--- +phase: 04-destination-search-kl-gazetteer +plan: 04 +subsystem: web +tags: [destination-preload, deep-link, start-param, gazetteer, homescreen, add-to-home-screen, device-gate, capture, tdd] +requires: + - phase: 04-01 (shared search module) + provides: "@araharah/search — getEntryById for the webview's own build-time id lookup" + - phase: 04-03 (chat search surface) + provides: "the corrected carrier — /?dest= on a web_app button; MINI_APP_URL origin" + - phase: 03 (mini app shell) + provides: "the staged boot, card stack, strip, harness mock, capture runner, BA gates" +provides: + - "web/src/search/resolve-destination.ts — the two-carrier reader (URL ?dest= PRIMARY, signed initData start_param SECONDARY, one slug validation, dest_ prefix stripped) + the memory-only holder" + - "web/src/search/destination-card.ts — the destination confirmation + honest-unavailable surfaces (createElement/textContent only)" + - "web/src/telegram/homescreen.ts — wireHomeScreen behind the BOTH-halves Bot API 8.0 guard (added hides / unknown shows / missed shows / unsupported nothing)" + - "TelegramWebAppLike gains startParam, addToHomeScreen?, checkHomeScreenStatus? + HomeScreenStatus; the mock satisfies them in the same change" + - "BA7 (bot/web id-set parity: the shipped bundle carries EVERY gazetteer id) + BA8 (no deep-link crypto in the shipped JS)" + - "ARAHARAH-DEST state-token boot signal + the shell-dest-preload capture leg (8/8)" + - "the deployed Worker (31138f79) with the destination-preload webview live; 04-DEVICE-GATE.md with six UNVERIFIED physical legs" +affects: + - "phase 5 (origin/destination resolvers consume getDestination(); the destination is already seeded at boot)" + - "phase 7 (ONBD-02 device verification fallback venue if legs stay unverified)" +tech-stack: + added: [] + patterns: + - "two-carriers-one-validation reader: URLSearchParams for location.search, hand-rolled &-split (never URLSearchParams) for the signed initData string" + - "RED-verified gates first (suite-load failure = RED), per-task test→feat commit pairs" + - "state-token capture signals (ARAHARAH-DEST state=resolved|absent, never the id) paired with a DOM text assertion" +key-files: + created: + - web/src/search/resolve-destination.ts + - web/src/search/destination-card.ts + - web/src/telegram/homescreen.ts + - web/test/destination-preload.test.mjs + - web/test/homescreen.test.mjs + - .planning/phases/04-destination-search-kl-gazetteer/04-DEVICE-GATE.md + modified: + - web/src/telegram/webapp.ts + - web/src/mock/telegram-mock.ts + - web/src/i18n/strings.ts + - web/src/main.ts + - web/index.html + - web/package.json + - package-lock.json + - web/test/build-artifact.test.mjs + - web/test/no-storage.test.mjs + - web/scripts/capture.mjs +decisions: + - "The destination surface mounts into the EXISTING card stack and holds the center register at live (null when no id → Phase 3 boot byte-identical, D-12); the denied/awaiting location registers keep their cards — the destination returns at live" + - "waitMode 'dest' waits on the DOM (page.waitForFunction for 'Suria KLCC') after the state-token assertion — the signal fires at boot but the card mounts at live, so a one-shot text sample would race the chain" + - "homeScreenAlreadyAdded copy is defined in both locales but has NO render site: status 'added' HIDES the affordance (do not nag) — the string is reserved for a future surface that must say 'already added' (T-04-37 law)" + - "Deploy canary drift (menu button unarmed, command list empty on the live bot) fixed by re-running the repo's own one-time registration scripts — Telegram-side state, not source" +metrics: + duration: "~14 min executor time" + completed: 2026-10-23 + tasks: 4 (3 automated + 1 blocking device-gate checkpoint) + filesCreated: 6 + filesModified: 10 +--- + +# Phase 4 Plan 4: Webview Deep-Link Hand-off + Device Gate Summary + +**One-liner:** the webview half of ONBD-02 — a two-carrier destination reader (`?dest=` URL +query first, signed `initData.start_param` second, one `[A-Za-z0-9_-]{1,64}` validation, +`dest_` prefix stripped) resolving against the webview's own build-time copy of the shared +gazetteer into a memory-only holder, rendering the destination card (never a blank map, +never a fabricated coordinate) — plus ONBD-03's minimal Telegram-native home-screen hooks +behind a Bot API 8.0 guard with the iOS "unknown" treated as indeterminate, the BA7/BA8 +drift gates proving the shipped bundle carries all 30 ids and zero crypto, the 8/8 capture +including the destination-preload leg, and the deployed origin with its blocking +six-leg device gate recorded honest-UNVERIFIED. + +## Performance + +- **Duration:** ~14 min +- **Started:** 2026-10-23T17:31:23Z +- **Completed:** 2026-10-23T17:45Z (automated half; device gate pending user) +- **Tasks:** 3/3 automated + the blocking checkpoint escalated +- **Files:** 16 (6 created, 10 modified) + +## Accomplishments + +- The deep-link hand-off is complete end-to-end in code and live on the deployed Worker: + `/cari` → venue card → OPEN (`?dest=`) → the webview resolves the id against its + own gazetteer copy → the DESTINATION card renders (verified by the capture leg's + `state=resolved` + "Suria KLCC" DOM assertion). No crypto anywhere on the path. +- ONBD-03's minimal hooks are live: `wireHomeScreen` guards on BOTH halves (method + presence + `isVersionAtLeast("8.0")`), hides on "added", shows the neutral prompt on + "unknown"/"missed", nothing on "unsupported", catches refused installs, and hides on + `homeScreenAdded` — with NO browser install APIs (HS9). +- The honesty laws are mechanical: DP6 rejects traversal/XSS/empty/200-char ids on BOTH + carriers; DP8/D-11 pin the honest null; BA7 proves the shipped bundle carries every + committed gazetteer id (the bot/web parity gate); BA8 proves no deep-link crypto ships. +- Deploy `31138f79` is live with all canaries green after re-arming Telegram-side + registrations (menu button web_app, help/privacy/cari command menus). + +## Task Commits + +| task | commit | message | +| ---- | ------ | ------- | +| 1 RED | `3e3d191` | test(04-04): RED — the ONBD-02 destination-preload gate suite (DP1-DP12) | +| 1 GREEN | `4f95841` | feat(04-04): the destination resolver — two carriers, one validation, memory only | +| 2 RED | `6e421e6` | test(04-04): RED — the ONBD-03 home-screen gate suite (HS1-HS9) | +| 2 GREEN | `c2d78b0` | feat(04-04): ONBD-03 home-screen hooks + the boot wiring + the ?dest= harness profile | +| 3 | `747eeb7` | test(04-04): the BA7/BA8 drift gates + the search-tree GEO3 pin + the destination-preload capture leg | +| 4 | `7b02c7d` | docs(04-04): the blocking ONBD-02/ONBD-03 device gate — deployed + canaries green, six legs UNVERIFIED pending a real device | + +## Verification Results + +- `npm test -w web` — **57 passed, 0 failed** (DP1–DP12, HS1–HS9, BA1–BA8, GEO3 incl. the + new explicit `web/src/search` pin, COPY gates over the 5 new strings, all prior suites) +- `npm test -w bot` — **65 passed, 0 failed** (unaffected; the deep-link contract's bot half) +- `npm run search:corpus` — threshold PASS: top-3 68/68 (100%), negatives refused 7/7, + margin 0.643 < 0.72 (D-14 close holds) +- `npm run web:typecheck` / `search:typecheck` — green +- `npm run build -w theme && npm run build -w web` — green; BA7 RED against the stale + pre-gazetteer bundle, GREEN after (the RED evidence for task 3) +- `npm run capture -w web` — **CAPTURE OK — 8/8 non-blank captures**, incl. + `shell-dest-preload.png` (34,499 B) whose leg asserted `ARAHARAH-DEST state=resolved` + AND the rendered card text "Suria KLCC"; GEO-03 runtime probe PASSED (storage empty) +- Live-origin canaries: `getWebhookInfo.url` ends `/telegram/webhook` (last_error is the + STALE 2026-10-22 phase-3-era 500, pending 0); menu button `web_app` → origin ✓; + commands default+ms+all_private_chats list `help/privacy/cari` ✓; unsigned webhook + POST → 401 ✓; the live `main-*.js` chunk carries **30/30 gazetteer ids, zero crypto + tokens**, and the new copy ✓ +- `MINI_APP_URL` == deployed origin (binding shown in the deploy log); secrets never echoed + +## Deviations from Plan + +### Auto-fixed Issues + +**1. [Rule 1 - Bug] The dest capture leg's DOM check raced the boot chain** +- **Found during:** task 3 (design review of the wait mode, pre-commit) +- **Issue:** the plan's `waitMode: 'dest'` snippet sampled `page.textContent('body')` ONCE, + immediately after the ARAHARAH-DEST race. The signal fires at boot stage 13, but the + destination card mounts only when the chain reaches LIVE (the boot stages replace the + card stack transiently) — a one-shot sample could read the body before the card existed. +- **Fix:** kept the plan's `state=resolved` assertion, then waited for the card text with + `page.waitForFunction(...'Suria KLCC', { timeout: 15000, polling: 250 })` instead of a + single sample. Same assertion, race-free. Capture passed 8/8. +- **Files modified:** web/scripts/capture.mjs + +**2. [Rule 3 - Blocking] Live-bot registrations were un-armed (menu button + command menu)** +- **Found during:** task 4 (deploy canaries — `getChatMenuButton` returned the default + `commands` type, `getMyCommands` empty) +- **Issue:** Telegram-side bot registrations from earlier phases did not survive on the + live bot; the plan requires the menu button web_app armed and the command list verified + post-deploy. +- **Fix:** re-ran the repo's own one-time registration scripts (`node + bot/scripts/set-menu-button.mjs`, `node bot/scripts/register-commands.mjs`); re-verified + via `getChatMenuButton`/`getMyCommands`. No source changes. +- **Files modified:** none (Telegram-side state) + +**3. [Planner-note] Capture-leg comment numbering** +- The plan's leg snippet was commented "/* 8 —" while instructing placement after leg 6; + inserted as leg 7 with gallery-compare renumbered 8 so execution order reads correctly. + Cosmetic only; the `expected` array and the 8/8 line match the plan verbatim. + +--- + +**Total deviations:** 2 auto-fixed (1 × Rule 1, 1 × Rule 3) + 1 cosmetic note +**Impact on plan:** none on scope; both fixes were required for the plan's own gates/ +canaries to hold. + +## Auth Gates + +None — no secrets handled beyond reading the local gitignored `bot/.dev.vars` for deploy +canary Bot API calls; the token was never echoed (only concatenated into API URLs), and +`MINI_APP_URL` is a public var by design. + +## Known Stubs + +- `strings.*.homeScreenAlreadyAdded` (web/src/i18n/strings.ts) — defined + copy-gated in + both locales but with NO render site: the plan's own behaviour law makes status "added" + HIDE the affordance (do not nag), so no surface can honestly display "Already on your + home screen" in this phase. Reserved for a future surface that must SAY "already added" + (e.g. a settings view); the string lives in the strings module so copy stays centralized. + +No other stubs — every export is wired to real behavior; no TODO/FIXME/placeholder in the +new tree. + +## Threat Flags + +None — the built surface is exactly the plan's threat model (T-04-32…T-04-42), every +mitigation landed WITH a gate: charset validation before any lookup (DP6, T-04-32), the +signed-string-only initData parse with start_param as a pure lookup key (DP2/DP10, +T-04-33), the bounded prank consequence + honest null (DP8, T-04-34), memory-only +destination (DP9/DP12 + GEO3 search-tree pin + runtime probe, T-04-35), the both-halves +capability guard with caught refusals (HS1/HS2/HS7, T-04-36), the never-fail status +handling (HS4/HS5, T-04-37), the browser-install-API ban (HS9, T-04-38), the id-parity +drift gate (BA7, T-04-39), the no-crypto bundle gate (BA8 + DP10, T-04-40), the harness +DCE proof (BA5/BA6 + capture's inverse assertion, T-04-41), and the anti-fake capture +race (state=resolved + DOM text, T-04-42). + +## TDD Gate Compliance + +PASSED — tasks 1 and 2 each carry a `test(...)` RED commit verified failing (suite-load +failures: 33+1 and 45+1) followed by a `feat(...)` GREEN commit: +`3e3d191→4f95841`, `6e421e6→c2d78b0`. Task 3 is a gates-and-tooling task (no production +source): its RED (`BA7` failing against the stale pre-gazetteer `web/dist`, 56+1) and its +GREEN (BA1–BA8 green after the rebuild — the build output is gitignored, so no source +commit exists for the GREEN half) are recorded here and in the execution log; the git +sequence is therefore `test → feat → feat → test → test → docs` at plan level. + +## Device Gate (task 4 — BLOCKING CHECKPOINT) + +`.planning/phases/04-destination-search-kl-gazetteer/04-DEVICE-GATE.md` records the +deploy (version `31138f79`), the canary table, the origin prerequisite, and SIX physical +legs — ONBD-02 on Android / iOS / Desktop, the ONBD-03 home-screen add + launch, the +unknown-id honesty check, and the `/cari Kuching` honest refusal — **every leg +UNVERIFIED**: no physical device is attached to this environment and none was faked. + +**ORCHESTRATOR ACTION REQUIRED:** per this wave's split of ownership, `.planning/STATE.md` +and `.planning/ROADMAP.md` were deliberately NOT touched. The device-gate blocker +("ONBD-02/ONBD-03 device legs UNVERIFIED — needs a real Android/iOS/Desktop; phase held +open") must be recorded under STATE.md "Blockers/Concerns" by the orchestrator, and +ONBD-02/ONBD-03 must NOT be marked complete in REQUIREMENTS.md until the legs pass (the +plan's resume signal: "device gate passed"). + +## User Setup Required + +Walk the six legs in `04-DEVICE-GATE.md` on a real device (the bot is LIVE at +https://araharah-bot.araharah-bot.workers.dev — `/cari KLCC` → OPEN). Also visually +confirm @BotFather's Mini App URL equals that origin (the Bot API cannot read the +BotFather-side value; the bot-side menu button + `MINI_APP_URL` are confirmed equal). + +## Next Phase Readiness + +- Phase 5 can consume `getDestination()` — the boot already seeds the memory-only holder + from either carrier; the origin/destination resolvers plug into the SearchSource seam. +- The carrier-swap lever stands ready if device legs 1–3 fail: `miniAppUrlFor(origin, id)` + in `bot/src/bot/commands/cari.ts` is the one place the deep link is built. +- `/pergi_ke` remains registered nowhere (D-01 reservation); the corpus gate and all + suite gates are green for the phase-exit verifier. + +## Self-Check: PASSED + +- All 6 created files exist on disk (verified below); all 10 modified files committed. +- All 6 task commits present in `git log` (`3e3d191`, `4f95841`, `6e421e6`, `c2d78b0`, + `747eeb7`, `7b02c7d`); zero file deletions in any (`git diff --diff-filter=D` = 0 after + each). +- Suites re-run at close: web 57/57, bot 65/65, corpus threshold PASS; capture 8/8; + deploy live with canaries green.