Tasks: Continuous Train Path Calculation with Network Topology

Feature: 002-train-path-calculation
Input: Design documents from /specs/002-train-path-calculation/
Prerequisites: plan.md, spec.md, research.md, data-model.md, contracts/

Tests: Tests are included per constitution requirement (TDD is NON-NEGOTIABLE).
Organization: Tasks are grouped by user story to enable independent implementation and testing of each story.

Format: `[ID] [P?] [Story] Description`

[P]: Can run in parallel (different files, no dependencies)
[Story]: Which user story this task belongs to (e.g., US1, US2, US3)
Include exact file paths in descriptions

Phase 1: Setup (Shared Infrastructure)

Purpose: Project initialization and basic structure

Phase 2: Foundational (Blocking Prerequisites)

Purpose: Core infrastructure that MUST be complete before ANY user story can be implemented

⚠️ CRITICAL: No user story work can begin until this phase is complete

Models (Data Structures)

T011 [P] Create tp-core/src/models/netrelation.rs with NetRelation struct (id, from_netelement_id, to_netelement_id, position_on_a, position_on_b, navigable_forward, navigable_backward)
T012 [P] Create tp-core/src/models/train_path.rs with TrainPath struct (id, segments, mode, overall_probability, metadata)
T013 [P] Create AssociatedNetElement struct in tp-core/src/models/train_path.rs (netelement_id, begin_intrinsic, end_intrinsic, length, probability)
T014 [P] Extend GnssPosition in tp-core/src/models/gnss.rs with optional heading and distance fields
T015 [P] Create GnssNetElementLink struct in tp-core/src/models/train_path.rs for candidate projections
T016 Add NetRelation module to tp-core/src/models.rs public exports
T017 Add TrainPath and AssociatedNetElement to tp-core/src/models.rs public exports

Graph Infrastructure

T018 Create tp-core/src/path/graph.rs with NetelementSide struct (netelement_id, position: 0|1)
T019 Implement build_topology_graph() in tp-core/src/path/graph.rs to create petgraph DiGraph from netelements and netrelations
T020 Write unit test for NetelementSide node creation in tests/unit/path_construction_test.rs
T021 Write unit test for internal edge creation (start→end, end→start) in tests/unit/path_construction_test.rs
T022 Write unit test for netrelation connection edge creation in tests/unit/path_construction_test.rs

Validation and Error Handling

T023 Extend ProjectionError enum in tp-core/src/errors.rs with PathCalculationFailed, NoNavigablePath, InvalidNetRelation variants
T024 Implement NetRelation::validate() method for position value validation (0 or 1 only)
T025 Implement NetRelation self-reference check (from != to) validation
T026 Write unit test for NetRelation validation rules in tests/unit/path_construction_test.rs
T026a Implement validate_netrelation_references() checking elementA/B IDs exist in netelements collection (FR-006a)
T026b Write unit test for invalid netelement reference handling and warning logs in tests/unit/path_construction_test.rs

I/O Extensions

T027 [P] Extend GeoJSON parser in tp-core/src/io/geojson.rs to parse netrelations from features with type="netrelation"
T028 [P] Implement TrainPath GeoJSON serialization in tp-core/src/io/geojson.rs (FeatureCollection with segments)
T029 [P] Implement TrainPath CSV serialization in tp-core/src/io/csv.rs (one row per segment)
T030 [P] Implement TrainPath CSV deserialization for reading pre-calculated paths
T031 Write integration test for netrelation GeoJSON parsing in tests/integration/path_calculation_test.rs
T032 Write integration test for TrainPath serialization roundtrip in tests/integration/path_calculation_test.rs

Configuration

T033 [P] Create PathConfig struct in tp-core/src/path.rs (distance_scale, heading_scale, cutoff_distance, heading_cutoff, probability_threshold, resampling_distance, max_candidates)
T034 [P] Implement PathConfig::default() with documented default values (distance_scale: 10.0, heading_scale: 2.0, cutoff_distance: 500.0, heading_cutoff: 5.0, probability_threshold: 0.25, max_candidates: 3)
T035 [P] Create PathConfigBuilder with fluent API and validation
T036 [P] Create PathResult struct (path: Option, mode: PathCalculationMode enum, projected_positions, warnings)
T037 [P] Create PathCalculationMode enum (TopologyBased, FallbackIndependent) in tp-core/src/path.rs
T038 Write contract test for PathConfig defaults in tests/contract/path_api_contract.rs

