mirror of
https://github.com/gadgethd/ukmesh.git
synced 2026-09-03 13:53:43 +00:00
70 lines
2.5 KiB
Markdown
70 lines
2.5 KiB
Markdown
# Pathing
|
|
|
|
## Purpose
|
|
|
|
Pathing resolves packet routes into confident relay chains. The production
|
|
pipeline (2026-08) is the Viterbi champion (`vit_src`) from the pathing
|
|
experiment: it walks a candidate trellis built from 1-byte hop prefixes and
|
|
scores emissions/transitions from seven calibrated signals, including
|
|
positional prefix-frequency priors, corridor interpolation, and **ITM
|
|
terrain feasibility** (no hop is placed where line-of-sight physics rules it
|
|
out). Measured on the gold holdout set: **97.27% route accuracy / 99.24%
|
|
hop accuracy**.
|
|
|
|
## Main layers
|
|
|
|
- `backend/src/path-beta/`
|
|
- resolver implementation (`resolver.ts`) — Viterbi candidate trellis
|
|
- worker pool
|
|
- geometry helpers (terrain-aware arcs)
|
|
- fallback logic
|
|
- `backend/src/pathing/`
|
|
- service/repository orchestration for API-facing pathing endpoints
|
|
- `pathingPublicDto.ts` — the public DTO projector. **Any new resolver
|
|
field must be added here or the API silently drops it.**
|
|
- `backend/src/pathing/pathingService.ts`
|
|
- cache and resolver orchestration
|
|
|
|
## Production behaviour (2026-08-06)
|
|
|
|
- **Slow-mode resolution**: packets wait out their propagation window before
|
|
the path is finalised (`469c84e`), so late observations don't re-shape a
|
|
settled route.
|
|
- **Physics gates + held-path refinement** (`5dd15d9`): candidate hops that
|
|
violate physical feasibility are gated; held paths are refined in place.
|
|
- **Canonical path DTO**: `canonicalPath` is the authoritative route in API
|
|
responses; the frontend renders it as blue paths. Path identity colours
|
|
live-path arcs by the resolved packet (`f6f8290`).
|
|
- Terrain-aware live paths + airborne-hop markers (`a76ab1e`); live path arcs
|
|
stay above terrain (`7bcabcc`).
|
|
|
|
## Evidence priorities
|
|
|
|
In practice the resolver should rank evidence roughly like this:
|
|
|
|
- physically plausible link support (ITM/LOS)
|
|
- multibyte path evidence
|
|
- radio-neighbour evidence
|
|
- weaker observational hints
|
|
|
|
## API ownership
|
|
|
|
- `backend/src/api/routes/pathing.ts`
|
|
- thin HTTP wrapper
|
|
- `backend/src/pathing/pathingService.ts`
|
|
- cache and resolver orchestration
|
|
- `backend/src/pathing/pathingRepository.ts`
|
|
- DB-backed path history and learning queries
|
|
|
|
## Contributor rule
|
|
|
|
If a path looks wrong, first determine whether the issue is:
|
|
|
|
- evidence weighting
|
|
- physical graph quality (ITM feasibility)
|
|
- ambiguous short-hash matching
|
|
- cache reuse
|
|
- a missing field in the public DTO projector (`pathingPublicDto.ts`)
|
|
|
|
Do not debug path rendering as if it were a frontend-only problem.
|