arah2/.planning/phases/05-routing-route-display/05-01-SUMMARY.md

---

phase: 05-routing-route-display plan: 01 subsystem: routing tags: [routing, fixture-backend, polyline6, encoded-polyline, routing-source, npm-workspaces, tdd, osrm]

Dependency graph

requires:

• phase: 04-destination-search-kl-gazetteer provides: the search/ workspace pattern (RoutingSource mirrors SearchSource: interface + backend ladder + lazy loader + hand-rolled runners) and the gazetteer destinationId namespace the route requests carry provides:
• "@araharah/routing — the fifth buildless npm workspace (pure .ts + .json, zero runtime deps)"
• "RoutingSource interface + full route model with D-07 day-one fields (RouteStep typed, RouteGeometry.cumulativeDistanceM)"
• "polyline6 codec (decode/encode, 1e-6 grid, round-trip law, truncated-input refusal)"
• "geo math: haversineM + deriveCumulativeDistanceM"
• "createFixtureRoutingSource — backend #1 with the 200 m origin-tolerance matching law and honest-null pending semantics"
• "committed EMPTY route-fixtures.json seed with ODbL header (schema + license surfaces ship now)"
• "getPairOrigin / getPairs introspection for the corpus runner (05-02) and ?fixpair= harness knob (05-05)"
• "three-environment loader proof (bare Node 24, esbuild, Vite-family) — L1–L3" affects: [05-02 fixtures corpus, 05-04 web route surface, 05-05 gates, phase-6 guidance]

Tech tracking

tech-stack: added: [] # zero new dependencies — buildless TS consumed via workspace paths (search/ precedent) patterns: - "RoutingSource seam with documented backend ladder (fixture → wasm-router → valhalla), backend selected in code at the import site" - "polyline6 verbatim storage + pure codec with round-trip law as the corpus gate's free assertion" - "lazy memoized index at factory-closure scope; module scope holds only the static JSON import binding" - "defensive pair validation at index build (malformed → skipped → honest null, never a throw)"

key-files: created: - routing/package.json - routing/tsconfig.json - routing/src/types.ts - routing/src/polyline.ts - routing/src/geo.ts - routing/src/fixture-source.ts - routing/src/index.ts - routing/src/data/route-fixtures.json - routing/test/runner.mjs - routing/test/harness.mjs - routing/test/contract.test.mjs - routing/test/polyline.test.mjs - routing/test/fixture-source.test.mjs - routing/test/loader-env.test.mjs modified: - package.json (workspaces + routing:test/typecheck/corpus delegates) - package-lock.json (routing workspace registered)

key-decisions:

• "polyline.ts is zero-import: it declares a structural PolyPoint instead of importing RoutePoint because the plan's acceptance gate greps polyline.ts for zero from \"\" occurrences; structural identity keeps full type compatibility"
• "F8's positive half (getPairOrigin resolving a known pair) ships as a visible SKIP while the committed seed is empty — the lookup machinery is proven by F2's injected dataset; the positive half arms automatically when 05-02 populates the corpus (loader-env L2/L3 precedent)"
• "RouteFixturesFile added to types.ts (beyond the plan's listed ten interfaces) because createFixtureRoutingSource(data?) needs a public parameter type; index.ts re-exports kept exactly per plan"

patterns-established:

• "RoutingSource ladder: interface header documents backends #2/#3 without shipping them (the SearchSource analog, D-04)"
• "Null contract as contract documentation: 'router pending' grep-pinned by C3 so the semantics cannot silently drift"
• "Three zero-laws gate (C4): comments stripped, then banned tokens (logging/storage/network) grepped across routing/src — grows with 05-02's script"

requirements-completed: [RTNG-01]

Metrics

duration: 14min completed: 2026-10-23

Phase 5 Plan 1: Routing Workspace — RoutingSource Seam + Fixture Backend + polyline6 Codec Summary

@araharah/routing — the fifth buildless workspace landing the D-01 RoutingSource seam (fixture → wasm-router → valhalla ladder), the polyline6 codec proven against live OSRM geometry, 200 m-tolerance fixture matching with honest-null pending semantics, and a committed ODbL-headed empty fixture seed — 25/25 tests green in three environments.

Performance

• Duration: 14 min
• Started: 2026-10-23T20:50:09Z
• Completed: 2026-10-23T21:04:00Z
• Tasks: 3/3
• Files modified: 16 (14 created, 2 modified)

Accomplishments

