---
phase: 08.1-contraction-hierarchies-routing-backend-v3-the-lever-that-cl
plan: 03
type: execute
wave: 3
depends_on:
- 08.1-02
files_modified:
- docs/ROAD-GRAPH.md
- docs/BUDGETS.md
- docs/KNOWN-LIMITATIONS.md
- docs/ALT-DIRECTION-SPLIT.md
- routing/README.md
autonomous: true
requirements:
- D-01
- D-03
- D-06
- D-08
- D-09
- D-10
- D-13
must_haves:
truths:
- "The public ARG3 fork contract is documented field-by-field so a browser/webview consumer can decode the same asset without Node-specific assumptions."
- "The budget and known-limitations records state the measured CH verdict and never claim success when the measurement failed."
- "The direction-split potentials experiment is closed as superseded while its measured facts remain intact."
- "The repository's routing module map describes the CH data plane and contains no active ALT engine claim."
artifacts:
- path: "docs/ROAD-GRAPH.md"
provides: "ARG3 header/section contract, CH build facts, and CPU ladder record"
- path: "docs/BUDGETS.md"
provides: "Measured CH CPU verdict and retire-or-shrink c3 record"
- path: "docs/KNOWN-LIMITATIONS.md"
provides: "Honest cross-metro status after the CH measurement"
- path: "docs/ALT-DIRECTION-SPLIT.md"
provides: "Superseded closing header with historical measured facts preserved"
key_links:
- from: "docs/ROAD-GRAPH.md"
to: "routing/src/graph.ts"
via: "documented ARG3 header offsets and section order match the codec authority"
pattern: "ARG3|chShortcutCount|chRank"
- from: "docs/BUDGETS.md"
to: "routing/scripts/measure-route-cpu.mjs"
via: "quoted measured p95 and 8 ms budget come from the local gate output"
pattern: "p95|8 ms"
- from: "docs/ALT-DIRECTION-SPLIT.md"
to: "docs/BUDGETS.md"
via: "historical ALT facts retained while the post-CH verdict lives in the budget record"
pattern: "Phase 8|superseded"
---
Close the phase with an honest public record: the ARG3 fork contract, the measured CH build and CPU facts, the retire-or-shrink c3 verdict, and the superseded direction-split experiment.
Purpose: The phase's value depends on truthful engineering records. A passing implementation with a stale or optimistic document would preserve the exact failure mode Phase 8 exposed.
Output: Updated road-graph contract, budgets, known limitations, ALT experiment closure, and routing module map.
@$HOME/.config/opencode/get-shit-done/workflows/execute-plan.md
@$HOME/.config/opencode/get-shit-done/templates/summary.md
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
@.planning/phases/08.1-contraction-hierarchies-routing-backend-v3-the-lever-that-cl/08.1-CONTEXT.md
@.planning/phases/08.1-contraction-hierarchies-routing-backend-v3-the-lever-that-cl/08.1-RESEARCH.md
@.planning/phases/08.1-contraction-hierarchies-routing-backend-v3-the-lever-that-cl/08.1-PATTERNS.md
@.planning/phases/08.1-contraction-hierarchies-routing-backend-v3-the-lever-that-cl/08.1-VALIDATION.md
@docs/ROAD-GRAPH.md
@docs/BUDGETS.md
@docs/KNOWN-LIMITATIONS.md
@docs/ALT-DIRECTION-SPLIT.md
@routing/README.md
task 1: document the ARG3 fork contract and measured build facts
docs/ROAD-GRAPH.md, routing/README.md
- docs/ROAD-GRAPH.md
- routing/README.md
- routing/src/graph.ts
- routing/scripts/build-road-graph.mjs
- routing/scripts/measure-route-cpu.mjs
- .planning/phases/08.1-contraction-hierarchies-routing-backend-v3-the-lever-that-cl/08.1-RESEARCH.md
In `docs/ROAD-GRAPH.md`, replace the ARG2 layout section with an ARG3 section that is the public fork contract required by D-10. Document these exact facts:
- magic `0x41524733` ("ARG3"), version 3, header size 72 bytes, little-endian only.
- The header field table with byte offsets: magic @0 u32, version @4 u32, nodeCount @8 u32, edgeCount @12 u32, nameCount @16 u32, namePoolLen @20 u32, bbox @24 as four f64 values, maxSpeedKmh @56 f32, chShortcutCount @60 u32, reserved0 @64 u32, reserved1 @68 u32.
- The section order: lat[N] ++ lng[N] ++ edgeStart[N+1] ++ edgeTarget[E] ++ edgeFlags[E] ++ edgeSeconds[E] ++ edgeNameId[E] ++ nameOffset[M+1] ++ namePool ++ chRank[N] ++ shortcutStart[N+1] ++ shortcutTarget[S] ++ shortcutSeconds[S] ++ shortcutVia[S].
- The alignment law: header 72 bytes keeps f64 views 8-byte aligned; every u32/f32 section starts at a 4-byte boundary using `(offset + 3) & ~3`.
- The decode law: only exact ARG3 bytes decode; `chShortcutCount === 0`, any size mismatch, and ARG1/ARG2 bytes return null and route to the designed router-pending state. There is no version fallback branch.
- The semantics of each CH field: `chRank[u]` is the contraction position (0 contracted first, a strict total order); `shortcutStart` is the shortcut CSR row pointer array; `shortcutTarget` is the shortcut head; `shortcutSeconds` is the shortcut's f32 seconds; `shortcutVia` is the contracted midpoint used to unpack the shortcut recursively.
- The phone-first browser-decodability statement: little-endian typed arrays only, no Node-specific alignment assumptions, so Phase 11's webview can decode this same asset.
- The build-artifact discipline: the hierarchy is valid only for the exact topology and edge weights it was built against; a graph edit requires a full rebuild and re-upload under the unchanged key `kl-roadgraph.v1.bin`.
In the same file, update the CPU ladder table and key-facts table to include the CH rung with the measured values from Plan 02: contracted node count, shortcut count and ratio per node, witness search count and budget hits, CH-section bytes, total ARG3 bytes, build wall-clock, 25-route p95, and extended 100-route p95. State the verdict as measured: retired below 8 ms, or the c3 class remains. Do not describe an unmeasured or projected number as measured.
In `routing/README.md`, update the module map to list `contraction.ts` as the build-time CH core and `ch-query.ts` as the request-time uphill query, remove `landmark.ts` if present, and describe `graph.ts` as the ARG3 codec. Do not add a new dependency or install instruction.
grep -q 'ARG3' docs/ROAD-GRAPH.md && grep -q 'chShortcutCount' docs/ROAD-GRAPH.md && grep -q 'shortcutVia' docs/ROAD-GRAPH.md && grep -q 'contraction.ts' routing/README.md && ! grep -q 'landmark.ts' routing/README.md
- `docs/ROAD-GRAPH.md` contains `ARG3`, `0x41524733`, `chShortcutCount`, `chRank`, `shortcutStart`, `shortcutTarget`, `shortcutSeconds`, `shortcutVia`, and `72`.
- `docs/ROAD-GRAPH.md` contains the byte offset `60` for `chShortcutCount` and `68` for `reserved1`.
- `docs/ROAD-GRAPH.md` contains the measured p95 values copied from Plan 02's recorded gate output.
- `routing/README.md` contains `contraction.ts` and `ch-query.ts` and contains no `landmark.ts`.
A browser-oriented fork contract fully describes ARG3, and the routing module map reflects the CH data plane truthfully.
task 2: record the measured c3 verdict and close the direction-split experiment
docs/BUDGETS.md, docs/KNOWN-LIMITATIONS.md, docs/ALT-DIRECTION-SPLIT.md
- docs/BUDGETS.md
- docs/KNOWN-LIMITATIONS.md
- docs/ALT-DIRECTION-SPLIT.md
- docs/ROAD-GRAPH.md
- .planning/phases/08.1-contraction-hierarchies-routing-backend-v3-the-lever-that-cl/08.1-CONTEXT.md
- .planning/phases/08-alt-landmark-preprocessing-routing-backend-v2/08-05-SUMMARY.md
Update `docs/BUDGETS.md` section c3 using the measured outputs from Plan 02. The new record must include:
- The CH build facts: contracted nodes, shortcut count, ratio per node, witness searches and budget hits, CH-section bytes, total ARG3 bytes, and build wall-clock.
- The CH CPU facts: the 25-route p95 and the extended 100-route p95 exactly as printed by the local gate, alongside the unchanged 8 ms product budget and the 10 ms free-plan ceiling.
- The verdict in D-01's exact terms: if p95 is below 8 ms, write that the c3 class RETIRED because the measured CH p95 landed under the 8 ms budget; if p95 is at or above 8 ms, write that the c3 class REMAINS and that the $0 lever ladder is documented as a dead end, not a failure.
- The new drift guard value if the class retired, described as approximately 2x the measured CH p95. If it did not retire, state that the previous guard remains.
- The optimality evidence: D-03 gate green within ±0.1% and the 200-pair oracle sweep with zero SUBOPTIMAL, zero ORACLE-MISMATCH, and zero class breaks.
- The local-only evidence scope per D-02, including the documented host variance, and no claim of a deployed-Worker measurement.
Update `docs/KNOWN-LIMITATIONS.md` so the cross-metro section reflects the measured CH state: remove the active ALT roadmap pointer, replace it with the CH verdict, and state whether cross-metro routing is now within budget, still in the c3 honest-degradation class, or otherwise limited by the measured result. Keep the existing honest-limitations tone; do not claim a traffic-confidence, lane-guidance, or turn-restriction capability.
Update `docs/ALT-DIRECTION-SPLIT.md` with a closing header stating: `Status: SUPERSEDED by Phase 08.1 Contraction Hierarchies (2026-10-26)` and a short paragraph explaining that CH closes SC-1 at a lower proof burden because its optimality needs no new meet-rule proof. Preserve the entire measured-facts table and the one-directional-Lipschitz law below the header; the facts remain the historical record of why CH was chosen. Do not delete the existing analysis.
Also update the ALT roadmap-pointer row in `docs/KNOWN-LIMITATIONS.md` and any ALT phase pointer in `docs/BUDGETS.md` so no document tells the reader that ALT is the active engine or that the direction-split experiment is still open.
grep -q 'SUPERSEDED' docs/ALT-DIRECTION-SPLIT.md && grep -q 'CH' docs/BUDGETS.md && grep -q 'CH' docs/KNOWN-LIMITATIONS.md && ! grep -qi 'direction-split potentials.*still open' docs/KNOWN-LIMITATIONS.md
- `docs/ALT-DIRECTION-SPLIT.md` contains `SUPERSEDED by Phase 08.1 Contraction Hierarchies` and still contains its original measured-facts table rows.
- `docs/BUDGETS.md` contains the measured CH p95 value copied from Plan 02, the literal `8 ms`, and the words `CH` and `ARG3`.
- `docs/BUDGETS.md` states either `RETIRED` or `REMAINS` for the c3 class, matching Plan 02's measured verdict.
- `docs/KNOWN-LIMITATIONS.md` contains `CH` and no longer presents ALT as the active engine.
- `grep -c 'Contraction Hierarchies' docs/ALT-DIRECTION-SPLIT.md` is at least 1.
The records carry the measured CH truth, the c3 verdict matches the gate output, and the direction-split experiment is closed without erasing its historical facts.
## Trust Boundaries
| Boundary | Description |
|----------|-------------|
| Public fork contract -> external implementer | docs/ROAD-GRAPH.md is the interface a fork or Phase 11 browser decoder relies on; an inaccurate offset table produces silent misdecoding. |
| Measurement output -> published engineering record | Numbers copied into docs are the evidence for SC-1 closure; paraphrase or stale values could retire the c3 class dishonestly. |
## STRIDE Threat Register
| Threat ID | Category | Component | Disposition | Mitigation Plan |
|-----------|----------|-----------|-------------|-----------------|
| T-08.1-16 | Tampering | Public ARG3 header/section documentation | mitigate | The documented offsets are copied from `routing/src/graph.ts`, and acceptance criteria require the exact offsets 0, 4, 8, 12, 16, 20, 24, 56, 60, 64, 68 plus the full section order and the alignment law. |
| T-08.1-17 | Repudiation | Published budget claim differing from the measured gate output | mitigate | The plan requires copying the exact printed p95, byte, and wall-clock values from Plan 02's campaign; acceptance criteria require the literal `8 ms` and an explicit RETIRED/REMAINS verdict. |
| T-08.1-18 | Tampering | Erosion of the one-directional-Lipschitz historical facts | accept | D-06 intentionally preserves the historical measured facts; the risk is editorial, not technical. The closing header is additive and the existing analysis must remain intact. |
| T-08.1-19 | Information Disclosure | Public docs exposing user location | accept | The documents contain only road-network geometry, build statistics, and public bbox-derived measurements; no user coordinates, chat ids, or route payloads are added. |
Manually read and compare the four record surfaces against the Plan 02 measurement output, then run:
```bash
grep -q 'ARG3' docs/ROAD-GRAPH.md
grep -q 'chShortcutCount' docs/ROAD-GRAPH.md
grep -q 'SUPERSEDED' docs/ALT-DIRECTION-SPLIT.md
grep -q 'CH' docs/BUDGETS.md
grep -q 'CH' docs/KNOWN-LIMITATIONS.md
npm run routing:test
```
Expected: all greps succeed and the routing suite remains green.
- The ARG3 header and section contract is documented exactly and is browser-decodable by construction.
- The build bytes, shortcut ratio, wall-clock, and both CPU p95 values in the docs match the measured Plan 02 output verbatim.
- The c3 class record says RETIRED or REMAINS exactly as the measurement dictates.
- The direction-split experiment is marked superseded with its measured facts intact.
- No document claims ALT is the active engine or that a deployed-Worker CPU probe was performed.