205 lines
14 KiB
Markdown
205 lines
14 KiB
Markdown
---
|
|
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"
|
|
---
|
|
|
|
<objective>
|
|
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.
|
|
</objective>
|
|
|
|
<execution_context>
|
|
@$HOME/.config/opencode/get-shit-done/workflows/execute-plan.md
|
|
@$HOME/.config/opencode/get-shit-done/templates/summary.md
|
|
</execution_context>
|
|
|
|
<context>
|
|
@.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
|
|
</context>
|
|
|
|
<tasks>
|
|
|
|
<task type="auto">
|
|
<name>task 1: document the ARG3 fork contract and measured build facts</name>
|
|
<files>docs/ROAD-GRAPH.md, routing/README.md</files>
|
|
<read_first>
|
|
- 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
|
|
</read_first>
|
|
<action>
|
|
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.
|
|
</action>
|
|
<verify>
|
|
<automated>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</automated>
|
|
</verify>
|
|
<acceptance_criteria>
|
|
- `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`.
|
|
</acceptance_criteria>
|
|
<done>A browser-oriented fork contract fully describes ARG3, and the routing module map reflects the CH data plane truthfully.</done>
|
|
</task>
|
|
|
|
<task type="auto">
|
|
<name>task 2: record the measured c3 verdict and close the direction-split experiment</name>
|
|
<files>docs/BUDGETS.md, docs/KNOWN-LIMITATIONS.md, docs/ALT-DIRECTION-SPLIT.md</files>
|
|
<read_first>
|
|
- 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
|
|
</read_first>
|
|
<action>
|
|
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.
|
|
</action>
|
|
<verify>
|
|
<automated>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</automated>
|
|
</verify>
|
|
<acceptance_criteria>
|
|
- `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.
|
|
</acceptance_criteria>
|
|
<done>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.</done>
|
|
</task>
|
|
|
|
</tasks>
|
|
|
|
<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>
|
|
|
|
<verification>
|
|
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.
|
|
</verification>
|
|
|
|
<success_criteria>
|
|
- 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.
|
|
</success_criteria>
|
|
|
|
<output>
|
|
After completion, create `.planning/phases/08.1-contraction-hierarchies-routing-backend-v3-the-lever-that-cl/08.1-03-SUMMARY.md`
|
|
</output>
|