---
phase: 01-semantic-position-model
plan: 01
subsystem: domain
tags: [swift, sortOrder, calendar, trip, itinerary]

# Dependency graph
requires: []
provides:
  - SortOrderProvider utility with 6 static methods for sortOrder calculation
  - Trip.dayNumber(for:) and Trip.date(forDay:) for semantic day derivation
affects:
  - 01-02-PLAN (tests depend on these utilities)
  - Phase 2 constraint validation (will use sortOrder utilities)
  - Phase 3 visual flattening (will sort by sortOrder)

# Tech tracking
tech-stack:
  added: []
  patterns:
    - "SortOrderProvider enum with static methods for sortOrder calculation"
    - "Double-based sortOrder with midpoint insertion (~52 insertions before precision loss)"
    - "1-indexed day numbering relative to trip.startDate"

key-files:
  created:
    - SportsTime/Core/Models/Domain/SortOrderProvider.swift
  modified:
    - SportsTime/Core/Models/Domain/Trip.swift

key-decisions:
  - "Games get sortOrder from 100 + minutes since midnight (range 100-1540)"
  - "Midpoint insertion via (above + below) / 2.0"
  - "Normalization threshold at 1e-10 gap between adjacent items"
  - "Day 1 = trip.startDate, games belong to their start date"

patterns-established:
  - "SortOrderProvider.initialSortOrder(forGameTime:) for deriving sortOrder from game time"
  - "SortOrderProvider.sortOrderBetween(_:_:) for insertion between items"
  - "Trip.dayNumber(for:) and Trip.date(forDay:) for semantic day calculation"

# Metrics
duration: 3min
completed: 2026-01-18
---

# Phase 1 Plan 1: SortOrder Utilities Summary

**SortOrderProvider enum with 6 static methods for sortOrder calculation plus Trip.dayNumber/date(forDay:) for semantic day derivation**

## Performance

- **Duration:** 3 min
- **Started:** 2026-01-18T19:49:28Z
- **Completed:** 2026-01-18T19:52:00Z
- **Tasks:** 2
- **Files modified:** 2

## Accomplishments
- Created SortOrderProvider utility with all sortOrder calculation methods
- Added day derivation methods to Trip for semantic (day, sortOrder) positioning
- Both files compile successfully with no warnings

## Task Commits

Each task was committed atomically:

1. **Task 1: Create SortOrderProvider utility** - `9915ad3` (feat)
2. **Task 2: Add day derivation methods to Trip** - `6d43edf` (feat)

## Files Created/Modified
- `SportsTime/Core/Models/Domain/SortOrderProvider.swift` - Enum with 6 static methods: initialSortOrder(forGameTime:), sortOrderBetween(_:_:), sortOrderBefore(_:), sortOrderAfter(_:), needsNormalization(_:), normalize(_:)
- `SportsTime/Core/Models/Domain/Trip.swift` - Added extension with dayNumber(for:) and date(forDay:) instance methods

## Decisions Made
None - followed plan as specified. Research document provided complete implementation guidance.

## Deviations from Plan
None - plan executed exactly as written.

## Issues Encountered
None.

## User Setup Required
None - no external service configuration required.

## Next Phase Readiness
- SortOrderProvider and Trip day derivation methods ready for use
- Plan 01-02 can now create tests verifying semantic position persistence
- All 6 SortOrderProvider methods are static and publicly accessible
- Trip extension methods are instance methods callable on any Trip value

---
*Phase: 01-semantic-position-model*
*Completed: 2026-01-18*