• The routing seam exists (D-01): RoutingSource + the full route model (RoutePoint → RouteResult) with the D-07 day-one fields typed and grep-pinned by tests (cumulativeDistanceM, steps: RouteStep[], the GUID-05/06 obligation note) — plans 05-02/05-04/05-05 and Phase 6 import these exact names.
• Backend #1 works end-to-end (D-02/D-03): fixture matching law (destinationId equality + 200 m haversine origin tolerance), best-first option order, steps: [] always (T-05-07), defensive malformed-pair skip, lazy memoized index (LAW 1), static JSON import (LAW 2), zero logging/storage/network (LAW 3).
• The polyline6 codec is proven against external ground truth (RESEARCH Finding 1): 8 vector cases including the live OSRM demo geometry (decode byte-exact + full-string round-trip) and the truncated-varint refusal law (T-05-02).
• Three-environment loader proof (Phase 4's top mechanical risk pattern): bare Node 24 static JSON import (L1), esbuild bundle inline marker router.project-osrm.org (L2), default source serving honest null from the committed seed (L3).
• Zero-dependency posture verified mechanically: no dependencies field (C5), zero banned tokens in routing/src with comments stripped (C4), zero imports in the codec.

Task Commits

Each task followed RED→GREEN with atomic commits:

1. task 1: workspace scaffold + type contracts + day-one fields
   • 69b6a20 test(05-01): scaffold routing workspace with failing contract suite (RED)
   • c92a955 feat(05-01): RoutingSource contract + day-one route model + fixture seed schema (GREEN)
2. task 2: polyline6 codec (pure, zero-dependency)
   • 9b66f90 test(05-01): add failing polyline6 codec vectors (P1-P8) (RED)
   • 4acb878 feat(05-01): polyline6 codec (pure, zero-dependency) (GREEN)
3. task 3: geo math + fixture backend + lazy loader + public API + three-environment proof
   • 0599ffe test(05-01): add failing fixture-source + loader-env suites (F1-F8, L1-L3) (RED)
   • 3e0c5e3 feat(05-01): geo math + fixture RoutingSource backend + public API (GREEN)

Files Created/Modified

• routing/src/types.ts — the seam + route model; D-01 ladder and D-03 null contract in the header; D-07 day-one fields documented with the GUID-05/06 obligation verbatim; RouteFixturesFile dataset envelope
• routing/src/polyline.ts — polyline6 codec; pure (zero imports), double-math varints (no int32 wrap), throws on truncated input
• routing/src/geo.ts — haversineM (R = 6 371 000 m) + deriveCumulativeDistanceM ([0] === 0, non-decreasing)
• routing/src/fixture-source.ts — backend #1: ORIGIN_TOLERANCE_M = 200, createFixtureRoutingSource(data?), getPairOrigin, getPairs; slug guard first; lazy memoized index; defensive pair skip
• routing/src/index.ts — named-export public surface; subpath-with-extension import law documented (bare @araharah/routing resolves to NOTHING)
• routing/src/data/route-fixtures.json — committed EMPTY seed (pairs: []) with the ODbL _license/_attribution/_notice header and the router.project-osrm.org _source marker (T-05-06)
• routing/test/{runner,harness}.mjs — zero-dependency runner, copied verbatim from search/test
• routing/test/contract.test.mjs — C1–C6: seam shape, day-one field grep, null-contract doc grep, three zero-laws gate, zero-deps gate, ODbL header gate
• routing/test/polyline.test.mjs — P1–P8: hand-derived + external OSRM vectors, round-trip law, malformed refusal
• routing/test/fixture-source.test.mjs — F1–F8: matching law, tolerance boundary, slug guard, honest null, malformed skip, lazy-index source gate, getPairOrigin
• routing/test/loader-env.test.mjs — L1–L3: bare Node, esbuild inline marker, default-source honest null
• routing/package.json + routing/tsconfig.json — manifest + platform-neutral tsconfig (search/ shapes)
• package.json (root) — workspaces + routing:test/routing:typecheck/routing:corpus delegates (corpus target lands with 05-02's script)
• package-lock.json — routing workspace registered

Decisions Made

• polyline.ts declares a structural PolyPoint instead of importing RoutePoint — the plan's acceptance gate requires zero from " occurrences in the codec file, and a import type line would violate it; structural identity is fully type-compatible at every consumer.
• F8's positive half is a visible SKIP while the committed seed is empty (its lookup target only exists after 05-02 populates the corpus). The negative/garbage halves are fully asserted now; the positive half arms automatically once pairs land. This mirrors the loader-env L2/L3 conditional-skip precedent.
• RouteFixturesFile exported from types.ts (an 11th interface beyond the plan's listed ten) — createFixtureRoutingSource(data?) needs a public parameter type for tests and 05-02's corpus runner. index.ts re-exports kept exactly per plan.

Deviations from Plan

Auto-fixed Issues

None — no bugs, no blocking issues. The three items above are judgment calls within the plan's stated laws, documented for the verifier.

Known Stubs

• routing/src/data/route-fixtures.json pairs: [] — intentional per plan ("plan 05-02 populates it via the build-time script"). Until then the committed corpus serves honest nulls (F1/L3 pin this). Resolved by plan 05-02; no UI surface consumes fixtures before 05-04.

Threat Surface Scan

No new surface beyond the plan's <threat_model>: no network endpoints, no auth paths, no storage, no schema at trust boundaries. All six register entries (T-05-01/02/03/04/06/07) have implemented mitigations covered by gates C4, P7, F4, the in-code backend selection, C6, and F2 respectively. No threat flags.

Issues Encountered

• Node lives under nvm in this environment and non-interactive shells start without it — every verification command sourced ~/.nvm/nvm.sh first. No project impact.

User Setup Required

None — no external service configuration required. (The OSRM demo server is touched only by 05-02's maintainer script, not by this plan.)

Next Phase Readiness

• 05-02 (fixtures corpus): imports getPairs/getPairOrigin/codec round-trip for the corpus gate; root delegate routing:corpus already points at routing/scripts/route-corpus.mjs (to be created); the committed seed schema is the write target.
• 05-04 (web route surface): imports createFixtureRoutingSource + model types from @araharah/routing/src/index.ts (subpath-with-extension law documented in the module header).
• 05-05 (gates): ?fixpair= knob reads getPairOrigin; the C4 banned-token gate is designed to grow with the corpus script.

---

Phase: 05-routing-route-display Completed: 2026-10-23

Self-Check: PASSED

• All 14 created files verified present on disk.
• All 6 plan commits verified in git log (69b6a20, c92a955, 9b66f90, 4acb878, 0599ffe, 3e0c5e3).
• npm run routing:test: 25 passed, 0 failed. npm run routing:typecheck: exit 0.
• Root delegates verified from repo root; workspaces contains routing.
• STATE.md and ROADMAP.md untouched (orchestrator-owned writes).