Checkpoint: Foundation ready - user story implementation can now begin in parallel

Phase 3: User Story 1 - Calculate Train Path from GNSS Data (Priority: P1) 🎯 MVP

Goal: Calculate the most probable continuous path through the rail network based on GNSS data and topology.

Independent Test: Provide GNSS coordinates and network with netrelations, verify output path is continuous and all connections are navigable.

Tests for User Story 1 ⚠️

NOTE: Write these tests FIRST, ensure they FAIL before implementation

T039 [P] [US1] Write integration test for successful path calculation with simple linear path in tests/integration/path_calculation_test.rs
T040 [P] [US1] Write integration test for path calculation with netelement connection (3 candidate branches) in tests/integration/path_calculation_test.rs
T041 [P] [US1] Write integration test for heading filtering (exclude segments with >5° difference) in tests/integration/path_calculation_test.rs
T042 [P] [US1] Write integration test for selecting highest probability path from multiple candidates in tests/integration/path_calculation_test.rs
T043 [P] [US1] Write contract test verifying calculate_train_path() signature and error types in tests/contract/path_api_contract.rs

Implementation for User Story 1

Phase 1: Candidate Selection Module

T044 [P] [US1] Create tp-core/src/path/candidate.rs module file
T045 [P] [US1] Implement find_candidate_netelements() using NetworkIndex (reuse from projection) with cutoff_distance filter
T046 [US1] Implement heading calculation at projection point on linestring (reuse from projection/geom.rs)
T047 [US1] Implement heading_difference() considering 180° equivalence (forward vs backward on same track)
T048 [US1] Write unit test for candidate selection within cutoff distance in tests/unit/path_candidate_test.rs
T049 [US1] Write unit test for heading difference calculation with 180° handling in tests/unit/path_candidate_test.rs

Phase 2: GNSS-Level Probability

T050 [P] [US1] Create tp-core/src/path/probability.rs module file
T051 [P] [US1] Implement calculate_distance_probability() with exponential decay formula exp(-distance/distance_scale)
T052 [P] [US1] Implement calculate_heading_probability() with exponential decay exp(-heading_diff/heading_scale) and heading_cutoff rejection
T053 [US1] Implement calculate_combined_probability() as product of distance and heading probabilities
T054 [US1] Implement assign_positions_to_netelements() mapping each GNSS position to candidate netelements with probabilities
T055 [P] [US1] Write unit test for distance probability formula validation (0m→1.0, scale→0.37) in tests/unit/path_probability_test.rs
T056 [P] [US1] Write unit test for heading probability with cutoff behavior in tests/unit/path_probability_test.rs
T057 [US1] Write unit test for combined probability calculation in tests/unit/path_probability_test.rs

Phase 3: Netelement-Level Probability

T058 [US1] Implement calculate_netelement_probability() averaging GNSS position probabilities for a netelement
T059 [US1] Implement identify_consecutive_positions() to find sequential GNSS positions assigned to same netelement
T060 [US1] Implement calculate_coverage_factor() as (consecutive_distance_sum / total_distance_first_to_last)
T061 [US1] Apply coverage correction factor to netelement probability
T062 [P] [US1] Write unit test for netelement probability averaging in tests/unit/path_probability_test.rs
T063 [US1] Write unit test for consecutive position identification in tests/unit/path_probability_test.rs
T064 [US1] Write unit test for coverage factor calculation in tests/unit/path_probability_test.rs

Phase 4: Path Decoding (HMM / Viterbi)

