ukmesh/docs/pathing.md

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.