arah2/.planning/phases/08-alt-landmark-preprocessing-routing-backend-v2/08-01-SUMMARY.md

phase, plan, subsystem, tags, requires, provides, affects, tech-stack, key-files, key-decisions, patterns-established, requirements-completed, duration, completed

phase	plan	subsystem	tags	requires	provides	affects	tech-stack	key-files	key-decisions	patterns-established	requirements-completed	duration	completed
08-alt-landmark-preprocessing-routing-backend-v2	01	routing	alt landmark astar cpu-gate measurement baseline arg1 fixture	phase provides 06-turn-by-turn-guidance-live-driving engine A (bidirectional routeAstar), the CPU gate (measure-route-cpu.mjs), the real KL binary, the A1 equivalence sweep phase provides 07-hardening-private-launch budget-audit (the zero-arg CLI contract the extended flag must preserve)	committed pre-ALT optimality baseline (routing/test/fixtures/alt-baseline.json — 100 coordinate-pinned pairs, seconds + verdict classes, epsilon block) — the D-03 comparison anchor the baseline recorder (routing/scripts/measure-optimality-baseline.mjs) with the exported generateCrossMetroPairs/measureBaselinePairs core the frozen ARG1 rejection vector (routing/test/fixtures/mini-graph-arg1.bin) — Plan 08-02's G-suite consumes it the --extended D-04 verdict on measure-route-cpu.mjs (default zero-arg mode byte-compatible)	08-02 (ARG2 codec + fixture regen) 08-05 (optimality gate + CPU verdicts) budget-audit	added patterns exported measurement core + CLI guard (route-corpus pattern) — one pair-set definition, two consumers (baseline recorder + extended CPU verdict) immutable committed record with refuse-overwrite + ARG-version guard (the recorder refuses any binary that is not ARG1 — a post-codec run can never fake the pre-ALT baseline)	created modified routing/scripts/measure-optimality-baseline.mjs routing/test/fixtures/alt-baseline.json routing/test/fixtures/mini-graph-arg1.bin routing/scripts/measure-route-cpu.mjs (--extended flag + usage doc) routing/test/fixtures/build-mini-graph.mjs (one provenance comment)	Baseline measured FIRST, before the ARG2 codec lands (research Pitfall 1) — the record pins 100 pairs by COORDINATES (never node indices, Pitfall 2) with f64-exact seconds (A8) The recorder reads the binary's version field and refuses anything that is not ARG1 — mechanical enforcement of the measure-first law (beyond the plan text; the plan's version-record field made the guard natural) straightLineKm computed from the ROUNDED (committed) coordinates so the record is reproducible from itself alone Extended verdict runs one unmeasured warm-up (same warm-isolate law as the default mode — the reverse-CSR build must not land inside a sample)	Shared seeded pair set: seed 0x08a1 + min 12 km + count 100 — the baseline record and the --extended CPU verdict measure IDENTICAL pairs (verified: 53/100 routed in both) Honest nulls are measurements: unsnappable/unreachable rows carry seconds: null + a verdict class, never skipped silently	SC3 SC4	~45min	2026-10-25

Plan 08-01: Wave-0 Measurement Instrumentation — Summary

The pre-ALT optimality baseline is committed (100 coordinate-pinned pairs, 53 routed with f64 seconds, ±0.1% epsilon block, immutable), the ARG1 fixture bytes are frozen as the decode-rejection vector, and the CPU gate gained the D-04 extended verdict — which measured the honest pre-ALT FAIL (p95 98.9 ms, n=53) that Plan 08-05's post-ALT verdict will answer.

Performance

• Duration: ~45 min
• Completed: 2026-10-25
• Tasks: 3/3
• Files modified: 5 (3 created, 2 modified)

Accomplishments

• The D-03 anchor exists and is immutable: alt-baseline.json records 100 seeded cross-metro pairs (seed 0x08a1, ≥12 km straight-line) as origin/destination coordinates + route seconds + verdict class — 53 reachable (mean 1521.3 s, max 2308.0 s), 6 unreachable, 41 unsnappable (honest nulls are measurements, never skips). Re-running the recorder exits 1 ("the record is immutable; delete by explicit git revert only").
• Pitfall 1 is closed mechanically: the recorder reads the binary's version field and refuses any non-ARG1 binary — after 08-02 lands, a v2 decode would succeed, and without this guard a post-codec run could silently fake the pre-ALT baseline.
• The pair-set identity is proven in the field: the --extended CPU verdict routes the exact same 100 pairs from the recorder's exported generateCrossMetroPairs — 53/100 routed in both, same snap behavior.
• The measured before-number exists: extended verdict p95 98.896 ms (max 102.056, mean 60.719, n=53 routed; 47 honest probes at mean 0.491 ms) → GATE FAIL … D-04 extended verdict, exit 1. This is the c3 evidence 08-05's post-ALT PASS retires.

Task Commits

1. task 1: Preserve ARG1 fixture bytes as the rejection vector — 0fca2e0 (feat)
2. task 2: Baseline recorder + the committed pre-ALT record — 643df1a (feat)
3. task 3: --extended flag on the CPU gate — 477961a (feat)

Files Created/Modified

• routing/scripts/measure-optimality-baseline.mjs — the recorder: exported generateCrossMetroPairs + measureBaselinePairs core, CLI guard (route-corpus pattern), refuse-overwrite + ARG1-version guards, collect-then-write
• routing/test/fixtures/alt-baseline.json — THE committed record (immutable; epsilon ±0.1%; argVersion 1)
• routing/test/fixtures/mini-graph-arg1.bin — byte-identical copy of the current ARG1 mini-graph.bin (cmp-verified); never regenerated
• routing/scripts/measure-route-cpu.mjs — --extended dispatch after the graph decode; per-pair + p95 + GATE (PASS|FAIL) … D-04 extended verdict lines; exit 1 on FAIL (same honest law); default zero-arg mode byte-compatible
• routing/test/fixtures/build-mini-graph.mjs — one provenance comment naming mini-graph-arg1.bin as the frozen rejection vector

Decisions Made

• ARG-version guard on the recorder (beyond the plan text): the plan records argVersion: 1 in the schema; making the recorder enforce it (read version @4, refuse ≠ 1) turns Pitfall 1's warning into a mechanical law. Verified: the refusal branch exists before any measurement.
• straightLineKm from rounded coordinates: the emitted lat/lng are rounded to 1e-6 (the codec's grid law); computing the straight-line distance from the rounded values makes the record reproducible from itself alone.
• Warm-up in extended mode: the default mode's unmeasured warm-up exists so the reverse-CSR build never lands inside a sample; the extended verdict inherits the same law.
• Acceptance criteria met as written: 100 pairs, zero nodeIndex keys, epsilon 0.1, argVersion 1, refuse-overwrite exit 1, ≥90 routed-pair lines in extended mode (53 routed + 47 honest probe lines printed), budget-audit 19/19, default-mode regex shapes unchanged.

Deviations from Plan

Total deviations: 0 auto-fixed scope changes; 1 self-caught implementation slip (never committed):

• During task 3, an edit momentarily replaced measure-route-cpu.mjs's getEntries import (used by the default mode's corpus sampling) instead of adding the new imports alongside it. Caught immediately, restored in the next edit, and the default mode was re-verified byte-compatible (p95: + GATE shapes, exit 1 on FAIL) before committing.

Impact on plan: none — all three tasks landed exactly as specified.

Issues Encountered

• 41/100 baseline pairs are unsnappable (random bbox points legitimately land off-road: water, forest, non-graph areas). This is the plan's designed honest-null class, not a defect — the D-03 gate (08-05) treats old-unsnappable → new-routed as counted "re-snapped" info with a printed warning, and reachable/unreachable flips as violations.
• The pre-ALT extended GATE FAIL (98.9 ms p95) is the EXPECTED Wave-1 measurement — a FAIL exit here is a valid measurement (the plan says so verbatim); the post-ALT answer belongs to Plan 08-05.

Verification Log

• cmp mini-graph.bin mini-graph-arg1.bin → identical; git diff --stat on mini-graph.bin empty
• npm run routing:test → 65 passed, 0 failed (after every task commit)
• Record schema check → 100 pairs, all endpoints {lat, lng}, zero nodeIndex, epsilon 0.1, argVersion 1
• Recorder re-run → exit 1, immutable-record message
• node routing/scripts/measure-route-cpu.mjs --extended → per-pair lines + p95: 98.896 ms … n=53 + GATE FAIL … D-04 extended verdict, exit 1
• node routing/scripts/measure-route-cpu.mjs (no args) → unchanged shapes (p95: 85.252 ms (max …, mean …, n=22)), exit 1 on FAIL
• node scripts/test/budget-audit.test.mjs → BUDGET-AUDIT SUITE: 19/19 vectors ok