T065 [P] [US1] Create tp-core/src/path/construction.rs module file
T066 [P] [US1] Implement candidate_netelements_for_positions() to select candidate netelements per GNSS position (top-N by probability with navigability constraints)
T067 [P] [US1] Implement emission_probability() functions using per-position/per-netelements probability components (position, heading, coverage)
T068 [US1] Implement transition_probability() modeling between consecutive candidate netelements using topology connectivity and direction of travel
T069 [US1] Implement viterbi_decode_path() HMM decoder over the candidate lattice to select the most probable netelement sequence
T070 [US1] Implement insert_bridge_segments() to add required connecting segments between chosen netelements based on network topology
T071 [US1] Implement calculate_train_path() orchestrator calling candidate selection, emission/transition probability, Viterbi decoding, and bridge insertion
T072 [US1] Write unit tests for viterbi_decode_path() in tests/unit/path_construction_test.rs
T073 [US1] Write unit tests for insert_bridge_segments() and calculate_train_path() in tests/unit/path_construction_test.rs

Phase 4b: Post-Viterbi Path Validation

T073a [US1] Implement validate_path_navigability() — Pass 1: reachability check with Dijkstra re-routing for unreachable consecutive pairs
T073b [US1] Implement remove_oscillations() — Pass 2: collapse A→B→A oscillation patterns (max 3 intermediate NEs)
T073c [US1] Implement remove_direction_violations() — Pass 3: remove direction-inconsistent segments with cascade detection (max 3 cascade removals, C-removability guard)
T073d [US1] Implement SanityDecision struct for recording per-pair validation outcomes
T073e [US1] Write unit tests for post-Viterbi validation passes in tests/integration/

Phase 4c: Gap Filling

T073f [US1] Implement fill_path_gaps() — Dijkstra-based gap filling between non-adjacent validated segments with U-turn detection
T073g [US1] Implement GapFill struct for recording per-gap fill outcomes
T073h [US1] Write unit tests for gap filling in tests/integration/

Phase 5: Path Selection

T075 [P] [US1] Create tp-core/src/path/selection.rs module file
T076 [US1] Implement calculate_path_probability() as length-weighted average of netelement probabilities
T077 [US1] Implement bidirectional probability averaging: (P_forward + P_backward) / 2
T078 [US1] Handle unidirectional paths (only forward or only backward) with 0 for missing direction
T079 [US1] Implement select_best_path() choosing path with highest probability (first if tied)
T080 [US1] Assign probability 0 to paths that terminate before reaching end position
T081 [P] [US1] Write unit test for path probability calculation in tests/unit/path_probability_test.rs
T082 [US1] Write unit test for bidirectional averaging in tests/unit/path_probability_test.rs
T083 [US1] Write unit test for early termination detection in tests/unit/path_construction_test.rs

Integration: Main API Function

T084 [US1] Implement calculate_train_path() main public function in tp-core/src/path.rs
T085 [US1] Wire candidate selection → probability calculation → path construction → path selection
T086 [US1] Add input validation (empty network, no netrelations, invalid geometry checks)
T087 [US1] Add logging for audit trail (CRS conversions, netelement selections, path probability scores)
T088 [US1] Verify all User Story 1 integration tests pass

Checkpoint: At this point, User Story 1 should be fully functional and testable independently

Phase 4: User Story 2 - Project Coordinates on Calculated Path (Priority: P2)

Goal: Project GNSS coordinates onto the calculated train path with intrinsic coordinates.

Independent Test: Provide pre-calculated train path and GNSS coordinates, verify each coordinate projected onto correct segment with accurate intrinsics.

Tests for User Story 2 ⚠️

T089 [P] [US2] Write integration test for projecting coordinates onto calculated path in tests/integration/path_calculation_test.rs
T090 [P] [US2] Write integration test for coordinates between segments assigned to nearest segment in path in tests/integration/path_calculation_test.rs
T091 [P] [US2] Write integration test for pre-supplied path skipping calculation in tests/integration/path_calculation_test.rs
T092 [P] [US2] Write contract test for project_onto_path() function signature in tests/contract/path_api_contract.rs

Implementation for User Story 2

Checkpoint: At this point, User Stories 1 AND 2 should both work independently

Phase 5: User Story 3 - Export Train Path Only (Priority: P3)

Goal: Export calculated train path without processing coordinate projections for debugging and validation.

Independent Test: Request path-only export mode and verify output contains ordered track segment sequence without projection data.

Tests for User Story 3 ⚠️

