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.
path
provides
docs/ROAD-GRAPH.md
ARG3 header/section contract, CH build facts, and CPU ladder record
path
provides
docs/BUDGETS.md
Measured CH CPU verdict and retire-or-shrink c3 record
path
provides
docs/KNOWN-LIMITATIONS.md
Honest cross-metro status after the CH measurement
path
provides
docs/ALT-DIRECTION-SPLIT.md
Superseded closing header with historical measured facts preserved
from
to
via
pattern
docs/ROAD-GRAPH.md
routing/src/graph.ts
documented ARG3 header offsets and section order match the codec authority
ARG3|chShortcutCount|chRank
from
to
via
pattern
docs/BUDGETS.md
routing/scripts/measure-route-cpu.mjs
quoted measured p95 and 8 ms budget come from the local gate output
p95|8 ms
from
to
via
pattern
docs/ALT-DIRECTION-SPLIT.md
docs/BUDGETS.md
historical ALT facts retained while the post-CH verdict lives in the budget record
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.
@.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.
<threat_model>
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.
</threat_model>
Manually read and compare the four record surfaces against the Plan 02 measurement output, then run:
