fix(timeline): resolve a multi-event letter link deterministically

A letter whose document is in more than one curated event's `documents`
set was linked by `putIfAbsent` over `eventRepository.findAll()`, whose
iteration order JPA does not guarantee — so the same letter could cluster
under a different event across re-seeds/VACUUM with no data change.

resolveLetterEventLinks now runs over a stably-ordered copy (earliest
event date, undated last, then lowest id), so the link is a deterministic
property of the data. Fixes review finding #9 (Architect-3).

Refs #850
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

backend/src/main/java/org/raddatz/familienarchiv/timeline/TimelineService.java

@@ -269,17 +269,28 @@ public class TimelineService {
      * event whose {@code documents} set contains the letter (REQ-009). A single doc→event map is
      * built over the already-loaded events — no per-letter query ({@code TimelineEvent.documents}
      * carries {@code @BatchSize(50)}). When a document is referenced by more than one curated
-     * event, the first by repository iteration order wins ({@code putIfAbsent}). The map is built
-     * from <em>all</em> events (not just the year/type-filtered ones) so the link is a stable
-     * property of the data; the frontend's filter-then-cluster decides whether the linked event is
-     * actually on screen (#850). Logs nothing — the assembly path keeps UUIDs out of logs (§2.7).
+     * event, the earliest-dated event wins (then lowest {@code eventId}); the pass runs over a
+     * stably-ordered copy so the link is a deterministic property of the data, not a coin-flip on
+     * the undefined repository iteration order ({@code putIfAbsent} keeps the first = winner). The
+     * map is built from <em>all</em> events (not just the year/type-filtered ones) so the link is a
+     * stable property of the data; the frontend's filter-then-cluster decides whether the linked
+     * event is actually on screen (#850). Logs nothing — the assembly path keeps UUIDs out of logs (§2.7).
      */
     private Map<UUID, UUID> resolveLetterEventLinks(List<Document> letters, List<TimelineEvent> events) {
         Set<UUID> letterDocIds = letters.stream().map(Document::getId).collect(Collectors.toSet());
         if (letterDocIds.isEmpty()) return Map.of();
 
+        // Stable order so a multi-event letter links deterministically: earliest event date
+        // (undated last), then lowest id. putIfAbsent below then keeps the winner (REQ-009).
+        List<TimelineEvent> ordered = events.stream()
+                .sorted(Comparator
+                        .comparing(TimelineEvent::getEventDate,
+                                Comparator.nullsLast(Comparator.naturalOrder()))
+                        .thenComparing(TimelineEvent::getId))
+                .toList();
+
         Map<UUID, UUID> eventByDocId = new HashMap<>();
-        for (TimelineEvent ev : events) {
+        for (TimelineEvent ev : ordered) {
             Set<Document> linkedDocs = ev.getDocuments();
             if (linkedDocs == null) continue;
             for (Document linked : linkedDocs) {

backend/src/test/java/org/raddatz/familienarchiv/timeline/TimelineServiceTest.java

@@ -549,6 +549,46 @@ class TimelineServiceTest {
         assertThat(entry.linkedEventId()).isNull();
     }
 
+    @Test
+    void multi_event_letter_links_deterministically_to_the_earliest_event() {
+        // REQ-009: a document referenced by >1 curated event links to the earliest-dated event
+        // (then lowest id), independent of repository iteration order — not a coin-flip on
+        // findAll()'s undefined order.
+        Document shared = docWithDate(LocalDate.of(1916, 5, 1), DatePrecision.MONTH);
+        TimelineEvent earlier = TimelineEvent.builder()
+                .id(UUID.fromString("00000000-0000-0000-0000-000000000001"))
+                .title("Frühes Ereignis").type(EventType.PERSONAL)
+                .eventDate(LocalDate.of(1913, 3, 1)).precision(DatePrecision.MONTH)
+                .documents(new HashSet<>(Set.of(shared)))
+                .build();
+        TimelineEvent later = TimelineEvent.builder()
+                .id(UUID.fromString("00000000-0000-0000-0000-000000000002"))
+                .title("Spätes Ereignis").type(EventType.PERSONAL)
+                .eventDate(LocalDate.of(1914, 3, 1)).precision(DatePrecision.MONTH)
+                .documents(new HashSet<>(Set.of(shared)))
+                .build();
+        when(timelineEventService.assembleDerivedEvents()).thenReturn(List.of());
+        when(documentService.getAllForTimeline()).thenReturn(List.of(shared));
+
+        // `later` first in iteration: a naive putIfAbsent would wrongly pick it.
+        when(eventRepository.findAll()).thenReturn(List.of(later, earlier));
+        assertThat(theLetter(timelineService.assemble(noFilters())).linkedEventId())
+                .isEqualTo(earlier.getId());
+
+        // Reversed order yields the same winner — the link is order-independent.
+        when(eventRepository.findAll()).thenReturn(List.of(earlier, later));
+        assertThat(theLetter(timelineService.assemble(noFilters())).linkedEventId())
+                .isEqualTo(earlier.getId());
+    }
+
+    private static TimelineEntryDTO theLetter(TimelineDTO result) {
+        return java.util.stream.Stream.concat(
+                        result.years().stream().flatMap(y -> y.entries().stream()),
+                        result.undated().stream())
+                .filter(e -> e.kind() == Kind.LETTER)
+                .findFirst().orElseThrow();
+    }
+
     private static TimelineEntryDTO onlyLetterEntry(TimelineDTO result) {
         assertThat(result.years()).hasSize(1);
         return result.years().get(0).entries().get(0);