T103 [P] [US3] Write integration test for path-only export in CSV format in tests/integration/path_calculation_test.rs
T104 [P] [US3] Write integration test for path-only export in GeoJSON format in tests/integration/path_calculation_test.rs
T105 [P] [US3] Write integration test verifying path shows segment sequence and connection info in tests/integration/path_calculation_test.rs
T106 [P] [US3] Write integration test for failed path calculation with diagnostic output in tests/integration/path_calculation_test.rs

Implementation for User Story 3

T107 [P] [US3] Extend calculate_train_path() to handle path_only=true parameter
T108 [US3] Skip projection phase when path_only=true, return PathResult with empty projected_positions
T109 [US3] Ensure TrainPath includes all diagnostic information (segment order, intrinsic ranges, probabilities)
T110 [US3] Add failure reporting: when path calculation fails, populate warnings with diagnostic information
T111 [US3] Verify all User Story 3 integration tests pass

Checkpoint: User Stories 1, 2, AND 3 should all work independently

Phase 6: User Story 4 - Enhanced GNSS Data with Heading and Distance (Priority: P2)

Goal: Use optional heading and distance data from GNSS to improve path calculation accuracy.

Independent Test: Provide GNSS data with heading/distance columns, compare path calculation results against coordinate-only data to verify improved accuracy.

Tests for User Story 4 ⚠️

T112 [P] [US4] Write integration test for heading-enhanced path calculation in tests/integration/path_calculation_test.rs
T113 [P] [US4] Write integration test for distance-based spacing calculation in tests/integration/path_calculation_test.rs
T114 [P] [US4] Write integration test for GNSS data without heading/distance still works in tests/integration/path_calculation_test.rs

Implementation for User Story 4

T115 [P] [US4] Extend CSV parser in tp-core/src/io/csv.rs to read optional "heading" column
T116 [P] [US4] Extend CSV parser to read optional "distance" column
T117 [P] [US4] Extend GeoJSON parser in tp-core/src/io/geojson.rs to read optional heading and distance properties
T118 [US4] Update calculate_heading_probability() to use GNSS heading when available (already in probability.rs)
T119 [US4] Implement use_distance_values_for_spacing() to calculate mean spacing using distance column
T120 [US4] Add backward compatibility check: heading/distance fields are optional, default to None
T121 [US4] Write unit test for heading-based filtering improvement in tests/unit/path_probability_test.rs
T122 [US4] Write unit test for distance-based spacing calculation in tests/unit/path_probability_test.rs
T123 [US4] Verify all User Story 4 integration tests pass

Checkpoint: User Stories 1-4 should all work independently

Phase 7: User Story 5 - Performance-Optimized Processing (Priority: P3)

Goal: Enable resampling for dense GNSS data while maintaining full output (all positions projected).

Independent Test: Process same dataset with different resampling values, measure execution time and verify all original positions in output.

Tests for User Story 5 ⚠️

T124 [P] [US5] Write integration test for resampling with 10m interval on 1m-spaced data in tests/integration/path_calculation_test.rs
T125 [P] [US5] Write integration test verifying all original positions in output despite resampling in tests/integration/path_calculation_test.rs
T126 [P] [US5] Write performance benchmark comparing resampled vs full processing in benches/path_calculation_bench.rs

Implementation for User Story 5

Checkpoint: User Stories 1-5 should all work independently

Phase 8: User Story 6 - Fallback to Simple Projection (Priority: P2)

Goal: Graceful degradation when path calculation fails - fall back to simple nearest-segment projection.

Independent Test: Provide data that cannot form continuous path (disconnected segments), verify system produces simple projection with warnings.

Tests for User Story 6 ⚠️

T137 [P] [US6] Write integration test for fallback with disconnected network in tests/integration/path_calculation_test.rs
T138 [P] [US6] Write integration test verifying fallback notification to user in tests/integration/path_calculation_test.rs
T139 [P] [US6] Write integration test for fallback ignoring navigability constraints in tests/integration/path_calculation_test.rs

Implementation for User Story 6

