Use git-like modification tree for versioning

Decision

The git object model, adapted for trips

Modifications form a tree via a parent_id pointer (adjacency list). The trip's head_modification_id tracks the current tip. Named versions are pointers to specific modifications — like git branches pointing to commits.

Data structures

┌─────────────────────────────────┐
│ trips                           │
│   head_modification_id  ───────────► current tip modification
│   active_version_id     ───────────► which version is "selected"
└─────────────────────────────────┘

┌─────────────────────────────────┐
│ trip_modifications              │
│   id                            │
│   parent_id  ──────────────────────► previous modification (NULL for root)
│   user_input                    │
│   effects    (JSON)             │
│   applied_at                    │
└─────────────────────────────────┘

┌─────────────────────────────────┐
│ trip_versions                   │
│   id                            │
│   modification_id  ────────────────► the modification this version points to
│   name                          │
│   description                   │
└─────────────────────────────────┘

State reconstruction

To build the current trip state, walk from HEAD to root via parent_id, reverse to chronological order, then replay all effects forward:

HEAD ──parent_id──► M4 ──parent_id──► M2 ──parent_id──► M1 ──parent_id──► NULL

Reverse to: [M1, M2, M4, HEAD]

Trip = apply(apply(apply(apply(empty, M1.effects), M2.effects), M4.effects), HEAD.effects)

This is implemented as a recursive CTE:

WITH RECURSIVE chain AS (
    SELECT id, parent_id, ...
    FROM trip_modifications
    WHERE id = (SELECT head_modification_id FROM trips WHERE id = $1)
    UNION ALL
    SELECT m.id, m.parent_id, ...
    FROM trip_modifications m
    JOIN chain c ON m.id = c.parent_id
)
SELECT ... FROM chain ORDER BY applied_at ASC

Branching (fork-on-write)

When switching to an older version and making a new modification, the new modification's parent_id points to the old version's modification. This naturally creates a branch in the tree — no special forking logic needed.

M1 ◄── M2 ◄── M3 ◄── M4          "Original" version points here
                 ▲
                 └── M5 ◄── M6    "Skip Florence" version points here

Both branches share M1–M3. Each version's pointer determines which branch fetch_modifications walks. Switching versions just moves head_modification_id and active_version_id — a single UPDATE, no data is copied or moved.

Version semantics (save-slot model)

Versions are auto-advancing save slots, not frozen snapshots:

• First modification on a trip auto-creates an "Original" version
• Every subsequent modification advances the active version's modification_id to the new HEAD
• Creating a new version forks from the current HEAD position
• Switching versions moves HEAD to that version's modification — instant, no prompts
• All versions are equal peers — no "main" version, no privileged branch

"What if..." exploration is a client-side state only. The backend has no concept of exploration mode — it just receives modifications and advances versions. If exploration produces a modification, the client creates a new version first, then the modification auto-advances that version.

The git analogy

Consequences

Positive

• No data loss by design — modifications are append-only; branches are never deleted, only potentially unreachable if their version is deleted
• Cheap branching — creating a version is an INSERT; switching is an UPDATE; no data duplication
• No "unsaved changes" — every modification immediately persists and the active version tracks it
• Simple state reconstruction — one recursive CTE, deterministic replay, same as the flat list but starting from a different HEAD
• Familiar mental model — engineers and users who know git understand branches and switching instantly

Negative

• Recursive CTE cost — walking the parent chain is O(n) in chain length per fetch; acceptable for trips (typically <100 modifications) but would need caching or materialized paths for much longer chains
• Orphaned modifications — deleting a version doesn't delete its modifications; the tree accumulates dead branches over time (acceptable for trip-scale data; could add periodic cleanup if needed)
• No merge — there's no mechanism to combine two branches; versions are independent alternatives, not collaborative branches (this matches the product intent — versions represent different trip ideas, not parallel work to be reconciled)

Related Decisions

• ADR-0033: Trip model as destinations with effect-based modifications (the foundation this builds on)
• ADR-0045: Newtype IDs (ModificationId, VersionId, TripId) prevent pointer mix-ups in this tree structure

References

• Issue #155: Original implementation (snapshots with fork-on-write)
• Issue #180: Evolution to save-slot version model
• PR #181: Implementation (rename snapshot→version, remove what-if mode)