# Phase 6: Turn-by-Turn Guidance (Live Driving) - Context

**Gathered:** 2026-10-24
**Status:** Ready for planning — **with a phase-scope addition** (engine A workstream, D-01)

<domain>
## Phase Boundary

araharah behaves like real navigation: prominent next-maneuver banner + collapsible list, silent self-healing rerouting powered by a REAL router (engine A: Worker-side A\* over an R2-hosted KL road graph — RoutingSource backend #2, built this phase), honest ETA progression with smoothing, haptic cues, full BackButton state graph with PX-03 close protections, and trip-end data deletion (PRIV-01 in-app half). While minimized, the bot pushes schematic glyph+text turn-cards via a Worker Cron Trigger over the Phase 5-frozen guidance envelope. Verified via scripted drive replays plus one real drive.

**PHASE-SCOPE ADDITION (user decision):** the "defer WASM-router" deferral from Phase 5 is superseded — **engine A is built IN this phase** as a first-class workstream. The fixture backend remains RoutingSource #1 (golden pairs demo), engine A becomes #2 (arbitrary-origin routing), and GUID-02's rerouting is REAL from day one.

</domain>

<decisions>
## Implementation Decisions

### Routing engine — THE PIVOT #2 (user decision; supersedes the phase-5 deferral)
- **D-01:** **Engine A ships this phase**: OSM → compact road-graph build script (KL: ~30–80MB binary, typed arrays; one-ways + speed weights; turn restrictions deferred), graph hosted in **R2** (upload script committed — forks upload their own), **Worker-side A\*** (JS typed arrays, WASM optional) exposed as **RoutingSource backend #2** via a JSON routing API on the Worker. Satisfies every law: $0, no VPS, fork-friendly, privacy (the Worker is our infrastructure).
- **D-02:** **Valhalla-to-JS port ruled infeasible** (C++/Boost/mmap tile stores) — recorded so it is never re-proposed. geojson-path-finder rejected (demo-grade: no alternatives/one-ways). Engine B (fully client-side webview router — graph on the phone) is the documented evolution of A, deferred post-v1.
- **D-03:** Fixture backend remains #1 (golden-pairs demo path); engine A is #2 and **becomes the guidance engine**: arbitrary current positions route for real. Router-pending state remains for graph-edge cases (e.g. R2 graph absent — a designed degradation, not an error).

### Reroute semantics (GUID-02)
- **D-04:** The reroute trigger is a **thresholds + grace state machine**: `ON_ROUTE → OFF_ROUTE` (deviation > threshold with a grace window + N consecutive off-route fixes before acting) `→ REROUTING` (engine A call; banner stays calm, no blame) `→ ON_ROUTE` (new route snapped in, list refreshed). Storm guard: minimum time between recalculations. Missed-turn detection = off-route past the maneuver point. All thresholds are named constants, replay-tested.
- **D-05:** **The router snaps** raw GPS fixes to the graph (engine A owns snapping — one authority, no client/server drift). The watch fix streams raw; the router does the rest.

### Guidance UX surface (UI-SPEC scope)
- **D-06:** Layout: **top maneuver banner** (distance + arrow + street) replacing the status strip's top register during guidance (location register compacts); **collapsible full maneuver list** (collapsed default, expands over the map, tap-out collapses); **bottom guidance card** (the route card evolves): ETA + remaining distance + progress.
- **D-07:** **ETA smoothing: EMA + deadband** — recompute from route model + snapped progress (never raw fix-to-destination distance); display updates only past a named threshold (±1 min / ±5% remaining); constants replay-tested. No visible whiplash.
- **D-08:** **Haptics**: `HapticFeedback.selectionChanged()` at maneuver-approach threshold (~300m), impact at the maneuver point. Graceful no-op where unsupported.
- **D-09:** **PX-03**: closing during guidance requires the **"abandon route?"** Rams confirm card (en/ms); `disableVerticalSwipes()` while guidance is active; safe-area insets respected. **PX-01**: BackButton walks the full graph — search → routes → guidance → back to search — never dead-ends (extends the phase-5 two-state walk).
- **D-10:** **Camera**: locked follow (center ≈65% down-screen, pitch 35°) easing along the snapped line; user pan unlocks follow → the Phase 3 recenter control returns with its semantics.

### Backgrounded turn-cards (GUID-05)
- **D-11:** Minimize during guidance → app POSTs the guidance session (the frozen envelope contract goes LIVE: KV writes begin, `guidance:<id>`, 7200s TTL). A **Worker Cron Trigger (60–120s)** scans active guidance keys, projects progress along the snapshot, and pushes a chat turn-card when the next maneuver changes (or every N minutes). App re-open resumes foreground guidance; cron pushes pause while foregrounded.
- **D-12:** The card is a **glyph + text card**: committed arrow-glyph icon set (8 cardinal/turn PNGs, token colors) + ETA/distance/street text — no map bitmap, no renderer dependency, fully $0. Bitmap snapshots deferred to v1.x (Workers cannot rasterize; honest best-effort framing).
- **D-13:** "Best-effort" is honest: cron lag, Telegram delivery variance, and TTL expiry are documented behaviors, not failures; the card copy never promises what the mechanism can't (copy table in UI-SPEC).

### Trip end (PRIV-01 in-app half)
- **D-14:** Ending a trip **deletes the guidance session** (KV record gone — completing the TTL law's promise actively) and shows **"trip ended, data deleted"** messaging (en/ms). Arrival detection = snapped progress ≥ end-of-route threshold; abandon = the PX-03 confirm path. Both delete.

### Watch cadence + verification (GUID-02/03)
- **D-15:** Battery cadence: `watchPosition` high-accuracy, but the **app throttles by distance** — guidance work runs on ≥10m moved or ≥5s elapsed, whichever first. D-05's gated-streaming law finally flips its watch ON here.
- **D-16:** **Scripted drive replays** verify the state machine: recorded JSON position streams (corridor follow, off-route excursion, missed-turn excursion, GPS jitter) replayed through the machine in tests, asserting every transition, the storm guard, and ETA deadband. **Plus one real drive** as the device gate (phase 3/4 protocol).

### OpenCode's Discretion
- Graph build toolchain choice (osmium/planetiler-graph/custom overpass extract), binary layout, A\* variant (bidirectional), alternatives generation via penalty runs
- Deviation/storm/ETA constants' initial values (replay-tuned; named, not magic)
- Cron interval within 60–120s; "N minutes" repeat cadence; glyph icon production method (hand SVG → PNG)
- Banner/list micro-layout within the Rams system; exact copy wording within the tone law
- Envelope write timing (on guidance start vs first minimize — either honors the contract)

</decisions>

<specifics>
## Specific Ideas

- The guidance screen is the product's cockpit: banner + guidance card are instruments, the map is the world — nothing decorative, everything reading-bearing.
- Reroute messaging follows the clinical-honest law: the banner never blames, never asks — it recalculates, states the new route, moves on.
- The 15 fixture pairs remain the demo script; engine A pairs with them (same destinations, arbitrary origins) for the real-drive gate.

</specifics>

<canonical_refs>
## Canonical References

**Downstream agents MUST read these before planning or implementing.**

### Phase scope + decisions
- `.planning/ROADMAP.md` §Phase 6 — goal, 5 success criteria, research-recommended framing
- `.planning/REQUIREMENTS.md` §GUID-01..06, PX-01, PX-03 (+ PRIV-01 trip half)
- `.planning/phases/05-routing-route-display/05-CONTEXT.md` — the envelope contract being activated; RoutingSource ladder; D-05 cadence law
- `.planning/phases/03-mini-app-shell-geolocation/03-CONTEXT.md` — memory-only law, follow/recenter semantics, capture harness
- `.planning/phases/05-routing-route-display/05-UI-SPEC.md` — shell conventions the guidance UI extends

### Codebase
- `routing/` — RoutingSource interface engine A implements
- `web/src/location/` — the chain; guidance watch extends it (D-05 flip)
- `web/src/map/follow.ts` + `recenter.ts` — camera semantics reused
- `web/src/route/` — phase 5 route surface evolving into guidance chrome
- `bot/src/kv/` — TTL-only patterns; the envelope service lands beside them
- `bot/wrangler.jsonc` — Cron Trigger wiring surface

</canonical_refs>

<code_context>
## Existing Code Insights

### Reusable Assets
- RoutingSource + polyline6 + fixture backend (phase 5) — engine A plugs beneath the same seam
- GuidanceSessionEnvelope types (phase 5, frozen) — the service implements, not redefines
- Follow controller + recenter control (phase 3) — locked-follow camera reuses them
- Mock-Telegram harness + capture profiles — replay fixtures + guidance captures extend them
- glyphs: none yet — the 8-arrow set is new, committed once, reused everywhere

### Established Patterns
- Interface + backend ladder (now 3 real stages); hand-rolled runners; TDD RED→GREEN
- TTL-only KV with keyed namespaces; category-only logging
- Device gates: real hardware at exit (this phase adds the real drive)

### Integration Points
- Cron Trigger = new Worker surface (first scheduled handler in the repo)
- R2 = new storage surface (first binding) — upload script + fork docs
- HapticFeedback/BackButton/vertical-swipes = Telegram WebApp APIs behind capability guards

</code_context>

<deferred>
## Deferred Ideas

- Engine B: fully client-side webview router (graph on the phone; privacy-maximal endgame)
- Turn restrictions in the graph; contraction hierarchies; CH preprocessing
- Bitmap map snapshots in turn-cards (needs a rasterizer we don't have — v1.x)
- Voice guidance, live trip share, toll toggle, speed limits (v1.x, REQUIREMENTS deferred table)
- Traffic-aware ETAs, incident-aware rerouting (v2)

</deferred>

---

*Phase: 06-turn-by-turn-guidance-live-driving*
*Context gathered: 2026-10-24*

### Post-planning ratification (2026-10-24)
- **A1 CPU decision: c3 now** (short routes in-budget; cross-metro → honest router-pending), **c2 (ALT landmarks) committed as the next-milestone upgrade lever**. c1 (Workers Paid) rejected — $0 law.
- **D-12 ratification: street-bearing turn-cards confirmed** (default stands).
- R2 activation pending user dashboard click (code 10042); non-blocking for cron/captures.