T140 [P] [US6] Implement detect_path_calculation_failure() checking if no valid path found
T141 [US6] Implement fallback_to_simple_projection() projecting each coordinate to nearest netelement independently
T142 [US6] Reuse existing simple projection logic from feature 001 (projection module)
T143 [US6] Set PathResult.mode = PathCalculationMode::FallbackIndependent when fallback used
T144 [US6] Populate PathResult.warnings with "No continuous path found, using fallback projection"
T145 [US6] Ensure fallback ignores navigability (project to geometrically nearest regardless)
T146 [US6] Add logging for fallback trigger event (optional enhancement)
T147 [US6] Write unit test for fallback detection logic in tests/unit/path_construction_test.rs (covered by integration tests)
T148 [US6] Verify all User Story 6 integration tests pass

Checkpoint: User Stories 1-6 should all work independently

Phase 9: User Story 7 - Debug Path Calculation (Priority: P4)

Goal: Export intermediate results for troubleshooting and parameter tuning (developer/support tool).

Independent Test: Enable debug export mode, verify intermediate files contain probability calculations and decision criteria.

Tests for User Story 7 ⚠️

T149 [P] [US7] Write integration test for debug export of candidate paths in tests/integration/path_calculation_test.rs
T150 [P] [US7] Write integration test for debug export showing track segment candidates per coordinate in tests/integration/path_calculation_test.rs
T151 [P] [US7] Write integration test for debug export showing forward/backward probability averaging in tests/integration/path_calculation_test.rs

Implementation for User Story 7

T152 [P] [US7] Add debug_mode: bool field to PathConfig
T153 [P] [US7] Create DebugInfo struct to collect intermediate results (candidate_paths, position_candidates, decision_tree)
T154 [US7] Implement export_candidate_paths() writing all candidate paths with probability scores
T155 [US7] Implement export_position_candidates() writing netelement candidates and probabilities per GNSS coordinate
T156 [US7] Implement export_decision_tree() showing bidirectional averaging and final path selection
T157 [US7] Integrate debug info collection throughout path calculation pipeline
T158 [US7] Write debug output to separate files (candidates.json, decisions.json) when debug_mode=true
T159 [US7] Verify all User Story 7 integration tests pass

Checkpoint: All user stories (1-7) should now be independently functional

Phase 10: CLI Integration

Purpose: Expose path calculation functionality via command-line interface

Tests for CLI

T160 [P] Write CLI integration test for default command (calculate + project) in tp-cli/tests/cli_integration_test.rs
T161 [P] Write CLI integration test for calculate-path command (path only) in tp-cli/tests/cli_integration_test.rs
T162 [P] Write CLI integration test for simple-projection command (feature 001 legacy) in tp-cli/tests/cli_integration_test.rs
T163 [P] Write CLI integration test for --train-path parameter (use existing path) in tp-cli/tests/cli_integration_test.rs

Implementation for CLI

Phase 11: Polish & Cross-Cutting Concerns

Purpose: Improvements that affect multiple user stories

Dependencies & Execution Order

Phase Dependencies

Setup (Phase 1): No dependencies - can start immediately
Foundational (Phase 2): Depends on Setup completion - BLOCKS all user stories
User Story 1 (Phase 3): Depends on Foundational phase completion - Core MVP functionality
User Story 2 (Phase 4): Depends on US1 (needs path calculation) - Projects coordinates onto path
User Story 3 (Phase 5): Depends on US1 (needs path calculation) - Path-only export
User Story 4 (Phase 6): Depends on US1 (enhances path calculation) - Optional enhancement
User Story 5 (Phase 7): Depends on US1 (optimizes path calculation) - Performance optimization
User Story 6 (Phase 8): Depends on US1+US2 (fallback from path projection) - Graceful degradation
User Story 7 (Phase 9): Depends on US1 (debugs path calculation) - Developer tool
CLI Integration (Phase 10): Depends on US1+US2+US3 complete - Exposes functionality
Polish (Phase 11): Depends on all desired user stories being complete

User Story Dependencies

