chore(planning): 08-01 summary — wave 0 complete (baseline record committed, ARG1 vector frozen, extended verdict measured); state synced
This commit is contained in:
araharah-executor
@@ -0,0 +1,110 @@
|
||||
---
|
||||
phase: 08-alt-landmark-preprocessing-routing-backend-v2
|
||||
plan: 01
|
||||
subsystem: routing
|
||||
tags: [alt, landmark, astar, cpu-gate, measurement, baseline, arg1, fixture]
|
||||
|
||||
requires:
|
||||
- phase: 06-turn-by-turn-guidance-live-driving
|
||||
provides: engine A (bidirectional routeAstar), the CPU gate (measure-route-cpu.mjs), the real KL binary, the A1 equivalence sweep
|
||||
- phase: 07-hardening-private-launch
|
||||
provides: budget-audit (the zero-arg CLI contract the extended flag must preserve)
|
||||
provides:
|
||||
- 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)
|
||||
affects: [08-02 (ARG2 codec + fixture regen), 08-05 (optimality gate + CPU verdicts), budget-audit]
|
||||
|
||||
tech-stack:
|
||||
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)"
|
||||
|
||||
key-files:
|
||||
created:
|
||||
- routing/scripts/measure-optimality-baseline.mjs
|
||||
- routing/test/fixtures/alt-baseline.json
|
||||
- routing/test/fixtures/mini-graph-arg1.bin
|
||||
modified:
|
||||
- routing/scripts/measure-route-cpu.mjs (--extended flag + usage doc)
|
||||
- routing/test/fixtures/build-mini-graph.mjs (one provenance comment)
|
||||
|
||||
key-decisions:
|
||||
- "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)"
|
||||
|
||||
patterns-established:
|
||||
- "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"
|
||||
|
||||
requirements-completed: [SC3, SC4]
|
||||
|
||||
duration: ~45min
|
||||
completed: 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`
|
||||
Reference in New Issue
Block a user