chore(planning): 08-03 summary — ALT potentials live, rollout pins committed (full battery green); state synced to 08-04
This commit is contained in:
araharah-executor
@@ -0,0 +1,115 @@
|
||||
---
|
||||
phase: 08-alt-landmark-preprocessing-routing-backend-v2
|
||||
plan: 03
|
||||
subsystem: routing
|
||||
tags: [alt, landmarks, astar, bidirectional, potentials, sentinel, typed-arrays, structural-pins, tdd]
|
||||
|
||||
requires:
|
||||
- phase: 08-alt-landmark-preprocessing-routing-backend-v2 (plan 08-02)
|
||||
provides: the ARG2 RoadGraph fields (landmarkCount/landmarkQuantumS/landmarkTo/landmarkFrom) the potential consumes, and landmark.ts's table builder the A-suite fixtures flow through
|
||||
- phase: 06-turn-by-turn-guidance-live-driving
|
||||
provides: the proven BH skeleton (reductions, balanced alternation, meet probes, stop rule, real-seconds reconstruction) this plan leaves byte-identical, and A1's 625-pair Dijkstra-equivalence seal
|
||||
|
||||
provides:
|
||||
- ALT steering live inside routeAstar — per-search Float64Array(L) constant tables in quanta (0xFFFF → NaN = search-scoped landmark drop), lazy per-node max over the four triangle families with RAW u16 sentinel compares, haversine max-fallback (Pattern 3 containment)
|
||||
- the A-suite extended to A1–A11 — A9 island sweep (169 pairs, anchors pinned in one component), A10 search-scoped-skip sweep (16 anchorless pairs), A11 structural pin (landmark-table reads in CODE, one sentinel spelling)
|
||||
- routing/test/rollout.test.mjs — RO1 upload-format-agnostic + RO2 one-decode-path structural pins: the D-01 rollout locks enforced suite-side (T-08-08), not customary
|
||||
- the optimality seal re-proven under ALT — A1's exhaustive 625-pair Dijkstra-equivalence sweep green with the potentials live
|
||||
affects: [08-04 (build script landmark stage feeds these tables at KL scale), 08-05 (CPU gate + optimality campaign measures THIS search), docs retirement record (c3 class evidence)]
|
||||
|
||||
tech-stack:
|
||||
added: []
|
||||
patterns:
|
||||
- "ALT max-rule: h = max(haversine bound, best triangle bound) — max of two consistent admissible heuristics stays consistent + admissible; sentinel-flooded nodes degrade to exactly the pre-ALT behavior"
|
||||
- "search-scoped skip law: landmark drop decisions live ONLY in the per-search constant tables (0xFFFF stored as NaN); per-node sentinel cells just skip their ℓ — never a per-node ℓ-mask mid-max (max-of-Lipschitz consistency)"
|
||||
- "raw-u16-before-float sentinel discipline: `tv === 0xffff` on the Uint16Array read, one spelling (never the decimal), so the sentinel can never masquerade as a finite bound"
|
||||
|
||||
key-files:
|
||||
created:
|
||||
- routing/test/rollout.test.mjs
|
||||
modified:
|
||||
- routing/src/astar.ts (potential() + its init + doc-comments ONLY — every other function pinned)
|
||||
- routing/test/astar.test.mjs (case index A1–A11, buildIslandFixture helper, A9/A10/A11)
|
||||
|
||||
key-decisions:
|
||||
- "The per-direction ℓ-loop factored into one local `bound()` helper (plan allows executor naming/shape) — the two cache-miss branches mirror through it instead of duplicating the family loop; the pf tail stays byte-identical"
|
||||
- "A9/A10 written to PASS at RED as baseline-equivalence seals and to stay green as containment seals after the swap (the plan's TDD shape); A11 is the RED gate"
|
||||
- "A9's anchor set is HAND-PINNED ([0, 8] inside component A) through landmarkTables, never derived — the island precondition (every B cell 0xFFFF in both families) is asserted as a fixture law before the sweep"
|
||||
|
||||
patterns-established:
|
||||
- "Structural pins for rollout locks: RO1/RO2 copy A8's comment-stripping grep shape so a doc mention can never satisfy a format-agnosticism law"
|
||||
- "Seconds-only equivalence assertions for steering changes (never node-path equality) — D-03's tie law carried into every new case"
|
||||
|
||||
requirements-completed: [SC3, SC4]
|
||||
|
||||
duration: ~9min
|
||||
completed: 2026-10-25
|
||||
---
|
||||
|
||||
# Phase 8 Plan 08-03: ALT Potentials + Rollout Pins Summary
|
||||
|
||||
**ALT steering is live in routeAstar — h_f/h_b are now max(ALT triangle bounds, haversine) over the ARG2 landmark tables inside the byte-identical BH skeleton, with A1's 625-pair Dijkstra-equivalence sweep re-proving optimality under ALT, dedicated island/skip containment cases, and RO1/RO2 pins locking the upload/router seams format-agnostic (routing 79/79 + bot 126/126 + both typechecks green).**
|
||||
|
||||
## Performance
|
||||
|
||||
- **Duration:** ~9 min (10:55–11:04 UTC)
|
||||
- **Started:** 2026-10-25T10:55:12Z
|
||||
- **Completed:** 2026-10-25T11:04:00Z
|
||||
- **Tasks:** 2/2 (task 1 with full RED→GREEN gate commits)
|
||||
- **Files modified:** 3 (1 created, 2 modified)
|
||||
|
||||
## Accomplishments
|
||||
|
||||
- **The entire runtime change of Phase 8 landed in one function**: `routeAstar`'s `potential()` now derives h_f/h_b from `graph.landmarkTo`/`landmarkFrom`/`landmarkQuantumS` — four per-search constant tables hoisted in quanta (0xFFFF written as NaN drops that landmark for the WHOLE search), then a lazy per-node max over the four triangle families (toward-goal A/B, toward-origin A/B) with RAW u16 sentinel compares before any float conversion, max-combined with the existing haversine bound. The (h_f−h_b)/2 combination, reductions, balanced alternation, meet probes, stop rule, and real-seconds reconstruction are byte-identical — the survey's (πf−πr)/2 is what p_f already was.
|
||||
- **Optimality re-proven under ALT**: A1's exhaustive 25×25 = 625-pair brute-force Dijkstra-equivalence sweep is green with the potentials live, plus A9 (169-pair island sweep: A-internal pairs with real ALT bounds, B-internal pairs on the haversine fallback, 72 cross pairs → null) and A10 (16 anchorless-component pairs — all families dropped at search scope, still exactly optimal).
|
||||
- **The D-01 rollout locks are mechanical**: new `rollout.test.mjs` pins upload-road-graph.mjs's KEY/BUCKET + zero format tokens in comment-stripped code (RO1), and worker-router.ts's unchanged GRAPH_KEY + exactly ONE decodeGraph call + no version branch (RO2) — the campaign (08-05) cannot silently grow format awareness (T-08-08 enforced, not customary).
|
||||
- **Full battery green at the final commit**: routing:test 79/79 (A1 seal + A9/A10/A11 + RO1/RO2 + untouched L/G/A/P/R/S suites), bot 126/126 — the FIRST commit where the RT trunks and guidance-cron run with ALT potentials reading real tables on their ARG2 corridor graphs — and routing+bot typechecks clean. `git diff --stat` on worker-router.ts and upload-road-graph.mjs is empty.
|
||||
|
||||
## Task Commits
|
||||
|
||||
Each task was committed atomically (task 1 carried its RED→GREEN gates):
|
||||
|
||||
1. **task 1: ALT potentials in routeAstar + the containment A-cases** — `92b97fc` (test, RED: A11 failing for the right reason, A9/A10 baseline-equivalent) → `ddd2f3c` (feat, GREEN)
|
||||
2. **task 2: Rollout pins (RO1/RO2) + the full-battery seal** — `8fac68b` (test)
|
||||
|
||||
## Files Created/Modified
|
||||
|
||||
- `routing/src/astar.ts` — ALT per-search constant tables + `bound()` helper + `potential()` swap + ALT doc paragraphs (module header + routeAstar BH block; Ikeda history intact); NO other function touched, no new imports
|
||||
- `routing/test/astar.test.mjs` — case index A1–A8 → A1–A11; `buildIslandFixture` (two-component synthetic whose tables flow through the ONE landmark module); A9 island sweep, A10 search-scoped-skip sweep, A11 structural pin (landmark tokens in comment-stripped CODE, one sentinel spelling, A8's no-Map law unchanged)
|
||||
- `routing/test/rollout.test.mjs` — created: RO1/RO2 structural pins in the harness's zero-dep shape
|
||||
|
||||
## Decisions Made
|
||||
|
||||
- **One `bound()` helper instead of a duplicated ℓ-loop**: the plan's sketch marks shape/naming as the executor's; both cache-miss branches mirror through the same allocation-free loop, keeping the family logic in exactly one place while the `const value = (hf - hb) / 2` tail stays byte-identical.
|
||||
- **A9/A10 pass at RED by design**: they assert seconds-only Dijkstra equivalence, which the pre-ALT haversine implementation already satisfies — they are baseline-equivalence at RED and containment seals at GREEN; A11 (structural) is the RED gate and fails for exactly the right reason ("must reference landmarkTo in code").
|
||||
- **Fixture anchors pinned, not derived**: `buildIslandFixture(anchors)` takes the anchor array and routes it through `landmarkTables` — the island precondition (every component-B cell is the 0xFFFF sentinel in both families) is asserted as a fixture law inside A9 before any routing assertion.
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
None - plan executed exactly as written. (One in-task compliance edit: the GREEN comment initially cited the sentinel's decimal value; the plan's own acceptance grep `65535 = 0` caught it before the commit — reworded, no behavior change, contained in `ddd2f3c`.)
|
||||
|
||||
## TDD Gate Compliance
|
||||
|
||||
Task 1 ran full RED→GREEN with separate commits: `92b97fc` (test — A11 FAIL verified for the right reason, 76/77 passing) BEFORE `ddd2f3c` (feat — 77/77). No gate skipped; no refactor commit needed (the swap landed clean).
|
||||
|
||||
## Issues Encountered
|
||||
|
||||
- None beyond the in-task comment reword above. The full battery passed on its first run after each gate.
|
||||
|
||||
## User Setup Required
|
||||
|
||||
None - no external service configuration required.
|
||||
|
||||
## Next Phase Readiness
|
||||
|
||||
- **08-04 (build script):** the preprocessing stage now has its live consumer — `build-road-graph.mjs` still encodes WITHOUT landmarks until its stage lands; once it emits ARG2 the real binary steers with these exact potentials.
|
||||
- **08-05 (campaign):** the search-side surface is final; the CPU gate (p95 ≤ 8) and the D-03 optimality gate measure THIS code. The D-02 remediation knob (raise L, rebuild) touches build parameters only — the reductions/stop rule are pinned untouched by A1/A8/A11 and RO1/RO2.
|
||||
- **Known state:** the real KL binary on disk is still ARG1 → decodes null → router-pending (designed, D-01) until 08-04/08-05 rebuild + re-upload; the committed fixtures all carry tables, so every suite surface runs ALT live.
|
||||
|
||||
---
|
||||
*Phase: 08-alt-landmark-preprocessing-routing-backend-v2*
|
||||
*Completed: 2026-10-25*
|
||||
|
||||
## Self-Check: PASSED
|
||||
|
||||
All 3 claimed files exist on disk; all 3 task commits (`92b97fc`, `ddd2f3c`, `8fac68b`) exist in git history. Final battery at `8fac68b`: routing:test 79/79, bot 126/126, routing:typecheck + bot:typecheck clean; `git diff --stat bot/src/routing/worker-router.ts routing/scripts/upload-road-graph.mjs` empty.
|
||||
@@ -42,8 +42,8 @@ created: 2026-10-25
|
||||
| ARG1 fixture preservation | 01 | 1 | D-01 | T-08-02 | old binary → decode null (fail-honest) | unit | `npm run routing:test` (G rejection case lands in 08-02) | ✅ W0 | ✅ green (bytes frozen) |
|
||||
| SC-1′ extended-sample flag | 01 | 1 | SC-1 (D-04) | — | N/A | measurement gate | `node routing/scripts/measure-route-cpu.mjs --extended` | ✅ W0 | ✅ green (pre-ALT honest FAIL: p95 98.9 ms, n=53) |
|
||||
| ARG2 codec G-suite | 02 | 2 | D-01/D-02 | T-08-01/02 | exact-size-before-allocation; version + landmarkCount laws; hostile header on tiny buffer rejects BEFORE view allocation | unit | `npm run routing:test` (G cases) | ✅ 08-02 | ✅ green (74/74; ARG1 vector + monster landmarkCount reject pre-allocation) |
|
||||
| ALT potentials A-suite (A1 re-pin + island A9/A10 + A11 pin) | 03 | 3 | SC-2 | T-08-05/06 | sentinel-safe potentials; equivalence sealed under ALT | unit (A1 625-pair sweep + new cases) | `npm run routing:test` (A cases) | ⚙ extends | ⬜ pending |
|
||||
| Rollout pins (upload-agnostic + GRAPH_KEY) | 03 | 3 | D-01 | T-08-08 | upload stays format-agnostic; loader keeps ONE decode path | structural grep (A8-shape) | `npm run routing:test` (RO1/RO2) | ❌ new | ⬜ pending |
|
||||
| ALT potentials A-suite (A1 re-pin + island A9/A10 + A11 pin) | 03 | 3 | SC-2 | T-08-05/06 | sentinel-safe potentials; equivalence sealed under ALT | unit (A1 625-pair sweep + new cases) | `npm run routing:test` (A cases) | ✅ 08-03 | ✅ green (RED `92b97fc` → GREEN `ddd2f3c`; A1 625 pairs + A9 169-pair island + A10 skip + A11 structural, ALT live) |
|
||||
| Rollout pins (upload-agnostic + GRAPH_KEY) | 03 | 3 | D-01 | T-08-08 | upload stays format-agnostic; loader keeps ONE decode path | structural grep (A8-shape) | `npm run routing:test` (RO1/RO2) | ✅ 08-03 | ✅ green (`8fac68b`; RO1/RO2 + full battery: routing 79/79, bot 126/126, both typechecks) |
|
||||
| Build preprocessing stage | 04 | 4 | SC-1 (D-02) | T-08-09/10/11 | coverage + quantum gates before write; L scaling rule | script gate | `node routing/scripts/build-road-graph.mjs` + `--check` | ⚙ extends | ⬜ pending |
|
||||
| Real ARG2 rebuild + check | 04 | 4 | SC-1 prereq | T-08-09 | envelope + coverage green on the real binary | script gate (network, maintainer-time) | `node routing/scripts/build-road-graph.mjs --check routing/data/kl-roadgraph.v1.bin` | ⚙ extends | ⬜ pending |
|
||||
| CPU gate + extended verdict | 05 | 5 | SC-1 | T-08-16 | print-the-measurement; pre-committed L ladder | measurement | `node routing/scripts/measure-route-cpu.mjs` (+ `--extended`) | ✅ extends | ⬜ pending |
|
||||
@@ -63,7 +63,7 @@ created: 2026-10-25
|
||||
- [x] `fixtures/mini-graph-arg1.bin` — bytes preserved from the current committed ARG1 fixture (decode-rejection vector) — DONE 08-01
|
||||
- [x] `fixtures/build-mini-graph.mjs` gains a landmark stage (tiny L; ARG2 output) — DONE 08-02 (L=2, anchors [0,18], quantum 0.1 s, coverage 1.0; byte-deterministic)
|
||||
- [x] New G cases (ARG2 codec + rejection matrix) — DONE 08-02 (G9–G11; island A case remains for 08-03)
|
||||
- [ ] Upload-unchanged structural pin case
|
||||
- [x] Upload-unchanged structural pin case — DONE 08-03 (RO1/RO2 in `routing/test/rollout.test.mjs`)
|
||||
|
||||
*Constraint re-verified in planning: `budget-audit` (Phase 7) re-runs `measure-route-cpu.mjs` — keep its CLI contract or account for the flag addition.*
|
||||
|
||||
|
||||
Reference in New Issue
Block a user