User Story 1 (P1): Can start after Foundational (Phase 2) - No dependencies on other stories ✅ MVP START HERE
User Story 2 (P2): Requires US1 complete (needs calculated path) - Can integrate with US1
User Story 3 (P3): Requires US1 complete (exports path) - Independent from US2
User Story 4 (P2): Requires US1 complete (enhances probability) - Independent from US2/US3
User Story 5 (P3): Requires US1 complete (optimizes path calc) - Independent from US2/US3/US4
User Story 6 (P2): Requires US1+US2 complete (fallback behavior) - Needs both path and projection
User Story 7 (P4): Requires US1 complete (debugs path calc) - Independent from others

Within Each User Story

Tests MUST be written and FAIL before implementation (TDD non-negotiable)
Models before services
Core implementation before integration
Story complete before moving to next priority

Parallel Opportunities

All Setup tasks marked [P] can run in parallel
All Foundational tasks marked [P] can run in parallel (within Phase 2)
Once Foundational phase completes:
- US1 (P1) must complete first (MVP foundation)
- After US1: US2, US3, US4 can be developed in parallel (all depend only on US1)
- After US1+US2: US6 can start (needs both)
- US5 and US7 can be developed anytime after US1
Within each user story:
- All tests marked [P] can run in parallel
- Module creation tasks marked [P] can run in parallel
- Different implementation modules marked [P] can run in parallel

Parallel Example: User Story 1

# Launch all tests for User Story 1 together:
Task T039: Integration test for successful path calculation
Task T040: Integration test for netelement connection handling
Task T041: Integration test for heading filtering
Task T042: Integration test for highest probability selection
Task T043: Contract test for API signature

# Launch all module creation tasks for US1 together:
Task T044: Create candidate.rs module
Task T050: Create probability.rs module
Task T065: Create construction.rs module
Task T075: Create selection.rs module

# Within Probability module, these can run in parallel:
Task T051: Implement distance probability formula
Task T052: Implement heading probability formula
# Then Task T053 depends on T051+T052 (product calculation)

Implementation Strategy

MVP First (User Story 1 Only)

Complete Phase 1: Setup
Complete Phase 2: Foundational (CRITICAL - blocks all stories)
Complete Phase 3: User Story 1 (core path calculation)
STOP and VALIDATE: Test User Story 1 independently
Deploy/demo if ready

Incremental Delivery

Complete Setup + Foundational → Foundation ready
Add User Story 1 → Test independently → Deploy/Demo (MVP!)
Add User Story 2 → Test independently → Deploy/Demo (path + projection)
Add User Story 3 → Test independently → Deploy/Demo (debugging support)
Add User Stories 4-7 as needed for production features

Parallel Team Strategy

With multiple developers:

Team completes Setup + Foundational together
Once Foundational is done:
- One developer: User Story 1 (MUST complete first - MVP blocker)
After US1 complete:
- Developer A: User Story 2 (projection)
- Developer B: User Story 3 (path export)
- Developer C: User Story 4 (heading/distance)
After US1+US2 complete:
- Any developer: User Story 6 (fallback)
Anytime after US1:
- Any developer: User Story 5 (resampling)
- Any developer: User Story 7 (debug)

Total Task Summary

Setup: 10 tasks
Foundational: 30 tasks (BLOCKING) - includes T026a, T026b for netrelation reference validation
User Story 1 (P1): 50 tasks - MVP Core
User Story 2 (P2): 14 tasks - Projection
User Story 3 (P3): 9 tasks - Export
User Story 4 (P2): 13 tasks - Enhancement
User Story 5 (P3): 13 tasks - Optimization
User Story 6 (P2): 12 tasks - Fallback
User Story 7 (P4): 11 tasks - Debug
CLI Integration: 18 tasks
Polish: 16 tasks

Total: 195 tasks (updated from 193 after adding reference validation tasks)

Estimated MVP Scope (Setup + Foundational + US1 + US2 + CLI basics):
~100 tasks for functional path-based projection

Notes

[P] tasks = different files, no dependencies
[Story] label maps task to specific user story for traceability
Each user story should be independently completable and testable
Verify tests fail before implementing (TDD non-negotiable per constitution)
Commit after each task or logical group
Stop at any checkpoint to validate story independently
Constitution Principle IV (TDD) is NON-NEGOTIABLE: tests MUST be written first

Feature Version: 1.0
Generated: January 2026
Implementation Start: After plan.md approval

FilesExpand file tree

tasks.md

Latest commit

History