# Phase 1: Semantic Position Model - Context

**Gathered:** 2026-01-18
**Status:** Ready for planning

<domain>
## Phase Boundary

All movable items have a persistent semantic position `(day: Int, sortOrder: Double)` that survives data reloads. Games are immovable anchors ordered by game time. Travel segments and custom items can be repositioned. This phase establishes the data model only — constraint validation, flattening, and drag interaction are separate phases.

</domain>

<decisions>
## Implementation Decisions

### sortOrder assignment
- Use integer spacing (1, 2, 3...) for initial sortOrder values
- Midpoint insertion (1.5, 1.25, etc.) when placing between items
- Claude's discretion on threshold/rebalancing strategy when gaps get very small
- Claude's discretion on negative vs positive sortOrder for "before games" items
- Claude's discretion on Double vs Decimal storage type

### Day boundaries
- Day = trip day backed by calendar date (Day 1 = trip.startDate, Day 2 = startDate + 1, etc.)
- Day number derived as: `calendar_days_since(trip.startDate) + 1`
- Games belong to their start date, even if they run past midnight
- Show all days including empty ones (no skipping gaps in the trip)

### Travel segment identity
- Each travel segment has a unique UUID (not keyed by route)
- Same route (e.g., Chicago→Boston) can appear multiple times in a trip
- Travel carries: from city, to city, estimated distance, estimated duration
- Moving travel to different day just updates the day property (no recalculation)

### Position initialization
- Games get sortOrder assigned by Claude based on game time
- Auto-generated travel appears after the origin city's games
- Custom items added via "+" button on day headers, inserted at top of that day
- Claude's discretion on handling position updates when trip is edited

### Claude's Discretion
- Exact sortOrder rebalancing threshold and strategy
- Whether to use negative sortOrder or offset games to higher values for "before" positioning
- Double vs Decimal for sortOrder storage
- Initial sortOrder derivation for games (time-based or sequential)
- Position preservation vs recomputation on trip edits

</decisions>

<specifics>
## Specific Ideas

- Day headers should have a "+" button for adding custom items
- When user taps "+", item is added to top of that day (lowest sortOrder)

</specifics>

<deferred>
## Deferred Ideas

None — discussion stayed within phase scope

</deferred>

---

*Phase: 01-semantic-position-model*
*Context gathered: 2026-01-18*