refactor(timeline): extract shared EventHeader for pill + event-card

EventCluster's same-year header re-implemented EventPill's glyph circle,
serif title, provenance subtitle, and the curator edit anchor near-
verbatim — the third copy of that markup. They now share a single
EventHeader component (glyph via GlyphLabel, title, `{date} · provenance`
subtitle, optional sr-only letter count, and the canEditEvent-gated edit
pencil); EventPill keeps only its pill border, EventCluster only its card
chrome. Second half of review finding #5 (Architect-1). No behavior
change — EventPill/EventCluster/YearBand/TimelineView specs stay green.

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

.gitea/workflows/ci.yml

@@ -229,9 +229,14 @@ jobs:
     name: Backend Unit Tests
     runs-on: ubuntu-latest
     env:
-      DOCKER_API_VERSION: "1.43"  # NAS runner runs Docker 24.x (max API 1.43); Testcontainers 2.x defaults to 1.44
+      # CI runs against the root-server Docker daemon (29.x). This API pin is a harmless
+      # carry-over from the old NAS runner (Docker 24.x, max API 1.43); safe to drop later.
+      DOCKER_API_VERSION: "1.43"
       DOCKER_HOST: unix:///var/run/docker.sock
-      TESTCONTAINERS_RYUK_DISABLED: "true"
+      # Ryuk (Testcontainers' out-of-process reaper) is intentionally LEFT ENABLED so it
+      # removes each run's containers after the JVM exits. Disabling it forced the in-JVM
+      # reaper, which hung at JVM shutdown and leaked Postgres containers run-over-run until
+      # the daemon degraded and the fork timed out at teardown — see #848.
     steps:
       - uses: actions/checkout@v4
 

.gitea/workflows/nightly.yml

@@ -192,17 +192,52 @@ jobs:
           REPO="${{ github.repository }}"
           RUN_URL="${GITEA_URL}/${REPO}/actions/runs/${{ github.run_id }}"
 
+          # --- Gitea API helper ---
+          # api METHOD URL [extra curl args...] — authenticated Gitea API call.
+          # `curl -sf` collapses every HTTP >=400 into a bare "exit 22", which
+          # surfaces as an opaque step failure (issue #839). Instead we read the
+          # status code and, on a >=400 response, print an actionable ::error::
+          # to stderr (so a calling command substitution does not swallow it) and
+          # return 1 — `set -e` then still fails the step. The token is never
+          # echoed (no set -x; never placed in the message).
+          api() {
+            local method="$1" url="$2"; shift 2
+            local resp http
+            resp=$(curl -s -w '\n%{http_code}' -X "$method" \
+              -H "Authorization: token $NIGHTLY_AUDIT_TOKEN" "$@" -- "$url")
+            http=${resp##*$'\n'}
+            printf '%s' "${resp%$'\n'*}"
+            case "$http" in
+              2*|3*) return 0 ;;
+              401|403)
+                echo "::error::Gitea returned HTTP $http for $method ${url%%\?*} — the NIGHTLY_AUDIT_TOKEN secret is missing, expired, or lacks issue read+write scope; recreate the renovate_bot PAT and update the secret." >&2
+                return 1 ;;
+              *)
+                echo "::error::Gitea returned HTTP ${http:-(none)} for $method ${url%%\?*}." >&2
+                return 1 ;;
+            esac
+          }
+
           # --- Self-test (mirrors ci.yml §Assert pattern) ---
-          # Tests the exact jq test() call used in the dedupe step, before any
-          # API call, so a broken matcher fails loudly early rather than silently
-          # opening duplicate issues. Proves the regex only — create-vs-update
-          # decision is exercised by the workflow_dispatch AC.
+          # Runs before any real API call so broken logic fails loudly early:
+          # (a) the jq title matcher used by the dedupe step — proves the regex
+          #     only; the create-vs-update decision is exercised by the
+          #     workflow_dispatch AC;
+          # (b) the api helper's HTTP-status handling, driven by a mocked curl so
+          #     it needs no network — proves a 2xx returns the body and a >=400
+          #     fails with an ::error:: instead of an opaque exit 22.
           echo "{\"title\": \"${MARKER}\"}" \
             | jq -e --arg m "$MARKER" '.title | test($m; "i")' > /dev/null \
             || { echo "FAIL: self-test — jq test() missed tracking issue title"; exit 1; }
           echo '{"title": "fix(deps): update dependency esbuild (CVE-2025-12345)"}' \
             | jq -e --arg m "$MARKER" '.title | test($m; "i") | not' > /dev/null \
             || { echo "FAIL: self-test — jq test() incorrectly matched unrelated title"; exit 1; }
+          ( curl() { printf 'OK\n200'; }; [ "$(api GET selftest)" = "OK" ] ) \
+            || { echo "FAIL: self-test — api helper dropped body on HTTP 200"; exit 1; }
+          ( curl() { printf 'nope\n401'; }
+            if api GET selftest >/dev/null 2>/tmp/api_selftest_err; then exit 1; fi
+            grep -q '::error::' /tmp/api_selftest_err ) \
+            || { echo "FAIL: self-test — api helper did not emit ::error:: on HTTP 401"; exit 1; }
           echo "Self-test passed."
 
           # --- Run audit ---
@@ -237,8 +272,7 @@ jobs:
             # Renovate vuln PRs also carry the "security" label, so >1 open
             # "security" issue WILL occur. Title-match (not just label) ensures
             # we deduplicate only our own tracking issue.
-            OPEN_ISSUES=$(curl -sf \
-              -H "Authorization: token $NIGHTLY_AUDIT_TOKEN" \
+            OPEN_ISSUES=$(api GET \
               "${GITEA_URL}/api/v1/repos/${REPO}/issues?state=open&type=issues&labels=security&limit=50")
 
             MATCHED=$(echo "$OPEN_ISSUES" | jq \
@@ -255,11 +289,10 @@ jobs:
                 --arg run_url "$RUN_URL" \
                 '$existing + "\n\n---\n\nUpdated by run: " + $run_url')
               PAYLOAD=$(jq -n --arg body "$NEW_BODY" '{"body": $body}')
-              curl -sf -X PATCH \
-                -H "Authorization: token $NIGHTLY_AUDIT_TOKEN" \
+              api PATCH \
+                "${GITEA_URL}/api/v1/repos/${REPO}/issues/${ISSUE_NUMBER}" \
                 -H "Content-Type: application/json" \
-                -d "$PAYLOAD" \
-                "${GITEA_URL}/api/v1/repos/${REPO}/issues/${ISSUE_NUMBER}" > /dev/null
+                -d "$PAYLOAD" > /dev/null
               echo "Updated tracking issue #${ISSUE_NUMBER}"
             else
               # Closed prior issue that recurs → new issue (not reopened).
@@ -268,24 +301,21 @@ jobs:
                 --arg title "$MARKER" \
                 --arg body "$ISSUE_BODY" \
                 '{"title": $title, "body": $body}')
-              CREATED=$(curl -sf -X POST \
-                -H "Authorization: token $NIGHTLY_AUDIT_TOKEN" \
+              CREATED=$(api POST \
+                "${GITEA_URL}/api/v1/repos/${REPO}/issues" \
                 -H "Content-Type: application/json" \
-                -d "$PAYLOAD" \
-                "${GITEA_URL}/api/v1/repos/${REPO}/issues")
+                -d "$PAYLOAD")
               NEW_NUMBER=$(echo "$CREATED" | jq -r '.number')
               echo "Opened new tracking issue #${NEW_NUMBER}"
 
               # Labels are ignored on issue create in Gitea — add in a follow-up call.
-              LABEL_IDS=$(curl -sf \
-                -H "Authorization: token $NIGHTLY_AUDIT_TOKEN" \
+              LABEL_IDS=$(api GET \
                 "${GITEA_URL}/api/v1/repos/${REPO}/labels?limit=50" \
                 | jq '[.[] | select(.name == "security" or .name == "devops" or .name == "P1-high") | .id]')
-              curl -sf -X POST \
-                -H "Authorization: token $NIGHTLY_AUDIT_TOKEN" \
+              api POST \
+                "${GITEA_URL}/api/v1/repos/${REPO}/issues/${NEW_NUMBER}/labels" \
                 -H "Content-Type: application/json" \
-                -d "{\"labels\": $LABEL_IDS}" \
-                "${GITEA_URL}/api/v1/repos/${REPO}/issues/${NEW_NUMBER}/labels" > /dev/null
+                -d "{\"labels\": $LABEL_IDS}" > /dev/null
             fi
 
             exit "$AUDIT_EXIT"

.specify/rtm.md

@@ -139,6 +139,25 @@
 | REQ-014 | no change to DTO order, density threshold (12), gap-folding, or ol/section/h2 structure | #833 | zeitstrahl-visual-fidelity | `frontend/src/lib/timeline/*` | existing timeline + `zeitstrahl/page.server.test.ts` suites stay green (142 tests) | Done |
 | REQ-015 | new user-facing strings are Paraglide keys present in de/en/es with matching key sets | #833 | zeitstrahl-visual-fidelity | `frontend/messages/{de,en,es}.json` | `messages.spec.ts#zeitstrahl visual-fidelity keys are present in all locales`, `#identical key sets` | Done |
 | REQ-016 | LetterCard with no title → no ✉, no sr-only "Brief"; sender→receiver + date still render | #833 | zeitstrahl-visual-fidelity | `frontend/src/lib/timeline/LetterCard.svelte` | `LetterCard.svelte.spec.ts#renders no ✉ glyph and no "Brief" label when the title is empty` | Done |
+| REQ-001 | store relationship from/to as nullable LocalDate + NOT-NULL DatePrecision (default UNKNOWN) | #837 | relationship-edit-dates | `person/relationship/PersonRelationship.java`, `V78__relationship_years_to_localdate.sql` | `RelationshipMigrationTest#yearColumnsDropped_andNamedCheckConstraintsExist`, `RelationshipServiceTest#addRelationship_persists_with_storage_truth` | Done |
+| REQ-002 | V78 backfills non-null years as `{year}-01-01`/YEAR, nulls → null/UNKNOWN, rows preserved | #837 | relationship-edit-dates | `V78__relationship_years_to_localdate.sql` | `RelationshipMigrationTest#backfill_fromYearAndToYear_becomeYearPrecisionDates`, `#backfill_bothNull_leavesDatesNullAndPrecisionsUnknown`, `#backfill_preservesRowCount` | Done |
+| REQ-003 | named DB CHECKs: coherence both ends + fromDate ≤ toDate | #837 | relationship-edit-dates | `V78__relationship_years_to_localdate.sql` | `RelationshipMigrationTest#orderCheckConstraint_rejectsToDateBeforeFromDate`, `#coherenceCheckConstraint_rejectsDatePresentWithUnknownPrecision` | Done |
+| REQ-004 | PUT updates the relationship → 200 RelationshipDTO | #837 | relationship-edit-dates | `person/relationship/RelationshipController#updateRelationship`, `RelationshipService#updateRelationship` | `RelationshipControllerTest#updateRelationship_returns200_with_RelationshipDTO_for_WRITE_ALL_user`, `RelationshipServiceIntegrationTest#updateRelationship_persists_new_type_dates_and_notes`, `page.server.spec.ts#updateRelationship PUTs to the relId path with the new body` | Done |
+| REQ-005 | create + update rejected with 403 without WRITE_ALL | #837 | relationship-edit-dates | `person/relationship/RelationshipController` (`@RequirePermission`) | `RelationshipControllerTest#updateRelationship_returns403_for_READ_ALL_only_user`, `#addRelationship_returns403_for_user_with_READ_ALL_only` | Done |
+| REQ-006 | relId not existing / not owned by person → 404 RELATIONSHIP_NOT_FOUND | #837 | relationship-edit-dates | `person/relationship/RelationshipService#loadOwnedRelationship` | `RelationshipServiceTest#updateRelationship_throws_NOT_FOUND_when_rel_belongs_to_different_person`, `RelationshipServiceIntegrationTest#updateRelationship_throws_404_when_rel_belongs_to_different_person` | Done |
+| REQ-007 | update with relatedPersonId == {id} → 400 VALIDATION_ERROR | #837 | relationship-edit-dates | `person/relationship/RelationshipService#updateRelationship` | `RelationshipServiceTest#updateRelationship_throws_VALIDATION_ERROR_on_self_relation` | Done |
+| REQ-008 | resulting (person, relatedPerson, type) duplicate → 409 DUPLICATE_RELATIONSHIP | #837 | relationship-edit-dates | `person/relationship/RelationshipService#updateRelationship` | `RelationshipServiceTest#updateRelationship_throws_DUPLICATE_when_db_constraint_violated` | Done |
+| REQ-009 | update to PARENT_OF with reverse PARENT_OF present → 409 CIRCULAR_RELATIONSHIP | #837 | relationship-edit-dates | `person/relationship/RelationshipService#updateRelationship` | `RelationshipServiceTest#updateRelationship_throws_CIRCULAR_when_reverse_PARENT_OF_exists` | Done |
+| REQ-010 | toDate before fromDate → 400 INVALID_RELATIONSHIP_DATES | #837 | relationship-edit-dates | `person/relationship/RelationshipService#validateRelationshipDates`, `exception/ErrorCode`, `frontend/src/lib/shared/errors.ts` | `RelationshipServiceTest#addRelationship_throws_INVALID_RELATIONSHIP_DATES_when_toDate_before_fromDate`, `#updateRelationship_throws_INVALID_RELATIONSHIP_DATES_when_toDate_before_fromDate` | Done |
+| REQ-011 | date+UNKNOWN precision, or precision without date → 400 INVALID_DATE_PRECISION | #837 | relationship-edit-dates | `person/relationship/RelationshipService#requireDatePrecisionCoherence` | `RelationshipServiceTest#addRelationship_throws_INVALID_DATE_PRECISION_when_date_present_but_precision_unknown`, `#addRelationship_throws_INVALID_DATE_PRECISION_when_precision_set_without_date` | Done |
+| REQ-012 | invalid enum / missing relatedPersonId·relationType / notes > 2000 → 400 VALIDATION_ERROR | #837 | relationship-edit-dates | `person/relationship/RelationshipUpsertRequest` (Bean Validation), `RelationshipController` | `RelationshipControllerTest#updateRelationship_returns400_when_relationType_is_unknown_value`, `#addRelationship_returns400_when_relationType_is_unknown_value` | Done |
+| REQ-013 | updating into a family type flags both endpoints (additive) | #837 | relationship-edit-dates | `person/relationship/RelationshipService#updateRelationship` | `RelationshipServiceTest#updateRelationship_marks_both_endpoints_family_when_updated_to_family_type` | Done |
+| REQ-014 | persist + display notes on create, update, read and edit views | #837 | relationship-edit-dates | `person/relationship/RelationshipService`, `frontend/.../AddRelationshipForm.svelte`, `routes/persons/[id]/PersonRelationshipsCard.svelte` | `RelationshipServiceIntegrationTest#updateRelationship_persists_new_type_dates_and_notes`, `AddRelationshipForm.svelte.spec.ts#round-trips the notes into the textarea`, `PersonRelationshipsCard.svelte.test.ts#shows the notes line` | Done |
+| REQ-015 | detail view shows the date range at its precision; no dates → no date line | #837 | relationship-edit-dates | `frontend/src/lib/person/relationshipDates.ts`, `routes/persons/[id]/PersonRelationshipsCard.svelte` | `relationshipDates.spec.ts`, `PersonRelationshipsCard.svelte.test.ts#renders the date range at its stored precision`, `#renders no date line when the relationship has no dates` | Done |
+| REQ-016 | edit affordance opens a form pre-filled with type/person/dates+precision/notes; precision DAY/MONTH/YEAR | #837 | relationship-edit-dates | `frontend/.../AddRelationshipForm.svelte`, `RelationshipDateField.svelte`, `RelationshipChip.svelte` | `AddRelationshipForm.svelte.spec.ts#pre-fills the from-date as dd.mm.yyyy`, `#offers only DAY/MONTH/YEAR in each precision select`, `RelationshipChip.svelte.spec.ts#shows an Edit affordance with an accessible name when canWrite and onEdit` | Done |
+| REQ-017 | derived Heirat sources SPOUSE_OF.fromDate + fromDatePrecision | #837 | relationship-edit-dates | `timeline/TimelineEventService#buildMarriageEvents` | `DerivedEventsAssemblyTest#should_emit_day_precision_heirat_from_spouse_fromDate` | Done |
+| REQ-018 | unauthenticated PUT → 401, no row modified | #837 | relationship-edit-dates | `person/relationship/RelationshipController` (SecurityConfig) | `RelationshipControllerTest#updateRelationship_returns401_whenUnauthenticated_and_does_not_touch_service` | Done |
+| REQ-019 | while a create/update request is in flight, submit is disabled + shows a progress indicator | #837 | relationship-edit-dates | `frontend/src/lib/person/relationship/AddRelationshipForm.svelte` | `AddRelationshipForm.svelte.spec.ts#disables the submit and shows a progress spinner while a submit is in flight` | Done |
 | REQ-001 | TimelineEntryDTO carries rootTagId/rootTagName/rootTagColor for LETTER entries, assembled in-transaction (id+name+token only) | #835 | zeitstrahl-tag-chips | `timeline/TimelineEntryDTO`, `timeline/TimelineService#mapDocument` | `TimelineServiceTest#letter_with_tags_carries_its_primary_root_tag` | Done |
 | REQ-002 | the three root-tag fields are nullable and not `@Schema(requiredMode = REQUIRED)` | #835 | zeitstrahl-tag-chips | `timeline/TimelineEntryDTO`, `frontend/src/lib/generated/api.ts` (optional) | `TimelineServiceTest#untagged_letter_has_no_root_tag_fields` (+ regenerated `api.ts` shows `rootTag*?`) | Done |
 | REQ-003 | primary tag = root ancestor of the alphabetically-first assigned tag, resolved via TagService | #835 | zeitstrahl-tag-chips | `tag/TagService#resolveRootTags`, `timeline/TimelineService#primaryTag` | `TimelineServiceTest#letter_with_tags_carries_its_primary_root_tag`, `TagServiceTest#resolveRootTags_walksChildToRoot_withRootColor`, `TagServiceIntegrationTest#resolveRootTags_walksPersistedChainToRoot_withRootColor` | Done |
@@ -154,3 +173,39 @@
 | REQ-012 | chip renders wherever a LetterCard renders (global timeline + expanded YearLetterStrip) | #835 | zeitstrahl-tag-chips | `frontend/src/lib/timeline/LetterCard.svelte` | `LetterCard.svelte.spec.ts#renders the chip inside an expanded YearLetterStrip too` | Done |
 | REQ-013 | sr-only theme label is a Paraglide key present in de/en/es | #835 | zeitstrahl-tag-chips | `frontend/messages/{de,en,es}.json` | `messages.spec.ts#zeitstrahl tag-chip label key is present in all locales` | Done |
 | REQ-014 | GET /api/timeline stays read-only (READ_ALL); no new endpoint/ErrorCode/IDOR; assembly logs UUIDs only | #835 | zeitstrahl-tag-chips | `timeline/TimelineController` (unchanged), `timeline/TimelineService` | `TimelineControllerTest#returns_200_with_read_all_permission`, `#returns_403_when_authenticated_without_read_all` (unchanged path); no tag names logged (review) | Done |
+| REQ-001 | TimelineFilters is presentation-only (3 $bindable layer booleans + onChange); no goto/url.searchParams/api.GET/fetch | #780 | timeline-layer-filter | `frontend/src/lib/timeline/TimelineFilters.svelte` | `TimelineFilters.svelte.spec.ts#renders the three layer toggles with accessible names`, `#reflects a layer as pressed and flips it, firing onChange`; `timelineFilterBoundary.spec.ts` | Done |
+| REQ-002 | route derives a client-side $derived filtered view, passes it to TimelineView; no goto/fetch on toggle | #780 | timeline-layer-filter | `frontend/src/routes/zeitstrahl/+page.svelte`, `frontend/src/lib/timeline/timelineFilter.ts#filterTimeline` | `page.svelte.spec.ts#hides letter cards when the Letters layer is off ... with no fetch`; `timelineFilterBoundary.spec.ts` | Done |
+| REQ-003 | Personal off → personal events (curated + derived life-events) hidden client-side | #780 | timeline-layer-filter | `frontend/src/lib/timeline/timelineFilter.ts#filterTimeline` | `timelineFilter.spec.ts#hides personal events — curated and derived`, `page.svelte.spec.ts#hides personal event cards` | Done |
+| REQ-004 | Historical off → historical event entries hidden client-side | #780 | timeline-layer-filter | `frontend/src/lib/timeline/timelineFilter.ts#filterTimeline` | `timelineFilter.spec.ts#hides HISTORICAL events`, `page.svelte.spec.ts#hides historical event cards` | Done |
+| REQ-005 | Letters off → letter entries hidden client-side | #780 | timeline-layer-filter | `frontend/src/lib/timeline/timelineFilter.ts#filterTimeline` | `timelineFilter.spec.ts#hides LETTER entries`, `page.svelte.spec.ts#hides letter cards` | Done |
+| REQ-006 | zero visible → filter empty-state + one-click reset below the open bar (never blank, never generic empty) | #780 | timeline-layer-filter | `frontend/src/routes/zeitstrahl/+page.svelte`, `frontend/src/lib/timeline/timelineFilter.ts#filterTimeline` | `page.svelte.spec.ts#shows the filtered-empty message + reset below the open bar`, `timelineFilter.spec.ts#drops year bands that become empty` | Done |
+| REQ-007 | sticky "Filter (N aktiv)" trigger; N from isDefaultState/hiddenLayerCount; 44px target | #780 | timeline-layer-filter | `frontend/src/lib/timeline/timelineFilter.ts`, `frontend/src/lib/timeline/TimelineFilters.svelte` | `timelineFilter.spec.ts#isDefaultState`, `#hiddenLayerCount`; `TimelineFilters.svelte.spec.ts#shows a plain trigger ... and a count`, `#gives the trigger a 44px touch target` | Done |
+| REQ-008 | reset text button restores all layers on; visibility tracks a $derived any-layer-off flag | #780 | timeline-layer-filter | `frontend/src/lib/timeline/TimelineFilters.svelte` | `TimelineFilters.svelte.spec.ts#hides the reset button by default and restores all layers when activated` | Done |
+| REQ-009 | prefers-reduced-motion → slide duration 0 (matchMedia guard reused from documents/[id]/+page.svelte:57) | #780 | timeline-layer-filter | `frontend/src/lib/timeline/TimelineFilters.svelte` | manual reduced-motion check + svelte-autofixer/code review (guard reused, only the slide `duration` zeroed) | Done |
+| REQ-010 | 8 timeline_filter_* keys in de/en/es; trigger vs trigger_active({count}) distinct | #780 | timeline-layer-filter | `frontend/messages/{de,en,es}.json` | `messages.spec.ts#zeitstrahl layer-filter keys are present in all locales (#780 REQ-010)` | Done |
+| REQ-001 | WRITE_ALL viewer → "Ereignis hinzufügen" link to /zeitstrahl/events/new in the wrapping Zeitstrahl header | #842 | timeline-curator-affordances | `frontend/src/routes/zeitstrahl/+page.svelte`, `frontend/messages/{de,en,es}.json` | `zeitstrahl/page.svelte.spec.ts#renders the add-event CTA in a wrapping header when the viewer can write` | Done |
+| REQ-002 | viewer without WRITE_ALL → no add-event affordance on /zeitstrahl | #842 | timeline-curator-affordances | `frontend/src/routes/zeitstrahl/+page.svelte` | `zeitstrahl/page.svelte.spec.ts#renders no add-event CTA when the viewer cannot write` | Done |
+| REQ-003 | WRITE_ALL viewer → person-page "Ereignis für diese Person" link to /zeitstrahl/events/new?personId={id} | #842 | timeline-curator-affordances | `frontend/src/routes/persons/[id]/PersonCard.svelte`, `frontend/messages/{de,en,es}.json` | `PersonCard.svelte.spec.ts#shows an add-event link pre-seeded with the person to a curator` | Done |
+| REQ-004 | viewer without WRITE_ALL → no add-event affordance on /persons/{id} | #842 | timeline-curator-affordances | `frontend/src/routes/persons/[id]/PersonCard.svelte` | `PersonCard.svelte.spec.ts#renders no add-event link to a reader` | Done |
+| REQ-005 | WRITE_ALL → EventPill edit link /zeitstrahl/events/{eventId}/edit for a curated PERSONAL event | #842 | timeline-curator-affordances | `frontend/src/lib/timeline/EventPill.svelte` | `EventPill.svelte.spec.ts#shows an edit affordance for a curated PERSONAL event when canWrite is true` | Done |
+| REQ-006 | WRITE_ALL → WorldBand edit link /zeitstrahl/events/{eventId}/edit for a curated HISTORICAL event (new inline ✎) | #842 | timeline-curator-affordances | `frontend/src/lib/timeline/WorldBand.svelte` | `WorldBand.svelte.spec.ts#shows an edit affordance for a curated HISTORICAL event when canWrite is true`, `#mirrors the EventPill pencil` | Done |
+| REQ-007 | viewer without WRITE_ALL → neither EventPill nor WorldBand renders an edit link | #842 | timeline-curator-affordances | `frontend/src/lib/timeline/EventPill.svelte`, `frontend/src/lib/timeline/WorldBand.svelte` | `EventPill.svelte.spec.ts#renders no edit affordance for a curated PERSONAL event when canWrite is false`, `WorldBand.svelte.spec.ts#renders no edit affordance for a curated HISTORICAL event when canWrite is false`, `TimelineView.svelte.spec.ts#renders no edit links in either path when canWrite is false` | Done |
+| REQ-008 | derived OR null eventId → no edit link regardless of permission (contract preserved) | #842 | timeline-curator-affordances | `frontend/src/lib/timeline/EventPill.svelte`, `frontend/src/lib/timeline/WorldBand.svelte` | `EventPill.svelte.spec.ts#shows no edit affordance when eventId is null even with canWrite`, `#shows no edit affordance for a derived event even with canWrite`, `WorldBand.svelte.spec.ts#shows no edit affordance when eventId is null even with canWrite` | Done |
+| REQ-009 | TimelineView threads canWrite through the year-band path and the undated bucket (identical gate) | #842 | timeline-curator-affordances | `frontend/src/lib/timeline/TimelineView.svelte`, `frontend/src/lib/timeline/YearBand.svelte` | `TimelineView.svelte.spec.ts#threads canWrite to a curated event in both a year band and the undated bucket`, `#threads canWrite to a curated HISTORICAL world band in both paths` | Done |
+| REQ-010 | person add-event opens #781 create form prefilled with the person, returns to /persons/{id} on save | #842 | timeline-curator-affordances | `frontend/src/routes/persons/[id]/PersonCard.svelte`, `frontend/src/routes/zeitstrahl/events/new/+page.server.ts` (#781) | `PersonCard.svelte.spec.ts#shows an add-event link pre-seeded with the person to a curator` (URL), `zeitstrahl/events/new/page.server.spec.ts#redirects to /persons/{id} when originPersonId is a valid UUID` (#781) | Done |
+| REQ-011 | non-curator direct nav to /zeitstrahl/events/new or /{id}/edit → 403 (existing #781 route guard, regression) | #842 | timeline-curator-affordances | `frontend/src/routes/zeitstrahl/events/new/+page.server.ts`, `frontend/src/routes/zeitstrahl/events/[id]/edit/+page.server.ts` (#781, unchanged — both share `requireWriteAll`) | `zeitstrahl/events/new/page.server.spec.ts#throws 403 for an authenticated user without WRITE_ALL`, `zeitstrahl/events/[id]/edit/page.server.spec.ts#throws 403 for a user without WRITE_ALL` | Done |
+| REQ-001 | `/zeitstrahl` renders a single chronological timeline with no grouping-mode control (no toggle/Thema/drawer) | #850 | inline-event-clustering | `frontend/src/routes/zeitstrahl/+page.svelte`, `frontend/src/lib/timeline/TimelineView.svelte` | `page.svelte.spec.ts#renders the meta sub-line with range and counts, no grouping segment`; absence of `GroupingControl`/`LetterBucket`/`BucketHeaderChip` (never ported) | Done |
+| REQ-002 | curated event with ≥1 same-year linked letter → contained card (event header + glyph/title/date·provenance/edit + compact letter cards) | #850 | inline-event-clustering | `frontend/src/lib/timeline/EventCluster.svelte`, `frontend/src/lib/timeline/YearBand.svelte`, `frontend/src/lib/timeline/eventClustering.ts` | `EventCluster.svelte.spec.ts#renders a data-testid event-card with the event title once`, `#shows the event-edit link for a curator`, `#renders its letters as compact a.lcard.ev cards`; `YearBand.svelte.spec.ts#renders a curated event with a same-year linked letter as one event-card, title once, no separate pill` | Done |
+| REQ-003 | event card body > 5 letters → first 5 + keyboard-operable show-more/less toggle (aria-expanded, ≥44px) | #850 | inline-event-clustering | `frontend/src/lib/timeline/EventCluster.svelte`, `frontend/src/lib/timeline/eventClustering.ts` (`CLUSTER_PREVIEW=5`) | `EventCluster.svelte.spec.ts#shows the first 5 of 8 letters + a show-more toggle that expands to 8 then back to 5`, `#renders no show-more toggle when the cluster holds 5 or fewer letters` | Done |
+| REQ-004 | linked letters in a year other than the event's band → labeled ✉ text-header card (no pill, no edit link) per such year | #850 | inline-event-clustering | `frontend/src/lib/timeline/EventCluster.svelte`, `frontend/src/lib/timeline/YearBand.svelte` | `EventCluster.svelte.spec.ts#renders a cross-year text header (✉ title, no event-edit, no pill) when no event is given`; `YearBand.svelte.spec.ts#renders a cross-year cluster (event not in this band) as a ✉ text-header card holding it` | Done |
+| REQ-005 | event/derived/world-band with no linked letters → existing plain pill/world-band (unchanged) | #850 | inline-event-clustering | `frontend/src/lib/timeline/YearBand.svelte`, `frontend/src/lib/timeline/EventPill.svelte`, `frontend/src/lib/timeline/WorldBand.svelte` | `YearBand.svelte.spec.ts#renders a curated event with NO linked letters as a plain EventPill, no card` | Done |
+| REQ-006 | letter linked to no curated event → loose chronological letter (alternating; density strip past 12) | #850 | inline-event-clustering | `frontend/src/lib/timeline/YearBand.svelte`, `frontend/src/lib/timeline/eventClustering.ts` | `eventClustering.spec.ts#keeps a letter with no linkedEventId loose`; `YearBand.svelte.spec.ts#renders loose (unlinked) letters in a sparse year as alternating .letter-row, no card` | Done |
+| REQ-007 | loose-letter layout + density strip count ONLY non-event-linked letters; clustered letter never also loose | #850 | inline-event-clustering | `frontend/src/lib/timeline/YearBand.svelte`, `frontend/src/lib/timeline/eventClustering.ts` | `eventClustering.spec.ts#places each letter in exactly one place`; `YearBand.svelte.spec.ts#counts only loose letters in the density strip; event letters stay in the card` | Done |
+| REQ-008 | letter whose only linking event is filtered out (absent from lookup) → loose, never re-introduces the event (filter-then-cluster) | #850 | inline-event-clustering | `frontend/src/lib/timeline/eventClustering.ts` (`splitYearLetters` filters via `eventLookup`) | `eventClustering.spec.ts#keeps a letter whose linkedEventId is absent from the lookup loose (filter-then-cluster, REQ-008)` | Done |
+| REQ-009 | `TimelineEntryDTO` carries nullable `linkedEventId` for LETTER entries, one batched pass, no new column/migration, not @Schema(REQUIRED); a multi-event letter links deterministically (earliest date, then id) | #850 | inline-event-clustering | `backend/.../timeline/TimelineEntryDTO.java`, `backend/.../timeline/TimelineService.java#resolveLetterEventLinks`, `frontend/src/lib/generated/api.ts` | `TimelineServiceTest#letter_in_a_curated_events_documents_carries_that_events_id`, `#letter_in_no_curated_event_has_null_linkedEventId`, `#multi_event_letter_links_deterministically_to_the_earliest_event` | Done |
+| REQ-010 | event/letter/sender/receiver text via Svelte `{...}` escaping; no `{@html}` anywhere in `lib/timeline/` (grep gate, CWE-79) | #850 | inline-event-clustering | `frontend/src/lib/timeline/*.svelte` | `timeline-no-raw-html.spec.ts#no timeline component contains the raw-HTML directive`; `EventCluster.svelte.spec.ts#renders an HTML-bearing event title verbatim as text, never as markup` | Done |
+| REQ-011 | wrapping header keeps #842 add-event CTA + #780 filter trigger; meta-line drops the grouping segment | #850 | inline-event-clustering | `frontend/src/routes/zeitstrahl/+page.svelte` | `page.svelte.spec.ts#renders the meta sub-line with range and counts, no grouping segment`, `#drops the letters segment instead of showing "0 Briefe"` (no "Gruppierung") | Done |
+| REQ-012 | show-more/less labels are new Paraglide keys in de/en/es; unused #827 grouping/Thema keys removed | #850 | inline-event-clustering | `frontend/messages/{de,en,es}.json`, `frontend/src/lib/timeline/EventCluster.svelte` | `messages.spec.ts#zeitstrahl visual-fidelity keys are present in all locales` (now asserts `timeline_bucket_show_more`/`_less`; `timeline_grouping_date` removed) | Done |
+| REQ-013 | `GET /api/timeline` failure → existing localized error state via `getErrorMessage(code)` (unchanged #779) | #850 | inline-event-clustering | `frontend/src/routes/zeitstrahl/+page.svelte` (unchanged error path) | covered by #779 `zeitstrahl` error-state tests (regression — no change) | Done |
+| REQ-014 | HISTORICAL curated event with ≥1 linked letter keeps its full-width WorldBand — never clusters into a card (preserves #779 REQ-009); its letters stay loose | #850 | inline-event-clustering | `frontend/src/lib/timeline/eventClustering.ts` (`buildEventLookup` excludes HISTORICAL) | `eventClustering.spec.ts#excludes a HISTORICAL event so its letters stay loose, keeping its WorldBand (REQ-014)`; `TimelineView.svelte.spec.ts#keeps a HISTORICAL event a WorldBand with a same-year linked letter — never clusters (REQ-014)` | Done |
+| REQ-015 | a cross-year ✉ card is placed at its earliest linked letter's chronological position in the band — never appended after later-dated loose letters | #850 | inline-event-clustering | `frontend/src/lib/timeline/YearBand.svelte` | `YearBand.svelte.spec.ts#interleaves a cross-year card before a later-dated loose letter in the same band (REQ-015)` | Done |

CLAUDE.md

@@ -170,7 +170,7 @@ Input DTOs live flat in the domain package. Response types are the model entitie
 
 → See [CONTRIBUTING.md §Error handling](./CONTRIBUTING.md#error-handling)
 
-**LLM reminder:** use `DomainException.notFound/forbidden/conflict/internal()` from service methods — never throw raw exceptions. When adding a new `ErrorCode`: (1) add to `ErrorCode.java`, (2) add to `ErrorCode` type in `frontend/src/lib/shared/errors.ts`, (3) add a `case` in `getErrorMessage()`, (4) add i18n keys in `messages/{de,en,es}.json`. Valid error codes include: `TOO_MANY_LOGIN_ATTEMPTS` (returned by `LoginRateLimiter` as HTTP 429 when a brute-force threshold is exceeded); `JOURNEY_NOTE_TOO_LONG`, `JOURNEY_DOCUMENT_ALREADY_ADDED`, `GESCHICHTE_TYPE_IMMUTABLE`, `GESCHICHTE_TITLE_TOO_LONG`, `GESCHICHTE_INTRO_TOO_LONG` (journey/geschichte domain constraints); `TIMELINE_EVENT_NOT_FOUND`, `TIMELINE_EVENT_CONFLICT`, `TIMELINE_TITLE_TOO_LONG` (timeline event CRUD), plus a generic `CONFLICT` (409 optimistic-lock backstop).
+**LLM reminder:** use `DomainException.notFound/forbidden/conflict/internal()` from service methods — never throw raw exceptions. When adding a new `ErrorCode`: (1) add to `ErrorCode.java`, (2) add to `ErrorCode` type in `frontend/src/lib/shared/errors.ts`, (3) add a `case` in `getErrorMessage()`, (4) add i18n keys in `messages/{de,en,es}.json`. Valid error codes include: `TOO_MANY_LOGIN_ATTEMPTS` (returned by `LoginRateLimiter` as HTTP 429 when a brute-force threshold is exceeded); `JOURNEY_NOTE_TOO_LONG`, `JOURNEY_DOCUMENT_ALREADY_ADDED`, `GESCHICHTE_TYPE_IMMUTABLE`, `GESCHICHTE_TITLE_TOO_LONG`, `GESCHICHTE_INTRO_TOO_LONG` (journey/geschichte domain constraints); `TIMELINE_EVENT_NOT_FOUND`, `TIMELINE_EVENT_CONFLICT`, `TIMELINE_TITLE_TOO_LONG` (timeline event CRUD); `INVALID_RELATIONSHIP_DATES` (relationship `toDate` before `fromDate`), plus a generic `CONFLICT` (409 optimistic-lock backstop).
 
 ### Security / Permissions
 
@@ -280,7 +280,7 @@ Back button pattern — use the shared `<BackButton>` component from `$lib/share
 
 → See [CONTRIBUTING.md §Error handling](./CONTRIBUTING.md#error-handling)
 
-**LLM reminder:** when adding a new `ErrorCode`: (1) add to `ErrorCode.java`, (2) add to `ErrorCode` type in `frontend/src/lib/shared/errors.ts`, (3) add a `case` in `getErrorMessage()`, (4) add i18n keys in `messages/{de,en,es}.json`. Valid error codes include: `TOO_MANY_LOGIN_ATTEMPTS` (returned by `LoginRateLimiter` as HTTP 429 when a brute-force threshold is exceeded); `JOURNEY_NOTE_TOO_LONG`, `JOURNEY_DOCUMENT_ALREADY_ADDED`, `GESCHICHTE_TYPE_IMMUTABLE`, `GESCHICHTE_TITLE_TOO_LONG`, `GESCHICHTE_INTRO_TOO_LONG` (journey/geschichte domain constraints); `TIMELINE_EVENT_NOT_FOUND`, `TIMELINE_EVENT_CONFLICT`, `TIMELINE_TITLE_TOO_LONG` (timeline event CRUD), plus a generic `CONFLICT` (409 optimistic-lock backstop).
+**LLM reminder:** when adding a new `ErrorCode`: (1) add to `ErrorCode.java`, (2) add to `ErrorCode` type in `frontend/src/lib/shared/errors.ts`, (3) add a `case` in `getErrorMessage()`, (4) add i18n keys in `messages/{de,en,es}.json`. Valid error codes include: `TOO_MANY_LOGIN_ATTEMPTS` (returned by `LoginRateLimiter` as HTTP 429 when a brute-force threshold is exceeded); `JOURNEY_NOTE_TOO_LONG`, `JOURNEY_DOCUMENT_ALREADY_ADDED`, `GESCHICHTE_TYPE_IMMUTABLE`, `GESCHICHTE_TITLE_TOO_LONG`, `GESCHICHTE_INTRO_TOO_LONG` (journey/geschichte domain constraints); `TIMELINE_EVENT_NOT_FOUND`, `TIMELINE_EVENT_CONFLICT`, `TIMELINE_TITLE_TOO_LONG` (timeline event CRUD); `INVALID_RELATIONSHIP_DATES` (relationship `toDate` before `fromDate`), plus a generic `CONFLICT` (409 optimistic-lock backstop).
 
 ---
 

backend/pom.xml

@@ -369,6 +369,12 @@
 				<artifactId>maven-surefire-plugin</artifactId>
 				<configuration>
 					<forkedProcessTimeoutInSeconds>600</forkedProcessTimeoutInSeconds>
+					<!-- Grace period after the test JVM calls System.exit(0). The 30s default is too
+					     short: the single reused fork closes ~32 cached Spring contexts at shutdown,
+					     each tearing down a Testcontainers Postgres + HikariCP pool, which overruns 30s
+					     and makes Surefire kill the fork (BUILD FAILURE despite 0 test failures). This is
+					     a different knob from forkedProcessTimeoutInSeconds above. See issue #848. -->
+					<forkedProcessExitTimeoutInSeconds>120</forkedProcessExitTimeoutInSeconds>
 					<systemPropertyVariables>
 						<junit.jupiter.execution.timeout.default>90 s</junit.jupiter.execution.timeout.default>
 					</systemPropertyVariables>

backend/src/main/java/org/raddatz/familienarchiv/document/DatePrecisionValidation.java

@@ -0,0 +1,42 @@
+package org.raddatz.familienarchiv.document;
+
+import org.raddatz.familienarchiv.exception.DomainException;
+import org.raddatz.familienarchiv.exception.ErrorCode;
+
+import java.time.LocalDate;
+
+/**
+ * Cross-field validation and normalization shared by every domain that stores a
+ * {@link LocalDate} + {@link DatePrecision} pair — a person's life dates (ADR-039 / V76)
+ * and a relationship's from/to dates (ADR-044 / V78). Kept out of {@link DatePrecision}
+ * itself because that enum is a frozen contract mirror of the import normalizer (ADR-025)
+ * and must carry no behaviour.
+ */
+public final class DatePrecisionValidation {
+
+    private DatePrecisionValidation() {}
+
+    /**
+     * Enforces the date ⇔ precision coherence the V76/V78 CHECK constraints also enforce:
+     * a date requires a non-{@code UNKNOWN} precision, and a non-{@code UNKNOWN} precision
+     * requires a date. Validated in-service so the caller gets a structured 400 instead of
+     * the database constraint's raw 500.
+     *
+     * @param side human-readable field label woven into the error message ("birth", "from", …)
+     */
+    public static void requireCoherence(LocalDate date, DatePrecision precision, String side) {
+        if (date != null && (precision == null || precision == DatePrecision.UNKNOWN)) {
+            throw DomainException.badRequest(ErrorCode.INVALID_DATE_PRECISION,
+                    side + " date is set but its precision is missing or UNKNOWN");
+        }
+        if (date == null && precision != null && precision != DatePrecision.UNKNOWN) {
+            throw DomainException.badRequest(ErrorCode.INVALID_DATE_PRECISION,
+                    side + " date precision " + precision + " is set without a date");
+        }
+    }
+
+    /** A null precision means "no precision recorded" → {@link DatePrecision#UNKNOWN}. */
+    public static DatePrecision normalize(DatePrecision precision) {
+        return precision == null ? DatePrecision.UNKNOWN : precision;
+    }
+}

backend/src/main/java/org/raddatz/familienarchiv/exception/ErrorCode.java

@@ -122,6 +122,8 @@ public enum ErrorCode {
     CIRCULAR_RELATIONSHIP,
     /** A relationship with the same (person, relatedPerson, type) already exists. 409 */
     DUPLICATE_RELATIONSHIP,
+    /** A relationship's toDate is before its fromDate. 400 */
+    INVALID_RELATIONSHIP_DATES,
 
     // --- Geschichten (Stories) ---
     /** A Geschichte (story) with the given ID does not exist, or is a DRAFT and the caller lacks BLOG_WRITE. 404 */

backend/src/main/java/org/raddatz/familienarchiv/importing/PersonTreeImporter.java

@@ -13,7 +13,7 @@ import org.raddatz.familienarchiv.person.PersonType;
 import org.raddatz.familienarchiv.person.PersonUpsertCommand;
 import org.raddatz.familienarchiv.person.relationship.RelationType;
 import org.raddatz.familienarchiv.person.relationship.RelationshipService;
-import org.raddatz.familienarchiv.person.relationship.dto.CreateRelationshipRequest;
+import org.raddatz.familienarchiv.person.relationship.dto.RelationshipUpsertRequest;
 import org.springframework.stereotype.Component;
 
 import java.io.File;
@@ -126,7 +126,7 @@ public class PersonTreeImporter {
     private boolean addRelationshipIdempotently(UUID person, UUID related, String type) {
         try {
             relationshipService.addRelationship(person,
-                    new CreateRelationshipRequest(related, RelationType.valueOf(type), null, null, null));
+                    new RelationshipUpsertRequest(related, RelationType.valueOf(type), null, null, null, null, null));
             return true;
         } catch (DomainException e) {
             if (e.getCode() == ErrorCode.DUPLICATE_RELATIONSHIP

backend/src/main/java/org/raddatz/familienarchiv/person/PersonService.java

@@ -18,6 +18,7 @@ import org.raddatz.familienarchiv.person.PersonNameAliasDTO;
 import org.raddatz.familienarchiv.person.PersonSummaryDTO;
 import org.raddatz.familienarchiv.person.PersonUpdateDTO;
 import org.raddatz.familienarchiv.document.DatePrecision;
+import org.raddatz.familienarchiv.document.DatePrecisionValidation;
 import org.raddatz.familienarchiv.exception.DomainException;
 import org.raddatz.familienarchiv.exception.ErrorCode;
 import org.raddatz.familienarchiv.person.Person;
@@ -448,41 +449,28 @@ public class PersonService {
                 .alias(dto.getAlias() == null || dto.getAlias().isBlank() ? null : dto.getAlias().trim())
                 .notes(dto.getNotes() == null || dto.getNotes().isBlank() ? null : dto.getNotes().trim())
                 .birthDate(dto.getBirthDate())
-                .birthDatePrecision(normalizePrecision(dto.getBirthDatePrecision()))
+                .birthDatePrecision(DatePrecisionValidation.normalize(dto.getBirthDatePrecision()))
                 .deathDate(dto.getDeathDate())
-                .deathDatePrecision(normalizePrecision(dto.getDeathDatePrecision()))
+                .deathDatePrecision(DatePrecisionValidation.normalize(dto.getDeathDatePrecision()))
                 .generation(dto.getGeneration())
                 .build();
         return personRepository.save(person);
     }
 
     // Cross-field invariants the V76 CHECK constraints also enforce — validated here so the
-    // user gets a structured ErrorCode instead of a raw constraint-violation 500.
+    // user gets a structured ErrorCode instead of a raw constraint-violation 500. Coherence
+    // is shared with the relationship domain (DatePrecisionValidation); only the order check
+    // (and its BIRTH_AFTER_DEATH code) is life-date specific.
     private void validateLifeDates(LocalDate birthDate, DatePrecision birthPrecision,
                                    LocalDate deathDate, DatePrecision deathPrecision) {
-        requireDatePrecisionCoherence(birthDate, birthPrecision, "birth");
-        requireDatePrecisionCoherence(deathDate, deathPrecision, "death");
+        DatePrecisionValidation.requireCoherence(birthDate, birthPrecision, "birth");
+        DatePrecisionValidation.requireCoherence(deathDate, deathPrecision, "death");
         if (birthDate != null && deathDate != null && birthDate.isAfter(deathDate)) {
             throw DomainException.badRequest(ErrorCode.BIRTH_AFTER_DEATH,
                     "Birth date " + birthDate + " is after death date " + deathDate);
         }
     }
 
-    private static void requireDatePrecisionCoherence(LocalDate date, DatePrecision precision, String side) {
-        if (date != null && (precision == null || precision == DatePrecision.UNKNOWN)) {
-            throw DomainException.badRequest(ErrorCode.INVALID_DATE_PRECISION,
-                    side + " date is set but its precision is missing or UNKNOWN");
-        }
-        if (date == null && precision != null && precision != DatePrecision.UNKNOWN) {
-            throw DomainException.badRequest(ErrorCode.INVALID_DATE_PRECISION,
-                    side + " date precision " + precision + " is set without a date");
-        }
-    }
-
-    private static DatePrecision normalizePrecision(DatePrecision precision) {
-        return precision == null ? DatePrecision.UNKNOWN : precision;
-    }
-
     @Transactional
     public Person updatePerson(UUID id, PersonUpdateDTO dto) {
         if (dto.getPersonType() == PersonType.SKIP) {
@@ -499,9 +487,9 @@ public class PersonService {
         person.setAlias(dto.getAlias() == null || dto.getAlias().isBlank() ? null : dto.getAlias().trim());
         person.setNotes(dto.getNotes() == null || dto.getNotes().isBlank() ? null : dto.getNotes().trim());
         person.setBirthDate(dto.getBirthDate());
-        person.setBirthDatePrecision(normalizePrecision(dto.getBirthDatePrecision()));
+        person.setBirthDatePrecision(DatePrecisionValidation.normalize(dto.getBirthDatePrecision()));
         person.setDeathDate(dto.getDeathDate());
-        person.setDeathDatePrecision(normalizePrecision(dto.getDeathDatePrecision()));
+        person.setDeathDatePrecision(DatePrecisionValidation.normalize(dto.getDeathDatePrecision()));
         // Form path: a human can clear generation back to null. Unlike the importer
         // which routes through preferHuman, we write the DTO value verbatim.
         person.setGeneration(dto.getGeneration());

backend/src/main/java/org/raddatz/familienarchiv/person/relationship/PersonRelationship.java

@@ -5,9 +5,11 @@ import io.swagger.v3.oas.annotations.media.Schema;
 import jakarta.persistence.*;
 import lombok.*;
 import org.hibernate.annotations.CreationTimestamp;
+import org.raddatz.familienarchiv.document.DatePrecision;
 import org.raddatz.familienarchiv.person.Person;
 
 import java.time.Instant;
+import java.time.LocalDate;
 import java.util.UUID;
 
 @Entity
@@ -39,11 +41,25 @@ public class PersonRelationship {
     @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
     private RelationType relationType;
 
-    @Column(name = "from_year")
-    private Integer fromYear;
+    // Start/end of the relationship (wedding, employment start, …). The date column
+    // is nullable, the precision column is NOT NULL with UNKNOWN meaning "no date" —
+    // the V78 CHECK constraints enforce (date IS NULL) = (precision = UNKNOWN) and
+    // from_date <= to_date. Mirrors Person.{birth,death}Date (ADR-039 / ADR-044).
+    private LocalDate fromDate;
 
-    @Column(name = "to_year")
-    private Integer toYear;
+    @Enumerated(EnumType.STRING)
+    @Column(name = "from_date_precision", nullable = false, length = 16)
+    @Builder.Default
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private DatePrecision fromDatePrecision = DatePrecision.UNKNOWN;
+
+    private LocalDate toDate;
+
+    @Enumerated(EnumType.STRING)
+    @Column(name = "to_date_precision", nullable = false, length = 16)
+    @Builder.Default
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private DatePrecision toDatePrecision = DatePrecision.UNKNOWN;
 
     @Column(length = 2000)
     private String notes;

backend/src/main/java/org/raddatz/familienarchiv/person/relationship/RelationshipController.java

@@ -3,7 +3,7 @@ package org.raddatz.familienarchiv.person.relationship;
 import jakarta.validation.Valid;
 import lombok.RequiredArgsConstructor;
 import org.raddatz.familienarchiv.person.Person;
-import org.raddatz.familienarchiv.person.relationship.dto.CreateRelationshipRequest;
+import org.raddatz.familienarchiv.person.relationship.dto.RelationshipUpsertRequest;
 import org.raddatz.familienarchiv.person.relationship.dto.FamilyMemberPatchDTO;
 import org.raddatz.familienarchiv.person.relationship.dto.InferredRelationshipDTO;
 import org.raddatz.familienarchiv.person.relationship.dto.InferredRelationshipWithPersonDTO;
@@ -63,11 +63,20 @@ public class RelationshipController {
     @RequirePermission(Permission.WRITE_ALL)
     public ResponseEntity<RelationshipDTO> addRelationship(
             @PathVariable UUID id,
-            @Valid @RequestBody CreateRelationshipRequest dto) {
+            @Valid @RequestBody RelationshipUpsertRequest dto) {
         return ResponseEntity.status(HttpStatus.CREATED)
                 .body(relationshipService.addRelationship(id, dto));
     }
 
+    @PutMapping("/api/persons/{id}/relationships/{relId}")
+    @RequirePermission(Permission.WRITE_ALL)
+    public RelationshipDTO updateRelationship(
+            @PathVariable UUID id,
+            @PathVariable UUID relId,
+            @Valid @RequestBody RelationshipUpsertRequest dto) {
+        return relationshipService.updateRelationship(id, relId, dto);
+    }
+
     @DeleteMapping("/api/persons/{id}/relationships/{relId}")
     @ResponseStatus(HttpStatus.NO_CONTENT)
     @RequirePermission(Permission.WRITE_ALL)

backend/src/main/java/org/raddatz/familienarchiv/person/relationship/RelationshipService.java

@@ -1,10 +1,12 @@
 package org.raddatz.familienarchiv.person.relationship;
 
 import lombok.RequiredArgsConstructor;
+import org.raddatz.familienarchiv.document.DatePrecision;
+import org.raddatz.familienarchiv.document.DatePrecisionValidation;
 import org.raddatz.familienarchiv.exception.DomainException;
 import org.raddatz.familienarchiv.exception.ErrorCode;
 import org.raddatz.familienarchiv.person.Person;
-import org.raddatz.familienarchiv.person.relationship.dto.CreateRelationshipRequest;
+import org.raddatz.familienarchiv.person.relationship.dto.RelationshipUpsertRequest;
 import org.raddatz.familienarchiv.person.relationship.dto.InferredRelationshipDTO;
 import org.raddatz.familienarchiv.person.relationship.dto.InferredRelationshipWithPersonDTO;
 import org.raddatz.familienarchiv.person.relationship.dto.NetworkDTO;
@@ -96,65 +98,129 @@ public class RelationshipService {
     }
 
     @Transactional
-    public RelationshipDTO addRelationship(UUID personId, CreateRelationshipRequest dto) {
-        if (personId.equals(dto.relatedPersonId())) {
-            throw DomainException.badRequest(
-                    ErrorCode.VALIDATION_ERROR, "Cannot relate a person to themselves");
-        }
+    public RelationshipDTO addRelationship(UUID personId, RelationshipUpsertRequest dto) {
+        requireNotSelf(personId, dto.relatedPersonId());
         Person person = personService.getById(personId);
         Person relatedPerson = personService.getById(dto.relatedPersonId());
 
-        validateYears(dto.fromYear(), dto.toYear());
-
-        if (dto.relationType() == RelationType.PARENT_OF
-                && relationshipRepository.existsByPersonIdAndRelatedPersonIdAndRelationType(
-                        relatedPerson.getId(), personId, RelationType.PARENT_OF)) {
-            throw DomainException.conflict(
-                    ErrorCode.CIRCULAR_RELATIONSHIP,
-                    "Reverse PARENT_OF already exists between " + personId + " and " + relatedPerson.getId());
-        }
+        validateRelationshipDates(dto.fromDate(), dto.fromDatePrecision(), dto.toDate(), dto.toDatePrecision());
+        requireNoReverseParent(person.getId(), relatedPerson.getId(), dto.relationType());
 
         PersonRelationship rel = PersonRelationship.builder()
                 .person(person)
                 .relatedPerson(relatedPerson)
                 .relationType(dto.relationType())
-                .fromYear(dto.fromYear())
-                .toYear(dto.toYear())
+                .fromDate(dto.fromDate())
+                .fromDatePrecision(DatePrecisionValidation.normalize(dto.fromDatePrecision()))
+                .toDate(dto.toDate())
+                .toDatePrecision(DatePrecisionValidation.normalize(dto.toDatePrecision()))
                 .notes(blankToNull(dto.notes()))
                 .build();
 
-        PersonRelationship saved;
-        try {
-            // saveAndFlush so the unique_rel constraint violates synchronously and is
-            // caught here, not at commit time outside the @Transactional boundary.
-            saved = relationshipRepository.saveAndFlush(rel);
-        } catch (DataIntegrityViolationException e) {
-            throw DomainException.conflict(
-                    ErrorCode.DUPLICATE_RELATIONSHIP,
-                    "Relationship already exists for (" + personId + ", " + relatedPerson.getId() + ", " + dto.relationType() + ")");
-        }
-        // Family-graph edges imply both endpoints are family members. Idempotent: the
-        // setter is a no-op when the person is already flagged, so re-imports stay clean.
-        if (FAMILY_RELATION_TYPES.contains(dto.relationType())) {
-            personService.setFamilyMember(person.getId(), true);
-            personService.setFamilyMember(relatedPerson.getId(), true);
-        }
+        PersonRelationship saved = persistOrConflict(rel, person.getId(), relatedPerson.getId(), dto.relationType());
+        flagFamilyMembership(dto.relationType(), person.getId(), relatedPerson.getId());
         return toDTO(saved);
     }
 
+    @Transactional
+    public RelationshipDTO updateRelationship(UUID personId, UUID relId, RelationshipUpsertRequest dto) {
+        PersonRelationship rel = loadOwnedRelationship(personId, relId);
+
+        // The other party from {personId}'s viewpoint cannot be {personId} itself.
+        requireNotSelf(personId, dto.relatedPersonId());
+        validateRelationshipDates(dto.fromDate(), dto.fromDatePrecision(), dto.toDate(), dto.toDatePrecision());
+
+        // Preserve the directed orientation: {personId} keeps whichever role (subject or
+        // object) it already holds on the row, and the edited "related person" takes the
+        // other role. So a PARENT_OF edge stays parent→child whether the curator edits it
+        // from the parent's page or the child's.
+        boolean viewpointIsSubject = personId.equals(rel.getPerson().getId());
+        Person viewpoint = viewpointIsSubject ? rel.getPerson() : rel.getRelatedPerson();
+        Person other = personService.getById(dto.relatedPersonId());
+        Person newSubject = viewpointIsSubject ? viewpoint : other;
+        Person newObject = viewpointIsSubject ? other : viewpoint;
+
+        requireNoReverseParent(newSubject.getId(), newObject.getId(), dto.relationType());
+
+        rel.setPerson(newSubject);
+        rel.setRelatedPerson(newObject);
+        rel.setRelationType(dto.relationType());
+        rel.setFromDate(dto.fromDate());
+        rel.setFromDatePrecision(DatePrecisionValidation.normalize(dto.fromDatePrecision()));
+        rel.setToDate(dto.toDate());
+        rel.setToDatePrecision(DatePrecisionValidation.normalize(dto.toDatePrecision()));
+        rel.setNotes(blankToNull(dto.notes()));
+
+        PersonRelationship saved = persistOrConflict(rel, newSubject.getId(), newObject.getId(), dto.relationType());
+        flagFamilyMembership(dto.relationType(), newSubject.getId(), newObject.getId());
+        return toDTO(saved);
+    }
+
+    // --- shared create/update invariants ---------------------------------------------
+
+    // A person cannot be related to themselves, from either viewpoint.
+    private static void requireNotSelf(UUID viewpointId, UUID relatedPersonId) {
+        if (viewpointId.equals(relatedPersonId)) {
+            throw DomainException.badRequest(
+                    ErrorCode.VALIDATION_ERROR, "Cannot relate a person to themselves");
+        }
+    }
+
+    // A PARENT_OF edge must not already have its mirror (child PARENT_OF parent) stored —
+    // that would be a cycle. No-op for every other relation type.
+    private void requireNoReverseParent(UUID subjectId, UUID objectId, RelationType type) {
+        if (type == RelationType.PARENT_OF
+                && relationshipRepository.existsByPersonIdAndRelatedPersonIdAndRelationType(
+                        objectId, subjectId, RelationType.PARENT_OF)) {
+            throw DomainException.conflict(
+                    ErrorCode.CIRCULAR_RELATIONSHIP,
+                    "Reverse PARENT_OF already exists between " + subjectId + " and " + objectId);
+        }
+    }
+
+    // saveAndFlush so the unique_rel constraint violates synchronously and is caught here,
+    // inside the @Transactional boundary, not at commit time as a raw 500.
+    private PersonRelationship persistOrConflict(PersonRelationship rel, UUID subjectId, UUID objectId, RelationType type) {
+        try {
+            return relationshipRepository.saveAndFlush(rel);
+        } catch (DataIntegrityViolationException e) {
+            throw DomainException.conflict(
+                    ErrorCode.DUPLICATE_RELATIONSHIP,
+                    "Relationship already exists for (" + subjectId + ", " + objectId + ", " + type + ")");
+        }
+    }
+
+    // Family-graph edges imply both endpoints are family members. Idempotent (the setter is
+    // a no-op when already flagged, so re-imports stay clean) and additive — an edit never
+    // auto-unflags.
+    private void flagFamilyMembership(RelationType type, UUID subjectId, UUID objectId) {
+        if (FAMILY_RELATION_TYPES.contains(type)) {
+            personService.setFamilyMember(subjectId, true);
+            personService.setFamilyMember(objectId, true);
+        }
+    }
+
     @Transactional
     public void deleteRelationship(UUID personId, UUID relId) {
+        PersonRelationship rel = loadOwnedRelationship(personId, relId);
+        relationshipRepository.delete(rel);
+    }
+
+    // Loads the row and verifies {personId} is one of its endpoints. A mismatch is 404
+    // (not 403): an anti-enumeration choice so a curator cannot probe relationship ids
+    // belonging to people they cannot see. Shared by update + delete for consistency.
+    private PersonRelationship loadOwnedRelationship(UUID personId, UUID relId) {
         PersonRelationship rel = relationshipRepository.findById(relId)
                 .orElseThrow(() -> DomainException.notFound(
                         ErrorCode.RELATIONSHIP_NOT_FOUND, "Relationship not found: " + relId));
-
         UUID storageSubject = rel.getPerson().getId();
         UUID storageObject = rel.getRelatedPerson().getId();
         if (!personId.equals(storageSubject) && !personId.equals(storageObject)) {
-            throw DomainException.forbidden(
+            throw DomainException.notFound(
+                    ErrorCode.RELATIONSHIP_NOT_FOUND,
                     "Relationship " + relId + " does not belong to person " + personId);
         }
-        relationshipRepository.delete(rel);
+        return rel;
     }
 
     @Transactional
@@ -173,10 +239,17 @@ public class RelationshipService {
         return date != null ? date.getYear() : null;
     }
 
-    private static void validateYears(Integer fromYear, Integer toYear) {
-        if (fromYear != null && toYear != null && toYear < fromYear) {
-            throw DomainException.badRequest(
-                    ErrorCode.VALIDATION_ERROR, "toYear must not be before fromYear");
+    // Mirrors PersonService.validateLifeDates (ADR-039/044): coherence first so the
+    // user gets a structured 400 instead of the DB CHECK constraint's 500, then order.
+    // Coherence is shared with the person domain (DatePrecisionValidation); only the order
+    // check (and its INVALID_RELATIONSHIP_DATES code) is relationship specific.
+    private static void validateRelationshipDates(LocalDate fromDate, DatePrecision fromPrecision,
+                                                  LocalDate toDate, DatePrecision toPrecision) {
+        DatePrecisionValidation.requireCoherence(fromDate, fromPrecision, "from");
+        DatePrecisionValidation.requireCoherence(toDate, toPrecision, "to");
+        if (fromDate != null && toDate != null && toDate.isBefore(fromDate)) {
+            throw DomainException.badRequest(ErrorCode.INVALID_RELATIONSHIP_DATES,
+                    "toDate " + toDate + " is before fromDate " + fromDate);
         }
     }
 
@@ -194,8 +267,10 @@ public class RelationshipService {
                 yearOf(rp.getBirthDate()),
                 yearOf(rp.getDeathDate()),
                 r.getRelationType(),
-                r.getFromYear(),
-                r.getToYear(),
+                r.getFromDate(),
+                r.getFromDatePrecision(),
+                r.getToDate(),
+                r.getToDatePrecision(),
                 r.getNotes());
     }
 }

backend/src/main/java/org/raddatz/familienarchiv/person/relationship/dto/CreateRelationshipRequest.java

@@ -1,15 +0,0 @@
-package org.raddatz.familienarchiv.person.relationship.dto;
-
-import jakarta.validation.constraints.NotNull;
-import jakarta.validation.constraints.Size;
-import org.raddatz.familienarchiv.person.relationship.RelationType;
-
-import java.util.UUID;
-
-public record CreateRelationshipRequest(
-        @NotNull UUID relatedPersonId,
-        @NotNull RelationType relationType,
-        Integer fromYear,
-        Integer toYear,
-        @Size(max = 2000) String notes
-) {}

backend/src/main/java/org/raddatz/familienarchiv/person/relationship/dto/RelationshipDTO.java

@@ -1,8 +1,10 @@
 package org.raddatz.familienarchiv.person.relationship.dto;
 
 import io.swagger.v3.oas.annotations.media.Schema;
+import org.raddatz.familienarchiv.document.DatePrecision;
 import org.raddatz.familienarchiv.person.relationship.RelationType;
 
+import java.time.LocalDate;
 import java.util.UUID;
 
 /**
@@ -26,7 +28,9 @@ public record RelationshipDTO(
         Integer relatedPersonBirthYear,
         Integer relatedPersonDeathYear,
         @Schema(requiredMode = Schema.RequiredMode.REQUIRED) RelationType relationType,
-        Integer fromYear,
-        Integer toYear,
+        LocalDate fromDate,
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED) DatePrecision fromDatePrecision,
+        LocalDate toDate,
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED) DatePrecision toDatePrecision,
         String notes
 ) {}

backend/src/main/java/org/raddatz/familienarchiv/person/relationship/dto/RelationshipUpsertRequest.java

@@ -0,0 +1,26 @@
+package org.raddatz.familienarchiv.person.relationship.dto;
+
+import jakarta.validation.constraints.NotNull;
+import jakarta.validation.constraints.Size;
+import org.raddatz.familienarchiv.document.DatePrecision;
+import org.raddatz.familienarchiv.person.relationship.RelationType;
+
+import java.time.LocalDate;
+import java.util.UUID;
+
+/**
+ * Request body for both creating and updating a relationship — the fields are
+ * identical, so one record serves {@code POST} and {@code PUT} (DRY). A null
+ * {@code *DatePrecision} is normalized to {@code UNKNOWN} by the service; the
+ * service then enforces coherence (date ⇔ non-UNKNOWN precision) and order
+ * (fromDate ≤ toDate).
+ */
+public record RelationshipUpsertRequest(
+        @NotNull UUID relatedPersonId,
+        @NotNull RelationType relationType,
+        LocalDate fromDate,
+        DatePrecision fromDatePrecision,
+        LocalDate toDate,
+        DatePrecision toDatePrecision,
+        @Size(max = 2000) String notes
+) {}

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

@@ -28,6 +28,13 @@ import java.util.UUID;
  * They are deliberately NOT {@code @Schema(requiredMode = REQUIRED)} so the generated TypeScript
  * types stay optional.
  *
+ * <p><b>Letter→event link ({@code linkedEventId}):</b> for a {@link Kind#LETTER} entry, the id of
+ * the curated {@link TimelineEvent} whose {@code documents} set contains the letter's document, or
+ * {@code null} when the letter is referenced by no curated event (#850). Computed on read from the
+ * existing {@code timeline_event_documents} join — no new column. {@code null} for non-letter
+ * entries. Deliberately NOT {@code @Schema(requiredMode = REQUIRED)} so the generated TypeScript
+ * type stays optional.
+ *
  * <p>Callers of {@code TimelineEventService.assembleDerivedEvents()} must independently enforce
  * {@code READ_ALL} authorization before invoking that method (see ADR-043).
  */
@@ -47,6 +54,7 @@ public record TimelineEntryDTO(
         DerivedEventType derivedType,
         UUID rootTagId,
         String rootTagName,
-        String rootTagColor
+        String rootTagColor,
+        UUID linkedEventId
 ) {
 }

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

@@ -267,7 +267,7 @@ public class TimelineEventService {
                         p.getBirthDate(), null,
                         p.getDisplayName(), EventType.PERSONAL,
                         null, null, List.of(p.getId()), DerivedEventType.BIRTH,
-                        null, null, null))
+                        null, null, null, null))
                 .toList();
     }
 
@@ -279,7 +279,7 @@ public class TimelineEventService {
                         p.getDeathDate(), null,
                         p.getDisplayName(), EventType.PERSONAL,
                         null, null, List.of(p.getId()), DerivedEventType.DEATH,
-                        null, null, null))
+                        null, null, null, null))
                 .toList();
     }
 
@@ -290,13 +290,11 @@ public class TimelineEventService {
         List<TimelineEntryDTO> result = new ArrayList<>();
         for (PersonRelationship r : spouseEdges) {
             if (seen.add(r.getId())) {
-                // JOIN FETCH in findAllSpouseEdges() guarantees person/relatedPerson are loaded
-                LocalDate eventDate = r.getFromYear() != null
-                        ? LocalDate.of(r.getFromYear(), 1, 1)
-                        : null;
-                DatePrecision precision = r.getFromYear() != null
-                        ? DatePrecision.YEAR
-                        : DatePrecision.UNKNOWN;
+                // JOIN FETCH in findAllSpouseEdges() guarantees person/relatedPerson are loaded.
+                // The marriage date is the relationship's from_date at its stored precision
+                // (ADR-044): a DAY-precision wedding now surfaces the exact day, not just the year.
+                LocalDate eventDate = r.getFromDate();
+                DatePrecision precision = r.getFromDatePrecision();
                 String title = r.getPerson().getDisplayName()
                         + " & " + r.getRelatedPerson().getDisplayName();
                 result.add(new TimelineEntryDTO(
@@ -306,7 +304,7 @@ public class TimelineEventService {
                         null, null,
                         List.of(r.getPerson().getId(), r.getRelatedPerson().getId()),
                         DerivedEventType.MARRIAGE,
-                        null, null, null));
+                        null, null, null, null));
             }
         }
         return result;

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

@@ -80,13 +80,20 @@ public class TimelineService {
         // Resolve generation person IDs once — used across all three layers
         Set<UUID> genPersonIds = resolveGenerationPersonIds(filter.generation());
 
+        // Fetch curated events once; the events that survive the filter below feed both the
+        // event entries and the batched letter→event link pass (resolveLetterEventLinks), so the
+        // membership pass costs no extra query and touches only on-screen events. REQ-009.
+        List<TimelineEvent> allEvents = eventRepository.findAll();
+
         // ── curated events ───────────────────────────────────────────────────
         List<TimelineEntryDTO> entries = new ArrayList<>();
-        for (TimelineEvent ev : eventRepository.findAll()) {
+        List<TimelineEvent> filteredEvents = new ArrayList<>();
+        for (TimelineEvent ev : allEvents) {
             if (!passesTypeFilter(ev.getType(), filter.type())) continue;
             if (!passesPersonFilter(ev.getPersons(), filter.personId())) continue;
             if (!passesGenerationFilter(ev.getPersons(), genPersonIds)) continue;
             if (!passesYearFilter(ev.getEventDate(), ev.getPrecision(), filter)) continue;
+            filteredEvents.add(ev);
             entries.add(mapEvent(ev));
         }
 
@@ -107,8 +114,9 @@ public class TimelineService {
             letters.add(doc);
         }
         Map<UUID, RootTag> rootByDocId = resolveLetterRootTags(letters);
+        Map<UUID, UUID> eventByDocId = resolveLetterEventLinks(letters, filteredEvents);
         for (Document doc : letters) {
-            entries.add(mapDocument(doc, rootByDocId));
+            entries.add(mapDocument(doc, rootByDocId, eventByDocId));
         }
 
         return bucket(entries);
@@ -229,11 +237,13 @@ public class TimelineService {
                 null,
                 null,
                 null,
+                null,
                 null
         );
     }
 
-    private TimelineEntryDTO mapDocument(Document doc, Map<UUID, RootTag> rootByDocId) {
+    private TimelineEntryDTO mapDocument(Document doc, Map<UUID, RootTag> rootByDocId,
+                                         Map<UUID, UUID> eventByDocId) {
         RootTag root = rootByDocId.get(doc.getId());
         return new TimelineEntryDTO(
                 Kind.LETTER,
@@ -251,10 +261,50 @@ public class TimelineService {
                 null,
                 root == null ? null : root.id(),
                 root == null ? null : root.name(),
-                root == null ? null : root.color()
+                root == null ? null : root.color(),
+                eventByDocId.get(doc.getId())
         );
     }
 
+    /**
+     * Resolves each letter's linked curated event in one batched pass, keyed by document id: the
+     * 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 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 only over the events that survived the timeline filter, so the lazy
+     * {@code documents} collection is hydrated for on-screen events alone (finding #10); a letter
+     * whose only linking event was filtered out links to nothing, matching the frontend's
+     * filter-then-cluster (#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 : ordered) {
+            Set<Document> linkedDocs = ev.getDocuments();
+            if (linkedDocs == null) continue;
+            for (Document linked : linkedDocs) {
+                if (letterDocIds.contains(linked.getId())) {
+                    eventByDocId.putIfAbsent(linked.getId(), ev.getId());
+                }
+            }
+        }
+        return eventByDocId;
+    }
+
     /**
      * Resolves each letter's primary root tag in one batched pass, keyed by document id — no
      * per-letter N+1: each letter contributes only its alphabetically-first assigned tag (#835),

backend/src/main/resources/db/migration/V78__relationship_years_to_localdate.sql

@@ -0,0 +1,43 @@
+-- V78: person_relationships.from_year/to_year (integer) → from_date/to_date (date)
+-- plus NOT NULL precision columns, mirroring persons.{birth,death}_date (V76 / ADR-039).
+-- Existing years are backfilled as YYYY-01-01 at YEAR precision (ADR-044).
+-- One-way migration: rollback is a targeted pg_restore -t person_relationships from
+-- the pre-deploy backup (see docs/DEPLOYMENT.md). The column drop is NOT
+-- rolling-deploy-safe — stop the old JAR before running this migration.
+
+-- Pre-check (data quality gate — not a race guard): abort on corrupt year data
+-- before any DDL runs. Single-writer family archive, so no race window matters.
+DO $$ BEGIN
+  IF EXISTS (SELECT 1 FROM person_relationships WHERE from_year IS NOT NULL AND to_year IS NOT NULL AND from_year > to_year)
+    THEN RAISE EXCEPTION 'V78 aborted: % relationships have from_year > to_year — fix data before migrating',
+      (SELECT COUNT(*) FROM person_relationships WHERE from_year IS NOT NULL AND to_year IS NOT NULL AND from_year > to_year);
+  END IF;
+  IF EXISTS (SELECT 1 FROM person_relationships WHERE from_year = 0 OR to_year = 0)
+    THEN RAISE EXCEPTION 'V78 aborted: person_relationships table contains from_year=0 or to_year=0 rows — clean data before migrating';
+  END IF;
+END $$;
+
+ALTER TABLE person_relationships ADD COLUMN from_date date;
+ALTER TABLE person_relationships ADD COLUMN from_date_precision varchar(16) NOT NULL DEFAULT 'UNKNOWN';
+ALTER TABLE person_relationships ADD COLUMN to_date date;
+ALTER TABLE person_relationships ADD COLUMN to_date_precision varchar(16) NOT NULL DEFAULT 'UNKNOWN';
+
+UPDATE person_relationships SET from_date = make_date(from_year, 1, 1), from_date_precision = 'YEAR'
+    WHERE from_year IS NOT NULL;
+UPDATE person_relationships SET to_date = make_date(to_year, 1, 1), to_date_precision = 'YEAR'
+    WHERE to_year IS NOT NULL;
+
+-- Named constraints: readable Postgres error messages when violated.
+ALTER TABLE person_relationships ADD CONSTRAINT chk_relationship_from_coherence
+    CHECK ((from_date IS NULL) = (from_date_precision = 'UNKNOWN'));
+ALTER TABLE person_relationships ADD CONSTRAINT chk_relationship_to_coherence
+    CHECK ((to_date IS NULL) = (to_date_precision = 'UNKNOWN'));
+ALTER TABLE person_relationships ADD CONSTRAINT chk_relationship_date_order
+    CHECK (from_date IS NULL OR to_date IS NULL OR from_date <= to_date);
+ALTER TABLE person_relationships ADD CONSTRAINT chk_relationship_from_precision_values
+    CHECK (from_date_precision IN ('DAY', 'MONTH', 'SEASON', 'YEAR', 'RANGE', 'APPROX', 'UNKNOWN'));
+ALTER TABLE person_relationships ADD CONSTRAINT chk_relationship_to_precision_values
+    CHECK (to_date_precision IN ('DAY', 'MONTH', 'SEASON', 'YEAR', 'RANGE', 'APPROX', 'UNKNOWN'));
+
+ALTER TABLE person_relationships DROP COLUMN from_year;
+ALTER TABLE person_relationships DROP COLUMN to_year;

backend/src/test/java/org/raddatz/familienarchiv/importing/CanonicalImportOrchestratorTest.java

@@ -6,6 +6,7 @@ import org.junit.jupiter.api.io.TempDir;
 import org.mockito.InOrder;
 import org.mockito.Mock;
 import org.mockito.junit.jupiter.MockitoExtension;
+import org.raddatz.familienarchiv.document.DatePrecision;
 import org.raddatz.familienarchiv.exception.DomainException;
 import org.raddatz.familienarchiv.person.relationship.RelationType;
 import org.raddatz.familienarchiv.person.relationship.RelationshipService;
@@ -169,7 +170,7 @@ class CanonicalImportOrchestratorTest {
         RelationshipDTO edge = new RelationshipDTO(
                 UUID.randomUUID(), parentId, childId,
                 "Parent", null, null, "Child", null, null,
-                RelationType.PARENT_OF, null, null, null);
+                RelationType.PARENT_OF, null, DatePrecision.UNKNOWN, null, DatePrecision.UNKNOWN, null);
         when(relationshipService.getFamilyNetwork())
                 .thenReturn(new NetworkDTO(List.of(parent, child), List.of(edge)));
         when(documentImporter.load(any())).thenReturn(new DocumentImporter.LoadResult(0, List.of()));

backend/src/test/java/org/raddatz/familienarchiv/importing/PersonTreeImporterTest.java

@@ -12,7 +12,7 @@ import org.raddatz.familienarchiv.person.PersonService;
 import org.raddatz.familienarchiv.person.PersonUpsertCommand;
 import org.raddatz.familienarchiv.person.relationship.RelationType;
 import org.raddatz.familienarchiv.person.relationship.RelationshipService;
-import org.raddatz.familienarchiv.person.relationship.dto.CreateRelationshipRequest;
+import org.raddatz.familienarchiv.person.relationship.dto.RelationshipUpsertRequest;
 
 import java.nio.file.Files;
 import java.nio.file.Path;
@@ -76,7 +76,7 @@ class PersonTreeImporterTest {
         new PersonTreeImporter(personService, relationshipService)
                 .load(json.toFile());
 
-        ArgumentCaptor<CreateRelationshipRequest> captor = ArgumentCaptor.forClass(CreateRelationshipRequest.class);
+        ArgumentCaptor<RelationshipUpsertRequest> captor = ArgumentCaptor.forClass(RelationshipUpsertRequest.class);
         verify(relationshipService).addRelationship(eq(idA), captor.capture());
         assertThat(captor.getValue().relatedPersonId()).isEqualTo(idB);
         assertThat(captor.getValue().relationType()).isEqualTo(RelationType.SPOUSE_OF);

backend/src/test/java/org/raddatz/familienarchiv/person/relationship/RelationshipControllerTest.java

@@ -1,6 +1,7 @@
 package org.raddatz.familienarchiv.person.relationship;
 
 import org.junit.jupiter.api.Test;
+import org.raddatz.familienarchiv.document.DatePrecision;
 import org.raddatz.familienarchiv.security.SecurityConfig;
 import org.raddatz.familienarchiv.exception.ErrorCode;
 import org.raddatz.familienarchiv.person.relationship.dto.InferredRelationshipWithPersonDTO;
@@ -25,6 +26,8 @@ import java.util.UUID;
 
 import static org.mockito.ArgumentMatchers.any;
 import static org.mockito.Mockito.doNothing;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.verify;
 import static org.mockito.Mockito.when;
 import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.*;
 import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.*;
@@ -98,7 +101,7 @@ class RelationshipControllerTest {
                 UUID.randomUUID(), PERSON_ID, OTHER_ID,
                 "Alice Müller", 1900, 1980,
                 "Bob Müller", 1930, null,
-                RelationType.PARENT_OF, null, null, null);
+                RelationType.PARENT_OF, null, DatePrecision.UNKNOWN, null, DatePrecision.UNKNOWN, null);
         when(relationshipService.getFamilyNetwork())
                 .thenReturn(new NetworkDTO(List.of(node), List.of(edge)));
 
@@ -139,7 +142,7 @@ class RelationshipControllerTest {
                 UUID.randomUUID(), PERSON_ID, OTHER_ID,
                 "Alice Müller", null, null,
                 "Bob Müller", null, null,
-                RelationType.PARENT_OF, null, null, null);
+                RelationType.PARENT_OF, null, DatePrecision.UNKNOWN, null, DatePrecision.UNKNOWN, null);
         when(relationshipService.addRelationship(any(), any())).thenReturn(created);
 
         mockMvc.perform(post("/api/persons/{id}/relationships", PERSON_ID).with(csrf())
@@ -158,4 +161,51 @@ class RelationshipControllerTest {
         mockMvc.perform(delete("/api/persons/{id}/relationships/{relId}", PERSON_ID, relId).with(csrf()))
                 .andExpect(status().isNoContent());
     }
+
+    // ─── PUT /api/persons/{id}/relationships/{relId} ──────────────────────────
+
+    @Test
+    @WithMockUser(username = "testuser", authorities = {"WRITE_ALL"})
+    void updateRelationship_returns200_with_RelationshipDTO_for_WRITE_ALL_user() throws Exception {
+        UUID relId = UUID.randomUUID();
+        RelationshipDTO updated = new RelationshipDTO(
+                relId, PERSON_ID, OTHER_ID,
+                "Alice Müller", null, null,
+                "Bob Müller", null, null,
+                RelationType.SPOUSE_OF, null, DatePrecision.UNKNOWN, null, DatePrecision.UNKNOWN, null);
+        when(relationshipService.updateRelationship(any(), any(), any())).thenReturn(updated);
+
+        mockMvc.perform(put("/api/persons/{id}/relationships/{relId}", PERSON_ID, relId).with(csrf())
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("{\"relatedPersonId\":\"" + OTHER_ID + "\",\"relationType\":\"SPOUSE_OF\"}"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.relationType").value("SPOUSE_OF"));
+    }
+
+    @Test
+    void updateRelationship_returns401_whenUnauthenticated_and_does_not_touch_service() throws Exception {
+        mockMvc.perform(put("/api/persons/{id}/relationships/{relId}", PERSON_ID, UUID.randomUUID()).with(csrf())
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("{\"relatedPersonId\":\"" + OTHER_ID + "\",\"relationType\":\"SPOUSE_OF\"}"))
+                .andExpect(status().isUnauthorized());
+        verify(relationshipService, never()).updateRelationship(any(), any(), any());
+    }
+
+    @Test
+    @WithMockUser(username = "testuser", authorities = {"READ_ALL"})
+    void updateRelationship_returns403_for_READ_ALL_only_user() throws Exception {
+        mockMvc.perform(put("/api/persons/{id}/relationships/{relId}", PERSON_ID, UUID.randomUUID()).with(csrf())
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("{\"relatedPersonId\":\"" + OTHER_ID + "\",\"relationType\":\"SPOUSE_OF\"}"))
+                .andExpect(status().isForbidden());
+    }
+
+    @Test
+    @WithMockUser(username = "testuser", authorities = {"WRITE_ALL"})
+    void updateRelationship_returns400_when_relationType_is_unknown_value() throws Exception {
+        mockMvc.perform(put("/api/persons/{id}/relationships/{relId}", PERSON_ID, UUID.randomUUID()).with(csrf())
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("{\"relatedPersonId\":\"" + OTHER_ID + "\",\"relationType\":\"NOT_A_REAL_TYPE\"}"))
+                .andExpect(status().isBadRequest());
+    }
 }

backend/src/test/java/org/raddatz/familienarchiv/person/relationship/RelationshipMigrationTest.java

@@ -0,0 +1,306 @@
+package org.raddatz.familienarchiv.person.relationship;
+
+import org.flywaydb.core.Flyway;
+import org.junit.jupiter.api.AfterAll;
+import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.testcontainers.containers.PostgreSQLContainer;
+
+import java.sql.Connection;
+import java.sql.DriverManager;
+import java.sql.PreparedStatement;
+import java.sql.ResultSet;
+import java.sql.SQLException;
+import java.sql.Statement;
+import java.util.Map;
+import java.util.UUID;
+import java.util.concurrent.atomic.AtomicInteger;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+/**
+ * Verifies V78: person_relationships.from_year/to_year (integer) become
+ * from_date/to_date (date) + *_date_precision columns, with backfill to
+ * YYYY-01-01 at YEAR precision, named CHECK constraints, and a data-quality
+ * pre-check that aborts the migration on corrupt year data. Mirrors
+ * {@code PersonBirthDeathMigrationTest} (V76 / ADR-039).
+ *
+ * <p>Runs Flyway programmatically (no Spring context): each test gets its own
+ * database so the staged migrate-to-V77 → seed → migrate-to-latest flow and
+ * the abort cases cannot interfere with each other. Uses a real Postgres
+ * container — H2 does not honour CHECK constraints.
+ */
+class RelationshipMigrationTest {
+
+    private static final PostgreSQLContainer<?> POSTGRES = new PostgreSQLContainer<>("postgres:16-alpine");
+    private static final AtomicInteger DB_COUNTER = new AtomicInteger();
+
+    private String dbUrl;
+
+    @BeforeAll
+    static void startContainer() {
+        POSTGRES.start();
+    }
+
+    @AfterAll
+    static void stopContainer() {
+        POSTGRES.stop();
+    }
+
+    @BeforeEach
+    void createFreshDatabase() throws SQLException {
+        String dbName = "mig_v78_" + DB_COUNTER.incrementAndGet();
+        try (Connection conn = DriverManager.getConnection(
+                baseUrl("postgres"), POSTGRES.getUsername(), POSTGRES.getPassword());
+             Statement stmt = conn.createStatement()) {
+            stmt.execute("CREATE DATABASE " + dbName);
+        }
+        dbUrl = baseUrl(dbName);
+    }
+
+    @Test
+    void precheck_abortsWhenFromYearAfterToYear() throws SQLException {
+        migrateTo("77");
+        UUID a = seedPerson("Alpha");
+        UUID b = seedPerson("Beta");
+        seedRelationship(a, b, "SPOUSE_OF", 1958, 1923);
+
+        assertThatThrownBy(this::migrateToLatest)
+                .hasMessageContaining("V78 aborted")
+                .hasMessageContaining("from_year > to_year");
+    }
+
+    @Test
+    void precheck_abortsWhenYearZeroPresent() throws SQLException {
+        migrateTo("77");
+        UUID a = seedPerson("Alpha");
+        UUID b = seedPerson("Beta");
+        seedRelationship(a, b, "FRIEND", 0, null);
+
+        assertThatThrownBy(this::migrateToLatest)
+                .hasMessageContaining("V78 aborted")
+                .hasMessageContaining("from_year=0 or to_year=0");
+    }
+
+    @Test
+    void backfill_fromYearAndToYear_becomeYearPrecisionDates() throws SQLException {
+        migrateTo("77");
+        UUID a = seedPerson("Alpha");
+        UUID b = seedPerson("Beta");
+        seedRelationship(a, b, "SPOUSE_OF", 1923, 1958);
+
+        migrateToLatest();
+
+        RelationDates row = relationDates(a, b, "SPOUSE_OF");
+        assertThat(row.fromDate()).hasToString("1923-01-01");
+        assertThat(row.fromPrecision()).isEqualTo("YEAR");
+        assertThat(row.toDate()).hasToString("1958-01-01");
+        assertThat(row.toPrecision()).isEqualTo("YEAR");
+    }
+
+    @Test
+    void backfill_bothNull_leavesDatesNullAndPrecisionsUnknown() throws SQLException {
+        migrateTo("77");
+        UUID a = seedPerson("Alpha");
+        UUID b = seedPerson("Beta");
+        seedRelationship(a, b, "FRIEND", null, null);
+
+        migrateToLatest();
+
+        RelationDates row = relationDates(a, b, "FRIEND");
+        assertThat(row.fromDate()).isNull();
+        assertThat(row.fromPrecision()).isEqualTo("UNKNOWN");
+        assertThat(row.toDate()).isNull();
+        assertThat(row.toPrecision()).isEqualTo("UNKNOWN");
+    }
+
+    @Test
+    void backfill_preservesRowCount() throws SQLException {
+        migrateTo("77");
+        UUID a = seedPerson("Alpha");
+        UUID b = seedPerson("Beta");
+        UUID c = seedPerson("Gamma");
+        seedRelationship(a, b, "SPOUSE_OF", 1923, 1958);
+        seedRelationship(a, c, "FRIEND", null, null);
+
+        migrateToLatest();
+
+        assertThat(countWhere("1 = 1")).isEqualTo(2);
+    }
+
+    @Test
+    void orderCheckConstraint_rejectsToDateBeforeFromDate() throws SQLException {
+        migrateTo("77");
+        UUID a = seedPerson("Alpha");
+        UUID b = seedPerson("Beta");
+        migrateToLatest();
+
+        assertThatThrownBy(() -> insertDatedRelationship(
+                a, b, "FRIEND", "1958-01-01", "YEAR", "1923-01-01", "YEAR"))
+                .hasMessageContaining("chk_relationship_date_order");
+    }
+
+    @Test
+    void coherenceCheckConstraint_rejectsDatePresentWithUnknownPrecision() throws SQLException {
+        migrateTo("77");
+        UUID a = seedPerson("Alpha");
+        UUID b = seedPerson("Beta");
+        migrateToLatest();
+
+        assertThatThrownBy(() -> insertDatedRelationship(
+                a, b, "FRIEND", "1923-01-01", "UNKNOWN", null, "UNKNOWN"))
+                .hasMessageContaining("chk_relationship_from_coherence");
+    }
+
+    @Test
+    void yearColumnsDropped_andNamedCheckConstraintsExist() throws SQLException {
+        migrateTo("77");
+        UUID a = seedPerson("Alpha");
+        UUID b = seedPerson("Beta");
+        seedRelationship(a, b, "SPOUSE_OF", 1923, 1958);
+
+        migrateToLatest();
+
+        assertThat(columnExists("from_year")).isFalse();
+        assertThat(columnExists("to_year")).isFalse();
+        assertThat(columnExists("from_date")).isTrue();
+        assertThat(columnExists("to_date")).isTrue();
+        for (String constraint : new String[]{
+                "chk_relationship_from_coherence",
+                "chk_relationship_to_coherence",
+                "chk_relationship_date_order",
+                "chk_relationship_from_precision_values",
+                "chk_relationship_to_precision_values"}) {
+            assertThat(constraintExists(constraint)).as(constraint).isTrue();
+        }
+    }
+
+    // --- helpers ---
+
+    private static String baseUrl(String dbName) {
+        return "jdbc:postgresql://" + POSTGRES.getHost() + ":" + POSTGRES.getMappedPort(5432) + "/" + dbName;
+    }
+
+    private void migrateTo(String targetVersion) {
+        flywayBuilder().target(targetVersion).load().migrate();
+    }
+
+    private void migrateToLatest() {
+        flywayBuilder().load().migrate();
+    }
+
+    private org.flywaydb.core.api.configuration.FluentConfiguration flywayBuilder() {
+        return Flyway.configure()
+                .dataSource(dbUrl, POSTGRES.getUsername(), POSTGRES.getPassword())
+                .locations("classpath:db/migration")
+                .placeholders(Map.of("grafanaDbPassword", "test-only"));
+    }
+
+    private UUID seedPerson(String lastName) throws SQLException {
+        UUID id = UUID.randomUUID();
+        try (Connection conn = connect();
+             PreparedStatement stmt = conn.prepareStatement(
+                     "INSERT INTO persons (id, last_name, person_type, family_member, provisional) "
+                             + "VALUES (?, ?, 'PERSON', false, false)")) {
+            stmt.setObject(1, id);
+            stmt.setString(2, lastName);
+            stmt.executeUpdate();
+        }
+        return id;
+    }
+
+    private void seedRelationship(UUID personId, UUID relatedId, String type, Integer fromYear, Integer toYear)
+            throws SQLException {
+        try (Connection conn = connect();
+             PreparedStatement stmt = conn.prepareStatement(
+                     "INSERT INTO person_relationships (id, person_id, related_person_id, relation_type, from_year, to_year) "
+                             + "VALUES (gen_random_uuid(), ?, ?, ?, ?, ?)")) {
+            stmt.setObject(1, personId);
+            stmt.setObject(2, relatedId);
+            stmt.setString(3, type);
+            stmt.setObject(4, fromYear);
+            stmt.setObject(5, toYear);
+            stmt.executeUpdate();
+        }
+    }
+
+    private void insertDatedRelationship(UUID personId, UUID relatedId, String type,
+                                         String fromDate, String fromPrecision,
+                                         String toDate, String toPrecision) throws SQLException {
+        try (Connection conn = connect();
+             PreparedStatement stmt = conn.prepareStatement(
+                     "INSERT INTO person_relationships "
+                             + "(id, person_id, related_person_id, relation_type, from_date, from_date_precision, to_date, to_date_precision) "
+                             + "VALUES (gen_random_uuid(), ?, ?, ?, CAST(? AS date), ?, CAST(? AS date), ?)")) {
+            stmt.setObject(1, personId);
+            stmt.setObject(2, relatedId);
+            stmt.setString(3, type);
+            stmt.setObject(4, fromDate);
+            stmt.setString(5, fromPrecision);
+            stmt.setObject(6, toDate);
+            stmt.setString(7, toPrecision);
+            stmt.executeUpdate();
+        }
+    }
+
+    private record RelationDates(Object fromDate, String fromPrecision, Object toDate, String toPrecision) {}
+
+    private RelationDates relationDates(UUID personId, UUID relatedId, String type) throws SQLException {
+        try (Connection conn = connect();
+             PreparedStatement stmt = conn.prepareStatement(
+                     "SELECT from_date, from_date_precision, to_date, to_date_precision "
+                             + "FROM person_relationships WHERE person_id = ? AND related_person_id = ? AND relation_type = ?")) {
+            stmt.setObject(1, personId);
+            stmt.setObject(2, relatedId);
+            stmt.setString(3, type);
+            try (ResultSet rs = stmt.executeQuery()) {
+                assertThat(rs.next()).as("relationship exists").isTrue();
+                return new RelationDates(
+                        rs.getObject("from_date"),
+                        rs.getString("from_date_precision"),
+                        rs.getObject("to_date"),
+                        rs.getString("to_date_precision"));
+            }
+        }
+    }
+
+    private long countWhere(String condition) throws SQLException {
+        try (Connection conn = connect();
+             Statement stmt = conn.createStatement();
+             ResultSet rs = stmt.executeQuery("SELECT COUNT(*) FROM person_relationships WHERE " + condition)) {
+            rs.next();
+            return rs.getLong(1);
+        }
+    }
+
+    private boolean columnExists(String columnName) throws SQLException {
+        try (Connection conn = connect();
+             PreparedStatement stmt = conn.prepareStatement(
+                     "SELECT COUNT(*) FROM information_schema.columns "
+                             + "WHERE table_schema = 'public' AND table_name = 'person_relationships' AND column_name = ?")) {
+            stmt.setString(1, columnName);
+            try (ResultSet rs = stmt.executeQuery()) {
+                rs.next();
+                return rs.getInt(1) > 0;
+            }
+        }
+    }
+
+    private boolean constraintExists(String constraintName) throws SQLException {
+        try (Connection conn = connect();
+             PreparedStatement stmt = conn.prepareStatement(
+                     "SELECT COUNT(*) FROM pg_constraint WHERE conname = ?")) {
+            stmt.setString(1, constraintName);
+            try (ResultSet rs = stmt.executeQuery()) {
+                rs.next();
+                return rs.getInt(1) > 0;
+            }
+        }
+    }
+
+    private Connection connect() throws SQLException {
+        return DriverManager.getConnection(dbUrl, POSTGRES.getUsername(), POSTGRES.getPassword());
+    }
+}

backend/src/test/java/org/raddatz/familienarchiv/person/relationship/RelationshipServiceIntegrationTest.java

@@ -4,10 +4,11 @@ import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
 import org.raddatz.familienarchiv.PostgresContainerConfig;
 import org.raddatz.familienarchiv.config.FlywayConfig;
+import org.raddatz.familienarchiv.document.DatePrecision;
 import org.raddatz.familienarchiv.exception.DomainException;
 import org.raddatz.familienarchiv.exception.ErrorCode;
 import org.raddatz.familienarchiv.person.Person;
-import org.raddatz.familienarchiv.person.relationship.dto.CreateRelationshipRequest;
+import org.raddatz.familienarchiv.person.relationship.dto.RelationshipUpsertRequest;
 import org.raddatz.familienarchiv.person.relationship.dto.NetworkDTO;
 import org.raddatz.familienarchiv.person.relationship.dto.RelationshipDTO;
 import org.raddatz.familienarchiv.person.PersonNameAliasRepository;
@@ -20,6 +21,7 @@ import org.springframework.context.annotation.Import;
 
 import jakarta.persistence.EntityManager;
 
+import java.time.LocalDate;
 import java.util.List;
 import java.util.UUID;
 
@@ -65,13 +67,17 @@ class RelationshipServiceIntegrationTest {
 
     @Test
     void addRelationship_stores_and_is_readable() {
-        var dto = new CreateRelationshipRequest(bob.getId(), RelationType.PARENT_OF, 1900, null, null);
+        var dto = new RelationshipUpsertRequest(bob.getId(), RelationType.PARENT_OF,
+                LocalDate.of(1900, 1, 1), DatePrecision.YEAR, null, null, null);
 
         RelationshipDTO created = relationshipService.addRelationship(alice.getId(), dto);
 
         assertThat(created.id()).isNotNull();
         assertThat(created.personId()).isEqualTo(alice.getId());
         assertThat(created.relatedPersonId()).isEqualTo(bob.getId());
+        assertThat(created.fromDate()).isEqualTo(LocalDate.of(1900, 1, 1));
+        assertThat(created.fromDatePrecision()).isEqualTo(DatePrecision.YEAR);
+        assertThat(created.toDatePrecision()).isEqualTo(DatePrecision.UNKNOWN);
 
         List<RelationshipDTO> rels = relationshipService.getRelationships(alice.getId());
         assertThat(rels).hasSize(1);
@@ -80,7 +86,7 @@ class RelationshipServiceIntegrationTest {
 
     @Test
     void addRelationship_throws_409_when_duplicate() {
-        var dto = new CreateRelationshipRequest(bob.getId(), RelationType.PARENT_OF, null, null, null);
+        var dto = new RelationshipUpsertRequest(bob.getId(), RelationType.PARENT_OF, null, null, null, null, null);
         relationshipService.addRelationship(alice.getId(), dto);
 
         assertThatThrownBy(() -> relationshipService.addRelationship(alice.getId(), dto))
@@ -93,9 +99,9 @@ class RelationshipServiceIntegrationTest {
     void addRelationship_throws_409_when_circular_parent() {
         // alice PARENT_OF bob; now try bob PARENT_OF alice → must be rejected.
         relationshipService.addRelationship(alice.getId(),
-                new CreateRelationshipRequest(bob.getId(), RelationType.PARENT_OF, null, null, null));
+                new RelationshipUpsertRequest(bob.getId(), RelationType.PARENT_OF, null, null, null, null, null));
 
-        var reverse = new CreateRelationshipRequest(alice.getId(), RelationType.PARENT_OF, null, null, null);
+        var reverse = new RelationshipUpsertRequest(alice.getId(), RelationType.PARENT_OF, null, null, null, null, null);
         assertThatThrownBy(() -> relationshipService.addRelationship(bob.getId(), reverse))
                 .isInstanceOf(DomainException.class)
                 .extracting("code")
@@ -103,28 +109,58 @@ class RelationshipServiceIntegrationTest {
     }
 
     @Test
-    void deleteRelationship_throws_403_when_rel_belongs_to_different_person() {
+    void deleteRelationship_throws_404_when_rel_belongs_to_different_person() {
         RelationshipDTO created = relationshipService.addRelationship(alice.getId(),
-                new CreateRelationshipRequest(bob.getId(), RelationType.PARENT_OF, null, null, null));
+                new RelationshipUpsertRequest(bob.getId(), RelationType.PARENT_OF, null, null, null, null, null));
 
-        // Charlie is unrelated to this row.
+        // Charlie is unrelated to this row. Ownership mismatch is 404, not 403, so a
+        // curator cannot enumerate relationship ids belonging to people they can't see
+        // (anti-enumeration; aligned with the PUT endpoint — ADR-044).
         assertThatThrownBy(() -> relationshipService.deleteRelationship(charlie.getId(), created.id()))
                 .isInstanceOf(DomainException.class)
                 .extracting("code")
-                .isEqualTo(ErrorCode.FORBIDDEN);
+                .isEqualTo(ErrorCode.RELATIONSHIP_NOT_FOUND);
 
         // The row is still there.
         assertThat(relationshipRepository.findById(created.id())).isPresent();
     }
 
+    @Test
+    void updateRelationship_persists_new_type_dates_and_notes() {
+        RelationshipDTO created = relationshipService.addRelationship(alice.getId(),
+                new RelationshipUpsertRequest(bob.getId(), RelationType.FRIEND, null, null, null, null, null));
+
+        RelationshipDTO updated = relationshipService.updateRelationship(alice.getId(), created.id(),
+                new RelationshipUpsertRequest(bob.getId(), RelationType.SPOUSE_OF,
+                        LocalDate.of(1923, 5, 12), DatePrecision.DAY, null, null, "wedding day"));
+
+        assertThat(updated.id()).isEqualTo(created.id());
+        assertThat(updated.relationType()).isEqualTo(RelationType.SPOUSE_OF);
+        assertThat(updated.fromDate()).isEqualTo(LocalDate.of(1923, 5, 12));
+        assertThat(updated.fromDatePrecision()).isEqualTo(DatePrecision.DAY);
+        assertThat(updated.notes()).isEqualTo("wedding day");
+    }
+
+    @Test
+    void updateRelationship_throws_404_when_rel_belongs_to_different_person() {
+        RelationshipDTO created = relationshipService.addRelationship(alice.getId(),
+                new RelationshipUpsertRequest(bob.getId(), RelationType.PARENT_OF, null, null, null, null, null));
+
+        assertThatThrownBy(() -> relationshipService.updateRelationship(charlie.getId(), created.id(),
+                new RelationshipUpsertRequest(bob.getId(), RelationType.FRIEND, null, null, null, null, null)))
+                .isInstanceOf(DomainException.class)
+                .extracting("code")
+                .isEqualTo(ErrorCode.RELATIONSHIP_NOT_FOUND);
+    }
+
     @Test
     void addRelationship_throws_409_when_reverse_SPOUSE_OF_pair_already_exists() {
         // V55 enforces symmetric uniqueness for SPOUSE_OF. Inserting (alice, bob, SPOUSE_OF)
         // and then (bob, alice, SPOUSE_OF) must be rejected, just like reverse SIBLING_OF.
         relationshipService.addRelationship(alice.getId(),
-                new CreateRelationshipRequest(bob.getId(), RelationType.SPOUSE_OF, null, null, null));
+                new RelationshipUpsertRequest(bob.getId(), RelationType.SPOUSE_OF, null, null, null, null, null));
 
-        var reverse = new CreateRelationshipRequest(alice.getId(), RelationType.SPOUSE_OF, null, null, null);
+        var reverse = new RelationshipUpsertRequest(alice.getId(), RelationType.SPOUSE_OF, null, null, null, null, null);
         assertThatThrownBy(() -> relationshipService.addRelationship(bob.getId(), reverse))
                 .isInstanceOf(DomainException.class)
                 .extracting("code")
@@ -135,7 +171,7 @@ class RelationshipServiceIntegrationTest {
     void deleteRelationship_succeeds_for_symmetric_type_from_either_side() {
         // alice SPOUSE_OF bob. Bob deletes from his side.
         RelationshipDTO created = relationshipService.addRelationship(alice.getId(),
-                new CreateRelationshipRequest(bob.getId(), RelationType.SPOUSE_OF, null, null, null));
+                new RelationshipUpsertRequest(bob.getId(), RelationType.SPOUSE_OF, null, null, null, null, null));
 
         relationshipService.deleteRelationship(bob.getId(), created.id());
 
@@ -148,7 +184,7 @@ class RelationshipServiceIntegrationTest {
         // edges (PARENT_OF/SPOUSE_OF/SIBLING_OF). Reset charlie so the explicit
         // setFamilyMember(true) call below is the thing under test, not the auto-flip.
         relationshipService.addRelationship(alice.getId(),
-                new CreateRelationshipRequest(charlie.getId(), RelationType.PARENT_OF, null, null, null));
+                new RelationshipUpsertRequest(charlie.getId(), RelationType.PARENT_OF, null, null, null, null, null));
         relationshipService.setFamilyMember(charlie.getId(), false);
 
         NetworkDTO before = relationshipService.getFamilyNetwork();
@@ -165,7 +201,7 @@ class RelationshipServiceIntegrationTest {
     @Test
     void delete_person_cascades_to_relationships() {
         RelationshipDTO created = relationshipService.addRelationship(alice.getId(),
-                new CreateRelationshipRequest(bob.getId(), RelationType.PARENT_OF, null, null, null));
+                new RelationshipUpsertRequest(bob.getId(), RelationType.PARENT_OF, null, null, null, null, null));
         UUID relId = created.id();
         assertThat(relationshipRepository.findById(relId)).isPresent();
 

backend/src/test/java/org/raddatz/familienarchiv/person/relationship/RelationshipServiceTest.java

@@ -6,16 +6,18 @@ import org.junit.jupiter.api.extension.ExtendWith;
 import org.mockito.InjectMocks;
 import org.mockito.Mock;
 import org.mockito.junit.jupiter.MockitoExtension;
+import org.raddatz.familienarchiv.document.DatePrecision;
 import org.raddatz.familienarchiv.exception.DomainException;
 import org.raddatz.familienarchiv.exception.ErrorCode;
 import org.raddatz.familienarchiv.person.Person;
-import org.raddatz.familienarchiv.person.relationship.dto.CreateRelationshipRequest;
+import org.raddatz.familienarchiv.person.relationship.dto.RelationshipUpsertRequest;
 import org.raddatz.familienarchiv.person.PersonService;
 import org.springframework.dao.DataIntegrityViolationException;
 
 import org.raddatz.familienarchiv.person.relationship.dto.NetworkDTO;
 
 import java.time.Instant;
+import java.time.LocalDate;
 import java.util.List;
 import java.util.Optional;
 import java.util.UUID;
@@ -59,9 +61,9 @@ class RelationshipServiceTest {
         charlie = person("Charlie");
     }
 
-    // --- Nora blocker 1 ---
+    // --- Nora blocker 1 (anti-enumeration: ownership mismatch is 404, aligned with PUT) ---
     @Test
-    void deleteRelationship_throws_FORBIDDEN_when_rel_belongs_to_different_person() {
+    void deleteRelationship_throws_NOT_FOUND_when_rel_belongs_to_different_person() {
         UUID relId = UUID.randomUUID();
         PersonRelationship rel = parentOf(alice, bob, relId);
         when(relationshipRepository.findById(relId)).thenReturn(Optional.of(rel));
@@ -69,7 +71,7 @@ class RelationshipServiceTest {
         assertThatThrownBy(() -> service.deleteRelationship(charlie.getId(), relId))
                 .isInstanceOf(DomainException.class)
                 .extracting("code")
-                .isEqualTo(ErrorCode.FORBIDDEN);
+                .isEqualTo(ErrorCode.RELATIONSHIP_NOT_FOUND);
         verify(relationshipRepository, never()).delete(any());
     }
 
@@ -82,7 +84,7 @@ class RelationshipServiceTest {
         when(relationshipRepository.existsByPersonIdAndRelatedPersonIdAndRelationType(
                 alice.getId(), bob.getId(), RelationType.PARENT_OF)).thenReturn(true);
 
-        var dto = new CreateRelationshipRequest(alice.getId(), RelationType.PARENT_OF, null, null, null);
+        var dto = new RelationshipUpsertRequest(alice.getId(), RelationType.PARENT_OF, null, null, null, null, null);
         assertThatThrownBy(() -> service.addRelationship(bob.getId(), dto))
                 .isInstanceOf(DomainException.class)
                 .extracting("code")
@@ -98,7 +100,7 @@ class RelationshipServiceTest {
                 bob.getId(), alice.getId(), RelationType.PARENT_OF)).thenReturn(false);
         when(relationshipRepository.saveAndFlush(any())).thenThrow(new DataIntegrityViolationException("unique_rel"));
 
-        var dto = new CreateRelationshipRequest(bob.getId(), RelationType.PARENT_OF, null, null, null);
+        var dto = new RelationshipUpsertRequest(bob.getId(), RelationType.PARENT_OF, null, null, null, null, null);
         assertThatThrownBy(() -> service.addRelationship(alice.getId(), dto))
                 .isInstanceOf(DomainException.class)
                 .extracting("code")
@@ -107,7 +109,7 @@ class RelationshipServiceTest {
 
     @Test
     void addRelationship_throws_BAD_REQUEST_when_self_relationship() {
-        var dto = new CreateRelationshipRequest(alice.getId(), RelationType.FRIEND, null, null, null);
+        var dto = new RelationshipUpsertRequest(alice.getId(), RelationType.FRIEND, null, null, null, null, null);
         assertThatThrownBy(() -> service.addRelationship(alice.getId(), dto))
                 .isInstanceOf(DomainException.class)
                 .extracting("code")
@@ -116,14 +118,42 @@ class RelationshipServiceTest {
     }
 
     @Test
-    void addRelationship_throws_BAD_REQUEST_when_to_year_before_from_year() {
+    void addRelationship_throws_INVALID_RELATIONSHIP_DATES_when_toDate_before_fromDate() {
         when(personService.getById(alice.getId())).thenReturn(alice);
         when(personService.getById(bob.getId())).thenReturn(bob);
-        var dto = new CreateRelationshipRequest(bob.getId(), RelationType.FRIEND, 1950, 1940, null);
+        var dto = new RelationshipUpsertRequest(bob.getId(), RelationType.FRIEND,
+                LocalDate.of(1950, 1, 1), DatePrecision.YEAR,
+                LocalDate.of(1940, 1, 1), DatePrecision.YEAR, null);
         assertThatThrownBy(() -> service.addRelationship(alice.getId(), dto))
                 .isInstanceOf(DomainException.class)
                 .extracting("code")
-                .isEqualTo(ErrorCode.VALIDATION_ERROR);
+                .isEqualTo(ErrorCode.INVALID_RELATIONSHIP_DATES);
+        verify(relationshipRepository, never()).saveAndFlush(any());
+    }
+
+    @Test
+    void addRelationship_throws_INVALID_DATE_PRECISION_when_date_present_but_precision_unknown() {
+        when(personService.getById(alice.getId())).thenReturn(alice);
+        when(personService.getById(bob.getId())).thenReturn(bob);
+        var dto = new RelationshipUpsertRequest(bob.getId(), RelationType.FRIEND,
+                LocalDate.of(1950, 1, 1), DatePrecision.UNKNOWN, null, null, null);
+        assertThatThrownBy(() -> service.addRelationship(alice.getId(), dto))
+                .isInstanceOf(DomainException.class)
+                .extracting("code")
+                .isEqualTo(ErrorCode.INVALID_DATE_PRECISION);
+        verify(relationshipRepository, never()).saveAndFlush(any());
+    }
+
+    @Test
+    void addRelationship_throws_INVALID_DATE_PRECISION_when_precision_set_without_date() {
+        when(personService.getById(alice.getId())).thenReturn(alice);
+        when(personService.getById(bob.getId())).thenReturn(bob);
+        var dto = new RelationshipUpsertRequest(bob.getId(), RelationType.FRIEND,
+                null, DatePrecision.DAY, null, null, null);
+        assertThatThrownBy(() -> service.addRelationship(alice.getId(), dto))
+                .isInstanceOf(DomainException.class)
+                .extracting("code")
+                .isEqualTo(ErrorCode.INVALID_DATE_PRECISION);
         verify(relationshipRepository, never()).saveAndFlush(any());
     }
 
@@ -140,13 +170,16 @@ class RelationshipServiceTest {
             return r;
         });
 
-        var dto = new CreateRelationshipRequest(bob.getId(), RelationType.PARENT_OF, 1900, null, "first born");
+        var dto = new RelationshipUpsertRequest(bob.getId(), RelationType.PARENT_OF,
+                LocalDate.of(1900, 1, 1), DatePrecision.YEAR, null, null, "first born");
         var result = service.addRelationship(alice.getId(), dto);
 
         assertThat(result.personId()).isEqualTo(alice.getId());
         assertThat(result.relatedPersonId()).isEqualTo(bob.getId());
         assertThat(result.relationType()).isEqualTo(RelationType.PARENT_OF);
-        assertThat(result.fromYear()).isEqualTo(1900);
+        assertThat(result.fromDate()).isEqualTo(LocalDate.of(1900, 1, 1));
+        assertThat(result.fromDatePrecision()).isEqualTo(DatePrecision.YEAR);
+        assertThat(result.toDatePrecision()).isEqualTo(DatePrecision.UNKNOWN);
         assertThat(result.notes()).isEqualTo("first born");
     }
 
@@ -166,7 +199,7 @@ class RelationshipServiceTest {
             return r;
         });
 
-        var dto = new CreateRelationshipRequest(bob.getId(), RelationType.PARENT_OF, null, null, null);
+        var dto = new RelationshipUpsertRequest(bob.getId(), RelationType.PARENT_OF, null, null, null, null, null);
         service.addRelationship(alice.getId(), dto);
 
         verify(personService).setFamilyMember(alice.getId(), true);
@@ -187,7 +220,7 @@ class RelationshipServiceTest {
             return r;
         });
 
-        var dto = new CreateRelationshipRequest(bob.getId(), RelationType.FRIEND, null, null, null);
+        var dto = new RelationshipUpsertRequest(bob.getId(), RelationType.FRIEND, null, null, null, null, null);
         service.addRelationship(alice.getId(), dto);
 
         verify(personService, never()).setFamilyMember(eq(alice.getId()), anyBoolean());
@@ -216,6 +249,131 @@ class RelationshipServiceTest {
                 .isEqualTo(ErrorCode.RELATIONSHIP_NOT_FOUND);
     }
 
+    // --- updateRelationship (REQ-004/006/007/008/009/010/013) ---
+
+    @Test
+    void updateRelationship_throws_NOT_FOUND_when_relId_unknown() {
+        UUID relId = UUID.randomUUID();
+        when(relationshipRepository.findById(relId)).thenReturn(Optional.empty());
+
+        var dto = new RelationshipUpsertRequest(bob.getId(), RelationType.FRIEND, null, null, null, null, null);
+        assertThatThrownBy(() -> service.updateRelationship(alice.getId(), relId, dto))
+                .isInstanceOf(DomainException.class)
+                .extracting("code")
+                .isEqualTo(ErrorCode.RELATIONSHIP_NOT_FOUND);
+        verify(relationshipRepository, never()).saveAndFlush(any());
+    }
+
+    @Test
+    void updateRelationship_throws_NOT_FOUND_when_rel_belongs_to_different_person() {
+        UUID relId = UUID.randomUUID();
+        PersonRelationship rel = parentOf(alice, bob, relId);
+        when(relationshipRepository.findById(relId)).thenReturn(Optional.of(rel));
+
+        var dto = new RelationshipUpsertRequest(bob.getId(), RelationType.FRIEND, null, null, null, null, null);
+        assertThatThrownBy(() -> service.updateRelationship(charlie.getId(), relId, dto))
+                .isInstanceOf(DomainException.class)
+                .extracting("code")
+                .isEqualTo(ErrorCode.RELATIONSHIP_NOT_FOUND);
+        verify(relationshipRepository, never()).saveAndFlush(any());
+    }
+
+    @Test
+    void updateRelationship_throws_VALIDATION_ERROR_on_self_relation() {
+        UUID relId = UUID.randomUUID();
+        PersonRelationship rel = relOf(alice, bob, RelationType.FRIEND, relId);
+        when(relationshipRepository.findById(relId)).thenReturn(Optional.of(rel));
+
+        var dto = new RelationshipUpsertRequest(alice.getId(), RelationType.FRIEND, null, null, null, null, null);
+        assertThatThrownBy(() -> service.updateRelationship(alice.getId(), relId, dto))
+                .isInstanceOf(DomainException.class)
+                .extracting("code")
+                .isEqualTo(ErrorCode.VALIDATION_ERROR);
+        verify(relationshipRepository, never()).saveAndFlush(any());
+    }
+
+    @Test
+    void updateRelationship_throws_INVALID_RELATIONSHIP_DATES_when_toDate_before_fromDate() {
+        UUID relId = UUID.randomUUID();
+        PersonRelationship rel = relOf(alice, bob, RelationType.FRIEND, relId);
+        when(relationshipRepository.findById(relId)).thenReturn(Optional.of(rel));
+
+        var dto = new RelationshipUpsertRequest(bob.getId(), RelationType.FRIEND,
+                LocalDate.of(1950, 1, 1), DatePrecision.YEAR,
+                LocalDate.of(1940, 1, 1), DatePrecision.YEAR, null);
+        assertThatThrownBy(() -> service.updateRelationship(alice.getId(), relId, dto))
+                .isInstanceOf(DomainException.class)
+                .extracting("code")
+                .isEqualTo(ErrorCode.INVALID_RELATIONSHIP_DATES);
+        verify(relationshipRepository, never()).saveAndFlush(any());
+    }
+
+    @Test
+    void updateRelationship_throws_CIRCULAR_when_reverse_PARENT_OF_exists() {
+        UUID relId = UUID.randomUUID();
+        PersonRelationship rel = relOf(alice, bob, RelationType.FRIEND, relId);
+        when(relationshipRepository.findById(relId)).thenReturn(Optional.of(rel));
+        when(personService.getById(bob.getId())).thenReturn(bob);
+        when(relationshipRepository.existsByPersonIdAndRelatedPersonIdAndRelationType(
+                bob.getId(), alice.getId(), RelationType.PARENT_OF)).thenReturn(true);
+
+        var dto = new RelationshipUpsertRequest(bob.getId(), RelationType.PARENT_OF, null, null, null, null, null);
+        assertThatThrownBy(() -> service.updateRelationship(alice.getId(), relId, dto))
+                .isInstanceOf(DomainException.class)
+                .extracting("code")
+                .isEqualTo(ErrorCode.CIRCULAR_RELATIONSHIP);
+        verify(relationshipRepository, never()).saveAndFlush(any());
+    }
+
+    @Test
+    void updateRelationship_throws_DUPLICATE_when_db_constraint_violated() {
+        UUID relId = UUID.randomUUID();
+        PersonRelationship rel = relOf(alice, bob, RelationType.FRIEND, relId);
+        when(relationshipRepository.findById(relId)).thenReturn(Optional.of(rel));
+        when(personService.getById(bob.getId())).thenReturn(bob);
+        when(relationshipRepository.saveAndFlush(any())).thenThrow(new DataIntegrityViolationException("unique_rel"));
+
+        var dto = new RelationshipUpsertRequest(bob.getId(), RelationType.SPOUSE_OF, null, null, null, null, null);
+        assertThatThrownBy(() -> service.updateRelationship(alice.getId(), relId, dto))
+                .isInstanceOf(DomainException.class)
+                .extracting("code")
+                .isEqualTo(ErrorCode.DUPLICATE_RELATIONSHIP);
+    }
+
+    @Test
+    void updateRelationship_updates_fields_and_returns_dto() {
+        UUID relId = UUID.randomUUID();
+        PersonRelationship rel = relOf(alice, bob, RelationType.FRIEND, relId);
+        when(relationshipRepository.findById(relId)).thenReturn(Optional.of(rel));
+        when(personService.getById(bob.getId())).thenReturn(bob);
+        when(relationshipRepository.saveAndFlush(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        var dto = new RelationshipUpsertRequest(bob.getId(), RelationType.SPOUSE_OF,
+                LocalDate.of(1923, 5, 12), DatePrecision.DAY, null, null, "wedding day");
+        var result = service.updateRelationship(alice.getId(), relId, dto);
+
+        assertThat(result.relationType()).isEqualTo(RelationType.SPOUSE_OF);
+        assertThat(result.fromDate()).isEqualTo(LocalDate.of(1923, 5, 12));
+        assertThat(result.fromDatePrecision()).isEqualTo(DatePrecision.DAY);
+        assertThat(result.toDatePrecision()).isEqualTo(DatePrecision.UNKNOWN);
+        assertThat(result.notes()).isEqualTo("wedding day");
+    }
+
+    @Test
+    void updateRelationship_marks_both_endpoints_family_when_updated_to_family_type() {
+        UUID relId = UUID.randomUUID();
+        PersonRelationship rel = relOf(alice, bob, RelationType.FRIEND, relId);
+        when(relationshipRepository.findById(relId)).thenReturn(Optional.of(rel));
+        when(personService.getById(bob.getId())).thenReturn(bob);
+        when(relationshipRepository.saveAndFlush(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        var dto = new RelationshipUpsertRequest(bob.getId(), RelationType.SIBLING_OF, null, null, null, null, null);
+        service.updateRelationship(alice.getId(), relId, dto);
+
+        verify(personService).setFamilyMember(alice.getId(), true);
+        verify(personService).setFamilyMember(bob.getId(), true);
+    }
+
     @Test
     void getFamilyNetwork_excludes_edges_where_one_endpoint_is_not_a_family_member() {
         // alice and bob are family members; charlie is NOT (not in findAllFamilyMembers result).
@@ -260,11 +418,15 @@ class RelationshipServiceTest {
     }
 
     private static PersonRelationship parentOf(Person parent, Person child, UUID id) {
+        return relOf(parent, child, RelationType.PARENT_OF, id);
+    }
+
+    private static PersonRelationship relOf(Person subject, Person object, RelationType type, UUID id) {
         return PersonRelationship.builder()
                 .id(id)
-                .person(parent)
-                .relatedPerson(child)
-                .relationType(RelationType.PARENT_OF)
+                .person(subject)
+                .relatedPerson(object)
+                .relationType(type)
                 .createdAt(Instant.now())
                 .build();
     }

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

@@ -81,12 +81,19 @@ class DerivedEventsAssemblyTest {
     }
 
     private PersonRelationship makeSpouseEdge(Person a, Person b, Integer fromYear) {
+        return makeSpouseEdgeWithDate(a, b,
+                fromYear != null ? LocalDate.of(fromYear, 1, 1) : null,
+                fromYear != null ? DatePrecision.YEAR : DatePrecision.UNKNOWN);
+    }
+
+    private PersonRelationship makeSpouseEdgeWithDate(Person a, Person b, LocalDate fromDate, DatePrecision precision) {
         return PersonRelationship.builder()
                 .id(UUID.randomUUID())
                 .person(a)
                 .relatedPerson(b)
                 .relationType(RelationType.SPOUSE_OF)
-                .fromYear(fromYear)
+                .fromDate(fromDate)
+                .fromDatePrecision(precision)
                 .build();
     }
 
@@ -223,6 +230,24 @@ class DerivedEventsAssemblyTest {
         assertThat(heirat.precision()).isEqualTo(DatePrecision.UNKNOWN);
     }
 
+    // --- REQ-017 (#837): derived Heirat sources SPOUSE_OF.fromDate at its stored precision ---
+
+    @Test
+    void should_emit_day_precision_heirat_from_spouse_fromDate() {
+        Person anna = makePerson(null, DatePrecision.UNKNOWN);
+        Person hans = makePersonWithDeath(null, DatePrecision.UNKNOWN);
+        PersonRelationship edge = makeSpouseEdgeWithDate(anna, hans, LocalDate.of(1923, 5, 12), DatePrecision.DAY);
+        when(personService.findAllFamilyMembers()).thenReturn(List.of(anna, hans));
+        when(relationshipService.findAllSpouseEdges()).thenReturn(List.of(edge));
+
+        TimelineEntryDTO heirat = service.assembleDerivedEvents().stream()
+                .filter(e -> e.derivedType() == DerivedEventType.MARRIAGE)
+                .findFirst().orElseThrow();
+
+        assertThat(heirat.eventDate()).isEqualTo(LocalDate.of(1923, 5, 12));
+        assertThat(heirat.precision()).isEqualTo(DatePrecision.DAY);
+    }
+
     // --- REQ-007: exactly one Heirat per SPOUSE_OF edge (dedup) ---
 
     @Test

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

@@ -69,10 +69,10 @@ class TimelineServiceTest {
         UUID id2 = UUID.fromString("00000000-0000-0000-0000-000000000002");
         var e1 = new TimelineEntryDTO(Kind.LETTER, DatePrecision.DAY, false, "", "",
                 LocalDate.of(1914, 7, 28), null, "Same Title", null, null, id1, List.of(), null,
-                null, null, null);
+                null, null, null, null);
         var e2 = new TimelineEntryDTO(Kind.LETTER, DatePrecision.DAY, false, "", "",
                 LocalDate.of(1914, 7, 28), null, "Same Title", null, null, id2, List.of(), null,
-                null, null, null);
+                null, null, null, null);
 
         var sorted = List.of(e2, e1).stream()
                 .sorted(TimelineService.WITHIN_BAND_ORDER)
@@ -511,6 +511,106 @@ class TimelineServiceTest {
         verify(tagService, times(1)).resolveRootTags(anyList());
     }
 
+    // ─── letter→event link (#850, REQ-009) ───────────────────────────────────
+
+    @Test
+    void letter_in_a_curated_events_documents_carries_that_events_id() {
+        // REQ-009: linkedEventId = the curated event whose documents set contains the letter.
+        Document letterDoc = docWithDate(LocalDate.of(1915, 5, 1), DatePrecision.MONTH);
+        UUID eventId = UUID.randomUUID();
+        TimelineEvent event = TimelineEvent.builder().id(eventId)
+                .title("Briefe von der Front").type(EventType.PERSONAL)
+                .documents(new HashSet<>(Set.of(letterDoc)))
+                .build(); // no eventDate → event lands undated, leaving the year band to the letter
+        when(eventRepository.findAll()).thenReturn(List.of(event));
+        when(timelineEventService.assembleDerivedEvents()).thenReturn(List.of());
+        when(documentService.getAllForTimeline()).thenReturn(List.of(letterDoc));
+
+        TimelineEntryDTO entry = onlyLetterEntry(timelineService.assemble(noFilters()));
+
+        assertThat(entry.linkedEventId()).isEqualTo(eventId);
+    }
+
+    @Test
+    void letter_in_no_curated_event_has_null_linkedEventId() {
+        // REQ-009: a letter referenced by no curated event → linkedEventId null; the frontend
+        // then renders it as a loose chronological letter (REQ-006).
+        Document letterDoc = docWithDate(LocalDate.of(1915, 5, 1), DatePrecision.MONTH);
+        TimelineEvent event = TimelineEvent.builder().id(UUID.randomUUID())
+                .title("Anderes Ereignis").type(EventType.PERSONAL)
+                .documents(new HashSet<>(Set.of(Document.builder().id(UUID.randomUUID()).build())))
+                .build();
+        when(eventRepository.findAll()).thenReturn(List.of(event));
+        when(timelineEventService.assembleDerivedEvents()).thenReturn(List.of());
+        when(documentService.getAllForTimeline()).thenReturn(List.of(letterDoc));
+
+        TimelineEntryDTO entry = onlyLetterEntry(timelineService.assemble(noFilters()));
+
+        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());
+    }
+
+    @Test
+    void letter_linked_only_to_a_filtered_out_event_has_null_linkedEventId() {
+        // finding #10: the link pass runs over the events that survived the filter, not all of
+        // them. A letter whose only linking event is excluded by the active filter links to
+        // nothing (the frontend would drop it loose anyway) — and the lazy `documents` collection
+        // is never hydrated for events that are off-screen.
+        Document letterDoc = docWithDate(LocalDate.of(1916, 5, 1), DatePrecision.MONTH);
+        TimelineEvent worldEvent = TimelineEvent.builder().id(UUID.randomUUID())
+                .title("Somme").type(EventType.HISTORICAL)
+                .documents(new HashSet<>(Set.of(letterDoc)))
+                .build();
+        when(eventRepository.findAll()).thenReturn(List.of(worldEvent));
+        when(timelineEventService.assembleDerivedEvents()).thenReturn(List.of());
+        when(documentService.getAllForTimeline()).thenReturn(List.of(letterDoc));
+
+        // Filter to PERSONAL only → the HISTORICAL event is filtered out of the view.
+        TimelineEntryDTO entry = theLetter(timelineService.assemble(
+                new TimelineFilter(null, null, EventType.PERSONAL, null, null)));
+
+        assertThat(entry.linkedEventId()).isNull();
+    }
+
+    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);
@@ -523,7 +623,7 @@ class TimelineServiceTest {
     private static TimelineEntryDTO letter(LocalDate date, DatePrecision precision, String title) {
         return new TimelineEntryDTO(Kind.LETTER, precision, false, "", "",
                 date, null, title, null, null, UUID.randomUUID(), List.of(), null,
-                null, null, null);
+                null, null, null, null);
     }
 
     private static Document docWithDate(LocalDate date, DatePrecision precision) {

docs/DEPLOYMENT.md

@@ -538,6 +538,29 @@ pg_restore -t persons -d ${POSTGRES_DB} backup-YYYYMMDD.dump
 
 (For a plain-SQL dump, extract the persons COPY block instead of replaying the full file.)
 
+### Deploy note — V78 (person_relationships from/to → date + precision, #837)
+
+V78 drops `person_relationships.from_year`/`to_year` after backfilling the new
+`from_date`/`to_date` + precision columns — a **one-way migration** (Flyway cannot roll
+it back). Like V76 it runs its pre-check + DDL in one atomic Flyway transaction and
+needs **no maintenance window** (single-writer archive, no concurrent importers).
+
+It is, however, **not rolling-deploy-safe**: the previously-running JAR still maps the
+`from_year`/`to_year` columns, so it would error against the migrated schema. Deploy in
+this order (the default stop-then-start, single-instance deploy already satisfies it):
+
+1. Take a manual `pg_dump` (see above) and confirm it completed.
+2. **Stop the old JAR**, then **start the new JAR** — Flyway V78 runs first thing on the
+   new JAR's startup, before any request is served. Never run the old and new JARs
+   concurrently across this migration.
+
+If post-deploy data issues are found, restore **only the person_relationships table**
+from the pre-migration dump:
+
+```bash
+pg_restore -t person_relationships -d ${POSTGRES_DB} backup-YYYYMMDD.dump
+```
+
 ### Rollback
 
 Each release tag corresponds to a docker image tag on the host daemon (built via DooD; no registry). Rolling back to a previous tag is one command:

docs/adr/044-relationship-dates-localdate-precision.md

@@ -0,0 +1,91 @@
+# ADR-044 — Relationship dates become LocalDate + DatePrecision; relationships become editable
+
+**Status:** Accepted
+**Date:** 2026-06-14
+**Issue:** #837 (Zeitstrahl milestone; deferred follow-up to #773 / ADR-039)
+
+## Context
+
+`PersonRelationship` stored its span as `Integer fromYear`/`toYear`. A wedding could
+never be more precise than `1923`, while `Person` (ADR-039), `Document`, and
+`TimelineEvent` already carry full `DatePrecision`. Relationships also supported only
+create + delete: fixing a wrong type, a wrong person, or adding a date learned later
+meant deleting and re-creating the edge — losing `createdAt`. A `notes` column existed
+that no form set and nothing displayed.
+
+V78 replaces the two integer columns with `from_date`/`to_date` (`DATE`, nullable) plus
+`from_date_precision`/`to_date_precision` (`VARCHAR(16) NOT NULL DEFAULT 'UNKNOWN'`),
+backfilling existing years as `YYYY-01-01` at `YEAR` precision — exactly the V76 / ADR-039
+pattern applied to the relationship edge. A new `PUT /api/persons/{id}/relationships/{relId}`
+makes relationships editable, and `notes` is activated end to end.
+
+## Decisions
+
+### 1. Mirror ADR-039 verbatim for the relationship edge
+
+`DatePrecision` is imported cross-domain from `document/` (ADR-039 §1 — value-type
+sharing, not a layering breach). The precision columns are NOT NULL default `UNKNOWN`,
+guarded by five named CHECK constraints (`chk_relationship_from_coherence`,
+`chk_relationship_to_coherence`, `chk_relationship_date_order`,
+`chk_relationship_{from,to}_precision_values`). `RelationshipService.validateRelationshipDates`
+enforces the same rules first, so the user gets a structured 400
+(`INVALID_DATE_PRECISION` for coherence, the new `INVALID_RELATIONSHIP_DATES` for a
+`toDate < fromDate` order violation) instead of a constraint-violation 500. The form
+offers only **DAY / MONTH / YEAR**; storage still accepts all seven values, and a
+stored non-offered precision seeds the edit select as `YEAR` (ADR-039 §2).
+
+### 2. Update re-runs every create invariant
+
+An edit can violate the same invariants as a create, so `updateRelationship` re-runs
+all of them: self-relation (`VALIDATION_ERROR`), date coherence + order, reverse
+`PARENT_OF` (`CIRCULAR_RELATIONSHIP`), and the `(person, relatedPerson, type)` unique
+constraint via `saveAndFlush` (`DUPLICATE_RELATIONSHIP`). Editing into a family type
+flags both endpoints as family members (additive; never auto-unflags). The directed
+orientation is preserved per viewpoint — whichever endpoint `{personId}` already holds
+on the row stays put — so a `PARENT_OF` edge remains parent→child whether edited from
+either person's page.
+
+### 3. No optimistic locking (`@Version`)
+
+`PersonRelationship` gains no `@Version`; the edit is last-write-wins, matching the
+person edit form. This is a single-writer family archive, and it avoids the managed-
+`setVersion` pitfall (a `setVersion` on a managed entity is silently ignored by
+Hibernate — see the integration-test note in #496-era work). If concurrent curation
+ever becomes real, add `@Version` plus an explicit client-version compare then.
+
+### 4. IDOR / anti-enumeration: ownership mismatch is 404, for PUT **and** DELETE
+
+A `{relId}` that does not belong to `{personId}` returns 404 `RELATIONSHIP_NOT_FOUND`
+(a shared `loadOwnedRelationship` helper), so a curator cannot probe relationship ids
+belonging to people they cannot see. This **aligns `deleteRelationship`** from its
+former 403 to 404 in the same change, so the two mutating endpoints behave identically
+on the same mismatch.
+
+### 5. Derived marriage events gain precision for free
+
+`TimelineEventService.buildMarriageEvents` now sources the Heirat date from the
+`SPOUSE_OF` row's `from_date` + `from_date_precision` (previously
+`LocalDate.of(fromYear, 1, 1)` at hard-coded `YEAR`). A DAY-precision wedding now
+surfaces the exact day on the Zeitstrahl. `RelationshipInferenceService` is unchanged
+— it is time-ignorant and never read the year fields.
+
+### 6. `relationshipDates.ts` lives in `$lib/person/`, no new boundary
+
+`formatRelationshipDateRange` mirrors `personLifeDates.ts` and delegates entirely to the
+already-tested `formatDocumentDate` (zero new precision logic). It sits in `$lib/person/`
+next to `personLifeDates.ts`; its only cross-domain import is `formatDocumentDate` from
+`$lib/shared/utils/`, which the existing `person → shared` rule in `eslint.config.js`
+already permits — **no new eslint boundary rule is added**.
+
+## Consequences
+
+- V78 is one-way (columns dropped) and is **not** rolling-deploy-safe — the running JAR
+  maps `from_year` until redeploy. Deploy order: **stop old JAR → run Flyway V78 →
+  start new JAR**. Rollback = targeted `pg_restore -t person_relationships` from the
+  pre-deploy dump (see `docs/DEPLOYMENT.md` §8). No maintenance window needed
+  (single-writer archive).
+- Relationships are fully editable (type, related person, dates, notes) and the read
+  view shows the date range + notes.
+- `RelationshipDTO` drops `fromYear`/`toYear` for `fromDate`/`fromDatePrecision`/
+  `toDate`/`toDatePrecision`; the `personBirthYear`/`relatedPersonBirthYear` derived
+  fields are unaffected (ADR-039 §3).

docs/architecture/db/db-orm.puml

@@ -1,6 +1,6 @@
 @startuml db-orm
-' Schema source: Flyway V1–V77 (excl. V37, V43 — intentionally removed)
-' Schema as of:  V77 (2026-06-12)
+' Schema source: Flyway V1–V78 (excl. V37, V43 — intentionally removed)
+' Schema as of:  V78 (2026-06-14)
 ' ⚠ This is a versioned snapshot. Update when the schema changes significantly.
 
 hide circle
@@ -211,8 +211,10 @@ package "Persons" {
     person_id : UUID <<FK>>
     related_person_id : UUID <<FK>>
     relation_type : VARCHAR(30) NOT NULL
-    from_year : INTEGER
-    to_year : INTEGER
+    from_date : DATE
+    from_date_precision : VARCHAR(16) NOT NULL DEFAULT 'UNKNOWN'
+    to_date : DATE
+    to_date_precision : VARCHAR(16) NOT NULL DEFAULT 'UNKNOWN'
     notes : VARCHAR(2000)
     created_at : TIMESTAMPTZ NOT NULL
   }

docs/architecture/db/db-relationships.puml

@@ -7,6 +7,8 @@
 ' Note: V76 swaps persons.birth_year/death_year for birth_date/death_date +
 ' precision columns; columns only, no new FK relationships, diagram unchanged.
 ' Note: V77 adds the timeline_events table + two join tables (Timeline package below).
+' Note: V78 swaps person_relationships.from_year/to_year for from_date/to_date +
+' precision columns; columns only, no new FK relationships, diagram unchanged.
 
 hide circle
 skinparam linetype ortho

frontend/e2e/zeitstrahl-filter.spec.ts

@@ -0,0 +1,93 @@
+import AxeBuilder from '@axe-core/playwright';
+import { test, expect, type APIRequestContext } from '@playwright/test';
+
+/**
+ * Global /zeitstrahl layer filter (#780). Runs against the real stack with the
+ * seeded admin session (auth.setup). Covers the primary journey (hide the
+ * Letters layer → letter cards vanish + the trigger reports one active filter →
+ * reset restores everything) and a 375px axe pass with the collapsible open in
+ * both light and dark mode.
+ *
+ * #779 (the /zeitstrahl route) is merged, so this spec is NOT skipped. Per
+ * e2e/CLAUDE.md, E2E is not yet wired into CI — this axe gate runs locally only
+ * for now.
+ */
+
+const stamp = () => new Date().toISOString().replace(/[^0-9]/g, '');
+
+async function createPerson(request: APIRequestContext, firstName: string, lastName: string) {
+	const res = await request.post('/api/persons', {
+		data: { personType: 'PERSON', firstName, lastName }
+	});
+	if (!res.ok()) throw new Error(`create person failed: ${res.status()}`);
+	return (await res.json()).id as string;
+}
+
+/** Seeds one dated letter so the timeline has content (and a LetterCard to hide). */
+async function seedDatedLetter(request: APIRequestContext, isoDate: string, title: string) {
+	const senderId = await createPerson(request, 'Filter-Test', `Absender ${stamp()}`);
+	const receiverId = await createPerson(request, 'Filter-Test', `Empfaenger ${stamp()}`);
+
+	const createRes = await request.post('/api/documents', { multipart: { title } });
+	if (!createRes.ok()) throw new Error(`create document failed: ${createRes.status()}`);
+	const docId = (await createRes.json()).id as string;
+
+	const put = await request.put(`/api/documents/${docId}`, {
+		multipart: {
+			title,
+			documentDate: isoDate,
+			metaDatePrecision: 'DAY',
+			senderId,
+			receiverIds: receiverId
+		}
+	});
+	if (!put.ok()) throw new Error(`update document failed: ${put.status()}`);
+}
+
+test.describe('Zeitstrahl — layer filter (#780)', () => {
+	test('hiding the Letters layer removes letter cards and reports the active count; reset restores', async ({
+		page,
+		request
+	}) => {
+		// A sparse year keeps the seeded letter an individual card (not a dense strip).
+		const title = `E2E Filter Brief ${stamp()}`;
+		await seedDatedLetter(request, '1903-03-03', title);
+
+		await page.goto('/zeitstrahl');
+		await page.waitForSelector('[data-hydrated]');
+		await expect(page.getByText(title)).toBeVisible();
+
+		await page.getByTestId('timeline-filter-trigger').click();
+		await page.getByTestId('timeline-filter-letters').click();
+
+		await expect(page.getByText(title)).toHaveCount(0);
+		await expect(page.getByTestId('timeline-filter-trigger')).toContainText('1 aktiv');
+
+		await page.getByTestId('timeline-filter-reset').click();
+		await expect(page.getByText(title)).toBeVisible();
+	});
+
+	test('no wcag2a/wcag2aa violations at 375px with the filter bar open (light + dark)', async ({
+		page,
+		request
+	}) => {
+		await seedDatedLetter(request, '1915-06-15', `E2E Filter A11y ${stamp()}`);
+
+		await page.setViewportSize({ width: 375, height: 800 });
+		await page.goto('/zeitstrahl');
+		await page.waitForSelector('[data-hydrated]');
+
+		// Open the collapsible so axe scans the toggles, not just the trigger.
+		await page.getByTestId('timeline-filter-trigger').click();
+		await expect(page.getByTestId('timeline-filter-personal')).toBeVisible();
+
+		const scan = () => new AxeBuilder({ page }).withTags(['wcag2a', 'wcag2aa']).analyze();
+
+		const light = await scan();
+		expect(light.violations, JSON.stringify(light.violations, null, 2)).toEqual([]);
+
+		await page.evaluate(() => document.documentElement.setAttribute('data-theme', 'dark'));
+		const dark = await scan();
+		expect(dark.violations, JSON.stringify(dark.violations, null, 2)).toEqual([]);
+	});
+});

frontend/messages/de.json

@@ -188,6 +188,7 @@
 	"person_hint_generation": "Generation in der Familie (G 0 = älteste Generation)",
 	"person_year_error": "Bitte eine vierstellige Jahreszahl eingeben",
 	"person_years_error_order": "Geburtsjahr muss vor dem Todesjahr liegen",
+	"person_add_event": "Ereignis für diese Person",
 	"person_docs_heading": "Gesendete Dokumente",
 	"person_no_docs": "Diese Person ist noch nicht als Absender verknüpft.",
 	"person_received_docs_heading": "Empfangene Dokumente",
@@ -651,6 +652,7 @@
 	"error_invalid_date_range": "Das Enddatum darf nicht vor dem Startdatum liegen.",
 	"error_birth_after_death": "Geburtsdatum muss vor dem Sterbedatum liegen. Tipp: Falls nur das Todesjahr bekannt ist und der Geburtstag spät im selben Jahr lag, bitte das Folgejahr eintragen.",
 	"error_invalid_date_precision": "Datum und Genauigkeit stimmen nicht überein.",
+	"error_invalid_relationship_dates": "Das Ende-Datum darf nicht vor dem Beginn-Datum liegen.",
 	"validation_last_name_required": "Nachname ist Pflichtfeld.",
 	"validation_first_name_required": "Vorname ist Pflichtfeld.",
 	"error_ocr_service_unavailable": "Der OCR-Dienst ist nicht verfügbar.",
@@ -1034,6 +1036,7 @@
 	"nav_geschichten": "Geschichten",
 	"nav_zeitstrahl": "Zeitstrahl",
 	"timeline_heading": "Zeitstrahl",
+	"timeline_add_event": "Ereignis hinzufügen",
 	"timeline_empty_state": "Noch keine Ereignisse.",
 	"timeline_undated_section": "Ohne Datum",
 	"timeline_unknown_person": "Unbekannt",
@@ -1046,16 +1049,26 @@
 	"timeline_derived_birth": "Geburt",
 	"timeline_derived_death": "Tod",
 	"timeline_derived_marriage": "Heirat",
-	"timeline_grouping_date": "Gruppierung: Datum",
 	"timeline_provenance_derived": "abgeleitet",
 	"timeline_provenance_curated": "kuratiert",
+	"timeline_bucket_show_more": "+ {count} weitere Briefe anzeigen",
+	"timeline_bucket_show_less": "Weniger anzeigen",
 	"timeline_letter_glyph_label": "Brief",
+	"timeline_cluster_letter_count": "{count} Briefe",
 	"timeline_tag_chip_label": "Thema",
 	"timeline_layer_historical_suffix": "historisch",
 	"timeline_strip_density_caption": "Monats-Dichte",
 	"timeline_events_count": "{count} Ereignisse",
 	"timeline_letters_count_singular": "1 Brief",
 	"timeline_events_count_singular": "1 Ereignis",
+	"timeline_filter_label_layers": "Ebenen anzeigen",
+	"timeline_filter_layer_personal": "Persönliche Ereignisse",
+	"timeline_filter_layer_historical": "Historische Ereignisse",
+	"timeline_filter_layer_letters": "Briefe",
+	"timeline_filter_trigger": "Filter",
+	"timeline_filter_trigger_active": "Filter ({count} aktiv)",
+	"timeline_filter_reset": "Filter zurücksetzen",
+	"timeline_filter_empty_state": "Keine Einträge entsprechen diesen Filtern.",
 	"event_editor_new_title": "Neues Ereignis",
 	"event_editor_edit_title": "Ereignis bearbeiten",
 	"event_editor_section_when": "Wann",
@@ -1221,6 +1234,16 @@
 	"relation_form_field_from_year": "Von Jahr",
 	"relation_form_field_to_year": "Bis Jahr",
 	"relation_form_year_placeholder": "z.B. 1920",
+	"relation_label_from_date": "Beginn (Datum)",
+	"relation_label_to_date": "Ende (Datum)",
+	"relation_label_date_precision": "Genauigkeit",
+	"relation_precision_day": "Genaues Datum (Tag)",
+	"relation_precision_month": "Monat bekannt",
+	"relation_precision_year": "Nur Jahreszahl",
+	"relation_label_notes": "Notizen",
+	"relation_notes_placeholder": "Optionaler Hinweis zu dieser Beziehung",
+	"relation_date_placeholder_hint": "Leer lassen, wenn unbekannt",
+	"relation_edit": "Beziehung bearbeiten",
 	"person_relationships_heading": "Beziehungen",
 	"person_relationships_empty": "Noch keine Beziehungen bekannt.",
 	"timeline_aria_label": "Zeitachse Dokumentdichte",

frontend/messages/en.json

@@ -188,6 +188,7 @@
 	"person_hint_generation": "Generation within the family (G 0 = oldest generation)",
 	"person_year_error": "Please enter a four-digit year",
 	"person_years_error_order": "Birth year must be before death year",
+	"person_add_event": "Add event for this person",
 	"person_docs_heading": "Sent documents",
 	"person_no_docs": "This person has not yet been linked as a sender.",
 	"person_received_docs_heading": "Received documents",
@@ -651,6 +652,7 @@
 	"error_invalid_date_range": "The end date must not be before the start date.",
 	"error_birth_after_death": "Birth date must be before death date. Tip: if only the death year is known and the birthday is late in the same year, enter the following year.",
 	"error_invalid_date_precision": "Date and precision do not match.",
+	"error_invalid_relationship_dates": "The end date must not be before the start date.",
 	"validation_last_name_required": "Last name is required.",
 	"validation_first_name_required": "First name is required.",
 	"error_ocr_service_unavailable": "The OCR service is not available.",
@@ -1034,6 +1036,7 @@
 	"nav_geschichten": "Stories",
 	"nav_zeitstrahl": "Timeline",
 	"timeline_heading": "Timeline",
+	"timeline_add_event": "Add event",
 	"timeline_empty_state": "No events yet.",
 	"timeline_undated_section": "Without Date",
 	"timeline_unknown_person": "Unknown",
@@ -1046,16 +1049,26 @@
 	"timeline_derived_birth": "Birth",
 	"timeline_derived_death": "Death",
 	"timeline_derived_marriage": "Marriage",
-	"timeline_grouping_date": "Grouping: Date",
 	"timeline_provenance_derived": "derived",
 	"timeline_provenance_curated": "curated",
+	"timeline_bucket_show_more": "+ {count} more letters",
+	"timeline_bucket_show_less": "Show fewer",
 	"timeline_letter_glyph_label": "Letter",
+	"timeline_cluster_letter_count": "{count} letters",
 	"timeline_tag_chip_label": "Topic",
 	"timeline_layer_historical_suffix": "historical",
 	"timeline_strip_density_caption": "Monthly density",
 	"timeline_events_count": "{count} events",
 	"timeline_letters_count_singular": "1 letter",
 	"timeline_events_count_singular": "1 event",
+	"timeline_filter_label_layers": "Show layers",
+	"timeline_filter_layer_personal": "Personal events",
+	"timeline_filter_layer_historical": "Historical events",
+	"timeline_filter_layer_letters": "Letters",
+	"timeline_filter_trigger": "Filter",
+	"timeline_filter_trigger_active": "Filter ({count} active)",
+	"timeline_filter_reset": "Reset filters",
+	"timeline_filter_empty_state": "No entries match these filters.",
 	"event_editor_new_title": "New event",
 	"event_editor_edit_title": "Edit event",
 	"event_editor_section_when": "When",
@@ -1221,6 +1234,16 @@
 	"relation_form_field_from_year": "From year",
 	"relation_form_field_to_year": "To year",
 	"relation_form_year_placeholder": "e.g. 1920",
+	"relation_label_from_date": "Start date",
+	"relation_label_to_date": "End date",
+	"relation_label_date_precision": "Precision",
+	"relation_precision_day": "Exact date (day)",
+	"relation_precision_month": "Month known",
+	"relation_precision_year": "Year only",
+	"relation_label_notes": "Notes",
+	"relation_notes_placeholder": "Optional note about this relationship",
+	"relation_date_placeholder_hint": "Leave empty if unknown",
+	"relation_edit": "Edit relationship",
 	"person_relationships_heading": "Relationships",
 	"person_relationships_empty": "No relationships known yet.",
 	"timeline_aria_label": "Document density timeline",

frontend/messages/es.json

@@ -188,6 +188,7 @@
 	"person_hint_generation": "Generación dentro de la familia (G 0 = generación más antigua)",
 	"person_year_error": "Introduzca un año de cuatro dígitos",
 	"person_years_error_order": "El año de nacimiento debe ser anterior al año de fallecimiento",
+	"person_add_event": "Añadir evento para esta persona",
 	"person_docs_heading": "Documentos enviados",
 	"person_no_docs": "Esta persona aún no está vinculada como remitente.",
 	"person_received_docs_heading": "Documentos recibidos",
@@ -651,6 +652,7 @@
 	"error_invalid_date_range": "La fecha final no puede ser anterior a la inicial.",
 	"error_birth_after_death": "La fecha de nacimiento debe ser anterior a la de defunción.",
 	"error_invalid_date_precision": "La fecha y la precisión no coinciden.",
+	"error_invalid_relationship_dates": "La fecha de fin no puede ser anterior a la de inicio.",
 	"validation_last_name_required": "El apellido es obligatorio.",
 	"validation_first_name_required": "El nombre es obligatorio.",
 	"error_ocr_service_unavailable": "El servicio OCR no está disponible.",
@@ -1034,6 +1036,7 @@
 	"nav_geschichten": "Historias",
 	"nav_zeitstrahl": "Línea de tiempo",
 	"timeline_heading": "Línea de tiempo",
+	"timeline_add_event": "Añadir evento",
 	"timeline_empty_state": "Aún no hay eventos.",
 	"timeline_undated_section": "Sin Fecha",
 	"timeline_unknown_person": "Desconocido",
@@ -1046,16 +1049,26 @@
 	"timeline_derived_birth": "Nacimiento",
 	"timeline_derived_death": "Fallecimiento",
 	"timeline_derived_marriage": "Matrimonio",
-	"timeline_grouping_date": "Agrupación: Fecha",
 	"timeline_provenance_derived": "derivado",
 	"timeline_provenance_curated": "curado",
+	"timeline_bucket_show_more": "+ {count} cartas más",
+	"timeline_bucket_show_less": "Mostrar menos",
 	"timeline_letter_glyph_label": "Carta",
+	"timeline_cluster_letter_count": "{count} cartas",
 	"timeline_tag_chip_label": "Tema",
 	"timeline_layer_historical_suffix": "histórico",
 	"timeline_strip_density_caption": "Densidad mensual",
 	"timeline_events_count": "{count} eventos",
 	"timeline_letters_count_singular": "1 carta",
 	"timeline_events_count_singular": "1 evento",
+	"timeline_filter_label_layers": "Mostrar capas",
+	"timeline_filter_layer_personal": "Eventos personales",
+	"timeline_filter_layer_historical": "Eventos históricos",
+	"timeline_filter_layer_letters": "Cartas",
+	"timeline_filter_trigger": "Filtro",
+	"timeline_filter_trigger_active": "Filtro ({count} activos)",
+	"timeline_filter_reset": "Restablecer filtros",
+	"timeline_filter_empty_state": "Ninguna entrada coincide con estos filtros.",
 	"event_editor_new_title": "Nuevo evento",
 	"event_editor_edit_title": "Editar evento",
 	"event_editor_section_when": "Cuándo",
@@ -1221,6 +1234,16 @@
 	"relation_form_field_from_year": "Desde año",
 	"relation_form_field_to_year": "Hasta año",
 	"relation_form_year_placeholder": "ej. 1920",
+	"relation_label_from_date": "Fecha de inicio",
+	"relation_label_to_date": "Fecha de fin",
+	"relation_label_date_precision": "Precisión",
+	"relation_precision_day": "Fecha exacta (día)",
+	"relation_precision_month": "Mes conocido",
+	"relation_precision_year": "Solo año",
+	"relation_label_notes": "Notas",
+	"relation_notes_placeholder": "Nota opcional sobre esta relación",
+	"relation_date_placeholder_hint": "Dejar vacío si es desconocido",
+	"relation_edit": "Editar relación",
 	"person_relationships_heading": "Relaciones",
 	"person_relationships_empty": "Aún no se conocen relaciones.",
 	"timeline_aria_label": "Cronología de densidad de documentos",

frontend/package-lock.json

@@ -9515,9 +9515,9 @@
 			}
 		},
 		"node_modules/vite": {
-			"version": "7.3.3",
-			"resolved": "https://registry.npmjs.org/vite/-/vite-7.3.3.tgz",
-			"integrity": "sha512-/4XH147Ui7OGTjg3HbdWe5arnZQSbfuRzdr9Ec7TQi5I7R+ir0Rlc9GIvD4v0XZurELqA035KVXJXpR61xhiTA==",
+			"version": "7.3.5",
+			"resolved": "https://registry.npmjs.org/vite/-/vite-7.3.5.tgz",
+			"integrity": "sha512-KuOaNhcnGFN2zIPGA7wRmzF+lJA1sea7rHq17aiJ++9lzY1WWG6Jpwqwe1KNbRVPIqHmr8GLYx7jbrQcN/7/ww==",
 			"license": "MIT",
 			"dependencies": {
 				"esbuild": "^0.27.0",

frontend/src/lib/generated/api.ts

@@ -100,6 +100,22 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/persons/{id}/relationships/{relId}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put: operations["updateRelationship"];
+        post?: never;
+        delete: operations["deleteRelationship"];
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/geschichten/{id}/items/reorder": {
         parameters: {
             query?: never;
@@ -1640,22 +1656,6 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
-    "/api/persons/{id}/relationships/{relId}": {
-        parameters: {
-            query?: never;
-            header?: never;
-            path?: never;
-            cookie?: never;
-        };
-        get?: never;
-        put?: never;
-        post?: never;
-        delete: operations["deleteRelationship"];
-        options?: never;
-        head?: never;
-        patch?: never;
-        trace?: never;
-    };
     "/api/persons/{id}/aliases/{aliasId}": {
         parameters: {
             query?: never;
@@ -1853,6 +1853,50 @@ export interface components {
             provisional: boolean;
             readonly displayName: string;
         };
+        RelationshipUpsertRequest: {
+            /** Format: uuid */
+            relatedPersonId: string;
+            /** @enum {string} */
+            relationType: "PARENT_OF" | "SPOUSE_OF" | "SIBLING_OF" | "FRIEND" | "COLLEAGUE" | "EMPLOYER" | "DOCTOR" | "NEIGHBOR" | "OTHER";
+            /** Format: date */
+            fromDate?: string;
+            /** @enum {string} */
+            fromDatePrecision?: "DAY" | "MONTH" | "SEASON" | "YEAR" | "RANGE" | "APPROX" | "UNKNOWN";
+            /** Format: date */
+            toDate?: string;
+            /** @enum {string} */
+            toDatePrecision?: "DAY" | "MONTH" | "SEASON" | "YEAR" | "RANGE" | "APPROX" | "UNKNOWN";
+            notes?: string;
+        };
+        RelationshipDTO: {
+            /** Format: uuid */
+            id: string;
+            /** Format: uuid */
+            personId: string;
+            /** Format: uuid */
+            relatedPersonId: string;
+            personDisplayName: string;
+            /** Format: int32 */
+            personBirthYear?: number;
+            /** Format: int32 */
+            personDeathYear?: number;
+            relatedPersonDisplayName: string;
+            /** Format: int32 */
+            relatedPersonBirthYear?: number;
+            /** Format: int32 */
+            relatedPersonDeathYear?: number;
+            /** @enum {string} */
+            relationType: "PARENT_OF" | "SPOUSE_OF" | "SIBLING_OF" | "FRIEND" | "COLLEAGUE" | "EMPLOYER" | "DOCTOR" | "NEIGHBOR" | "OTHER";
+            /** Format: date */
+            fromDate?: string;
+            /** @enum {string} */
+            fromDatePrecision: "DAY" | "MONTH" | "SEASON" | "YEAR" | "RANGE" | "APPROX" | "UNKNOWN";
+            /** Format: date */
+            toDate?: string;
+            /** @enum {string} */
+            toDatePrecision: "DAY" | "MONTH" | "SEASON" | "YEAR" | "RANGE" | "APPROX" | "UNKNOWN";
+            notes?: string;
+        };
         JourneyReorderDTO: {
             itemIds?: string[];
         };
@@ -2008,42 +2052,6 @@ export interface components {
             /** Format: uuid */
             targetId: string;
         };
-        CreateRelationshipRequest: {
-            /** Format: uuid */
-            relatedPersonId: string;
-            /** @enum {string} */
-            relationType: "PARENT_OF" | "SPOUSE_OF" | "SIBLING_OF" | "FRIEND" | "COLLEAGUE" | "EMPLOYER" | "DOCTOR" | "NEIGHBOR" | "OTHER";
-            /** Format: int32 */
-            fromYear?: number;
-            /** Format: int32 */
-            toYear?: number;
-            notes?: string;
-        };
-        RelationshipDTO: {
-            /** Format: uuid */
-            id: string;
-            /** Format: uuid */
-            personId: string;
-            /** Format: uuid */
-            relatedPersonId: string;
-            personDisplayName: string;
-            /** Format: int32 */
-            personBirthYear?: number;
-            /** Format: int32 */
-            personDeathYear?: number;
-            relatedPersonDisplayName: string;
-            /** Format: int32 */
-            relatedPersonBirthYear?: number;
-            /** Format: int32 */
-            relatedPersonDeathYear?: number;
-            /** @enum {string} */
-            relationType: "PARENT_OF" | "SPOUSE_OF" | "SIBLING_OF" | "FRIEND" | "COLLEAGUE" | "EMPLOYER" | "DOCTOR" | "NEIGHBOR" | "OTHER";
-            /** Format: int32 */
-            fromYear?: number;
-            /** Format: int32 */
-            toYear?: number;
-            notes?: string;
-        };
         PersonNameAliasDTO: {
             lastName: string;
             firstName?: string;
@@ -2459,6 +2467,8 @@ export interface components {
             rootTagId?: string;
             rootTagName?: string;
             rootTagColor?: string;
+            /** Format: uuid */
+            linkedEventId?: string;
         };
         TimelineYearDTO: {
             /** Format: int32 */
@@ -3200,6 +3210,54 @@ export interface operations {
             };
         };
     };
+    updateRelationship: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: string;
+                relId: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["RelationshipUpsertRequest"];
+            };
+        };
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "*/*": components["schemas"]["RelationshipDTO"];
+                };
+            };
+        };
+    };
+    deleteRelationship: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: string;
+                relId: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description No Content */
+            204: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
     reorderItems: {
         parameters: {
             query?: never;
@@ -3663,7 +3721,7 @@ export interface operations {
         };
         requestBody: {
             content: {
-                "application/json": components["schemas"]["CreateRelationshipRequest"];
+                "application/json": components["schemas"]["RelationshipUpsertRequest"];
             };
         };
         responses: {
@@ -5909,27 +5967,6 @@ export interface operations {
             };
         };
     };
-    deleteRelationship: {
-        parameters: {
-            query?: never;
-            header?: never;
-            path: {
-                id: string;
-                relId: string;
-            };
-            cookie?: never;
-        };
-        requestBody?: never;
-        responses: {
-            /** @description No Content */
-            204: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content?: never;
-            };
-        };
-    };
     removeAlias: {
         parameters: {
             query?: never;

frontend/src/lib/messages.spec.ts

@@ -74,9 +74,10 @@ describe('message key parity', () => {
 	// every locale so no surface ever falls back to a missing translation.
 	it('zeitstrahl visual-fidelity keys are present in all locales (#833 REQ-015)', () => {
 		const requiredKeys = [
-			'timeline_grouping_date',
 			'timeline_provenance_derived',
 			'timeline_provenance_curated',
+			'timeline_bucket_show_more',
+			'timeline_bucket_show_less',
 			'timeline_letter_glyph_label',
 			'timeline_layer_historical_suffix',
 			'timeline_strip_density_caption',
@@ -98,4 +99,47 @@ describe('message key parity', () => {
 		expect(en).toMatchObject({ timeline_tag_chip_label: 'Topic' });
 		expect(es).toMatchObject({ timeline_tag_chip_label: 'Tema' });
 	});
+
+	// #850 finding #6: the event-card letter count carries an sr-only "{count} Briefe" so the
+	// bare "· 2" never announces to a screen reader without context.
+	it('zeitstrahl cluster letter-count key is present in all locales (#850 finding #6)', () => {
+		expect(de).toHaveProperty('timeline_cluster_letter_count');
+		expect(en).toHaveProperty('timeline_cluster_letter_count');
+		expect(es).toHaveProperty('timeline_cluster_letter_count');
+	});
+
+	// #780 REQ-010: the layer-filter strings are Paraglide keys in every locale.
+	// timeline_filter_trigger (0 active) and timeline_filter_trigger_active ({count},
+	// ≥1 active) are distinct keys so the trigger never reads "Filter (0 aktiv)".
+	it('zeitstrahl layer-filter keys are present in all locales (#780 REQ-010)', () => {
+		const requiredKeys = [
+			'timeline_filter_label_layers',
+			'timeline_filter_layer_personal',
+			'timeline_filter_layer_historical',
+			'timeline_filter_layer_letters',
+			'timeline_filter_trigger',
+			'timeline_filter_trigger_active',
+			'timeline_filter_reset',
+			'timeline_filter_empty_state'
+		];
+		for (const key of requiredKeys) {
+			expect(de, `missing key in de: ${key}`).toHaveProperty(key);
+			expect(en, `missing key in en: ${key}`).toHaveProperty(key);
+			expect(es, `missing key in es: ${key}`).toHaveProperty(key);
+		}
+		// the active-count key carries the established {count} placeholder
+		expect(de.timeline_filter_trigger_active).toContain('{count}');
+		expect(en.timeline_filter_trigger_active).toContain('{count}');
+		expect(es.timeline_filter_trigger_active).toContain('{count}');
+	});
+
+	// #842: the two curator-affordance CTA labels (Zeitstrahl header + person page)
+	// are Paraglide keys present in every locale; the edit pencils reuse btn_edit.
+	it('curator-affordance CTA keys are present in all locales (#842)', () => {
+		for (const key of ['timeline_add_event', 'person_add_event']) {
+			expect(de, `missing key in de: ${key}`).toHaveProperty(key);
+			expect(en, `missing key in en: ${key}`).toHaveProperty(key);
+			expect(es, `missing key in es: ${key}`).toHaveProperty(key);
+		}
+	});
 });

frontend/src/lib/person/PersonHoverCard.svelte.spec.ts

@@ -193,7 +193,9 @@ describe('PersonHoverCard — loaded state', () => {
 				relatedPersonId: 'p-spouse',
 				personDisplayName: 'Auguste',
 				relatedPersonDisplayName: 'Otto Raddatz',
-				relationType: 'SPOUSE_OF'
+				relationType: 'SPOUSE_OF',
+				fromDatePrecision: 'UNKNOWN',
+				toDatePrecision: 'UNKNOWN'
 			},
 			{
 				id: 'r2',
@@ -201,7 +203,9 @@ describe('PersonHoverCard — loaded state', () => {
 				relatedPersonId: 'p-friend',
 				personDisplayName: 'Auguste',
 				relatedPersonDisplayName: 'Karl Friend',
-				relationType: 'FRIEND'
+				relationType: 'FRIEND',
+				fromDatePrecision: 'UNKNOWN',
+				toDatePrecision: 'UNKNOWN'
 			},
 			{
 				id: 'r3',
@@ -209,7 +213,9 @@ describe('PersonHoverCard — loaded state', () => {
 				relatedPersonId: 'p-sibling',
 				personDisplayName: 'Auguste',
 				relatedPersonDisplayName: 'Marie Sister',
-				relationType: 'SIBLING_OF'
+				relationType: 'SIBLING_OF',
+				fromDatePrecision: 'UNKNOWN',
+				toDatePrecision: 'UNKNOWN'
 			}
 		];
 		render(PersonHoverCard, {
@@ -235,7 +241,9 @@ describe('PersonHoverCard — loaded state', () => {
 				relatedPersonId: 'p-aug',
 				personDisplayName: 'Heinrich Raddatz',
 				relatedPersonDisplayName: 'Auguste Raddatz',
-				relationType: 'PARENT_OF'
+				relationType: 'PARENT_OF',
+				fromDatePrecision: 'UNKNOWN',
+				toDatePrecision: 'UNKNOWN'
 			}
 		];
 		render(PersonHoverCard, {
@@ -258,7 +266,9 @@ describe('PersonHoverCard — loaded state', () => {
 				relatedPersonId: 'p-friend',
 				personDisplayName: 'Auguste',
 				relatedPersonDisplayName: 'Karl Friend',
-				relationType: 'FRIEND'
+				relationType: 'FRIEND',
+				fromDatePrecision: 'UNKNOWN',
+				toDatePrecision: 'UNKNOWN'
 			}
 		];
 		render(PersonHoverCard, {

frontend/src/lib/person/PersonLifeDateField.svelte

@@ -1,17 +1,10 @@
 <script lang="ts">
-import { onMount } from 'svelte';
 import { m } from '$lib/paraglide/messages.js';
-import DateInput from '$lib/shared/primitives/DateInput.svelte';
+import DateInputWithPrecision from '$lib/shared/primitives/DateInputWithPrecision.svelte';
 import type { DatePrecision } from '$lib/shared/utils/documentDate';
 
 // Only DAY / MONTH / YEAR are offered for life dates: RANGE and SEASON make no
 // sense for a birth or death, and APPROX stays display-only for legacy imports (#773).
-const PERSON_DATE_PRECISIONS: { value: DatePrecision; label: () => string }[] = [
-	{ value: 'DAY', label: m.person_precision_day },
-	{ value: 'MONTH', label: m.person_precision_month },
-	{ value: 'YEAR', label: m.person_precision_year }
-];
-
 let {
 	name,
 	legend,
@@ -26,73 +19,21 @@ let {
 	initialPrecision?: string | null;
 } = $props();
 
-let iso = $state('');
-let errorMessage = $state<string | null>(null);
-let inputEl = $state<HTMLInputElement | undefined>();
-let precision = $state<DatePrecision>('DAY');
-
-// Seed once at mount (WhoWhenSection pattern): a later load() rerun must not
-// stomp the user's in-progress edit.
-onMount(() => {
-	if (initialIso) {
-		iso = initialIso;
-	}
-	const offered = PERSON_DATE_PRECISIONS.some((p) => p.value === initialPrecision);
-	if (offered) {
-		precision = initialPrecision as DatePrecision;
-	} else if (initialIso) {
-		// Legacy APPROX/SEASON/RANGE precision is not editable here — seed YEAR so an
-		// untouched save does not silently claim DAY precision for the stored date.
-		precision = 'YEAR';
-	}
-});
-
-// A partial date leaves the hidden ISO empty — submitting then would silently
-// clear a stored date. Block native submission until completed or fully emptied.
-$effect(() => {
-	inputEl?.setCustomValidity(errorMessage ?? '');
-});
-
-const controlCls =
-	'block min-h-[44px] w-full rounded border border-line px-3 py-2 font-serif text-ink focus:outline-none focus-visible:ring-2 focus-visible:ring-focus-ring';
+const precisions: { value: DatePrecision; label: string }[] = $derived([
+	{ value: 'DAY', label: m.person_precision_day() },
+	{ value: 'MONTH', label: m.person_precision_month() },
+	{ value: 'YEAR', label: m.person_precision_year() }
+]);
+const hint = $derived(`${m.person_precision_hint()} · ${m.person_date_placeholder_hint()}`);
 </script>
 
-<fieldset>
-	<legend class="mb-1 block text-xs font-bold tracking-widest text-ink-3 uppercase">
-		{legend}
-	</legend>
-	<div class="flex flex-col gap-2 sm:flex-row">
-		<div class="flex-1">
-			<DateInput
-				bind:value={iso}
-				bind:errorMessage={errorMessage}
-				bind:inputEl={inputEl}
-				name={name}
-				id={name}
-				placeholder="TT.MM.JJJJ"
-				ariaLabel={legend}
-				ariaDescribedby={errorMessage ? `${name}-error` : undefined}
-				class={controlCls}
-			/>
-			{#if errorMessage}
-				<p id="{name}-error" class="mt-1 font-sans text-xs text-red-600">{errorMessage}</p>
-			{/if}
-		</div>
-		<div class="flex-1">
-			<select
-				id="{name}Precision"
-				name="{name}Precision"
-				aria-label="{legend}: {precisionLabel}"
-				bind:value={precision}
-				class="{controlCls} bg-surface"
-			>
-				{#each PERSON_DATE_PRECISIONS as p (p.value)}
-					<option value={p.value}>{p.label()}</option>
-				{/each}
-			</select>
-		</div>
-	</div>
-	<p class="mt-1 font-sans text-xs text-ink-3">
-		{m.person_precision_hint()} · {m.person_date_placeholder_hint()}
-	</p>
-</fieldset>
+<DateInputWithPrecision
+	name={name}
+	legend={legend}
+	precisionLabel={precisionLabel}
+	precisions={precisions}
+	hint={hint}
+	initialIso={initialIso}
+	initialPrecision={initialPrecision}
+	selectClass="bg-surface"
+/>

frontend/src/lib/person/genealogy/StammbaumCard.svelte

@@ -4,6 +4,7 @@ import { m } from '$lib/paraglide/messages.js';
 import RelationshipChip from '$lib/person/relationship/RelationshipChip.svelte';
 import AddRelationshipForm from '$lib/person/relationship/AddRelationshipForm.svelte';
 import { chipLabel, otherName, inferredRelationshipLabel } from '$lib/person/relationshipLabels';
+import { formatRelationshipDateRange } from '$lib/person/relationshipDates';
 import type { components } from '$lib/generated/api';
 
 type RelationshipDTO = components['schemas']['RelationshipDTO'];
@@ -29,13 +30,15 @@ let {
 
 type RelationType = NonNullable<RelationshipDTO['relationType']>;
 
-const sortedDirect = $derived([...relationships].sort(byTypeThenYear));
+const sortedDirect = $derived([...relationships].sort(byTypeThenDate));
 const topDerived = $derived(inferredRelationships.slice(0, 5));
+let editingRelId = $state<string | null>(null);
 
-function byTypeThenYear(a: RelationshipDTO, b: RelationshipDTO): number {
+function byTypeThenDate(a: RelationshipDTO, b: RelationshipDTO): number {
 	const order = relationTypeOrder(a.relationType) - relationTypeOrder(b.relationType);
 	if (order !== 0) return order;
-	return (a.fromYear ?? 0) - (b.fromYear ?? 0);
+	// ISO dates sort lexicographically == chronologically; a missing date sorts first.
+	return (a.fromDate ?? '').localeCompare(b.fromDate ?? '');
 }
 
 function relationTypeOrder(t: RelationType | undefined): number {
@@ -53,13 +56,13 @@ function relationTypeOrder(t: RelationType | undefined): number {
 	return order[t ?? 'OTHER'] ?? 99;
 }
 
-function yearRange(rel: RelationshipDTO): string {
-	const from = rel.fromYear;
-	const to = rel.toYear;
-	if (from && to) return `${from}–${to}`;
-	if (from) return m.relation_year_from({ year: from });
-	if (to) return m.relation_year_to({ year: to });
-	return '';
+function dateRangeOf(rel: RelationshipDTO): string {
+	return formatRelationshipDateRange(
+		rel.fromDate,
+		rel.fromDatePrecision,
+		rel.toDate,
+		rel.toDatePrecision
+	);
 }
 </script>
 
@@ -132,10 +135,20 @@ function yearRange(rel: RelationshipDTO): string {
 				<RelationshipChip
 					chipLabel={chipLabel(rel, personId)}
 					otherName={otherName(rel, personId)}
-					yearRange={yearRange(rel)}
+					dateRange={dateRangeOf(rel)}
 					canWrite={canWrite}
 					relId={rel.id}
+					onEdit={canWrite ? () => (editingRelId = rel.id) : undefined}
 				/>
+				{#if editingRelId === rel.id}
+					<li>
+						<AddRelationshipForm
+							personId={personId}
+							relationship={rel}
+							onClose={() => (editingRelId = null)}
+						/>
+					</li>
+				{/if}
 			{/each}
 		</ul>
 	{/if}

frontend/src/lib/person/genealogy/StammbaumCard.svelte.test.ts

@@ -111,17 +111,21 @@ describe('StammbaumCard', () => {
 		expect(items.length).toBeGreaterThanOrEqual(2);
 	});
 
-	it('renders the year range "from–to" for a relationship with both years', async () => {
+	it('renders the date range "from – to" for a relationship with both dates', async () => {
 		render(StammbaumCard, {
 			props: baseProps({
 				relationships: [
 					{
 						id: 'r-1',
+						personId: 'p-1',
+						relatedPersonId: 'p-x',
+						personDisplayName: 'Anna',
+						relatedPersonDisplayName: 'Xavier',
 						relationType: 'COLLEAGUE',
-						fromYear: 1940,
-						toYear: 1945,
-						personA: { id: 'p-1', displayName: 'Anna' },
-						personB: { id: 'p-x', displayName: 'Xavier' }
+						fromDate: '1940-01-01',
+						fromDatePrecision: 'YEAR',
+						toDate: '1945-01-01',
+						toDatePrecision: 'YEAR'
 					}
 				]
 			})
@@ -131,23 +135,27 @@ describe('StammbaumCard', () => {
 		expect(document.body.textContent).toContain('1945');
 	});
 
-	it('renders only "fromYear" for a relationship with no end year', async () => {
+	it('renders only the start date for a relationship with no end date', async () => {
 		render(StammbaumCard, {
 			props: baseProps({
 				relationships: [
 					{
 						id: 'r-2',
+						personId: 'p-1',
+						relatedPersonId: 'p-y',
+						personDisplayName: 'Anna',
+						relatedPersonDisplayName: 'Yvonne',
 						relationType: 'NEIGHBOR',
-						fromYear: 1935,
-						personA: { id: 'p-1', displayName: 'Anna' },
-						personB: { id: 'p-y', displayName: 'Yvonne' }
+						fromDate: '1935-01-01',
+						fromDatePrecision: 'YEAR',
+						toDatePrecision: 'UNKNOWN'
 					}
 				]
 			})
 		});
 
 		expect(document.body.textContent).toContain('1935');
-		expect(document.body.textContent).not.toContain('1935–');
+		expect(document.body.textContent).not.toContain('1935 –');
 	});
 
 	it('renders the inferred-relationships disclosure when topDerived has items', async () => {

frontend/src/lib/person/genealogy/StammbaumConnectors.svelte

@@ -250,7 +250,7 @@ const parentLinks = $derived.by<ParentLinks>(() => {
 				y2={bCenter.y}
 				stroke="var(--c-primary)"
 				stroke-width="1.5"
-				stroke-dasharray={e.toYear ? '4 4' : undefined}
+				stroke-dasharray={e.toDate ? '4 4' : undefined}
 			/>
 			<circle
 				cx={(aCenter.x + bCenter.x) / 2}

frontend/src/lib/person/genealogy/StammbaumConnectors.svelte.test.ts

@@ -18,7 +18,9 @@ function parentEdge(parentId: string, childId: string): RelationshipDTO {
 		relatedPersonId: childId,
 		personDisplayName: '',
 		relatedPersonDisplayName: '',
-		relationType: 'PARENT_OF'
+		relationType: 'PARENT_OF',
+		fromDatePrecision: 'UNKNOWN',
+		toDatePrecision: 'UNKNOWN'
 	};
 }
 
@@ -30,7 +32,9 @@ function endedSpouseEdge(a: string, b: string): RelationshipDTO {
 		personDisplayName: '',
 		relatedPersonDisplayName: '',
 		relationType: 'SPOUSE_OF',
-		toYear: 1950
+		fromDatePrecision: 'UNKNOWN',
+		toDate: '1950-01-01',
+		toDatePrecision: 'YEAR'
 	};
 }
 

frontend/src/lib/person/genealogy/StammbaumSidePanel.svelte

@@ -54,12 +54,19 @@ async function loadFor(id: string) {
 }
 
 async function handleAddRelationship(data: RelFormData) {
-	const body: Record<string, string | number> = {
+	const body: Record<string, string> = {
 		relatedPersonId: data.relatedPersonId,
 		relationType: data.relationType
 	};
-	if (data.fromYear !== undefined) body.fromYear = data.fromYear;
-	if (data.toYear !== undefined) body.toYear = data.toYear;
+	if (data.fromDate) {
+		body.fromDate = data.fromDate;
+		if (data.fromDatePrecision) body.fromDatePrecision = data.fromDatePrecision;
+	}
+	if (data.toDate) {
+		body.toDate = data.toDate;
+		if (data.toDatePrecision) body.toDatePrecision = data.toDatePrecision;
+	}
+	if (data.notes) body.notes = data.notes;
 	const res = await csrfFetch(`/api/persons/${node.id}/relationships`, {
 		method: 'POST',
 		headers: { 'Content-Type': 'application/json' },

frontend/src/lib/person/genealogy/StammbaumSidePanel.svelte.spec.ts

@@ -72,20 +72,20 @@ describe('StammbaumSidePanel', () => {
 		await expect.element(page.getByText('Noch keine Beziehungen bekannt.')).toBeInTheDocument();
 	});
 
-	it('year inputs inside the add form have label elements (canWrite=true)', async () => {
+	it('date inputs inside the add form have accessible labels (canWrite=true)', async () => {
 		render(StammbaumSidePanel, { node: makeNode(), onClose: vi.fn(), canWrite: true });
 		await expect.element(page.getByText('Noch keine Beziehungen bekannt.')).toBeInTheDocument();
 		const addBtn = [...document.querySelectorAll<HTMLButtonElement>('button')].find((b) =>
 			/Beziehung hinzufügen/i.test(b.textContent ?? '')
 		);
 		addBtn!.click();
-		await expect.element(page.getByRole('combobox')).toBeInTheDocument();
-		const yearInputs = [...document.querySelectorAll('input')].filter(
+		await expect.element(page.getByRole('combobox', { name: 'Typ' })).toBeInTheDocument();
+		const dateInputs = [...document.querySelectorAll('input')].filter(
 			(i) => i.inputMode === 'numeric'
 		);
-		expect(yearInputs.length).toBeGreaterThan(0);
-		for (const input of yearInputs) {
-			expect(input.closest('label')).not.toBeNull();
+		expect(dateInputs.length).toBeGreaterThan(0);
+		for (const input of dateInputs) {
+			expect(input.getAttribute('aria-label')).toBeTruthy();
 		}
 	});
 

frontend/src/lib/person/genealogy/StammbaumTree.svelte.test.ts

@@ -3,6 +3,9 @@ import { render } from 'vitest-browser-svelte';
 import StammbaumTree from './StammbaumTree.svelte';
 import type { PanZoomState } from './panZoom';
 import { DIMMED_OPACITY } from './layout/highlightLineage';
+import type { components } from '$lib/generated/api';
+
+type RelationshipDTO = components['schemas']['RelationshipDTO'];
 
 const ID_A = '00000000-0000-0000-0000-000000000001';
 const ID_B = '00000000-0000-0000-0000-000000000002';
@@ -105,7 +108,9 @@ describe('StammbaumTree viewBox', () => {
 					relatedPersonId: PARENT_B,
 					personDisplayName: 'Walter',
 					relatedPersonDisplayName: 'Eugenie',
-					relationType: 'SPOUSE_OF'
+					relationType: 'SPOUSE_OF',
+					fromDatePrecision: 'UNKNOWN',
+					toDatePrecision: 'UNKNOWN'
 				},
 				{
 					id: 'p1a',
@@ -113,7 +118,9 @@ describe('StammbaumTree viewBox', () => {
 					relatedPersonId: CHILD_1,
 					personDisplayName: 'Walter',
 					relatedPersonDisplayName: 'Clara',
-					relationType: 'PARENT_OF'
+					relationType: 'PARENT_OF',
+					fromDatePrecision: 'UNKNOWN',
+					toDatePrecision: 'UNKNOWN'
 				},
 				{
 					id: 'p1b',
@@ -121,7 +128,9 @@ describe('StammbaumTree viewBox', () => {
 					relatedPersonId: CHILD_1,
 					personDisplayName: 'Eugenie',
 					relatedPersonDisplayName: 'Clara',
-					relationType: 'PARENT_OF'
+					relationType: 'PARENT_OF',
+					fromDatePrecision: 'UNKNOWN',
+					toDatePrecision: 'UNKNOWN'
 				},
 				{
 					id: 'p2a',
@@ -129,7 +138,9 @@ describe('StammbaumTree viewBox', () => {
 					relatedPersonId: CHILD_2,
 					personDisplayName: 'Walter',
 					relatedPersonDisplayName: 'Hans',
-					relationType: 'PARENT_OF'
+					relationType: 'PARENT_OF',
+					fromDatePrecision: 'UNKNOWN',
+					toDatePrecision: 'UNKNOWN'
 				},
 				{
 					id: 'p2b',
@@ -137,7 +148,9 @@ describe('StammbaumTree viewBox', () => {
 					relatedPersonId: CHILD_2,
 					personDisplayName: 'Eugenie',
 					relatedPersonDisplayName: 'Hans',
-					relationType: 'PARENT_OF'
+					relationType: 'PARENT_OF',
+					fromDatePrecision: 'UNKNOWN',
+					toDatePrecision: 'UNKNOWN'
 				}
 			],
 			selectedId: null,
@@ -181,7 +194,9 @@ describe('StammbaumTree viewBox', () => {
 					relatedPersonId: PARENT_B,
 					personDisplayName: 'Walter',
 					relatedPersonDisplayName: 'Eugenie',
-					relationType: 'SPOUSE_OF'
+					relationType: 'SPOUSE_OF',
+					fromDatePrecision: 'UNKNOWN',
+					toDatePrecision: 'UNKNOWN'
 				},
 				{
 					id: 'p1',
@@ -189,7 +204,9 @@ describe('StammbaumTree viewBox', () => {
 					relatedPersonId: CHILD,
 					personDisplayName: 'Walter',
 					relatedPersonDisplayName: 'Hans',
-					relationType: 'PARENT_OF'
+					relationType: 'PARENT_OF',
+					fromDatePrecision: 'UNKNOWN',
+					toDatePrecision: 'UNKNOWN'
 				},
 				{
 					id: 'p2',
@@ -197,7 +214,9 @@ describe('StammbaumTree viewBox', () => {
 					relatedPersonId: CHILD,
 					personDisplayName: 'Eugenie',
 					relatedPersonDisplayName: 'Hans',
-					relationType: 'PARENT_OF'
+					relationType: 'PARENT_OF',
+					fromDatePrecision: 'UNKNOWN',
+					toDatePrecision: 'UNKNOWN'
 				}
 			],
 			selectedId: null,
@@ -244,7 +263,9 @@ describe('StammbaumTree viewBox', () => {
 					relatedPersonId: EUGENIE,
 					personDisplayName: 'Walter',
 					relatedPersonDisplayName: 'Eugenie',
-					relationType: 'SPOUSE_OF'
+					relationType: 'SPOUSE_OF',
+					fromDatePrecision: 'UNKNOWN',
+					toDatePrecision: 'UNKNOWN'
 				},
 				{
 					id: 'p1',
@@ -252,7 +273,9 @@ describe('StammbaumTree viewBox', () => {
 					relatedPersonId: HANS,
 					personDisplayName: 'Walter',
 					relatedPersonDisplayName: 'Hans',
-					relationType: 'PARENT_OF'
+					relationType: 'PARENT_OF',
+					fromDatePrecision: 'UNKNOWN',
+					toDatePrecision: 'UNKNOWN'
 				},
 				{
 					id: 'p2',
@@ -260,7 +283,9 @@ describe('StammbaumTree viewBox', () => {
 					relatedPersonId: HANS,
 					personDisplayName: 'Eugenie',
 					relatedPersonDisplayName: 'Hans',
-					relationType: 'PARENT_OF'
+					relationType: 'PARENT_OF',
+					fromDatePrecision: 'UNKNOWN',
+					toDatePrecision: 'UNKNOWN'
 				},
 				{
 					id: 'p3',
@@ -268,7 +293,9 @@ describe('StammbaumTree viewBox', () => {
 					relatedPersonId: CLARA,
 					personDisplayName: 'Walter',
 					relatedPersonDisplayName: 'Clara',
-					relationType: 'PARENT_OF'
+					relationType: 'PARENT_OF',
+					fromDatePrecision: 'UNKNOWN',
+					toDatePrecision: 'UNKNOWN'
 				},
 				{
 					id: 'p4',
@@ -276,7 +303,9 @@ describe('StammbaumTree viewBox', () => {
 					relatedPersonId: CLARA,
 					personDisplayName: 'Eugenie',
 					relatedPersonDisplayName: 'Clara',
-					relationType: 'PARENT_OF'
+					relationType: 'PARENT_OF',
+					fromDatePrecision: 'UNKNOWN',
+					toDatePrecision: 'UNKNOWN'
 				},
 				{
 					id: 's2',
@@ -284,7 +313,9 @@ describe('StammbaumTree viewBox', () => {
 					relatedPersonId: HILDE,
 					personDisplayName: 'Hans',
 					relatedPersonDisplayName: 'Hilde',
-					relationType: 'SPOUSE_OF'
+					relationType: 'SPOUSE_OF',
+					fromDatePrecision: 'UNKNOWN',
+					toDatePrecision: 'UNKNOWN'
 				},
 				{
 					id: 'p5',
@@ -292,7 +323,9 @@ describe('StammbaumTree viewBox', () => {
 					relatedPersonId: LILI,
 					personDisplayName: 'Hans',
 					relatedPersonDisplayName: 'Lili',
-					relationType: 'PARENT_OF'
+					relationType: 'PARENT_OF',
+					fromDatePrecision: 'UNKNOWN',
+					toDatePrecision: 'UNKNOWN'
 				},
 				{
 					id: 'p6',
@@ -300,7 +333,9 @@ describe('StammbaumTree viewBox', () => {
 					relatedPersonId: LILI,
 					personDisplayName: 'Hilde',
 					relatedPersonDisplayName: 'Lili',
-					relationType: 'PARENT_OF'
+					relationType: 'PARENT_OF',
+					fromDatePrecision: 'UNKNOWN',
+					toDatePrecision: 'UNKNOWN'
 				}
 			],
 			selectedId: null,
@@ -358,7 +393,9 @@ describe('StammbaumTree viewBox', () => {
 					relatedPersonId: ID_B,
 					personDisplayName: 'Anna',
 					relatedPersonDisplayName: 'Bertha',
-					relationType: 'SPOUSE_OF'
+					relationType: 'SPOUSE_OF',
+					fromDatePrecision: 'UNKNOWN',
+					toDatePrecision: 'UNKNOWN'
 				}
 			],
 			selectedId: null,
@@ -391,7 +428,9 @@ describe('StammbaumTree viewBox', () => {
 					relatedPersonId: ID_B,
 					personDisplayName: 'Anna',
 					relatedPersonDisplayName: 'Bertha',
-					relationType: 'SPOUSE_OF'
+					relationType: 'SPOUSE_OF',
+					fromDatePrecision: 'UNKNOWN',
+					toDatePrecision: 'UNKNOWN'
 				}
 			],
 			selectedId: null,
@@ -599,7 +638,9 @@ describe('StammbaumTree keyboard pan/zoom (#692)', () => {
 					relatedPersonId: ID_B,
 					personDisplayName: 'Anna',
 					relatedPersonDisplayName: 'Bertha',
-					relationType: 'SPOUSE_OF'
+					relationType: 'SPOUSE_OF',
+					fromDatePrecision: 'UNKNOWN',
+					toDatePrecision: 'UNKNOWN'
 				}
 			],
 			selectedId: null,
@@ -668,7 +709,9 @@ describe('StammbaumTree keyboard pan/zoom (#692)', () => {
 					personDisplayName: 'Anna',
 					relatedPersonDisplayName: 'Bertha',
 					relationType: 'SPOUSE_OF',
-					toYear: 1925
+					fromDatePrecision: 'UNKNOWN',
+					toDate: '1925-01-01',
+					toDatePrecision: 'YEAR'
 				}
 			],
 			selectedId: null,
@@ -695,7 +738,9 @@ describe('StammbaumTree keyboard pan/zoom (#692)', () => {
 					relatedPersonId: ID_B,
 					personDisplayName: 'Anna',
 					relatedPersonDisplayName: 'Bertha',
-					relationType: 'SPOUSE_OF'
+					relationType: 'SPOUSE_OF',
+					fromDatePrecision: 'UNKNOWN',
+					toDatePrecision: 'UNKNOWN'
 				}
 			],
 			selectedId: null,
@@ -723,7 +768,9 @@ describe('StammbaumTree keyboard pan/zoom (#692)', () => {
 					relatedPersonId: CHILD,
 					personDisplayName: 'Parent',
 					relatedPersonDisplayName: 'Child',
-					relationType: 'PARENT_OF'
+					relationType: 'PARENT_OF',
+					fromDatePrecision: 'UNKNOWN',
+					toDatePrecision: 'UNKNOWN'
 				}
 			],
 			selectedId: null,
@@ -908,6 +955,8 @@ describe('StammbaumTree lineage highlight (#703)', () => {
 		personDisplayName: string;
 		relatedPersonDisplayName: string;
 		relationType: 'PARENT_OF' | 'SPOUSE_OF';
+		fromDatePrecision: 'UNKNOWN';
+		toDatePrecision: 'UNKNOWN';
 	};
 	const edge = (
 		personId: string,
@@ -919,7 +968,9 @@ describe('StammbaumTree lineage highlight (#703)', () => {
 		relatedPersonId,
 		personDisplayName: '',
 		relatedPersonDisplayName: '',
-		relationType
+		relationType,
+		fromDatePrecision: 'UNKNOWN',
+		toDatePrecision: 'UNKNOWN'
 	});
 
 	const NODES = [
@@ -1104,14 +1155,16 @@ describe('StammbaumTree keyboard tab order (#718)', () => {
 	// year, then a deterministic id tie-break), not alphabetically — with no birth
 	// years here Walter (id …a1) owns the run and Eugenie sits to his right. So the
 	// deterministic visual order is Walter, Eugenie (top row) then Clara, Hans.
-	const FAMILY_EDGES = [
+	const FAMILY_EDGES: RelationshipDTO[] = [
 		{
 			id: 'sp',
 			personId: WALTER,
 			relatedPersonId: EUGENIE,
 			personDisplayName: 'Walter',
 			relatedPersonDisplayName: 'Eugenie',
-			relationType: 'SPOUSE_OF'
+			relationType: 'SPOUSE_OF',
+			fromDatePrecision: 'UNKNOWN',
+			toDatePrecision: 'UNKNOWN'
 		},
 		{
 			id: 'p1',
@@ -1119,7 +1172,9 @@ describe('StammbaumTree keyboard tab order (#718)', () => {
 			relatedPersonId: CLARA,
 			personDisplayName: 'Walter',
 			relatedPersonDisplayName: 'Clara',
-			relationType: 'PARENT_OF'
+			relationType: 'PARENT_OF',
+			fromDatePrecision: 'UNKNOWN',
+			toDatePrecision: 'UNKNOWN'
 		},
 		{
 			id: 'p2',
@@ -1127,7 +1182,9 @@ describe('StammbaumTree keyboard tab order (#718)', () => {
 			relatedPersonId: CLARA,
 			personDisplayName: 'Eugenie',
 			relatedPersonDisplayName: 'Clara',
-			relationType: 'PARENT_OF'
+			relationType: 'PARENT_OF',
+			fromDatePrecision: 'UNKNOWN',
+			toDatePrecision: 'UNKNOWN'
 		},
 		{
 			id: 'p3',
@@ -1135,7 +1192,9 @@ describe('StammbaumTree keyboard tab order (#718)', () => {
 			relatedPersonId: HANS,
 			personDisplayName: 'Walter',
 			relatedPersonDisplayName: 'Hans',
-			relationType: 'PARENT_OF'
+			relationType: 'PARENT_OF',
+			fromDatePrecision: 'UNKNOWN',
+			toDatePrecision: 'UNKNOWN'
 		},
 		{
 			id: 'p4',
@@ -1143,7 +1202,9 @@ describe('StammbaumTree keyboard tab order (#718)', () => {
 			relatedPersonId: HANS,
 			personDisplayName: 'Eugenie',
 			relatedPersonDisplayName: 'Hans',
-			relationType: 'PARENT_OF'
+			relationType: 'PARENT_OF',
+			fromDatePrecision: 'UNKNOWN',
+			toDatePrecision: 'UNKNOWN'
 		}
 	];
 

frontend/src/lib/person/genealogy/layout/buildLayout.test.ts

@@ -42,7 +42,9 @@ function parentEdge(parentId: string, childId: string, id = parentId + childId):
 		relatedPersonId: childId,
 		personDisplayName: '',
 		relatedPersonDisplayName: '',
-		relationType: 'PARENT_OF'
+		relationType: 'PARENT_OF',
+		fromDatePrecision: 'UNKNOWN',
+		toDatePrecision: 'UNKNOWN'
 	};
 }
 
@@ -53,7 +55,9 @@ function spouseEdge(a: string, b: string, id = a + b): RelationshipDTO {
 		relatedPersonId: b,
 		personDisplayName: '',
 		relatedPersonDisplayName: '',
-		relationType: 'SPOUSE_OF'
+		relationType: 'SPOUSE_OF',
+		fromDatePrecision: 'UNKNOWN',
+		toDatePrecision: 'UNKNOWN'
 	};
 }
 
@@ -220,7 +224,10 @@ describe('buildLayout — multi-spouse ordering (#361)', () => {
 		fromYear: number | undefined,
 		id = a + b
 	): RelationshipDTO {
-		return { ...spouseEdge(a, b, id), fromYear };
+		return {
+			...spouseEdge(a, b, id),
+			...(fromYear != null ? { fromDate: `${fromYear}-01-01`, fromDatePrecision: 'YEAR' } : {})
+		};
 	}
 
 	it('multi_spouses_ordered_by_fromYear_then_displayName', () => {
@@ -329,7 +336,7 @@ describe('buildLayout — multi-spouse ordering (#361)', () => {
 		// fail fast instead so the maintainer either updates the test or
 		// splits into a year-branch / name-branch pair.
 		const spouseEdgesWithYear = fixtureEdges.filter(
-			(e) => e.relationType === 'SPOUSE_OF' && e.fromYear != null
+			(e) => e.relationType === 'SPOUSE_OF' && e.fromDate != null
 		);
 		expect(
 			spouseEdgesWithYear,

frontend/src/lib/person/genealogy/layout/familyForest.test.ts

@@ -21,7 +21,9 @@ function parent(p: string, c: string): RelationshipDTO {
 		relatedPersonId: c,
 		personDisplayName: '',
 		relatedPersonDisplayName: '',
-		relationType: 'PARENT_OF'
+		relationType: 'PARENT_OF',
+		fromDatePrecision: 'UNKNOWN',
+		toDatePrecision: 'UNKNOWN'
 	};
 }
 
@@ -33,7 +35,9 @@ function spouse(a: string, b: string, fromYear?: number): RelationshipDTO {
 		personDisplayName: '',
 		relatedPersonDisplayName: '',
 		relationType: 'SPOUSE_OF',
-		...(fromYear != null ? { fromYear } : {})
+		fromDatePrecision: 'UNKNOWN',
+		toDatePrecision: 'UNKNOWN',
+		...(fromYear != null ? { fromDate: `${fromYear}-01-01`, fromDatePrecision: 'YEAR' } : {})
 	};
 }
 

frontend/src/lib/person/genealogy/layout/familyForest.ts

@@ -82,7 +82,10 @@ export function buildFamilyForest(nodes: PersonNodeDTO[], edges: RelationshipDTO
 		} else if (e.relationType === 'SPOUSE_OF') {
 			addToSet(spouses, e.personId, e.relatedPersonId);
 			addToSet(spouses, e.relatedPersonId, e.personId);
-			spouseYear.set(pairKey(e.personId, e.relatedPersonId), e.fromYear ?? undefined);
+			spouseYear.set(
+				pairKey(e.personId, e.relatedPersonId),
+				e.fromDate ? Number(e.fromDate.slice(0, 4)) : undefined
+			);
 		}
 	}
 

frontend/src/lib/person/genealogy/layout/highlightLineage.test.ts

@@ -13,7 +13,9 @@ function parentEdge(parentId: string, childId: string, id = parentId + childId):
 		relatedPersonId: childId,
 		personDisplayName: '',
 		relatedPersonDisplayName: '',
-		relationType: 'PARENT_OF'
+		relationType: 'PARENT_OF',
+		fromDatePrecision: 'UNKNOWN',
+		toDatePrecision: 'UNKNOWN'
 	};
 }
 
@@ -24,7 +26,9 @@ function spouseEdge(a: string, b: string, id = a + b): RelationshipDTO {
 		relatedPersonId: b,
 		personDisplayName: '',
 		relatedPersonDisplayName: '',
-		relationType: 'SPOUSE_OF'
+		relationType: 'SPOUSE_OF',
+		fromDatePrecision: 'UNKNOWN',
+		toDatePrecision: 'UNKNOWN'
 	};
 }
 
@@ -35,7 +39,9 @@ function siblingEdge(a: string, b: string, id = a + b): RelationshipDTO {
 		relatedPersonId: b,
 		personDisplayName: '',
 		relatedPersonDisplayName: '',
-		relationType: 'SIBLING_OF'
+		relationType: 'SIBLING_OF',
+		fromDatePrecision: 'UNKNOWN',
+		toDatePrecision: 'UNKNOWN'
 	};
 }
 

frontend/src/lib/person/personLifeDates.ts

@@ -1,23 +1,17 @@
-import { formatDocumentDate, type DatePrecision } from '$lib/shared/utils/documentDate';
+import { formatDatePart, type DatePrecision } from '$lib/shared/utils/documentDate';
 
 /**
- * Formats one life date (birth or death) at the precision the data claims,
- * delegating all rendering to {@link formatDocumentDate}. Returns '' for a
- * missing date. Carries no * / † glyph — components that need the glyphs wrap
- * them in their own `aria-hidden` markup so screen readers only hear the date.
- *
- * A missing precision falls back to YEAR: pre-V76 rows only knew a year, and
- * a bare year is the only safe rendering for a date without precision metadata.
+ * Formats one life date (birth or death) at the precision the data claims.
+ * Thin domain alias over the shared {@link formatDatePart}: carries no * / †
+ * glyph — components that need the glyphs wrap them in their own `aria-hidden`
+ * markup so screen readers only hear the date.
  */
 export function formatLifeDate(
 	date: string | null | undefined,
 	precision: DatePrecision | null | undefined,
 	locale?: string
 ): string {
-	if (!date) {
-		return '';
-	}
-	return formatDocumentDate(date, precision ?? 'YEAR', null, null, locale);
+	return formatDatePart(date, precision, locale);
 }
 
 /**

frontend/src/lib/person/relationship/AddRelationshipForm.svelte

@@ -1,8 +1,11 @@
 <script lang="ts">
+import { onMount } from 'svelte';
 import { enhance } from '$app/forms';
 import { m } from '$lib/paraglide/messages.js';
 import PersonTypeahead from '$lib/person/PersonTypeahead.svelte';
+import RelationshipDateField from '$lib/person/relationship/RelationshipDateField.svelte';
 import type { components } from '$lib/generated/api';
+import type { DatePrecision } from '$lib/shared/utils/documentDate';
 
 type RelationshipDTO = components['schemas']['RelationshipDTO'];
 type RelationType = NonNullable<RelationshipDTO['relationType']>;
@@ -10,71 +13,96 @@ type RelationType = NonNullable<RelationshipDTO['relationType']>;
 export type RelFormData = {
 	relatedPersonId: string;
 	relationType: RelationType;
-	fromYear?: number;
-	toYear?: number;
+	fromDate?: string;
+	fromDatePrecision?: DatePrecision;
+	toDate?: string;
+	toDatePrecision?: DatePrecision;
+	notes?: string;
 };
 
 interface Props {
 	personId: string;
+	// When present the form is an EDIT: pre-filled and posting to ?/updateRelationship.
+	relationship?: RelationshipDTO;
 	onSubmit?: (data: RelFormData) => Promise<void>;
+	onClose?: () => void;
 }
 
-let { personId, onSubmit }: Props = $props();
+let { personId, relationship, onSubmit, onClose }: Props = $props();
+
+const isEdit = $derived(relationship != null);
 
 let open = $state(false);
 let addType = $state<RelationType>('PARENT_OF');
 let addRelatedPersonId = $state('');
 let addRelatedPersonName = $state('');
-let addFromYear = $state('');
-let addToYear = $state('');
+let notes = $state('');
 let callbackError = $state<string | null>(null);
+let submitting = $state(false);
 
-const yearError = $derived.by(() => {
-	const from = addFromYear.trim();
-	const to = addToYear.trim();
-	if (!from || !to) return null;
-	const fromInt = parseInt(from, 10);
-	const toInt = parseInt(to, 10);
-	if (Number.isNaN(fromInt) || Number.isNaN(toInt)) return null;
-	return toInt < fromInt ? m.relation_year_error_bis_before_von() : null;
+// Seed once at mount (reading props in a closure avoids state_referenced_locally).
+// The parent re-creates this form per edited row, so the relationship never
+// changes under a live instance.
+onMount(() => {
+	if (!relationship) return;
+	open = true;
+	addType = relationship.relationType ?? 'PARENT_OF';
+	const viewpointIsSubject = relationship.personId === personId;
+	addRelatedPersonId =
+		(viewpointIsSubject ? relationship.relatedPersonId : relationship.personId) ?? '';
+	addRelatedPersonName =
+		(viewpointIsSubject ? relationship.relatedPersonDisplayName : relationship.personDisplayName) ??
+		'';
+	notes = relationship.notes ?? '';
 });
 
 const selfError = $derived(
 	addRelatedPersonId !== '' && addRelatedPersonId === personId ? m.relation_error_self() : null
 );
 
-const submitDisabled = $derived(
-	yearError !== null || selfError !== null || addRelatedPersonId === ''
-);
+const submitDisabled = $derived(selfError !== null || addRelatedPersonId === '');
 
 function reset() {
 	addType = 'PARENT_OF';
 	addRelatedPersonId = '';
 	addRelatedPersonName = '';
-	addFromYear = '';
-	addToYear = '';
+	notes = '';
 	callbackError = null;
 }
 
 function cancel() {
+	if (isEdit) {
+		onClose?.();
+		return;
+	}
 	open = false;
 	reset();
 }
 
-async function handleCallbackSubmit(event: Event) {
+async function handleCallbackSubmit(event: SubmitEvent) {
 	event.preventDefault();
 	if (submitDisabled || !onSubmit) return;
-	const data: RelFormData = { relatedPersonId: addRelatedPersonId, relationType: addType };
-	const from = parseInt(addFromYear.trim(), 10);
-	if (!Number.isNaN(from)) data.fromYear = from;
-	const to = parseInt(addToYear.trim(), 10);
-	if (!Number.isNaN(to)) data.toYear = to;
+	const fd = new FormData(event.currentTarget as HTMLFormElement);
+	const fromDate = (fd.get('fromDate') as string) || undefined;
+	const toDate = (fd.get('toDate') as string) || undefined;
+	const data: RelFormData = {
+		relatedPersonId: addRelatedPersonId,
+		relationType: addType,
+		fromDate,
+		fromDatePrecision: fromDate ? (fd.get('fromDatePrecision') as DatePrecision) : undefined,
+		toDate,
+		toDatePrecision: toDate ? (fd.get('toDatePrecision') as DatePrecision) : undefined,
+		notes: (fd.get('notes') as string)?.trim() || undefined
+	};
+	submitting = true;
 	try {
 		await onSubmit(data);
 		open = false;
 		reset();
 	} catch {
 		callbackError = m.error_internal_error();
+	} finally {
+		submitting = false;
 	}
 }
 </script>
@@ -113,39 +141,32 @@ async function handleCallbackSubmit(event: Event) {
 				compact
 			/>
 		</div>
-		<label class="block">
-			<span class="font-sans text-xs font-medium text-ink-2"
-				>{m.relation_form_field_from_year()}</span
-			>
-			<input
-				type="text"
-				name="fromYear"
-				inputmode="numeric"
-				pattern="[0-9]*"
-				bind:value={addFromYear}
-				placeholder={m.relation_form_year_placeholder()}
-				class="mt-1 block w-full rounded-sm border border-line bg-surface px-2 py-1.5 text-sm text-ink focus:border-primary focus:outline-none"
-			/>
-		</label>
-		<label class="block">
-			<span class="font-sans text-xs font-medium text-ink-2">{m.relation_form_field_to_year()}</span
-			>
-			<input
-				type="text"
-				name="toYear"
-				inputmode="numeric"
-				pattern="[0-9]*"
-				bind:value={addToYear}
-				aria-describedby={yearError ? 'add-rel-year-error' : undefined}
-				class="mt-1 block w-full rounded-sm border border-line bg-surface px-2 py-1.5 text-sm text-ink focus:border-primary focus:outline-none"
-			/>
-			{#if yearError}
-				<p id="add-rel-year-error" class="mt-1 text-xs text-red-700" role="alert">
-					{yearError}
-				</p>
-			{/if}
-		</label>
 	</div>
+	<div class="mt-3 grid gap-3 md:grid-cols-2">
+		<RelationshipDateField
+			name="fromDate"
+			legend={m.relation_label_from_date()}
+			initialIso={relationship?.fromDate ?? ''}
+			initialPrecision={relationship?.fromDatePrecision ?? null}
+		/>
+		<RelationshipDateField
+			name="toDate"
+			legend={m.relation_label_to_date()}
+			initialIso={relationship?.toDate ?? ''}
+			initialPrecision={relationship?.toDatePrecision ?? null}
+		/>
+	</div>
+	<label class="mt-3 block">
+		<span class="font-sans text-xs font-medium text-ink-2">{m.relation_label_notes()}</span>
+		<textarea
+			name="notes"
+			maxlength="2000"
+			rows="2"
+			bind:value={notes}
+			placeholder={m.relation_notes_placeholder()}
+			class="mt-1 block w-full rounded-sm border border-line bg-surface px-2 py-1.5 font-serif text-sm text-ink-3 focus:border-primary focus:outline-none"
+		></textarea>
+	</label>
 	{#if selfError}
 		<p class="mt-2 text-xs text-red-700" role="alert">{selfError}</p>
 	{/if}
@@ -162,10 +183,18 @@ async function handleCallbackSubmit(event: Event) {
 		</button>
 		<button
 			type="submit"
-			disabled={submitDisabled}
-			class="rounded-sm bg-primary px-3 py-1.5 font-sans text-xs font-medium text-primary-fg transition hover:bg-primary/80 disabled:opacity-40"
+			disabled={submitDisabled || submitting}
+			aria-busy={submitting}
+			class="inline-flex items-center gap-1.5 rounded-sm bg-primary px-3 py-1.5 font-sans text-xs font-medium text-primary-fg transition hover:bg-primary/80 disabled:opacity-40"
 		>
-			{m.relation_btn_add()}
+			{#if submitting}
+				<span
+					class="h-3 w-3 animate-spin rounded-full border-2 border-primary-fg/40 border-t-primary-fg"
+					data-testid="submit-spinner"
+					aria-hidden="true"
+				></span>
+			{/if}
+			{isEdit ? m.relation_btn_save() : m.relation_btn_add()}
 		</button>
 	</div>
 {/snippet}
@@ -185,18 +214,27 @@ async function handleCallbackSubmit(event: Event) {
 {:else}
 	<form
 		method="POST"
-		action="?/addRelationship"
+		action={isEdit ? '?/updateRelationship' : '?/addRelationship'}
 		use:enhance={() => {
+			submitting = true;
 			return async ({ result, update }) => {
 				await update();
+				submitting = false;
 				if (result.type === 'success') {
-					open = false;
-					reset();
+					if (isEdit) {
+						onClose?.();
+					} else {
+						open = false;
+						reset();
+					}
 				}
 			};
 		}}
 		class="mt-3 rounded-sm border border-line bg-muted/40 p-3"
 	>
+		{#if relationship}
+			<input type="hidden" name="relId" value={relationship.id} />
+		{/if}
 		{@render formFields()}
 	</form>
 {/if}

frontend/src/lib/person/relationship/AddRelationshipForm.svelte.spec.ts

@@ -8,58 +8,116 @@ vi.mock('$lib/person/PersonTypeahead.svelte', () => ({ default: () => null }));
 
 afterEach(cleanup);
 
-describe('AddRelationshipForm', () => {
-	it('shows add-relationship button initially and no form', async () => {
-		render(AddRelationshipForm, { personId: 'person-1' });
+const PID = 'person-1';
+const OTHER = 'person-2';
+
+const editRel = () => ({
+	id: 'rel-9',
+	personId: PID,
+	relatedPersonId: OTHER,
+	personDisplayName: 'Anna Müller',
+	relatedPersonDisplayName: 'Hans Müller',
+	relationType: 'SPOUSE_OF' as const,
+	fromDate: '1923-05-12',
+	fromDatePrecision: 'DAY' as const,
+	toDatePrecision: 'UNKNOWN' as const,
+	notes: 'Hochzeit in Berlin'
+});
+
+describe('AddRelationshipForm — create mode', () => {
+	it('shows the add-relationship toggle initially and no form', async () => {
+		render(AddRelationshipForm, { personId: PID });
 		await expect.element(page.getByRole('button')).toBeInTheDocument();
-		await expect.element(page.getByRole('combobox')).not.toBeInTheDocument();
+		expect(document.querySelector('select[name="relationType"]')).toBeNull();
 	});
 
-	it('shows relationType select when add button is clicked', async () => {
-		render(AddRelationshipForm, { personId: 'person-1' });
+	it('shows the relationType select when the add toggle is clicked', async () => {
+		render(AddRelationshipForm, { personId: PID });
 		document.querySelector<HTMLButtonElement>('button')!.click();
-		await expect.element(page.getByRole('combobox')).toBeInTheDocument();
+		await expect.element(page.getByRole('combobox', { name: 'Typ' })).toBeInTheDocument();
 	});
 
-	it('hides form and shows button when cancel is clicked', async () => {
-		render(AddRelationshipForm, { personId: 'person-1' });
+	it('hides the form and shows the toggle again on cancel', async () => {
+		render(AddRelationshipForm, { personId: PID });
 		document.querySelector<HTMLButtonElement>('button')!.click();
-		await expect.element(page.getByRole('combobox')).toBeInTheDocument();
+		await expect.element(page.getByRole('combobox', { name: 'Typ' })).toBeInTheDocument();
 		const cancelBtn = [...document.querySelectorAll<HTMLButtonElement>('button')].find(
 			(b) => b.type === 'button' && /abbrechen/i.test(b.textContent ?? '')
 		);
 		cancelBtn!.click();
-		await expect.element(page.getByRole('combobox')).not.toBeInTheDocument();
+		await vi.waitFor(() =>
+			expect(document.querySelector('select[name="relationType"]')).toBeNull()
+		);
 	});
 
-	it('submit is disabled when no person is selected', async () => {
-		render(AddRelationshipForm, { personId: 'person-1' });
+	it('disables submit when no person is selected', async () => {
+		render(AddRelationshipForm, { personId: PID });
 		document.querySelector<HTMLButtonElement>('button')!.click();
 		await expect.element(page.getByRole('button', { name: /^Hinzufügen$/i })).toBeDisabled();
 	});
 
-	it('form has no server action when onSubmit prop is provided', async () => {
+	it('has no server action when an onSubmit prop is provided', async () => {
 		const onSubmit = vi.fn().mockResolvedValue(undefined);
-		render(AddRelationshipForm, { personId: 'person-1', onSubmit });
+		render(AddRelationshipForm, { personId: PID, onSubmit });
 		document.querySelector<HTMLButtonElement>('button')!.click();
-		await expect.element(page.getByRole('combobox')).toBeInTheDocument();
-		const form = document.querySelector('form');
-		expect(form?.hasAttribute('action')).toBe(false);
-	});
-
-	it('shows year-range error when toYear is before fromYear', async () => {
-		render(AddRelationshipForm, { personId: 'person-1' });
-		document.querySelector<HTMLButtonElement>('button')!.click();
-		await expect.element(page.getByRole('combobox')).toBeInTheDocument();
-
-		const fromInput = document.querySelector<HTMLInputElement>('input[name="fromYear"]')!;
-		fromInput.value = '1935';
-		fromInput.dispatchEvent(new InputEvent('input', { bubbles: true }));
-
-		const toInput = document.querySelector<HTMLInputElement>('input[name="toYear"]')!;
-		toInput.value = '1920';
-		toInput.dispatchEvent(new InputEvent('input', { bubbles: true }));
-
-		await expect.element(page.getByRole('alert')).toBeVisible();
+		await expect.element(page.getByRole('combobox', { name: 'Typ' })).toBeInTheDocument();
+		expect(document.querySelector('form')?.hasAttribute('action')).toBe(false);
+	});
+});
+
+describe('AddRelationshipForm — edit mode', () => {
+	it('opens pre-filled and labels the submit "Speichern"', async () => {
+		render(AddRelationshipForm, { personId: PID, relationship: editRel() });
+		await expect.element(page.getByRole('button', { name: /^Speichern$/i })).toBeInTheDocument();
+	});
+
+	it('pre-fills the from-date as dd.mm.yyyy', async () => {
+		render(AddRelationshipForm, { personId: PID, relationship: editRel() });
+		await expect.element(page.getByRole('combobox', { name: 'Typ' })).toBeInTheDocument();
+		const fromInput = document.querySelector<HTMLInputElement>('#fromDate')!;
+		await vi.waitFor(() => expect(fromInput.value).toBe('12.05.1923'));
+	});
+
+	it('round-trips the notes into the textarea', async () => {
+		render(AddRelationshipForm, { personId: PID, relationship: editRel() });
+		await expect.element(page.getByRole('combobox', { name: 'Typ' })).toBeInTheDocument();
+		const notes = document.querySelector<HTMLTextAreaElement>('textarea[name="notes"]')!;
+		await vi.waitFor(() => expect(notes.value).toBe('Hochzeit in Berlin'));
+	});
+
+	it('offers only DAY/MONTH/YEAR in each precision select', async () => {
+		render(AddRelationshipForm, { personId: PID, relationship: editRel() });
+		await expect.element(page.getByRole('combobox', { name: 'Typ' })).toBeInTheDocument();
+		const options = [
+			...document.querySelectorAll<HTMLOptionElement>('#fromDatePrecision option')
+		].map((o) => o.value);
+		expect(options).toEqual(['DAY', 'MONTH', 'YEAR']);
+	});
+
+	it('gives each date input an associated label (accessible name)', async () => {
+		render(AddRelationshipForm, { personId: PID, relationship: editRel() });
+		await expect.element(page.getByRole('combobox', { name: 'Typ' })).toBeInTheDocument();
+		expect(document.querySelector('#fromDate')?.getAttribute('aria-label')).toBe('Beginn (Datum)');
+		expect(document.querySelector('#toDate')?.getAttribute('aria-label')).toBe('Ende (Datum)');
+	});
+
+	it('disables the submit and shows a progress spinner while a submit is in flight', async () => {
+		let resolve: () => void = () => {};
+		const onSubmit = vi.fn(() => new Promise<void>((r) => (resolve = r)));
+		render(AddRelationshipForm, { personId: PID, relationship: editRel(), onSubmit });
+
+		const submit = await vi.waitFor(() => {
+			const b = [...document.querySelectorAll<HTMLButtonElement>('button')].find(
+				(x) => x.type === 'submit'
+			);
+			if (!b) throw new Error('submit not ready');
+			return b;
+		});
+		submit.click();
+
+		await expect.element(page.getByTestId('submit-spinner')).toBeInTheDocument();
+		await vi.waitFor(() => expect(submit.disabled).toBe(true));
+		expect(onSubmit).toHaveBeenCalledOnce();
+		resolve();
 	});
 });

frontend/src/lib/person/relationship/AddRelationshipForm.svelte.test.ts

@@ -33,36 +33,6 @@ describe('AddRelationshipForm', () => {
 		expect(optionValues).toContain('OTHER');
 	});
 
-	it('shows the year-error alert when toYear is before fromYear', async () => {
-		render(AddRelationshipForm, { props: { personId: 'p-1' } });
-
-		await page.getByRole('button', { name: /hinzufügen/i }).click();
-
-		const fromInput = document.querySelector('input[name="fromYear"]') as HTMLInputElement;
-		const toInput = document.querySelector('input[name="toYear"]') as HTMLInputElement;
-		fromInput.value = '1923';
-		fromInput.dispatchEvent(new Event('input', { bubbles: true }));
-		toInput.value = '1920';
-		toInput.dispatchEvent(new Event('input', { bubbles: true }));
-
-		await expect.element(page.getByText(/bis-jahr darf nicht vor von-jahr/i)).toBeVisible();
-	});
-
-	it('does not show the year-error when toYear equals fromYear', async () => {
-		render(AddRelationshipForm, { props: { personId: 'p-1' } });
-
-		await page.getByRole('button', { name: /hinzufügen/i }).click();
-
-		const fromInput = document.querySelector('input[name="fromYear"]') as HTMLInputElement;
-		const toInput = document.querySelector('input[name="toYear"]') as HTMLInputElement;
-		fromInput.value = '1923';
-		fromInput.dispatchEvent(new Event('input', { bubbles: true }));
-		toInput.value = '1923';
-		toInput.dispatchEvent(new Event('input', { bubbles: true }));
-
-		await expect.element(page.getByText(/bis-jahr darf nicht/i)).not.toBeInTheDocument();
-	});
-
 	it('cancel button closes the form', async () => {
 		render(AddRelationshipForm, { props: { personId: 'p-1' } });
 
@@ -136,25 +106,4 @@ describe('AddRelationshipForm', () => {
 			expect(submitBtn!.disabled).toBe(true);
 		});
 	});
-
-	it('keeps submit disabled when there is a yearError', async () => {
-		render(AddRelationshipForm, { props: { personId: 'p-1' } });
-
-		await page.getByRole('button', { name: /hinzufügen/i }).click();
-
-		const fromInput = document.querySelector('input[name="fromYear"]') as HTMLInputElement;
-		const toInput = document.querySelector('input[name="toYear"]') as HTMLInputElement;
-		const relInput = document.querySelector('input[name="relatedPersonId"]') as HTMLInputElement;
-		fromInput.value = '1923';
-		fromInput.dispatchEvent(new Event('input', { bubbles: true }));
-		toInput.value = '1920';
-		toInput.dispatchEvent(new Event('input', { bubbles: true }));
-		relInput.value = 'p-other';
-		relInput.dispatchEvent(new Event('input', { bubbles: true }));
-
-		await vi.waitFor(() => {
-			const submitBtn = document.querySelector('button[type="submit"]') as HTMLButtonElement;
-			expect(submitBtn.disabled).toBe(true);
-		});
-	});
 });

frontend/src/lib/person/relationship/RelationshipChip.svelte

@@ -5,12 +5,13 @@ import { m } from '$lib/paraglide/messages.js';
 interface Props {
 	chipLabel: string;
 	otherName: string;
-	yearRange?: string;
+	dateRange?: string;
 	canWrite: boolean;
 	relId: string;
+	onEdit?: () => void;
 }
 
-let { chipLabel, otherName, yearRange = '', canWrite, relId }: Props = $props();
+let { chipLabel, otherName, dateRange = '', canWrite, relId, onEdit }: Props = $props();
 </script>
 
 <li class="flex items-center gap-2 py-2">
@@ -22,8 +23,31 @@ let { chipLabel, otherName, yearRange = '', canWrite, relId }: Props = $props();
 	<span class="min-w-0 flex-1 truncate font-serif text-sm text-ink">
 		{otherName}
 	</span>
-	{#if yearRange}
-		<span class="shrink-0 font-sans text-xs text-ink-3" data-testid="year-range">{yearRange}</span>
+	{#if dateRange}
+		<span class="shrink-0 font-sans text-xs text-ink-3" data-testid="date-range">{dateRange}</span>
+	{/if}
+	{#if canWrite && onEdit}
+		<button
+			type="button"
+			onclick={onEdit}
+			aria-label="{m.relation_edit()} — {otherName}"
+			class="inline-flex h-11 w-11 items-center justify-center text-ink-3 transition-colors hover:text-primary"
+		>
+			<svg
+				class="h-3.5 w-3.5"
+				viewBox="0 0 24 24"
+				fill="none"
+				stroke="currentColor"
+				stroke-width="2"
+				aria-hidden="true"
+			>
+				<path
+					stroke-linecap="round"
+					stroke-linejoin="round"
+					d="M16.862 4.487l1.687-1.688a1.875 1.875 0 112.652 2.652L10.582 16.07a4.5 4.5 0 01-1.897 1.13L6 18l.8-2.685a4.5 4.5 0 011.13-1.897l8.932-8.931z"
+				/>
+			</svg>
+		</button>
 	{/if}
 	{#if canWrite}
 		<form method="POST" action="?/deleteRelationship" use:enhance class="shrink-0">

frontend/src/lib/person/relationship/RelationshipChip.svelte.spec.ts

@@ -10,7 +10,7 @@ afterEach(cleanup);
 const baseProps = {
 	chipLabel: 'Elternteil',
 	otherName: 'Anna Schmidt',
-	yearRange: '',
+	dateRange: '',
 	canWrite: false,
 	relId: 'rel-1'
 };
@@ -26,30 +26,55 @@ describe('RelationshipChip', () => {
 		await expect.element(page.getByText('Anna Schmidt')).toBeInTheDocument();
 	});
 
-	it('shows year range when provided', async () => {
-		render(RelationshipChip, { ...baseProps, yearRange: '1920–1980' });
-		await expect.element(page.getByText('1920–1980')).toBeInTheDocument();
+	it('shows the date range when provided', async () => {
+		render(RelationshipChip, { ...baseProps, dateRange: '12. Mai 1923 – 1958' });
+		await expect.element(page.getByText('12. Mai 1923 – 1958')).toBeInTheDocument();
 	});
 
-	it('does not show year range span when empty', async () => {
-		render(RelationshipChip, { ...baseProps, yearRange: '' });
-		expect(document.querySelector('[data-testid="year-range"]')).toBeNull();
+	it('does not render a date-range span when empty', async () => {
+		render(RelationshipChip, { ...baseProps, dateRange: '' });
+		expect(document.querySelector('[data-testid="date-range"]')).toBeNull();
 	});
 
-	it('shows delete button when canWrite is true', async () => {
+	it('shows the delete button when canWrite is true', async () => {
 		render(RelationshipChip, { ...baseProps, canWrite: true });
 		await expect.element(page.getByRole('button')).toBeInTheDocument();
 	});
 
-	it('hides delete button when canWrite is false', async () => {
+	it('hides the delete button when canWrite is false', async () => {
 		render(RelationshipChip, { ...baseProps, canWrite: false });
 		expect(document.querySelector('button')).toBeNull();
 	});
 
-	it('delete button has h-11 w-11 (44px) WCAG touch target class', async () => {
+	it('gives the delete button an h-11 w-11 (44px) WCAG touch target', async () => {
 		render(RelationshipChip, { ...baseProps, canWrite: true });
 		const btn = document.querySelector('button')!;
 		expect(btn.className).toContain('h-11');
 		expect(btn.className).toContain('w-11');
 	});
+
+	it('shows an Edit affordance with an accessible name when canWrite and onEdit', async () => {
+		render(RelationshipChip, { ...baseProps, canWrite: true, onEdit: () => {} });
+		await expect
+			.element(page.getByRole('button', { name: /Beziehung bearbeiten/i }))
+			.toBeInTheDocument();
+	});
+
+	it('does not show the Edit affordance without onEdit', async () => {
+		render(RelationshipChip, { ...baseProps, canWrite: true });
+		expect(document.querySelector('button[aria-label*="bearbeiten"]')).toBeNull();
+	});
+
+	it('does not show the Edit affordance when canWrite is false', async () => {
+		render(RelationshipChip, { ...baseProps, canWrite: false, onEdit: () => {} });
+		expect(document.querySelector('button[aria-label*="bearbeiten"]')).toBeNull();
+	});
+
+	it('calls onEdit when the Edit affordance is clicked', async () => {
+		const onEdit = vi.fn();
+		render(RelationshipChip, { ...baseProps, canWrite: true, onEdit });
+		const editBtn = document.querySelector<HTMLButtonElement>('button[aria-label*="bearbeiten"]')!;
+		editBtn.click();
+		expect(onEdit).toHaveBeenCalledOnce();
+	});
 });

frontend/src/lib/person/relationship/RelationshipDateField.svelte

@@ -0,0 +1,38 @@
+<script lang="ts">
+import { m } from '$lib/paraglide/messages.js';
+import DateInputWithPrecision from '$lib/shared/primitives/DateInputWithPrecision.svelte';
+import type { DatePrecision } from '$lib/shared/utils/documentDate';
+
+// Only DAY / MONTH / YEAR are offered (same as the person life-date field and the
+// 60+ author audience). Storage still accepts all seven precisions; SEASON/RANGE/
+// APPROX render correctly elsewhere but make no sense to enter for a relationship.
+let {
+	name,
+	legend,
+	initialIso = '',
+	initialPrecision = null
+}: {
+	name: string;
+	legend: string;
+	initialIso?: string | null;
+	initialPrecision?: string | null;
+} = $props();
+
+const precisions: { value: DatePrecision; label: string }[] = $derived([
+	{ value: 'DAY', label: m.relation_precision_day() },
+	{ value: 'MONTH', label: m.relation_precision_month() },
+	{ value: 'YEAR', label: m.relation_precision_year() }
+]);
+</script>
+
+<DateInputWithPrecision
+	name={name}
+	legend={legend}
+	precisionLabel={m.relation_label_date_precision()}
+	precisions={precisions}
+	hint={m.relation_date_placeholder_hint()}
+	initialIso={initialIso}
+	initialPrecision={initialPrecision}
+	inputClass="bg-surface"
+	selectClass="bg-surface text-ink-3"
+/>

frontend/src/lib/person/relationshipDates.spec.ts

@@ -0,0 +1,65 @@
+import { describe, expect, it } from 'vitest';
+import { formatRelationshipDateRange } from './relationshipDates';
+
+// Delegates all precision rendering to formatDocumentDate — these tests pin the
+// composition (dash, single sides, empty state) and one rendering per precision,
+// plus en/es for DAY/MONTH so a German-month leak is caught here, not on a card.
+describe('formatRelationshipDateRange', () => {
+	describe('both dates (de default)', () => {
+		it('renders DAY precision as full dates', () => {
+			expect(formatRelationshipDateRange('1923-05-12', 'DAY', '1958-06-13', 'DAY')).toBe(
+				'12. Mai 1923 – 13. Juni 1958'
+			);
+		});
+
+		it('renders MONTH precision as month + year', () => {
+			expect(formatRelationshipDateRange('1923-05-01', 'MONTH', '1958-06-01', 'MONTH')).toBe(
+				'Mai 1923 – Juni 1958'
+			);
+		});
+
+		it('renders YEAR precision as bare years', () => {
+			expect(formatRelationshipDateRange('1923-01-01', 'YEAR', '1958-01-01', 'YEAR')).toBe(
+				'1923 – 1958'
+			);
+		});
+
+		it('renders mixed precisions per side', () => {
+			expect(formatRelationshipDateRange('1923-05-12', 'DAY', '1958-01-01', 'YEAR')).toBe(
+				'12. Mai 1923 – 1958'
+			);
+		});
+	});
+
+	describe('single sides and empty states', () => {
+		it('renders from only without a trailing dash', () => {
+			expect(formatRelationshipDateRange('1923-05-12', 'DAY', null, null)).toBe('12. Mai 1923');
+		});
+
+		it('renders to only with a leading dash', () => {
+			expect(formatRelationshipDateRange(null, null, '1958-06-13', 'DAY')).toBe('– 13. Juni 1958');
+		});
+
+		it('renders nothing when both dates are missing (UNKNOWN)', () => {
+			expect(formatRelationshipDateRange(null, 'UNKNOWN', null, 'UNKNOWN')).toBe('');
+		});
+
+		it('renders nothing for a from-only with a null date', () => {
+			expect(formatRelationshipDateRange(null, null, null, null)).toBe('');
+		});
+	});
+
+	describe('localized months (catch German-month leak)', () => {
+		it('renders DAY in English with no German month name', () => {
+			const out = formatRelationshipDateRange('1923-05-12', 'DAY', null, null, 'en');
+			expect(out).toContain('May');
+			expect(out).not.toContain('Mai');
+			expect(out).toContain('1923');
+		});
+
+		it('renders MONTH in Spanish', () => {
+			const out = formatRelationshipDateRange('1923-05-01', 'MONTH', null, null, 'es');
+			expect(out.toLowerCase()).toContain('mayo');
+		});
+	});
+});

frontend/src/lib/person/relationshipDates.ts

@@ -0,0 +1,30 @@
+import { formatDatePart, type DatePrecision } from '$lib/shared/utils/documentDate';
+
+/**
+ * Formats a relationship's start–end range as plain text, e.g. for a marriage row.
+ * Examples (de):
+ *   12. Mai 1923 – 13. Juni 1958   (both)
+ *   12. Mai 1923                   (start only — no trailing dash)
+ *   – 13. Juni 1958                (end only)
+ *   ""                             (neither — the caller renders no date line)
+ */
+export function formatRelationshipDateRange(
+	fromDate: string | null | undefined,
+	fromDatePrecision: DatePrecision | null | undefined,
+	toDate: string | null | undefined,
+	toDatePrecision: DatePrecision | null | undefined,
+	locale?: string
+): string {
+	const from = formatDatePart(fromDate, fromDatePrecision, locale);
+	const to = formatDatePart(toDate, toDatePrecision, locale);
+	if (from && to) {
+		return `${from} – ${to}`;
+	}
+	if (from) {
+		return from;
+	}
+	if (to) {
+		return `– ${to}`;
+	}
+	return '';
+}

frontend/src/lib/person/relationshipLabels.test.ts

@@ -19,6 +19,8 @@ function makeRel(
 		personDisplayName: 'Alice',
 		relatedPersonDisplayName: 'Bob',
 		relationType,
+		fromDatePrecision: 'UNKNOWN',
+		toDatePrecision: 'UNKNOWN',
 		...override
 	};
 }

frontend/src/lib/shared/errors.ts

@@ -10,6 +10,7 @@ export type ErrorCode =
 	| 'INVALID_PERSON_TYPE'
 	| 'BIRTH_AFTER_DEATH'
 	| 'INVALID_DATE_PRECISION'
+	| 'INVALID_RELATIONSHIP_DATES'
 	| 'INVALID_DATE_RANGE'
 	| 'DOCUMENT_NOT_FOUND'
 	| 'DOCUMENT_NO_FILE'
@@ -106,6 +107,8 @@ export function getErrorMessage(code: ErrorCode | string | undefined): string {
 			return m.error_birth_after_death();
 		case 'INVALID_DATE_PRECISION':
 			return m.error_invalid_date_precision();
+		case 'INVALID_RELATIONSHIP_DATES':
+			return m.error_invalid_relationship_dates();
 		case 'INVALID_DATE_RANGE':
 			return m.error_invalid_date_range();
 		case 'DOCUMENT_NOT_FOUND':

frontend/src/lib/shared/primitives/DateInputWithPrecision.svelte

@@ -0,0 +1,106 @@
+<script lang="ts">
+import { onMount } from 'svelte';
+import DateInput from '$lib/shared/primitives/DateInput.svelte';
+import type { DatePrecision } from '$lib/shared/utils/documentDate';
+
+/**
+ * Compact date + precision field: the {@link DateInput} primitive paired with a
+ * precision <select> offering a caller-chosen subset of precisions. Shared base of
+ * PersonLifeDateField (birth/death) and RelationshipDateField (from/to).
+ *
+ * Distinct from {@link DatePrecisionField} — that one is the full document/timeline
+ * field (all seven precisions, German free-text entry, RANGE end-date disclosure).
+ * This one is the restricted, single-input variant for the person-family forms.
+ *
+ * All copy (legend, precision labels, hint, the select's accessible name) and the
+ * offered precisions are injected by the caller so this stays domain-agnostic.
+ */
+let {
+	name,
+	legend,
+	precisionLabel,
+	hint,
+	precisions,
+	initialIso = '',
+	initialPrecision = null,
+	inputClass = '',
+	selectClass = ''
+}: {
+	name: string;
+	legend: string;
+	precisionLabel: string;
+	hint: string;
+	precisions: { value: DatePrecision; label: string }[];
+	initialIso?: string | null;
+	initialPrecision?: string | null;
+	inputClass?: string;
+	selectClass?: string;
+} = $props();
+
+let iso = $state('');
+let errorMessage = $state<string | null>(null);
+let inputEl = $state<HTMLInputElement | undefined>();
+let precision = $state<DatePrecision>('DAY');
+
+// Seed once at mount so a later load() rerun does not stomp an in-progress edit.
+onMount(() => {
+	if (initialIso) {
+		iso = initialIso;
+	}
+	const offered = precisions.some((p) => p.value === initialPrecision);
+	if (offered) {
+		precision = initialPrecision as DatePrecision;
+	} else if (initialIso) {
+		// A stored non-offered precision (SEASON/RANGE/APPROX) seeds as YEAR so an
+		// untouched save does not silently claim DAY precision for the stored date.
+		precision = 'YEAR';
+	}
+});
+
+// A partial date leaves the hidden ISO empty — block native submission until the
+// date is completed or fully emptied, so a save can never silently clear a date.
+$effect(() => {
+	inputEl?.setCustomValidity(errorMessage ?? '');
+});
+
+const controlCls =
+	'block min-h-[44px] w-full rounded border border-line px-3 py-2 font-serif text-ink focus:outline-none focus-visible:ring-2 focus-visible:ring-focus-ring';
+</script>
+
+<fieldset>
+	<legend class="mb-1 block text-xs font-bold tracking-widest text-ink-3 uppercase">
+		{legend}
+	</legend>
+	<div class="flex flex-col gap-2 sm:flex-row">
+		<div class="flex-1">
+			<DateInput
+				bind:value={iso}
+				bind:errorMessage={errorMessage}
+				bind:inputEl={inputEl}
+				name={name}
+				id={name}
+				placeholder="TT.MM.JJJJ"
+				ariaLabel={legend}
+				ariaDescribedby={errorMessage ? `${name}-error` : undefined}
+				class="{controlCls} {inputClass}"
+			/>
+			{#if errorMessage}
+				<p id="{name}-error" class="mt-1 font-sans text-xs text-red-600">{errorMessage}</p>
+			{/if}
+		</div>
+		<div class="flex-1">
+			<select
+				id="{name}Precision"
+				name="{name}Precision"
+				aria-label="{legend}: {precisionLabel}"
+				bind:value={precision}
+				class="{controlCls} {selectClass}"
+			>
+				{#each precisions as p (p.value)}
+					<option value={p.value}>{p.label}</option>
+				{/each}
+			</select>
+		</div>
+	</div>
+	<p class="mt-1 font-sans text-xs text-ink-3">{hint}</p>
+</fieldset>

frontend/src/lib/shared/utils/documentDate.ts

@@ -66,6 +66,27 @@ export function formatDocumentDate(
 	}
 }
 
+/**
+ * Formats one nullable date at the precision the data claims, delegating all
+ * rendering to {@link formatDocumentDate}. Returns '' for a missing date; a
+ * missing precision falls back to YEAR — pre-precision rows knew only a year,
+ * and a bare year is the only safe rendering without precision metadata.
+ *
+ * This is the shared core of {@link formatLifeDate} (person birth/death) and the
+ * relationship from/to formatter. Range-level glyphs and dashes belong in those
+ * domain wrappers, never here.
+ */
+export function formatDatePart(
+	date: string | null | undefined,
+	precision: DatePrecision | null | undefined,
+	locale?: string
+): string {
+	if (!date) {
+		return '';
+	}
+	return formatDocumentDate(date, precision ?? 'YEAR', null, null, locale);
+}
+
 // ─── precision branches ──────────────────────────────────────────────────────
 
 function longDate(iso: string, locale: string): string {

frontend/src/lib/timeline/EventCluster.svelte

@@ -0,0 +1,104 @@
+<script lang="ts">
+import * as m from '$lib/paraglide/messages.js';
+import LetterCard from './LetterCard.svelte';
+import GlyphLabel from './GlyphLabel.svelte';
+import EventHeader from './EventHeader.svelte';
+import { entryKey } from './entryKey';
+import { CLUSTER_PREVIEW } from './eventClustering';
+import type { components } from '$lib/generated/api';
+
+type TimelineEntryDTO = components['schemas']['TimelineEntryDTO'];
+
+/**
+ * A curated event with linked letters, rendered as one contained card: the event IS the card's
+ * header (so its title reads once — never also as a floating pill, #850 REQ-002), and its letters
+ * sit inside as compact `.lcard.ev` cards.
+ *
+ * - Same-year event (`event` given): the shared EventHeader carries the accent glyph + sr-only
+ *   label, the title, a `{date} · {kuratiert|abgeleitet}` subtitle, the letter count, and — for a
+ *   curator on a curated event — an edit link to `/zeitstrahl/events/{eventId}/edit` (REQ-002).
+ * - Cross-year (`title` given, no `event`): a plain `✉ {title}` text header, no edit link, no pill
+ *   chrome — it holds that other year's linked letters (REQ-004).
+ *
+ * A card shows its first {@link CLUSTER_PREVIEW} letters, then a keyboard-operable show-more/less
+ * toggle reveals/collapses the rest instead of flooding the timeline (REQ-003).
+ */
+let {
+	letters,
+	event = undefined,
+	title = '',
+	canWrite = false
+}: {
+	letters: TimelineEntryDTO[];
+	/** The same-year curated event whose letters this card holds — renders as the header. */
+	event?: TimelineEntryDTO;
+	/** Header label for a cross-year card (no `event`). */
+	title?: string;
+	canWrite?: boolean;
+} = $props();
+
+const count = $derived(letters.length);
+
+// First-5 preview + show-more (REQ-003): a large cluster stays readable instead of dumping every
+// card into the timeline.
+let expanded = $state(false);
+const visible = $derived(expanded ? letters : letters.slice(0, CLUSTER_PREVIEW));
+const hiddenCount = $derived(letters.length - CLUSTER_PREVIEW);
+</script>
+
+<section
+	class="my-3 overflow-hidden rounded-md border border-l-2 border-line border-l-brand-mint bg-surface shadow-sm"
+	data-testid="event-card"
+>
+	{#if event}
+		<!-- A same-year curated event IS the card header (the shared EventHeader) — its title reads
+		     once here, never also as a floating pill (REQ-002); the edit pencil uses the single
+		     canEditEvent gate (REQ-010, #850 finding #5). -->
+		<header
+			data-testid="event-header"
+			class="flex items-center gap-2 border-b border-line bg-canvas px-3 py-2"
+		>
+			<EventHeader entry={event} canWrite={canWrite} count={count} />
+		</header>
+	{:else}
+		<!-- Cross-year card (REQ-004): the same event's letters in another year band get a plain
+		     ✉ text header — no pill chrome, no edit link. -->
+		<header
+			data-testid="event-header"
+			class="flex items-center gap-2 border-b border-line px-3 py-2"
+		>
+			<span class="font-serif text-sm font-bold whitespace-pre-line text-ink">
+				<GlyphLabel glyph="✉" label={m.timeline_letter_glyph_label()} />
+				{title}
+			</span>
+			<span data-testid="event-count" class="font-sans text-xs text-ink-3">
+				<span aria-hidden="true">· {count}</span>
+				<span class="sr-only">{m.timeline_cluster_letter_count({ count })}</span>
+			</span>
+		</header>
+	{/if}
+
+	<div class="px-3 py-2">
+		<ul class="space-y-1.5">
+			{#each visible as letter (entryKey(letter))}
+				<li>
+					<LetterCard entry={letter} variant="event" compact={true} />
+				</li>
+			{/each}
+		</ul>
+		{#if hiddenCount > 0}
+			<button
+				type="button"
+				data-testid="bucket-show-more"
+				aria-expanded={expanded}
+				onclick={() => (expanded = !expanded)}
+				style="display: inline-flex; align-items: center; min-height: 44px"
+				class="mt-1 px-1 font-sans text-xs font-semibold text-brand-navy hover:underline focus:outline-none focus-visible:ring-2 focus-visible:ring-brand-navy"
+			>
+				{expanded
+					? m.timeline_bucket_show_less()
+					: m.timeline_bucket_show_more({ count: hiddenCount })}
+			</button>
+		{/if}
+	</div>
+</section>

frontend/src/lib/timeline/EventCluster.svelte.spec.ts

@@ -0,0 +1,129 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import { cleanup, render } from 'vitest-browser-svelte';
+import { tick } from 'svelte';
+import * as m from '$lib/paraglide/messages.js';
+import EventCluster from './EventCluster.svelte';
+import { makeEntry } from './test-factories';
+import type { components } from '$lib/generated/api';
+
+type TimelineEntryDTO = components['schemas']['TimelineEntryDTO'];
+
+afterEach(() => cleanup());
+
+const EV_ID = 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa';
+
+const makeEvent = (overrides: Partial<TimelineEntryDTO> = {}): TimelineEntryDTO =>
+	makeEntry({
+		kind: 'EVENT',
+		type: 'PERSONAL',
+		documentId: undefined,
+		eventId: EV_ID,
+		eventDate: '1916-07-06',
+		precision: 'DAY',
+		title: 'Ein gewaltiger Stadtbrand',
+		...overrides
+	});
+
+const letters = (n: number): TimelineEntryDTO[] =>
+	Array.from({ length: n }, (_, i) =>
+		makeEntry({ kind: 'LETTER', documentId: `doc-${i}`, title: `Brief ${i}`, linkedEventId: EV_ID })
+	);
+
+describe('EventCluster — contained event card (#850)', () => {
+	it('renders a data-testid event-card with the event title once (REQ-002)', () => {
+		render(EventCluster, { letters: letters(2), event: makeEvent() });
+		expect(document.querySelector('[data-testid="event-card"]')).not.toBeNull();
+		const occurrences = (document.body.textContent?.match(/Ein gewaltiger Stadtbrand/g) ?? [])
+			.length;
+		expect(occurrences).toBe(1);
+	});
+
+	it('shows the event-edit link for a curator on a curated event (REQ-002)', () => {
+		render(EventCluster, { letters: letters(2), event: makeEvent(), canWrite: true });
+		const edit = document.querySelector('[data-testid="event-edit"]') as HTMLAnchorElement;
+		expect(edit).not.toBeNull();
+		expect(edit.getAttribute('href')).toBe(`/zeitstrahl/events/${EV_ID}/edit`);
+	});
+
+	it('hides the event-edit link when canWrite is false', () => {
+		render(EventCluster, { letters: letters(2), event: makeEvent(), canWrite: false });
+		expect(document.querySelector('[data-testid="event-edit"]')).toBeNull();
+	});
+
+	it('hides the event-edit link for a derived event even with canWrite', () => {
+		render(EventCluster, {
+			letters: letters(2),
+			event: makeEvent({ derived: true, eventId: undefined, derivedType: 'BIRTH' }),
+			canWrite: true
+		});
+		expect(document.querySelector('[data-testid="event-edit"]')).toBeNull();
+	});
+
+	it('renders its letters as compact a.lcard.ev cards (REQ-002)', () => {
+		render(EventCluster, { letters: letters(2), event: makeEvent() });
+		expect(document.querySelectorAll('a.lcard.ev').length).toBeGreaterThan(0);
+	});
+
+	it('shows the first 5 of 8 letters + a show-more toggle that expands to 8 then back to 5 (REQ-003)', async () => {
+		render(EventCluster, { letters: letters(8), event: makeEvent() });
+		expect(document.querySelectorAll('a.lcard').length).toBe(5);
+		const toggle = document.querySelector('[data-testid="bucket-show-more"]') as HTMLButtonElement;
+		expect(toggle).not.toBeNull();
+		expect(toggle.getAttribute('aria-expanded')).toBe('false');
+		expect(toggle.getBoundingClientRect().height).toBeGreaterThanOrEqual(44);
+
+		toggle.click();
+		await tick();
+		expect(document.querySelectorAll('a.lcard').length).toBe(8);
+		expect(toggle.getAttribute('aria-expanded')).toBe('true');
+
+		toggle.click();
+		await tick();
+		expect(document.querySelectorAll('a.lcard').length).toBe(5);
+	});
+
+	it('renders no show-more toggle when the cluster holds 5 or fewer letters', () => {
+		render(EventCluster, { letters: letters(5), event: makeEvent() });
+		expect(document.querySelector('[data-testid="bucket-show-more"]')).toBeNull();
+	});
+
+	it('renders a cross-year text header (✉ title, no event-edit, no pill) when no event is given (REQ-004)', () => {
+		render(EventCluster, {
+			letters: letters(2),
+			title: 'Briefe von der Front',
+			canWrite: true
+		});
+		expect(document.querySelector('[data-testid="event-card"]')).not.toBeNull();
+		expect(document.body.textContent).toContain('✉');
+		expect(document.body.textContent).toContain('Briefe von der Front');
+		expect(document.querySelector('[data-testid="event-edit"]')).toBeNull();
+	});
+
+	it('pairs the cross-year ✉ glyph with an sr-only label so it is not a silent glyph (finding #6)', () => {
+		render(EventCluster, { letters: letters(2), title: 'Briefe von der Front' });
+		const header = document.querySelector('[data-testid="event-header"]') as HTMLElement;
+		const hidden = header.querySelector('[aria-hidden="true"]');
+		expect(hidden?.textContent).toContain('✉');
+		const srOnly = header.querySelector('.sr-only');
+		expect(srOnly?.textContent).toBe(m.timeline_letter_glyph_label());
+	});
+
+	it('gives the letter count an sr-only "{count} Briefe" label so "· 2" is not announced bare (finding #6)', () => {
+		render(EventCluster, { letters: letters(2), title: 'Briefe von der Front' });
+		const count = document.querySelector('[data-testid="event-count"]') as HTMLElement;
+		// the visible "· 2" stays aria-hidden; the sr-only sibling carries the meaning
+		expect(count.querySelector('[aria-hidden="true"]')?.textContent).toContain('· 2');
+		expect(count.querySelector('.sr-only')?.textContent).toBe(
+			m.timeline_cluster_letter_count({ count: 2 })
+		);
+	});
+
+	it('renders an HTML-bearing event title verbatim as text, never as markup (REQ-010)', () => {
+		render(EventCluster, {
+			letters: letters(1),
+			event: makeEvent({ title: '<img src=x onerror=alert(1)>' })
+		});
+		expect(document.querySelector('[data-testid="event-card"] img')).toBeNull();
+		expect(document.body.textContent).toContain('<img src=x onerror=alert(1)>');
+	});
+});

frontend/src/lib/timeline/EventHeader.svelte

@@ -0,0 +1,69 @@
+<script lang="ts">
+import * as m from '$lib/paraglide/messages.js';
+import GlyphLabel from './GlyphLabel.svelte';
+import { getAccentConfig, canEditEvent } from './eventCardConfig';
+import { timelineDateLabel } from './dateLabel';
+import type { components } from '$lib/generated/api';
+
+type TimelineEntryDTO = components['schemas']['TimelineEntryDTO'];
+
+/**
+ * The shared header for a curated or derived timeline event — the accent glyph circle, the title,
+ * and the `{date} · {kuratiert|abgeleitet}` subtitle, plus a curator edit pencil gated by the
+ * single canEditEvent() contract. Rendered by EventPill (inside the floating axis pill) and by
+ * EventCluster (as a same-year event-card header), so the glyph/title/subtitle markup and the
+ * security-relevant edit gate live in one place (#850 finding #5). It renders three sibling nodes
+ * (glyph circle, text block, optional edit pencil) into the parent's flex row — the parent owns
+ * the wrapper (pill vs card header). An optional letter `count` appends a screen-reader-labeled
+ * "· {count}" for the event-card case.
+ */
+let {
+	entry,
+	canWrite = false,
+	count = undefined
+}: { entry: TimelineEntryDTO; canWrite?: boolean; count?: number } = $props();
+
+const config = $derived(getAccentConfig(entry));
+const dateLabel = $derived(timelineDateLabel(entry.eventDate, entry.precision, entry.eventDateEnd));
+// Provenance reads off entry.derived: a derived life-event is "abgeleitet", a curated event
+// "kuratiert"; the date is an optional prefix so an undated event still reads the provenance.
+const provenance = $derived(
+	entry.derived ? m.timeline_provenance_derived() : m.timeline_provenance_curated()
+);
+const subtitle = $derived(dateLabel ? `${dateLabel} · ${provenance}` : provenance);
+const canEdit = $derived(canEditEvent(entry, canWrite));
+</script>
+
+<span
+	class="flex h-7 w-7 shrink-0 items-center justify-center rounded-full {config.accent === 'curated'
+		? 'bg-brand-mint text-brand-navy'
+		: 'bg-brand-navy text-brand-mint'}"
+>
+	<GlyphLabel glyph={config.glyph} label={config.label} />
+</span>
+<span class="min-w-0 text-left">
+	{#if entry.title}
+		<span class="block font-serif text-sm font-bold whitespace-pre-line text-brand-navy"
+			>{entry.title}</span
+		>
+	{/if}
+	<span class="block font-sans text-xs text-ink-3">
+		{subtitle}
+		{#if count !== undefined}
+			<span data-testid="event-count">
+				<span aria-hidden="true">· {count}</span>
+				<span class="sr-only">{m.timeline_cluster_letter_count({ count })}</span>
+			</span>
+		{/if}
+	</span>
+</span>
+{#if canEdit}
+	<a
+		data-testid="event-edit"
+		href="/zeitstrahl/events/{entry.eventId}/edit"
+		class="ml-auto rounded-sm px-1 font-sans text-xs text-ink-3 hover:text-brand-navy focus:outline-none focus-visible:ring-2 focus-visible:ring-brand-navy"
+	>
+		<span aria-hidden="true">✎</span>
+		<span class="sr-only">{m.btn_edit()}</span>
+	</a>
+{/if}

frontend/src/lib/timeline/EventHeader.svelte.spec.ts

@@ -0,0 +1,66 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import { cleanup, render } from 'vitest-browser-svelte';
+import * as m from '$lib/paraglide/messages.js';
+import EventHeader from './EventHeader.svelte';
+import { makeEntry } from './test-factories';
+import type { components } from '$lib/generated/api';
+
+type TimelineEntryDTO = components['schemas']['TimelineEntryDTO'];
+
+afterEach(() => cleanup());
+
+const EV_ID = 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa';
+
+const curated = (overrides: Partial<TimelineEntryDTO> = {}): TimelineEntryDTO =>
+	makeEntry({
+		kind: 'EVENT',
+		type: 'PERSONAL',
+		derived: false,
+		eventId: EV_ID,
+		eventDate: '1916-07-06',
+		precision: 'DAY',
+		title: 'Ein gewaltiger Stadtbrand',
+		documentId: undefined,
+		...overrides
+	});
+
+describe('EventHeader', () => {
+	it('renders the glyph with an sr-only label, the title, and the provenance subtitle', () => {
+		render(EventHeader, { entry: curated() });
+		expect(document.querySelector('.sr-only')?.textContent).toBe(m.timeline_layer_family());
+		expect(document.body.textContent).toContain('Ein gewaltiger Stadtbrand');
+		expect(document.body.textContent).toContain(m.timeline_provenance_curated());
+	});
+
+	it('shows the edit pencil for a writer on a curated event (canEditEvent gate)', () => {
+		render(EventHeader, { entry: curated(), canWrite: true });
+		const edit = document.querySelector('[data-testid="event-edit"]') as HTMLAnchorElement;
+		expect(edit).not.toBeNull();
+		expect(edit.getAttribute('href')).toBe(`/zeitstrahl/events/${EV_ID}/edit`);
+	});
+
+	it('hides the edit pencil without write, for a derived event, and for a null eventId', () => {
+		render(EventHeader, { entry: curated(), canWrite: false });
+		expect(document.querySelector('[data-testid="event-edit"]')).toBeNull();
+		cleanup();
+		render(EventHeader, { entry: curated({ derived: true }), canWrite: true });
+		expect(document.querySelector('[data-testid="event-edit"]')).toBeNull();
+		cleanup();
+		render(EventHeader, { entry: curated({ eventId: undefined }), canWrite: true });
+		expect(document.querySelector('[data-testid="event-edit"]')).toBeNull();
+	});
+
+	it('renders a screen-reader-labeled letter count when a count is given', () => {
+		render(EventHeader, { entry: curated(), count: 3 });
+		const count = document.querySelector('[data-testid="event-count"]') as HTMLElement;
+		expect(count.querySelector('[aria-hidden="true"]')?.textContent).toContain('· 3');
+		expect(count.querySelector('.sr-only')?.textContent).toBe(
+			m.timeline_cluster_letter_count({ count: 3 })
+		);
+	});
+
+	it('omits the letter count when no count is given (the pill case)', () => {
+		render(EventHeader, { entry: curated() });
+		expect(document.querySelector('[data-testid="event-count"]')).toBeNull();
+	});
+});

frontend/src/lib/timeline/EventPill.svelte

@@ -1,30 +1,21 @@
 <script lang="ts">
-import * as m from '$lib/paraglide/messages.js';
+import EventHeader from './EventHeader.svelte';
 import { getAccentConfig } from './eventCardConfig';
-import { timelineDateLabel } from './dateLabel';
 import type { components } from '$lib/generated/api';
 
 type TimelineEntryDTO = components['schemas']['TimelineEntryDTO'];
 
 /**
  * Centered axis pill for a derived life-event or a curated PERSONAL event
- * (REQ-007/008). The glyph is wrapped aria-hidden with an sr-only label sibling
- * (REQ-018). An edit affordance shows only for a curated event with an eventId
- * (never derived, never null — REQ-008).
+ * (REQ-007/008). The pill border keys off the accent (curated = mint, derived =
+ * navy); its glyph, title, subtitle, and curator edit pencil are the shared
+ * EventHeader, so the edit gate (canEditEvent) lives in one place — #842
+ * REQ-005/007/008, #850 finding #5. The gate is UX only; the real boundary is the
+ * #781 route guard + backend permission.
  */
-let { entry }: { entry: TimelineEntryDTO } = $props();
+let { entry, canWrite = false }: { entry: TimelineEntryDTO; canWrite?: boolean } = $props();
 
 const config = $derived(getAccentConfig(entry));
-const dateLabel = $derived(timelineDateLabel(entry.eventDate, entry.precision, entry.eventDateEnd));
-// Provenance reads off entry.derived (not the accent): a derived life-event is
-// "abgeleitet", a curated PERSONAL event is "kuratiert" (REQ-007).
-const provenance = $derived(
-	entry.derived ? m.timeline_provenance_derived() : m.timeline_provenance_curated()
-);
-// Provenance always shows; the date is an optional prefix so an undated event
-// still reads "abgeleitet"/"kuratiert" (REQ-007).
-const subtitle = $derived(dateLabel ? `${dateLabel} · ${provenance}` : provenance);
-const canEdit = $derived(!entry.derived && entry.eventId != null);
 </script>
 
 <div class="flex justify-center">
@@ -34,32 +25,6 @@ const canEdit = $derived(!entry.derived && entry.eventId != null);
 			? 'border-2 border-brand-mint'
 			: 'border border-brand-navy'}"
 	>
-		<span
-			class="flex h-7 w-7 shrink-0 items-center justify-center rounded-full {config.accent ===
-			'curated'
-				? 'bg-brand-mint text-brand-navy'
-				: 'bg-brand-navy text-brand-mint'}"
-		>
-			<span aria-hidden="true">{config.glyph}</span>
-			<span class="sr-only">{config.label}</span>
-		</span>
-		<span class="text-left">
-			{#if entry.title}
-				<span class="block font-serif text-sm font-bold whitespace-pre-line text-brand-navy"
-					>{entry.title}</span
-				>
-			{/if}
-			<span class="block font-sans text-xs text-ink-3">{subtitle}</span>
-		</span>
-		{#if canEdit}
-			<a
-				data-testid="event-edit"
-				href="/zeitstrahl/events/{entry.eventId}/edit"
-				class="ml-1 rounded-sm px-1 font-sans text-xs text-ink-3 hover:text-brand-navy focus:outline-none focus-visible:ring-2 focus-visible:ring-brand-navy"
-			>
-				<span aria-hidden="true">✎</span>
-				<span class="sr-only">{m.btn_edit()}</span>
-			</a>
-		{/if}
+		<EventHeader entry={entry} canWrite={canWrite} />
 	</div>
 </div>

frontend/src/lib/timeline/EventPill.svelte.spec.ts

@@ -51,8 +51,9 @@ describe('EventPill', () => {
 		expect(srOnly?.textContent).toBe('Geburt');
 	});
 
-	it('shows an edit affordance for a curated PERSONAL event with an eventId (REQ-008)', () => {
+	it('shows an edit affordance for a curated PERSONAL event when canWrite is true (REQ-005)', () => {
 		render(EventPill, {
+			canWrite: true,
 			entry: makeEntry({
 				kind: 'EVENT',
 				derived: false,
@@ -66,11 +67,45 @@ describe('EventPill', () => {
 		});
 		const edit = document.querySelector('[data-testid="event-edit"]') as HTMLAnchorElement | null;
 		expect(edit).not.toBeNull();
-		expect(edit?.getAttribute('href')).toContain(EVENT_ID);
+		expect(edit?.getAttribute('href')).toBe(`/zeitstrahl/events/${EVENT_ID}/edit`);
 	});
 
-	it('shows no edit affordance when eventId is null (REQ-008)', () => {
+	it('renders no edit affordance for a curated PERSONAL event when canWrite is false (REQ-007)', () => {
 		render(EventPill, {
+			canWrite: false,
+			entry: makeEntry({
+				kind: 'EVENT',
+				derived: false,
+				type: 'PERSONAL',
+				eventId: EVENT_ID,
+				title: 'Auswanderung',
+				senderName: '',
+				receiverName: '',
+				documentId: undefined
+			})
+		});
+		expect(document.querySelector('[data-testid="event-edit"]')).toBeNull();
+	});
+
+	it('renders no edit affordance when the canWrite prop is omitted (gate-closed default) (REQ-007)', () => {
+		render(EventPill, {
+			entry: makeEntry({
+				kind: 'EVENT',
+				derived: false,
+				type: 'PERSONAL',
+				eventId: EVENT_ID,
+				title: 'Auswanderung',
+				senderName: '',
+				receiverName: '',
+				documentId: undefined
+			})
+		});
+		expect(document.querySelector('[data-testid="event-edit"]')).toBeNull();
+	});
+
+	it('shows no edit affordance when eventId is null even with canWrite (REQ-008)', () => {
+		render(EventPill, {
+			canWrite: true,
 			entry: makeEntry({
 				kind: 'EVENT',
 				derived: false,
@@ -85,8 +120,8 @@ describe('EventPill', () => {
 		expect(document.querySelector('[data-testid="event-edit"]')).toBeNull();
 	});
 
-	it('shows no edit affordance for a derived event (REQ-008)', () => {
-		render(EventPill, { entry: derived('MARRIAGE', 'Heirat') });
+	it('shows no edit affordance for a derived event even with canWrite (REQ-008)', () => {
+		render(EventPill, { canWrite: true, entry: derived('MARRIAGE', 'Heirat') });
 		expect(document.querySelector('[data-testid="event-edit"]')).toBeNull();
 	});
 

frontend/src/lib/timeline/LetterCard.svelte

@@ -11,11 +11,33 @@ type TimelineEntryDTO = components['schemas']['TimelineEntryDTO'];
  * A single archive letter on the timeline: sender → receiver, title, and a
  * precision-aware date chip, linking to the document. Names/titles are
  * OCR/import-derived — rendered via default `{...}` escaping with
- * `whitespace-pre-line` for line breaks (REQ-021); never the raw-HTML directive.
+ * `whitespace-pre-line` for line breaks (REQ-010); never the raw-HTML directive.
+ *
+ * Inside an event cluster the card sits in the contained event card and renders as
+ * the `.lcard.ev` `compact` variant (#850, REQ-002): tighter row, and the redundant
+ * date chip is dropped when the title already embeds the date. The per-letter tag
+ * chip can be suppressed via `suppressTagChip` for callers that already convey it.
  */
-let { entry }: { entry: TimelineEntryDTO } = $props();
+let {
+	entry,
+	variant = 'plain',
+	suppressTagChip = false,
+	compact = false
+}: {
+	entry: TimelineEntryDTO;
+	variant?: 'plain' | 'event';
+	suppressTagChip?: boolean;
+	compact?: boolean;
+} = $props();
 
+const isEventVariant = $derived(variant === 'event');
 const dateLabel = $derived(timelineDateLabel(entry.eventDate, entry.precision, entry.eventDateEnd));
+// Inside an event card the band frames the time, so a compact in-card letter drops the
+// redundant date chip — but ONLY when the (free-form OCR) title actually embeds the formatted
+// date, e.g. "H-0023 – 6. Juli 1916". A title without the date keeps its chip, so a letter like
+// "Brief an Mutter" never loses its month/day (the band frames only the year) — #850, finding #4.
+const titleEmbedsDate = $derived(!!dateLabel && !!entry.title && entry.title.includes(dateLabel));
+const showDate = $derived(!compact || !titleEmbedsDate);
 const sender = $derived(entry.senderName === '' ? m.timeline_unknown_person() : entry.senderName);
 const receiver = $derived(
 	entry.receiverName === '' ? m.timeline_unknown_person() : entry.receiverName
@@ -28,28 +50,37 @@ const receiver = $derived(
 <a
 	href="/documents/{entry.documentId}"
 	style="display: flex; flex-direction: column; justify-content: center; min-height: 44px"
-	class="rounded-sm border border-l-[3px] border-line border-l-brand-mint bg-surface px-3 py-2 shadow-sm transition-colors hover:border-brand-mint focus:outline-none focus-visible:ring-2 focus-visible:ring-brand-navy"
+	class="lcard rounded-sm border border-l-[3px] border-line border-l-brand-mint bg-surface px-3 shadow-sm transition-colors hover:border-brand-mint focus:outline-none focus-visible:ring-2 focus-visible:ring-brand-navy"
+	class:py-2={!compact}
+	class:py-1={compact}
+	class:ev={isEventVariant}
+	class:compact={compact}
 >
 	{#if entry.title}
 		<!-- ✉ + sr-only label are static chrome rendered as sibling nodes, NEVER
 		     interpolated into the escaped user title; the title keeps its own
 		     pre-line span for multi-line OCR text (REQ-008/016/021). -->
-		<span class="font-serif text-sm font-bold break-words text-ink">
+		<span
+			class="font-serif font-bold break-words text-ink"
+			class:text-sm={!compact}
+			class:text-xs={compact}
+		>
 			<GlyphLabel glyph="✉" label={m.timeline_letter_glyph_label()} />
 			<span class="whitespace-pre-line">{entry.title}</span>
 		</span>
 	{/if}
-	<span class="mt-0.5 font-sans text-xs break-words text-ink-3">
+	<span class="font-sans text-xs break-words text-ink-3" class:mt-0.5={!compact}>
 		<span class="font-serif whitespace-pre-line">{sender}</span>
 		<span aria-hidden="true">→</span>
 		<span class="font-serif whitespace-pre-line">{receiver}</span>
-		{#if dateLabel}
+		{#if dateLabel && showDate}
 			<span data-testid="letter-date"> · {dateLabel}</span>
 		{/if}
 	</span>
-	{#if entry.rootTagName}
+	{#if entry.rootTagName && !suppressTagChip}
 		<!-- The primary root-tag chip sits on its own line beneath the meta line
-		     (#835 §3); absent when the letter has no tag (REQ-005). -->
+		     (#835 §3); absent when the letter has no tag (REQ-006), and suppressed when
+		     the caller already conveys the topic (suppressTagChip). -->
 		<TagChip name={entry.rootTagName} color={entry.rootTagColor ?? null} />
 	{/if}
 </a>

frontend/src/lib/timeline/LetterCard.svelte.spec.ts

@@ -127,3 +127,58 @@ describe('LetterCard', () => {
 		expect(chip?.textContent).toContain('Familie');
 	});
 });
+
+describe('LetterCard — event-cluster variants (#850, REQ-002)', () => {
+	it('carries the .lcard.ev class in the event variant (REQ-002)', () => {
+		render(LetterCard, { entry: makeEntry(), variant: 'event' });
+		expect(document.querySelector('a.lcard.ev')).not.toBeNull();
+	});
+
+	it('is a plain card with no .ev marker by default (REQ-006)', () => {
+		render(LetterCard, { entry: makeEntry() });
+		expect(document.querySelector('a.ev')).toBeNull();
+	});
+
+	it('suppresses the per-letter tag chip when asked, even with a root tag', () => {
+		render(LetterCard, {
+			entry: makeEntry({ rootTagName: 'Krieg', rootTagColor: 'sienna' }),
+			suppressTagChip: true
+		});
+		expect(document.querySelector('[data-testid="tag-chip"]')).toBeNull();
+	});
+
+	it('still shows the per-letter tag chip when not suppressed', () => {
+		render(LetterCard, { entry: makeEntry({ rootTagName: 'Krieg', rootTagColor: 'sienna' }) });
+		expect(document.querySelector('[data-testid="tag-chip"]')).not.toBeNull();
+	});
+
+	it('drops the compact date chip only when the title actually embeds the formatted date (#850)', () => {
+		// An archive title like "H-0023 – 6. Juli 1916" already carries the date, so inside an
+		// event card (where the band frames the time) the redundant chip is dropped.
+		const entry = makeEntry({ eventDate: '1916-07-06', precision: 'DAY' });
+		const dateLabel = timelineDateLabel(entry.eventDate, entry.precision, entry.eventDateEnd);
+		render(LetterCard, { entry: { ...entry, title: `H-0023 – ${dateLabel}` }, compact: true });
+		expect(document.querySelector('[data-testid="letter-date"]')).toBeNull();
+		expect(document.body.textContent).toContain('Karl Raddatz'); // sender still shown
+	});
+
+	it('keeps the compact date chip when the title does NOT embed the date (#850, finding #4)', () => {
+		// Titles are free-form OCR text — a titled letter whose title carries no date must keep
+		// its month/day, since inside an event card the band frames only the year.
+		render(LetterCard, {
+			entry: makeEntry({ eventDate: '1916-07-06', precision: 'DAY', title: 'Brief an Mutter' }),
+			compact: true
+		});
+		expect(document.querySelector('[data-testid="letter-date"]')).not.toBeNull();
+	});
+
+	it('keeps the date in the compact variant when the letter has no title (#850)', () => {
+		render(LetterCard, { entry: makeEntry({ title: undefined }), compact: true });
+		expect(document.querySelector('[data-testid="letter-date"]')).not.toBeNull();
+	});
+
+	it('renders the compact variant on a single tighter row (#850)', () => {
+		render(LetterCard, { entry: makeEntry(), compact: true });
+		expect(document.querySelector('a.lcard.compact')).not.toBeNull();
+	});
+});

frontend/src/lib/timeline/TimelineFilters.svelte

@@ -0,0 +1,133 @@
+<script lang="ts">
+import * as m from '$lib/paraglide/messages.js';
+import { slide } from 'svelte/transition';
+import { hiddenLayerCount, isDefaultState, type TimelineLayerFilters } from './timelineFilter';
+
+// Presentation-only layer filter for the global /zeitstrahl (#780, REQ-001).
+// Holds no timeline data and never navigates or fetches — the route owns the
+// $state and derives the filtered view. Three $bindable layer booleans plus an
+// onChange notification hook are the whole contract.
+let {
+	personalOn = $bindable(true),
+	historicalOn = $bindable(true),
+	lettersOn = $bindable(true),
+	onChange
+}: {
+	personalOn?: boolean;
+	historicalOn?: boolean;
+	lettersOn?: boolean;
+	onChange?: () => void;
+} = $props();
+
+let open = $state(false);
+
+// Reuse the reduced-motion guard expression from documents/[id]/+page.svelte:57
+// for a new purpose — zeroing the slide duration so the collapsible opens
+// instantly when the reader prefers reduced motion (REQ-009).
+const prefersReducedMotion = $derived(
+	typeof window !== 'undefined' && window.matchMedia('(prefers-reduced-motion: reduce)').matches
+);
+const slideDuration = $derived(prefersReducedMotion ? 0 : 200);
+
+const filters: TimelineLayerFilters = $derived({ personalOn, historicalOn, lettersOn });
+const hiddenCount = $derived(hiddenLayerCount(filters));
+const anyLayerOff = $derived(!isDefaultState(filters));
+
+function reset() {
+	personalOn = true;
+	historicalOn = true;
+	lettersOn = true;
+	onChange?.();
+}
+</script>
+
+{#snippet layerToggle(label: string, testid: string, pressed: boolean, toggle: () => void)}
+	<button
+		type="button"
+		data-testid={testid}
+		aria-pressed={pressed}
+		onclick={toggle}
+		class="inline-flex min-h-[44px] items-center gap-2 rounded border px-3 font-sans text-sm transition-colors {pressed
+			? 'border-primary bg-primary text-primary-fg'
+			: 'border-line bg-muted text-ink-2 hover:bg-line'}"
+	>
+		<span
+			aria-hidden="true"
+			class="inline-flex h-4 w-4 items-center justify-center rounded-sm border {pressed
+				? 'border-primary-fg bg-primary-fg/20'
+				: 'border-ink-3'}"
+		>
+			{#if pressed}✓{/if}
+		</span>
+		{label}
+	</button>
+{/snippet}
+
+<section class="mb-6">
+	<!-- Sticky trigger kept in document flow so the hidden-layer count stays
+	     visible without clipping timeline content (REQ-007). -->
+	<div class="sticky top-16 z-20 bg-canvas py-2">
+		<button
+			type="button"
+			data-testid="timeline-filter-trigger"
+			aria-expanded={open}
+			aria-controls={open ? 'timeline-filter-panel' : undefined}
+			onclick={() => (open = !open)}
+			class="inline-flex min-h-[44px] items-center gap-2 rounded border border-line bg-surface px-4 font-sans text-xs font-bold tracking-widest text-ink-2 uppercase transition-colors hover:bg-muted"
+		>
+			{hiddenCount === 0
+				? m.timeline_filter_trigger()
+				: m.timeline_filter_trigger_active({ count: hiddenCount })}
+		</button>
+	</div>
+
+	{#if open}
+		<div id="timeline-filter-panel" transition:slide={{ duration: slideDuration }}>
+			<fieldset class="mt-2 rounded-sm border border-line bg-surface p-4">
+				<legend class="px-1 font-sans text-xs font-bold tracking-widest text-ink-3 uppercase">
+					{m.timeline_filter_label_layers()}
+				</legend>
+				<div class="flex flex-wrap gap-2">
+					{@render layerToggle(
+						m.timeline_filter_layer_personal(),
+						'timeline-filter-personal',
+						personalOn,
+						() => {
+							personalOn = !personalOn;
+							onChange?.();
+						}
+					)}
+					{@render layerToggle(
+						m.timeline_filter_layer_historical(),
+						'timeline-filter-historical',
+						historicalOn,
+						() => {
+							historicalOn = !historicalOn;
+							onChange?.();
+						}
+					)}
+					{@render layerToggle(
+						m.timeline_filter_layer_letters(),
+						'timeline-filter-letters',
+						lettersOn,
+						() => {
+							lettersOn = !lettersOn;
+							onChange?.();
+						}
+					)}
+				</div>
+
+				{#if anyLayerOff}
+					<button
+						type="button"
+						data-testid="timeline-filter-reset"
+						onclick={reset}
+						class="mt-3 inline-flex min-h-[44px] items-center font-sans text-sm text-primary underline-offset-2 hover:underline"
+					>
+						{m.timeline_filter_reset()}
+					</button>
+				{/if}
+			</fieldset>
+		</div>
+	{/if}
+</section>

frontend/src/lib/timeline/TimelineFilters.svelte.spec.ts

@@ -0,0 +1,74 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { cleanup, render } from 'vitest-browser-svelte';
+import { page } from 'vitest/browser';
+import * as m from '$lib/paraglide/messages.js';
+import TimelineFilters from './TimelineFilters.svelte';
+
+afterEach(() => cleanup());
+
+const allOn = () => ({ personalOn: true, historicalOn: true, lettersOn: true, onChange: vi.fn() });
+
+async function openBar() {
+	await page.getByTestId('timeline-filter-trigger').click();
+}
+
+describe('TimelineFilters', () => {
+	it('renders the three layer toggles with accessible names inside a labelled group (REQ-001)', async () => {
+		render(TimelineFilters, allOn());
+		await openBar();
+		await expect
+			.element(page.getByRole('button', { name: m.timeline_filter_layer_personal() }))
+			.toBeVisible();
+		await expect
+			.element(page.getByRole('button', { name: m.timeline_filter_layer_historical() }))
+			.toBeVisible();
+		await expect
+			.element(page.getByRole('button', { name: m.timeline_filter_layer_letters() }))
+			.toBeVisible();
+		// the fieldset legend groups the toggles
+		await expect.element(page.getByText(m.timeline_filter_label_layers())).toBeVisible();
+	});
+
+	it('reflects a layer as pressed and flips it, firing onChange (REQ-001)', async () => {
+		const props = allOn();
+		render(TimelineFilters, props);
+		await openBar();
+		const personal = page.getByTestId('timeline-filter-personal');
+		await expect.element(personal).toHaveAttribute('aria-pressed', 'true');
+		await personal.click();
+		await expect.element(personal).toHaveAttribute('aria-pressed', 'false');
+		expect(props.onChange).toHaveBeenCalled();
+	});
+
+	it('shows a plain trigger when all layers are on and a count once a layer is hidden (REQ-007/010)', async () => {
+		render(TimelineFilters, allOn());
+		const trigger = page.getByTestId('timeline-filter-trigger');
+		await expect.element(trigger).toHaveTextContent(m.timeline_filter_trigger());
+		await expect.element(trigger).not.toHaveTextContent('aktiv');
+		await trigger.click();
+		await page.getByTestId('timeline-filter-letters').click();
+		await expect.element(trigger).toHaveTextContent(m.timeline_filter_trigger_active({ count: 1 }));
+	});
+
+	it('gives the trigger a 44px touch target (REQ-007)', async () => {
+		render(TimelineFilters, allOn());
+		await expect.element(page.getByTestId('timeline-filter-trigger')).toHaveClass(/min-h-\[44px\]/);
+	});
+
+	it('hides the reset button by default and restores all layers when activated (REQ-008)', async () => {
+		const props = allOn();
+		render(TimelineFilters, props);
+		await openBar();
+		const reset = page.getByTestId('timeline-filter-reset');
+		// absent (not just hidden) while every layer is on
+		expect(reset.query()).toBeNull();
+		await page.getByTestId('timeline-filter-historical').click();
+		await expect.element(reset).toBeVisible();
+		await reset.click();
+		await expect
+			.element(page.getByTestId('timeline-filter-historical'))
+			.toHaveAttribute('aria-pressed', 'true');
+		await expect.poll(() => reset.query()).toBeNull();
+		expect(props.onChange).toHaveBeenCalled();
+	});
+});

frontend/src/lib/timeline/TimelineView.svelte

@@ -6,6 +6,7 @@ import LetterCard from './LetterCard.svelte';
 import EventPill from './EventPill.svelte';
 import WorldBand from './WorldBand.svelte';
 import { entryKey } from './entryKey';
+import { buildEventLookup } from './eventClustering';
 import type { components } from '$lib/generated/api';
 
 type TimelineDTO = components['schemas']['TimelineDTO'];
@@ -18,8 +19,19 @@ type TimelineYearDTO = components['schemas']['TimelineYearDTO'];
  * empty timeline shows a calm message (REQ-017). `personId` is a declared seam
  * for the per-person rail (issue #10) and is undefined here; it is not passed to
  * leaf cards (REQ-025). Owns no <main> — the layout does.
+ *
+ * The event lookup is built once over the whole (already layer-filtered) timeline
+ * and threaded to every band so a curated event's letters cluster under it inline
+ * (#850, REQ-002). The undated bucket stays plain (events as pills, letters as
+ * cards) — out of clustering scope.
  */
-let { timeline, personId = undefined }: { timeline: TimelineDTO; personId?: string } = $props();
+let {
+	timeline,
+	personId = undefined,
+	canWrite = false
+}: { timeline: TimelineDTO; personId?: string; canWrite?: boolean } = $props();
+
+const eventLookup = $derived(buildEventLookup(timeline));
 
 type Row = { t: 'band'; year: TimelineYearDTO } | { t: 'gap'; from: number; to: number };
 
@@ -50,7 +62,7 @@ const isEmpty = $derived(timeline.years.length === 0 && timeline.undated.length
 		{#each rows as row (row.t === 'band' ? `band-${row.year.year}` : `gap-${row.from}`)}
 			<li>
 				{#if row.t === 'band'}
-					<YearBand year={row.year} />
+					<YearBand year={row.year} canWrite={canWrite} eventLookup={eventLookup} />
 				{:else}
 					<GapSpan from={row.from} to={row.to} />
 				{/if}
@@ -75,9 +87,9 @@ const isEmpty = $derived(timeline.years.length === 0 && timeline.undated.length
 					<li>
 						{#if entry.kind === 'EVENT'}
 							{#if entry.type === 'HISTORICAL'}
-								<WorldBand entry={entry} />
+								<WorldBand entry={entry} canWrite={canWrite} />
 							{:else}
-								<EventPill entry={entry} />
+								<EventPill entry={entry} canWrite={canWrite} />
 							{/if}
 						{:else}
 							<LetterCard entry={entry} />

frontend/src/lib/timeline/TimelineView.svelte.spec.ts

@@ -105,6 +105,7 @@ describe('TimelineView', () => {
 
 	it('renders an undated curated EVENT as a pill, not a broken letter card (REQ-008/016)', () => {
 		render(TimelineView, {
+			canWrite: true,
 			timeline: makeTimelineDTO({
 				undated: [
 					makeEntry({
@@ -125,8 +126,8 @@ describe('TimelineView', () => {
 		// The event renders inside the undated section…
 		expect(document.querySelector('[data-testid="undated-section"]')).not.toBeNull();
 		expect(document.body.textContent).toContain('Auswanderung');
-		// …as an EventPill (its edit affordance), never as a letter card linking
-		// to /documents/undefined with "Unbekannt → Unbekannt".
+		// …as an EventPill (its edit affordance, threaded canWrite), never as a
+		// letter card linking to /documents/undefined with "Unbekannt → Unbekannt".
 		expect(document.querySelector('[data-testid="event-edit"]')).not.toBeNull();
 		expect(document.querySelector('a[href="/documents/undefined"]')).toBeNull();
 		expect(document.body.textContent).not.toContain('Unbekannt');
@@ -276,4 +277,131 @@ describe('TimelineView', () => {
 		);
 		expect(sides).toEqual(['left', 'right', 'left', 'right']);
 	});
+
+	// A curated PERSONAL event reachable through both dispatch paths: the year-band
+	// path (TimelineView → YearBand → EventPill) and the undated bucket
+	// (TimelineView → EventPill). canWrite must thread to both (REQ-009).
+	const curated = (eventId: string, title: string) =>
+		makeEntry({
+			kind: 'EVENT',
+			type: 'PERSONAL',
+			derived: false,
+			eventId,
+			title,
+			senderName: '',
+			receiverName: '',
+			documentId: undefined
+		});
+
+	const bothPaths = () =>
+		makeTimelineDTO({
+			years: [makeYear(1924, [curated('banded', 'Umzug nach Berlin')])],
+			undated: [curated('undated', 'Auswanderung')]
+		});
+
+	it('threads canWrite to a curated event in both a year band and the undated bucket (REQ-009)', () => {
+		render(TimelineView, { canWrite: true, timeline: bothPaths() });
+		const hrefs = Array.from(document.querySelectorAll('[data-testid="event-edit"]')).map((a) =>
+			a.getAttribute('href')
+		);
+		expect(hrefs).toContain('/zeitstrahl/events/banded/edit');
+		expect(hrefs).toContain('/zeitstrahl/events/undated/edit');
+	});
+
+	it('renders no edit links in either path when canWrite is false (REQ-007/009)', () => {
+		render(TimelineView, { canWrite: false, timeline: bothPaths() });
+		expect(document.querySelectorAll('[data-testid="event-edit"]')).toHaveLength(0);
+	});
+
+	it('threads canWrite to a curated HISTORICAL world band in both paths (REQ-006/009)', () => {
+		const world = (eventId: string, title: string) =>
+			makeEntry({
+				kind: 'EVENT',
+				type: 'HISTORICAL',
+				derived: false,
+				eventId,
+				precision: 'YEAR',
+				eventDate: '1929-01-01',
+				eventDateEnd: undefined,
+				title,
+				senderName: '',
+				receiverName: '',
+				documentId: undefined
+			});
+		render(TimelineView, {
+			canWrite: true,
+			timeline: makeTimelineDTO({
+				years: [makeYear(1929, [world('wb', 'Weltwirtschaftskrise')])],
+				undated: [world('wu', 'Unbekanntes Weltereignis')]
+			})
+		});
+		const hrefs = Array.from(document.querySelectorAll('[data-testid="event-edit"]')).map((a) =>
+			a.getAttribute('href')
+		);
+		expect(hrefs).toContain('/zeitstrahl/events/wb/edit');
+		expect(hrefs).toContain('/zeitstrahl/events/wu/edit');
+	});
+
+	it('builds the event lookup and clusters a curated event + same-year linked letter into an event-card (#850)', () => {
+		const evId = 'eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee';
+		const event = makeEntry({
+			kind: 'EVENT',
+			type: 'PERSONAL',
+			derived: false,
+			eventId: evId,
+			eventDate: '1916-07-06',
+			precision: 'DAY',
+			title: 'Ein gewaltiger Stadtbrand',
+			senderName: '',
+			receiverName: '',
+			documentId: undefined
+		});
+		const letter = makeEntry({
+			eventDate: '1916-05-10',
+			documentId: 'doc-linked',
+			title: 'Brief',
+			linkedEventId: evId
+		});
+		render(TimelineView, {
+			timeline: makeTimelineDTO({ years: [makeYear(1916, [event, letter])] })
+		});
+		expect(document.querySelector('[data-testid="event-card"]')).not.toBeNull();
+		expect(document.querySelector('a.lcard.ev')).not.toBeNull();
+		// the title reads once — the event is the card header, not also a loose pill
+		const titles = (document.body.textContent?.match(/Ein gewaltiger Stadtbrand/g) ?? []).length;
+		expect(titles).toBe(1);
+	});
+
+	it('keeps a HISTORICAL event a WorldBand with a same-year linked letter — never clusters (REQ-014)', () => {
+		const evId = 'dddddddd-dddd-dddd-dddd-dddddddddddd';
+		const world = makeEntry({
+			kind: 'EVENT',
+			type: 'HISTORICAL',
+			derived: false,
+			eventId: evId,
+			eventDate: '1916-07-01',
+			precision: 'DAY',
+			title: 'Schlacht an der Somme',
+			senderName: '',
+			receiverName: '',
+			documentId: undefined
+		});
+		const letter = makeEntry({
+			eventDate: '1916-05-10',
+			documentId: 'doc-world-linked',
+			title: 'Brief von der Front',
+			linkedEventId: evId
+		});
+		render(TimelineView, {
+			timeline: makeTimelineDTO({ years: [makeYear(1916, [world, letter])] })
+		});
+		// the world event stays a full-width band — no contained event card
+		expect(document.querySelector('[data-testid="event-card"]')).toBeNull();
+		expect(document.querySelector('a.lcard.ev')).toBeNull();
+		// the linked letter renders loose on the spine, not inside a card
+		expect(document.querySelector('.letter-row')).not.toBeNull();
+		// and the band keeps its WorldBand "· historisch" register
+		expect(document.body.textContent).toContain(m.timeline_layer_historical_suffix());
+		expect(document.body.textContent).toContain('Schlacht an der Somme');
+	});
 });

frontend/src/lib/timeline/WorldBand.svelte

@@ -1,6 +1,6 @@
 <script lang="ts">
 import * as m from '$lib/paraglide/messages.js';
-import { getAccentConfig } from './eventCardConfig';
+import { getAccentConfig, canEditEvent } from './eventCardConfig';
 import { timelineDateLabel } from './dateLabel';
 import type { components } from '$lib/generated/api';
 
@@ -11,9 +11,11 @@ type TimelineEntryDTO = components['schemas']['TimelineEntryDTO'];
  * (REQ-009). A RANGE carries a visible span pill ("1914–1918") with a Zeitraum
  * aria-label; a RANGE with no end degrades to the start year, no pill (REQ-010).
  * The glyph is a redundant non-color cue with an sr-only label (REQ-018); text
- * uses text-ink-2 to stay AA in both themes (REQ-019).
+ * uses text-ink-2 to stay AA in both themes (REQ-019). A curator (`canWrite`,
+ * gate-closed by default) gets an inline edit pencil for a curated event with an
+ * eventId — #842 REQ-006/007/008; UX gate only, the #781 route guard is the boundary.
  */
-let { entry }: { entry: TimelineEntryDTO } = $props();
+let { entry, canWrite = false }: { entry: TimelineEntryDTO; canWrite?: boolean } = $props();
 
 const config = $derived(getAccentConfig(entry));
 const dateLabel = $derived(timelineDateLabel(entry.eventDate, entry.precision, entry.eventDateEnd));
@@ -24,6 +26,9 @@ const dateText = $derived(showSpan ? null : entry.precision === 'RANGE' ? fromYe
 // Every WorldBand is a HISTORICAL band, so the visible "historisch" register
 // always trails the subtitle as plain text — never a second pill (REQ-009).
 const historical = $derived(m.timeline_layer_historical_suffix());
+// A HISTORICAL event is never derived, so canEditEvent's derived check is a
+// no-op here — the gate is the curator flag plus a real eventId (#842 REQ-006/008).
+const canEdit = $derived(canEditEvent(entry, canWrite));
 </script>
 
 <div class="my-3 border-y border-line bg-canvas px-4 py-2 text-center">
@@ -46,4 +51,14 @@ const historical = $derived(m.timeline_layer_historical_suffix());
 	<!-- Single trailing "· historisch" register, after the title and any
 	     span pill / date — one render site, consistent separator (REQ-009). -->
 	<span class="ml-2 font-sans text-xs text-ink-3">· {historical}</span>
+	{#if canEdit}
+		<a
+			data-testid="event-edit"
+			href="/zeitstrahl/events/{entry.eventId}/edit"
+			class="ml-2 rounded-sm px-1 font-sans text-xs text-ink-3 hover:text-brand-navy focus:outline-none focus-visible:ring-2 focus-visible:ring-brand-navy"
+		>
+			<span aria-hidden="true">✎</span>
+			<span class="sr-only">{m.btn_edit()}</span>
+		</a>
+	{/if}
 </div>

frontend/src/lib/timeline/WorldBand.svelte.spec.ts

@@ -73,4 +73,35 @@ describe('WorldBand', () => {
 		expect(pill?.textContent).not.toContain(m.timeline_layer_historical_suffix());
 		expect(document.body.textContent).toContain(m.timeline_layer_historical_suffix());
 	});
+
+	const HIST_EVENT_ID = '44444444-4444-4444-4444-444444444444';
+
+	it('shows an edit affordance for a curated HISTORICAL event when canWrite is true (REQ-006)', () => {
+		render(WorldBand, { canWrite: true, entry: historical({ eventId: HIST_EVENT_ID }) });
+		const edit = document.querySelector('[data-testid="event-edit"]') as HTMLAnchorElement | null;
+		expect(edit).not.toBeNull();
+		expect(edit?.getAttribute('href')).toBe(`/zeitstrahl/events/${HIST_EVENT_ID}/edit`);
+	});
+
+	it('mirrors the EventPill pencil: aria-hidden ✎ glyph + sr-only Bearbeiten label (REQ-006)', () => {
+		render(WorldBand, { canWrite: true, entry: historical({ eventId: HIST_EVENT_ID }) });
+		const edit = document.querySelector('[data-testid="event-edit"]');
+		expect(edit?.querySelector('[aria-hidden="true"]')?.textContent).toBe('✎');
+		expect(edit?.querySelector('.sr-only')?.textContent).toBe(m.btn_edit());
+	});
+
+	it('renders no edit affordance for a curated HISTORICAL event when canWrite is false (REQ-007)', () => {
+		render(WorldBand, { canWrite: false, entry: historical({ eventId: HIST_EVENT_ID }) });
+		expect(document.querySelector('[data-testid="event-edit"]')).toBeNull();
+	});
+
+	it('renders no edit affordance when the canWrite prop is omitted (gate-closed default) (REQ-007)', () => {
+		render(WorldBand, { entry: historical({ eventId: HIST_EVENT_ID }) });
+		expect(document.querySelector('[data-testid="event-edit"]')).toBeNull();
+	});
+
+	it('shows no edit affordance when eventId is null even with canWrite (REQ-008)', () => {
+		render(WorldBand, { canWrite: true, entry: historical({ eventId: undefined }) });
+		expect(document.querySelector('[data-testid="event-edit"]')).toBeNull();
+	});
 });

frontend/src/lib/timeline/YearBand.svelte

@@ -3,8 +3,10 @@ import EventPill from './EventPill.svelte';
 import WorldBand from './WorldBand.svelte';
 import LetterCard from './LetterCard.svelte';
 import YearLetterStrip from './YearLetterStrip.svelte';
+import EventCluster from './EventCluster.svelte';
 import { isDense } from './timelineDensity';
 import { entryKey } from './entryKey';
+import { splitYearLetters, type EventCluster as EventClusterModel } from './eventClustering';
 import type { components } from '$lib/generated/api';
 
 type TimelineYearDTO = components['schemas']['TimelineYearDTO'];
@@ -12,37 +14,113 @@ type TimelineEntryDTO = components['schemas']['TimelineEntryDTO'];
 
 /**
  * One year of the timeline: a <section> with a sticky <h2> (REQ-006). Events
- * render in DTO order as pills/bands; letters render as individual cards while
- * the band holds ≤ 12 (REQ-011) or collapse to a single density strip above that
- * (REQ-012). Entries are never re-sorted — DTO order is preserved (REQ-003).
+ * render in DTO order as pills/world-bands; entries are never re-sorted (REQ-003).
+ *
+ * A curated event with letters linked to it (#850) becomes a contained event card:
+ * the event IS the card header and its linked letters sit inside (no separate pill —
+ * REQ-002). A curated event with letters in another year band renders here as a
+ * cross-year text-header card (REQ-004). An event with no linked letters stays a
+ * plain pill/world-band (REQ-005).
+ *
+ * Every other letter (no linkedEventId, or linking to an event the #780 layer filter
+ * removed) stays loose: alternating left/right while the band holds ≤ 12 such loose
+ * letters (REQ-006), folding into a single month-density strip above that (REQ-007).
+ * The loose-letter layout and the strip count ONLY these loose letters — clustered
+ * letters never re-appear loose (REQ-007).
  */
-let { year }: { year: TimelineYearDTO } = $props();
+let {
+	year,
+	canWrite = false,
+	eventLookup
+}: {
+	year: TimelineYearDTO;
+	canWrite?: boolean;
+	eventLookup?: Map<string, string>;
+} = $props();
 
 type Row =
 	| { t: 'event'; entry: TimelineEntryDTO }
+	| { t: 'eventcard'; event?: TimelineEntryDTO; cluster: EventClusterModel }
 	| { t: 'letter'; entry: TimelineEntryDTO; side: 'left' | 'right' }
 	| { t: 'strip' };
 
-const letters = $derived(year.entries.filter((e) => e.kind === 'LETTER'));
-const dense = $derived(isDense(letters.length));
+// Split this band's letters into event clusters and the loose remainder once; the loose
+// list alone drives the alternating layout and the density strip (REQ-007).
+const split = $derived(
+	splitYearLetters(
+		year.entries.filter((e) => e.kind === 'LETTER'),
+		eventLookup
+	)
+);
+const loose = $derived(split.loose);
+const dense = $derived(isDense(loose.length));
+// Clusters keyed by eventId (built once in splitYearLetters): row assembly looks a letter's
+// disposition up in O(1) — `byEvent.has(linkedEventId)` — instead of scanning the loose array
+// per letter (was O(L²) on a dense band), and resolves an event's card with `byEvent.get`.
+const byEvent = $derived(split.byEvent);
+
+// Event ids that have a same-year EVENT entry in THIS band: those clusters render as that
+// event's header (at the EVENT position); every other cluster is cross-year (REQ-004/015).
+const sameYearEventIds = $derived.by<Record<string, true>>(() => {
+	const ids: Record<string, true> = {};
+	for (const entry of year.entries) {
+		if (entry.kind === 'EVENT' && entry.eventId) ids[entry.eventId] = true;
+	}
+	return ids;
+});
 
 const rows = $derived.by<Row[]>(() => {
 	const out: Row[] = [];
+	const emitted: Record<string, true> = {};
 	let stripInserted = false;
 	let letterIndex = 0;
+
 	for (const entry of year.entries) {
 		if (entry.kind === 'EVENT') {
-			out.push({ t: 'event', entry });
-		} else if (!dense) {
-			out.push({ t: 'letter', entry, side: letterIndex % 2 === 0 ? 'left' : 'right' });
-			letterIndex += 1;
-		} else if (!stripInserted) {
-			out.push({ t: 'strip' });
-			stripInserted = true;
+			// A curated event whose letters live in THIS band becomes the contained card's
+			// header — its title reads once, no separate pill (REQ-002). Otherwise it stays a
+			// plain pill/world-band (REQ-005).
+			const cluster = entry.eventId ? byEvent.get(entry.eventId) : undefined;
+			if (cluster) {
+				out.push({ t: 'eventcard', event: entry, cluster });
+				emitted[cluster.eventId] = true;
+			} else {
+				out.push({ t: 'event', entry });
+			}
+			continue;
+		}
+
+		const cluster = entry.linkedEventId ? byEvent.get(entry.linkedEventId) : undefined;
+		if (!cluster) {
+			// A loose letter (not clustered): alternate while sparse, or fold the whole loose set
+			// into one density strip (inserted once, at the first loose letter) when dense.
+			if (!dense) {
+				out.push({ t: 'letter', entry, side: letterIndex % 2 === 0 ? 'left' : 'right' });
+				letterIndex += 1;
+			} else if (!stripInserted) {
+				out.push({ t: 'strip' });
+				stripInserted = true;
+			}
+			continue;
+		}
+
+		// A clustered letter. A same-year cluster is emitted at its EVENT entry, so skip it here.
+		// A cross-year cluster has no EVENT anchor in this band — emit its ✉ card HERE, at the
+		// position of its earliest linked letter, so the band stays in strict time order (REQ-015).
+		if (!sameYearEventIds[cluster.eventId] && !emitted[cluster.eventId]) {
+			out.push({ t: 'eventcard', cluster });
+			emitted[cluster.eventId] = true;
 		}
 	}
+
 	return out;
 });
+
+function rowKey(row: Row): string {
+	if (row.t === 'strip') return `strip-${year.year}`;
+	if (row.t === 'eventcard') return `evcard:${row.cluster.eventId}`;
+	return entryKey(row.entry);
+}
 </script>
 
 <section class="py-2">
@@ -56,20 +134,27 @@ const rows = $derived.by<Row[]>(() => {
 	</h2>
 
 	<div class="mt-3 space-y-3">
-		{#each rows as row (row.t === 'strip' ? `strip-${year.year}` : entryKey(row.entry))}
+		{#each rows as row (rowKey(row))}
 			{#if row.t === 'event'}
 				{#if row.entry.type === 'HISTORICAL'}
-					<WorldBand entry={row.entry} />
+					<WorldBand entry={row.entry} canWrite={canWrite} />
 				{:else}
-					<EventPill entry={row.entry} />
+					<EventPill entry={row.entry} canWrite={canWrite} />
 				{/if}
+			{:else if row.t === 'eventcard'}
+				<EventCluster
+					letters={row.cluster.letters}
+					event={row.event}
+					title={row.cluster.title}
+					canWrite={canWrite}
+				/>
 			{:else if row.t === 'letter'}
 				<div class="letter-row" data-side={row.side}>
 					<span data-testid="letter-dot" class="letter-dot bg-surface" aria-hidden="true"></span>
 					<LetterCard entry={row.entry} />
 				</div>
 			{:else}
-				<YearLetterStrip letters={letters} year={year.year} />
+				<YearLetterStrip letters={loose} year={year.year} />
 			{/if}
 		{/each}
 	</div>

frontend/src/lib/timeline/YearBand.svelte.spec.ts

@@ -165,3 +165,126 @@ describe('YearBand', () => {
 		}
 	});
 });
+
+describe('YearBand — inline event clustering (#850)', () => {
+	const EV_ID = 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa';
+
+	function curatedEvent(overrides = {}) {
+		return makeEntry({
+			kind: 'EVENT',
+			derived: false,
+			type: 'PERSONAL',
+			eventId: EV_ID,
+			eventDate: '1916-07-06',
+			precision: 'DAY',
+			title: 'Ein gewaltiger Stadtbrand',
+			senderName: '',
+			receiverName: '',
+			documentId: undefined,
+			...overrides
+		});
+	}
+
+	function linkedLetters(year: number, count: number, eventId = EV_ID) {
+		return Array.from({ length: count }, (_, i) =>
+			makeEntry({
+				eventDate: `${year}-05-10`,
+				documentId: `linked-${i}`,
+				title: `Brief ${i}`,
+				linkedEventId: eventId
+			})
+		);
+	}
+
+	const lookup = new Map([[EV_ID, 'Ein gewaltiger Stadtbrand']]);
+
+	it('renders a curated event with a same-year linked letter as one event-card, title once, no separate pill (REQ-002)', () => {
+		render(YearBand, {
+			year: makeYear(1916, [curatedEvent(), ...linkedLetters(1916, 1)]),
+			eventLookup: lookup
+		});
+		expect(document.querySelectorAll('[data-testid="event-card"]')).toHaveLength(1);
+		const titles = (document.body.textContent?.match(/Ein gewaltiger Stadtbrand/g) ?? []).length;
+		expect(titles).toBe(1);
+		// the letter is inside the card, not a loose .letter-row
+		expect(document.querySelector('a.lcard.ev')).not.toBeNull();
+		expect(document.querySelector('.letter-row')).toBeNull();
+		// no plain EventPill for it (the pill is the only floating .rounded-full wrapper)
+		expect(document.querySelector('.justify-center .rounded-full.border-brand-mint')).toBeNull();
+	});
+
+	it('renders a curated event with NO linked letters as a plain EventPill, no card (REQ-005)', () => {
+		render(YearBand, {
+			year: makeYear(1916, [curatedEvent()]),
+			eventLookup: lookup
+		});
+		expect(document.querySelector('[data-testid="event-card"]')).toBeNull();
+		// the curated EventPill is the bordered floating rounded-full wrapper
+		expect(
+			document.querySelector('.justify-center .rounded-full.border-brand-mint')
+		).not.toBeNull();
+		expect(document.body.textContent).toContain('Ein gewaltiger Stadtbrand');
+	});
+
+	it('renders loose (unlinked) letters in a sparse year as alternating .letter-row, no card (REQ-006)', () => {
+		const loose = manyLetters(1916, 3); // no linkedEventId
+		render(YearBand, { year: makeYear(1916, loose), eventLookup: lookup });
+		expect(document.querySelectorAll('.letter-row')).toHaveLength(3);
+		expect(document.querySelector('[data-testid="event-card"]')).toBeNull();
+	});
+
+	it('counts only loose letters in the density strip; event letters stay in the card (REQ-006/007)', () => {
+		// 15 loose letters fold into one strip; a 3-letter event card shows its 3.
+		const loose = manyLetters(1916, 15);
+		const year = makeYear(1916, [curatedEvent(), ...linkedLetters(1916, 3), ...loose]);
+		render(YearBand, { year, eventLookup: lookup });
+		// the event card holds 3 letters
+		expect(document.querySelectorAll('a.lcard.ev')).toHaveLength(3);
+		// the loose letters fold into exactly one density strip
+		const strips = document.querySelectorAll('[data-testid="strip-expand"]');
+		expect(strips).toHaveLength(1);
+		// the strip card's count text is 15 (the loose letters), not 18 (REQ-006/007)
+		const stripCard = strips[0].closest('.max-w-md') as HTMLElement;
+		expect(stripCard.textContent).toContain('15');
+		expect(stripCard.textContent).not.toContain('18');
+	});
+
+	it('renders a cross-year cluster (event not in this band) as a ✉ text-header card holding it (REQ-004)', () => {
+		// The event id is in eventLookup but no matching EVENT entry sits in this band.
+		render(YearBand, {
+			year: makeYear(1917, linkedLetters(1917, 2)),
+			eventLookup: lookup
+		});
+		const card = document.querySelector('[data-testid="event-card"]');
+		expect(card).not.toBeNull();
+		expect(document.body.textContent).toContain('✉');
+		expect(document.body.textContent).toContain('Ein gewaltiger Stadtbrand');
+		// cross-year card carries no edit link and no pill
+		expect(document.querySelector('[data-testid="event-edit"]')).toBeNull();
+		expect(document.querySelector('.justify-center .rounded-full.border-brand-mint')).toBeNull();
+	});
+
+	it('interleaves a cross-year card before a later-dated loose letter in the same band (REQ-015)', () => {
+		// Chronological band order (what the backend delivers): a February cross-year letter, then
+		// a November loose letter. The cross-year card must sit at its earliest letter's position —
+		// before the November loose letter — so the band still reads in strict time order.
+		const febLinked = makeEntry({
+			eventDate: '1917-02-10',
+			documentId: 'feb-linked',
+			title: 'Feldpostbrief',
+			linkedEventId: EV_ID
+		});
+		const novLoose = makeEntry({
+			eventDate: '1917-11-20',
+			documentId: 'nov-loose',
+			title: 'Brief im November'
+		});
+		render(YearBand, { year: makeYear(1917, [febLinked, novLoose]), eventLookup: lookup });
+		const card = document.querySelector('[data-testid="event-card"]') as HTMLElement;
+		const looseLink = document.querySelector('a[href="/documents/nov-loose"]') as HTMLElement;
+		expect(card).not.toBeNull();
+		expect(looseLink).not.toBeNull();
+		// the cross-year card precedes the later-dated loose letter in DOM order
+		expect(card.compareDocumentPosition(looseLink) & Node.DOCUMENT_POSITION_FOLLOWING).toBeTruthy();
+	});
+});

frontend/src/lib/timeline/eventCardConfig.spec.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { getAccentConfig } from './eventCardConfig';
+import { getAccentConfig, canEditEvent } from './eventCardConfig';
 import type { components } from '$lib/generated/api';
 
 type TimelineEntryDTO = components['schemas']['TimelineEntryDTO'];
@@ -51,3 +51,24 @@ describe('getAccentConfig', () => {
 		expect(cfg.accent).toBe('curated');
 	});
 });
+
+// The single source of the curator edit-affordance gate (CLAUDE.md's TimelineEntryDTO contract):
+// a curated event shows its edit pencil only for a writer, never for a derived life-event or a
+// null eventId. Shared by EventPill, WorldBand, and EventCluster (#850 finding #5).
+describe('canEditEvent', () => {
+	it('allows a writer to edit a curated event with an eventId', () => {
+		expect(canEditEvent(event({ derived: false, eventId: 'e-1' }), true)).toBe(true);
+	});
+
+	it('denies a viewer without write permission', () => {
+		expect(canEditEvent(event({ derived: false, eventId: 'e-1' }), false)).toBe(false);
+	});
+
+	it('denies a derived life-event even for a writer', () => {
+		expect(canEditEvent(event({ derived: true, eventId: 'e-1' }), true)).toBe(false);
+	});
+
+	it('denies an event with no eventId even for a writer', () => {
+		expect(canEditEvent(event({ derived: false, eventId: undefined }), true)).toBe(false);
+	});
+});

frontend/src/lib/timeline/eventCardConfig.ts

@@ -36,3 +36,16 @@ export function getAccentConfig(entry: TimelineEntryDTO): AccentConfig {
 	}
 	return { glyph: '★', label: m.timeline_layer_family(), accent: 'curated' };
 }
+
+/**
+ * The curator edit-affordance gate, in one place — the security-relevant contract documented on
+ * CLAUDE.md's `TimelineEntryDTO` row (`derived || eventId == null` → no edit link). A curated
+ * event's edit pencil shows only for a viewer with WRITE_ALL (`canWrite`), and only when it is a
+ * real curated event: never a derived life-event (nothing to edit) and never a null `eventId`.
+ * HISTORICAL events are never derived, so this also covers the world band. The gate is UX only —
+ * the #781 route guard + backend permission are the real boundary. Shared by EventPill, WorldBand,
+ * and EventCluster so the gate has a single source of truth (#850 finding #5).
+ */
+export function canEditEvent(entry: TimelineEntryDTO, canWrite: boolean): boolean {
+	return canWrite && !entry.derived && entry.eventId != null;
+}

frontend/src/lib/timeline/eventClustering.spec.ts

@@ -0,0 +1,141 @@
+import { describe, it, expect } from 'vitest';
+import { buildEventLookup, splitYearLetters, CLUSTER_PREVIEW } from './eventClustering';
+import { makeEntry } from './test-factories';
+import type { components } from '$lib/generated/api';
+
+type TimelineDTO = components['schemas']['TimelineDTO'];
+type TimelineEntryDTO = components['schemas']['TimelineEntryDTO'];
+
+const EV_A = 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa';
+const EV_B = 'bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb';
+
+const makeEvent = (overrides: Partial<TimelineEntryDTO> = {}): TimelineEntryDTO =>
+	makeEntry({ kind: 'EVENT', type: 'PERSONAL', documentId: undefined, ...overrides });
+
+describe('eventClustering — buildEventLookup', () => {
+	it('maps a curated year-band event to its title, excluding undated-bucket events (#7)', () => {
+		const timeline: TimelineDTO = {
+			years: [
+				{
+					year: 1916,
+					entries: [makeEvent({ eventId: EV_A, title: 'Ein gewaltiger Stadtbrand' })]
+				}
+			],
+			undated: [makeEvent({ eventId: EV_B, title: 'Briefe von der Front' })]
+		};
+		const lookup = buildEventLookup(timeline);
+		expect(lookup.get(EV_A)).toBe('Ein gewaltiger Stadtbrand');
+		// An undated event renders as a plain pill in the undated bucket — out of clustering
+		// scope. Including it here would scatter its dated letters into orphaned ✉ cross-year
+		// cards detached from the pill (#7), so it must NOT enter the lookup.
+		expect(lookup.has(EV_B)).toBe(false);
+		expect(lookup.size).toBe(1);
+	});
+
+	it('ignores derived events (no eventId) and letters', () => {
+		const timeline: TimelineDTO = {
+			years: [
+				{
+					year: 1916,
+					entries: [
+						makeEvent({ eventId: undefined, title: 'Geburt' }), // derived
+						makeEntry({ kind: 'LETTER', documentId: 'doc-1' })
+					]
+				}
+			],
+			undated: []
+		};
+		expect(buildEventLookup(timeline).size).toBe(0);
+	});
+
+	it('excludes a HISTORICAL event so its letters stay loose, keeping its WorldBand (REQ-014)', () => {
+		const timeline: TimelineDTO = {
+			years: [
+				{ year: 1916, entries: [makeEvent({ eventId: EV_A, type: 'HISTORICAL', title: 'Somme' })] }
+			],
+			undated: []
+		};
+		const lookup = buildEventLookup(timeline);
+		expect(lookup.has(EV_A)).toBe(false);
+		expect(lookup.size).toBe(0);
+	});
+
+	it('skips an event with an empty or whitespace title — no bare ✉ card (#8)', () => {
+		const timeline: TimelineDTO = {
+			years: [
+				{
+					year: 1916,
+					entries: [
+						makeEvent({ eventId: EV_A, title: '' }),
+						makeEvent({ eventId: EV_B, title: '   ' })
+					]
+				}
+			],
+			undated: []
+		};
+		expect(buildEventLookup(timeline).size).toBe(0);
+	});
+});
+
+describe('eventClustering — splitYearLetters', () => {
+	it('exposes a CLUSTER_PREVIEW of 5', () => {
+		expect(CLUSTER_PREVIEW).toBe(5);
+	});
+
+	it('clusters letters by linkedEventId with matching counts', () => {
+		const lookup = new Map([[EV_A, 'Stadtbrand']]);
+		const letters = [
+			makeEntry({ kind: 'LETTER', documentId: 'd1', linkedEventId: EV_A }),
+			makeEntry({ kind: 'LETTER', documentId: 'd2', linkedEventId: EV_A })
+		];
+		const { clusters, loose } = splitYearLetters(letters, lookup);
+		expect(clusters).toHaveLength(1);
+		expect(clusters[0].eventId).toBe(EV_A);
+		expect(clusters[0].title).toBe('Stadtbrand');
+		expect(clusters[0].letters).toHaveLength(2);
+		expect(loose).toHaveLength(0);
+	});
+
+	it('keeps a letter with no linkedEventId loose', () => {
+		const lookup = new Map([[EV_A, 'Stadtbrand']]);
+		const letters = [makeEntry({ kind: 'LETTER', documentId: 'd1', linkedEventId: undefined })];
+		const { clusters, loose } = splitYearLetters(letters, lookup);
+		expect(clusters).toHaveLength(0);
+		expect(loose).toHaveLength(1);
+	});
+
+	it('keeps a letter whose linkedEventId is absent from the lookup loose (filter-then-cluster, REQ-008)', () => {
+		const lookup = new Map([[EV_A, 'Stadtbrand']]);
+		const letters = [makeEntry({ kind: 'LETTER', documentId: 'd1', linkedEventId: EV_B })];
+		const { clusters, loose } = splitYearLetters(letters, lookup);
+		expect(clusters).toHaveLength(0);
+		expect(loose).toHaveLength(1);
+	});
+
+	it('places each letter in exactly one place (REQ-007)', () => {
+		const lookup = new Map([[EV_A, 'Stadtbrand']]);
+		const letters = [
+			makeEntry({ kind: 'LETTER', documentId: 'd1', linkedEventId: EV_A }),
+			makeEntry({ kind: 'LETTER', documentId: 'd2', linkedEventId: undefined }),
+			makeEntry({ kind: 'LETTER', documentId: 'd3', linkedEventId: EV_B })
+		];
+		const { clusters, loose } = splitYearLetters(letters, lookup);
+		const clustered = clusters.flatMap((c) => c.letters.length).reduce((a, b) => a + b, 0);
+		expect(clustered + loose.length).toBe(3);
+		expect(clustered).toBe(1);
+		expect(loose).toHaveLength(2);
+	});
+
+	it('keeps clusters in first-seen order', () => {
+		const lookup = new Map([
+			[EV_B, 'Front'],
+			[EV_A, 'Stadtbrand']
+		]);
+		const letters = [
+			makeEntry({ kind: 'LETTER', documentId: 'd1', linkedEventId: EV_A }),
+			makeEntry({ kind: 'LETTER', documentId: 'd2', linkedEventId: EV_B })
+		];
+		const { clusters } = splitYearLetters(letters, lookup);
+		expect(clusters.map((c) => c.eventId)).toEqual([EV_A, EV_B]);
+	});
+});

frontend/src/lib/timeline/eventClustering.ts

@@ -0,0 +1,88 @@
+import type { components } from '$lib/generated/api';
+
+type TimelineDTO = components['schemas']['TimelineDTO'];
+type TimelineEntryDTO = components['schemas']['TimelineEntryDTO'];
+
+/** Letters shown inside an event card before a "show more" toggle appears (#850, REQ-003). */
+export const CLUSTER_PREVIEW = 5;
+
+/** One contained event card's worth of letters within a year band (#850). */
+export interface EventCluster {
+	/** The curated event's id — also the `{#each}` key. */
+	eventId: string;
+	/** The curated event's title (from the event lookup). */
+	title: string;
+	letters: TimelineEntryDTO[];
+}
+
+/** The result of splitting a year's letters into event clusters and the loose remainder. */
+export interface SplitLetters {
+	clusters: EventCluster[];
+	loose: TimelineEntryDTO[];
+	/** Clusters keyed by `eventId` for O(1) lookup during row assembly (a letter's disposition is
+	 *  `byEvent.has(linkedEventId)`; an event's card is `byEvent.get(eventId)`). */
+	byEvent: Map<string, EventCluster>;
+}
+
+/**
+ * Maps each curated event present in the (already layer-filtered) timeline to its title. These
+ * are the only events a letter may cluster under — a letter whose `linkedEventId` is absent here
+ * links to an event the #780 layer filter removed, so it falls back to a loose chronological
+ * letter (filter-then-cluster, REQ-008). Curated PERSONAL events carry an `eventId`; derived
+ * life-events and letters do not, so they never enter the lookup. HISTORICAL events are excluded
+ * too: a world event always keeps its full-width WorldBand and never clusters, even with linked
+ * letters (REQ-014) — those letters stay loose.
+ *
+ * Only year-band events are collected: an undated event renders as a plain pill in the undated
+ * bucket (out of clustering scope), so including it would scatter its dated letters into orphaned
+ * cross-year cards detached from that pill (#7).
+ *
+ * An event with an empty/whitespace title is skipped too — clustering under it would render a
+ * label-less `✉` mystery card; its letters stay loose instead (#8).
+ */
+export function buildEventLookup(timeline: TimelineDTO): Map<string, string> {
+	const lookup = new Map<string, string>();
+	const collect = (entries: TimelineEntryDTO[]) => {
+		for (const entry of entries) {
+			const title = entry.title?.trim();
+			if (entry.kind === 'EVENT' && entry.eventId && entry.type !== 'HISTORICAL' && title) {
+				lookup.set(entry.eventId, title);
+			}
+		}
+	};
+	for (const band of timeline.years) collect(band.entries);
+	return lookup;
+}
+
+/**
+ * Splits one year's `LETTER` entries into event clusters and the loose remainder. A letter joins
+ * the cluster keyed by its `linkedEventId` IFF that id is set AND present in `eventLookup`
+ * (filter-then-cluster, REQ-007/008); every other letter is loose and stays in the chronological
+ * flow (REQ-006). Clusters keep first-seen order; each letter appears in exactly one place.
+ */
+export function splitYearLetters(
+	letters: TimelineEntryDTO[],
+	eventLookup?: Map<string, string>
+): SplitLetters {
+	const byEvent = new Map<string, EventCluster>();
+	const clusters: EventCluster[] = [];
+	const loose: TimelineEntryDTO[] = [];
+
+	for (const letter of letters) {
+		const eventId = letter.linkedEventId;
+		const title = eventId != null ? eventLookup?.get(eventId) : undefined;
+		if (eventId != null && title !== undefined) {
+			let cluster = byEvent.get(eventId);
+			if (!cluster) {
+				cluster = { eventId, title, letters: [] };
+				byEvent.set(eventId, cluster);
+				clusters.push(cluster);
+			}
+			cluster.letters.push(letter);
+		} else {
+			loose.push(letter);
+		}
+	}
+
+	return { clusters, loose, byEvent };
+}

frontend/src/lib/timeline/timeline-no-raw-html.spec.ts

@@ -0,0 +1,24 @@
+import { describe, it, expect } from 'vitest';
+import { readdirSync, readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const timelineDir = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * REQ-010 / CWE-79: inline event clustering renders curator event titles and import-derived
+ * letter titles + sender/receiver text through every component under lib/timeline (the reused
+ * LetterCard, the new EventCluster card, the existing pills/bands/strip). That text must always
+ * render through Svelte's default `{...}` escaping — never `{@html}`. This grep gate fails loudly
+ * the moment any timeline component reaches for the raw-HTML directive.
+ */
+describe('lib/timeline never uses {@html} (REQ-010)', () => {
+	it('no timeline component contains the raw-HTML directive', () => {
+		const components = readdirSync(timelineDir).filter((file) => file.endsWith('.svelte'));
+		expect(components.length).toBeGreaterThan(0);
+		const offenders = components.filter((file) =>
+			readFileSync(join(timelineDir, file), 'utf8').includes('{@html')
+		);
+		expect(offenders).toEqual([]);
+	});
+});

frontend/src/lib/timeline/timelineFilter.spec.ts

@@ -0,0 +1,151 @@
+import { describe, it, expect } from 'vitest';
+import {
+	isDefaultState,
+	hiddenLayerCount,
+	filterTimeline,
+	ALL_LAYERS_ON,
+	type TimelineLayerFilters
+} from './timelineFilter';
+import { makeEntry, makeYear, makeTimelineDTO } from './test-factories';
+
+// Entry factories pinned to the three layers the filter discriminates (#780).
+const letter = (overrides = {}) => makeEntry({ kind: 'LETTER', ...overrides });
+
+const curatedPersonal = (overrides = {}) =>
+	makeEntry({
+		kind: 'EVENT',
+		type: 'PERSONAL',
+		derived: false,
+		documentId: undefined,
+		title: 'Umzug nach Berlin',
+		senderName: '',
+		receiverName: '',
+		...overrides
+	});
+
+// Derived life-events carry type=PERSONAL (issue #776 REQ-009) — they belong to
+// the Personal layer, not a fourth one.
+const derivedLifeEvent = (overrides = {}) =>
+	makeEntry({
+		kind: 'EVENT',
+		type: 'PERSONAL',
+		derived: true,
+		derivedType: 'BIRTH',
+		documentId: undefined,
+		title: 'Geburt',
+		senderName: '',
+		receiverName: '',
+		...overrides
+	});
+
+const historical = (overrides = {}) =>
+	makeEntry({
+		kind: 'EVENT',
+		type: 'HISTORICAL',
+		derived: false,
+		documentId: undefined,
+		title: 'Erster Weltkrieg',
+		senderName: '',
+		receiverName: '',
+		...overrides
+	});
+
+const off = (overrides: Partial<TimelineLayerFilters>): TimelineLayerFilters => ({
+	...ALL_LAYERS_ON,
+	...overrides
+});
+
+describe('isDefaultState (REQ-007)', () => {
+	it('is true when all three layers are on', () => {
+		expect(isDefaultState(ALL_LAYERS_ON)).toBe(true);
+	});
+
+	it('is false when any single layer is off', () => {
+		expect(isDefaultState(off({ personalOn: false }))).toBe(false);
+		expect(isDefaultState(off({ historicalOn: false }))).toBe(false);
+		expect(isDefaultState(off({ lettersOn: false }))).toBe(false);
+	});
+});
+
+describe('hiddenLayerCount (REQ-007)', () => {
+	it('is 0 in the default all-on state', () => {
+		expect(hiddenLayerCount(ALL_LAYERS_ON)).toBe(0);
+	});
+
+	it('counts each layer that is off', () => {
+		expect(hiddenLayerCount(off({ lettersOn: false }))).toBe(1);
+		expect(hiddenLayerCount(off({ personalOn: false, historicalOn: false }))).toBe(2);
+		expect(hiddenLayerCount({ personalOn: false, historicalOn: false, lettersOn: false })).toBe(3);
+	});
+});
+
+describe('filterTimeline', () => {
+	it('returns every entry unchanged in the default all-on state', () => {
+		const dto = makeTimelineDTO({
+			years: [makeYear(1915, [letter(), historical(), curatedPersonal()])],
+			undated: [letter({ documentId: 'u1' })]
+		});
+		const result = filterTimeline(dto, ALL_LAYERS_ON);
+		expect(result.years[0].entries).toHaveLength(3);
+		expect(result.undated).toHaveLength(1);
+	});
+
+	it('hides LETTER entries when lettersOn is false, keeping events (REQ-005)', () => {
+		const dto = makeTimelineDTO({
+			years: [makeYear(1915, [letter(), historical(), curatedPersonal()])],
+			undated: [letter({ documentId: 'u1' })]
+		});
+		const result = filterTimeline(dto, off({ lettersOn: false }));
+		expect(result.years[0].entries.every((e) => e.kind !== 'LETTER')).toBe(true);
+		expect(result.years[0].entries).toHaveLength(2);
+		expect(result.undated).toHaveLength(0);
+	});
+
+	it('hides HISTORICAL events when historicalOn is false, keeping personal + letters (REQ-004)', () => {
+		const dto = makeTimelineDTO({
+			years: [makeYear(1915, [letter(), historical(), curatedPersonal(), derivedLifeEvent()])]
+		});
+		const result = filterTimeline(dto, off({ historicalOn: false }));
+		const kept = result.years[0].entries;
+		expect(kept.some((e) => e.kind === 'EVENT' && e.type === 'HISTORICAL')).toBe(false);
+		expect(kept.some((e) => e.kind === 'LETTER')).toBe(true);
+		expect(kept.some((e) => e.kind === 'EVENT' && e.type === 'PERSONAL')).toBe(true);
+		expect(kept).toHaveLength(3);
+	});
+
+	it('hides personal events — curated and derived — when personalOn is false (REQ-003)', () => {
+		const dto = makeTimelineDTO({
+			years: [makeYear(1915, [letter(), historical(), curatedPersonal(), derivedLifeEvent()])]
+		});
+		const result = filterTimeline(dto, off({ personalOn: false }));
+		const kept = result.years[0].entries;
+		// neither the curated PERSONAL event nor the derived life-event survives
+		expect(kept.some((e) => e.kind === 'EVENT' && e.type === 'PERSONAL')).toBe(false);
+		expect(kept.some((e) => e.derived)).toBe(false);
+		// historical events and letters are untouched
+		expect(kept.some((e) => e.kind === 'EVENT' && e.type === 'HISTORICAL')).toBe(true);
+		expect(kept.some((e) => e.kind === 'LETTER')).toBe(true);
+		expect(kept).toHaveLength(2);
+	});
+
+	it('drops year bands that become empty and filters the undated bucket (REQ-006)', () => {
+		const dto = makeTimelineDTO({
+			years: [
+				makeYear(1915, [letter()]), // becomes empty when letters are hidden
+				makeYear(1918, [historical()]) // survives
+			],
+			undated: [letter({ documentId: 'u1' }), historical({ documentId: undefined })]
+		});
+		const result = filterTimeline(dto, off({ lettersOn: false }));
+		expect(result.years).toHaveLength(1);
+		expect(result.years[0].year).toBe(1918);
+		expect(result.undated.every((e) => e.kind !== 'LETTER')).toBe(true);
+		expect(result.undated).toHaveLength(1);
+	});
+
+	it('does not mutate the input timeline', () => {
+		const dto = makeTimelineDTO({ years: [makeYear(1915, [letter(), historical()])] });
+		filterTimeline(dto, off({ lettersOn: false }));
+		expect(dto.years[0].entries).toHaveLength(2);
+	});
+});

frontend/src/lib/timeline/timelineFilter.ts

@@ -0,0 +1,63 @@
+import type { components } from '$lib/generated/api';
+
+type TimelineDTO = components['schemas']['TimelineDTO'];
+type TimelineEntryDTO = components['schemas']['TimelineEntryDTO'];
+
+/**
+ * The three visibility layers a reader can toggle on the global `/zeitstrahl`
+ * (#780). Purely a presentation concern — the whole timeline is loaded once by
+ * #779; these toggles derive a client-side filtered view of it.
+ */
+export interface TimelineLayerFilters {
+	/** Personal events — curated `PERSONAL` events and derived life-events. */
+	personalOn: boolean;
+	/** Historical events (`type === 'HISTORICAL'`). */
+	historicalOn: boolean;
+	/** Letters (`kind === 'LETTER'`). */
+	lettersOn: boolean;
+}
+
+/** The default view: every layer visible. */
+export const ALL_LAYERS_ON: TimelineLayerFilters = {
+	personalOn: true,
+	historicalOn: true,
+	lettersOn: true
+};
+
+/** True when no layer is hidden — the default, all-on state (REQ-007). */
+export function isDefaultState(filters: TimelineLayerFilters): boolean {
+	return filters.personalOn && filters.historicalOn && filters.lettersOn;
+}
+
+/** How many layers are currently hidden — the "N active" trigger count (REQ-007). */
+export function hiddenLayerCount(filters: TimelineLayerFilters): number {
+	return (
+		(filters.personalOn ? 0 : 1) + (filters.historicalOn ? 0 : 1) + (filters.lettersOn ? 0 : 1)
+	);
+}
+
+/**
+ * Decides whether one entry survives the active layer toggles. A letter rides
+ * the Letters layer; a historical event the Historical layer; everything else
+ * (curated `PERSONAL` events and derived life-events, which also carry
+ * `type === 'PERSONAL'`) the Personal layer.
+ */
+function isVisible(entry: TimelineEntryDTO, filters: TimelineLayerFilters): boolean {
+	if (entry.kind === 'LETTER') return filters.lettersOn;
+	if (entry.type === 'HISTORICAL') return filters.historicalOn;
+	return filters.personalOn;
+}
+
+/**
+ * Derives a client-side filtered copy of the timeline (REQ-003/004/005/006).
+ * Year bands left empty by the active toggles are dropped so `TimelineView`
+ * never renders a hollow band, and the undated bucket is filtered the same way.
+ * Pure — the input DTO is never mutated.
+ */
+export function filterTimeline(timeline: TimelineDTO, filters: TimelineLayerFilters): TimelineDTO {
+	const years = timeline.years
+		.map((band) => ({ ...band, entries: band.entries.filter((e) => isVisible(e, filters)) }))
+		.filter((band) => band.entries.length > 0);
+	const undated = timeline.undated.filter((e) => isVisible(e, filters));
+	return { years, undated };
+}

frontend/src/lib/timeline/timelineFilterBoundary.spec.ts

@@ -0,0 +1,37 @@
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+// REQ-001/002: the layer filter is presentation-only and fully client-side. It
+// must never navigate or fetch — the route derives the filtered view from
+// already-loaded data. This static guard mirrors the project's existing
+// grep-gates (e.g. the no-`{@html}` checks) and fails the build if a future
+// edit reintroduces navigation or a network call into either file.
+const read = (relative: string) =>
+	readFileSync(fileURLToPath(new URL(relative, import.meta.url)), 'utf8');
+
+const FILES = {
+	'TimelineFilters.svelte': read('./TimelineFilters.svelte'),
+	'/zeitstrahl/+page.svelte': read('../../routes/zeitstrahl/+page.svelte')
+};
+
+const FORBIDDEN: { label: string; pattern: RegExp }[] = [
+	{ label: 'goto(', pattern: /\bgoto\s*\(/ },
+	{ label: 'url.searchParams', pattern: /url\.searchParams/ },
+	{ label: 'api.GET', pattern: /\bapi\.GET\b/ },
+	{ label: 'fetch(', pattern: /\bfetch\s*\(/ }
+];
+
+describe('layer-filter boundary (REQ-001/002)', () => {
+	for (const [name, source] of Object.entries(FILES)) {
+		it(`${name} was found and is non-empty`, () => {
+			expect(source.length).toBeGreaterThan(0);
+		});
+
+		for (const { label, pattern } of FORBIDDEN) {
+			it(`${name} contains no ${label}`, () => {
+				expect(pattern.test(source), `${name} must not use ${label}`).toBe(false);
+			});
+		}
+	}
+});

frontend/src/routes/persons/[id]/PersonCard.svelte

@@ -128,7 +128,8 @@ const deathText = $derived(formatLifeDate(person.deathDate, person.deathDatePrec
 			</div>
 		{/if}
 
-		<!-- Edit button — full width, outlined -->
+		<!-- Curator actions — full width, outlined. Both links are gated to
+		     WRITE_ALL; the gate is UX only (the #781 route guard is the boundary). -->
 		{#if canWrite}
 			<a
 				href="/persons/{person.id}/edit"
@@ -142,6 +143,15 @@ const deathText = $derived(formatLifeDate(person.deathDate, person.deathDatePrec
 				/>
 				{m.btn_edit()}
 			</a>
+			<!-- Opens #781's create form pre-seeded with this person; on save it
+			     returns to /persons/{id} (originPersonId). #842 REQ-003/010. -->
+			<a
+				data-testid="person-add-event"
+				href="/zeitstrahl/events/new?personId={person.id}"
+				class="mt-2 flex min-h-[44px] w-full items-center justify-center rounded border border-line px-3 py-2 font-sans text-xs font-bold tracking-widest text-ink-2 uppercase transition-colors hover:border-primary hover:text-ink"
+			>
+				{m.person_add_event()}
+			</a>
 		{/if}
 	</div>
 </div>

frontend/src/routes/persons/[id]/PersonCard.svelte.spec.ts

@@ -0,0 +1,32 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import { cleanup, render } from 'vitest-browser-svelte';
+import PersonCard from './PersonCard.svelte';
+
+afterEach(() => cleanup());
+
+const PERSON_ID = '55555555-5555-5555-5555-555555555555';
+
+const makePerson = (overrides = {}) => ({
+	id: PERSON_ID,
+	firstName: 'Karl',
+	lastName: 'Raddatz',
+	displayName: 'Karl Raddatz',
+	personType: 'PERSON',
+	...overrides
+});
+
+describe('PersonCard add-event affordance (#842)', () => {
+	it('shows an add-event link pre-seeded with the person to a curator (REQ-003)', () => {
+		render(PersonCard, { person: makePerson(), canWrite: true });
+		const add = document.querySelector(
+			'[data-testid="person-add-event"]'
+		) as HTMLAnchorElement | null;
+		expect(add).not.toBeNull();
+		expect(add?.getAttribute('href')).toBe(`/zeitstrahl/events/new?personId=${PERSON_ID}`);
+	});
+
+	it('renders no add-event link to a reader (REQ-004)', () => {
+		render(PersonCard, { person: makePerson(), canWrite: false });
+		expect(document.querySelector('[data-testid="person-add-event"]')).toBeNull();
+	});
+});

frontend/src/routes/persons/[id]/PersonRelationshipsCard.svelte

@@ -1,6 +1,7 @@
 <script lang="ts">
 import { m } from '$lib/paraglide/messages.js';
 import { chipLabel, otherName, inferredRelationshipLabel } from '$lib/person/relationshipLabels';
+import { formatRelationshipDateRange } from '$lib/person/relationshipDates';
 import type { components } from '$lib/generated/api';
 
 type RelationshipDTO = components['schemas']['RelationshipDTO'];
@@ -35,18 +36,37 @@ function otherId(rel: RelationshipDTO): string {
 		{#if relationships.length > 0}
 			<ul class="mb-4 space-y-2">
 				{#each relationships as rel (rel.id)}
-					<li class="flex items-center gap-2">
-						<span
-							class="inline-flex shrink-0 items-center rounded-full border border-accent/40 bg-accent/15 px-2 py-0.5 font-sans text-xs font-bold tracking-widest text-ink uppercase"
-						>
-							{chipLabel(rel, personId)}
-						</span>
-						<a
-							href="/persons/{otherId(rel)}"
-							class="min-w-0 flex-1 truncate font-serif text-sm text-ink hover:underline"
-						>
-							{otherName(rel, personId)}
-						</a>
+					{@const dateRange = formatRelationshipDateRange(
+						rel.fromDate,
+						rel.fromDatePrecision,
+						rel.toDate,
+						rel.toDatePrecision
+					)}
+					<li class="flex flex-col gap-0.5">
+						<div class="flex items-center gap-2">
+							<span
+								class="inline-flex shrink-0 items-center rounded-full border border-accent/40 bg-accent/15 px-2 py-0.5 font-sans text-xs font-bold tracking-widest text-ink uppercase"
+							>
+								{chipLabel(rel, personId)}
+							</span>
+							<a
+								href="/persons/{otherId(rel)}"
+								class="min-w-0 flex-1 truncate font-serif text-sm text-ink hover:underline"
+							>
+								{otherName(rel, personId)}
+							</a>
+							{#if dateRange}
+								<span
+									class="shrink-0 font-sans text-xs text-ink-3"
+									data-testid="relationship-date-range">{dateRange}</span
+								>
+							{/if}
+						</div>
+						{#if rel.notes}
+							<p class="pl-1 font-serif text-xs text-ink-2 italic" data-testid="relationship-notes">
+								{rel.notes}
+							</p>
+						{/if}
 					</li>
 				{/each}
 			</ul>

frontend/src/routes/persons/[id]/PersonRelationshipsCard.svelte.test.ts

@@ -18,7 +18,9 @@ describe('PersonRelationshipsCard', () => {
 					relatedPersonId: SPOUSE_ID,
 					personDisplayName: 'Anna Müller',
 					relatedPersonDisplayName: 'Bertha Müller',
-					relationType: 'SPOUSE_OF'
+					relationType: 'SPOUSE_OF',
+					fromDatePrecision: 'UNKNOWN',
+					toDatePrecision: 'UNKNOWN'
 				}
 			],
 			inferredRelationships: [
@@ -65,7 +67,9 @@ describe('PersonRelationshipsCard', () => {
 					relatedPersonId: PARENT_ID,
 					personDisplayName: 'Anna Müller',
 					relatedPersonDisplayName: 'Kind Müller',
-					relationType: 'PARENT_OF'
+					relationType: 'PARENT_OF',
+					fromDatePrecision: 'UNKNOWN',
+					toDatePrecision: 'UNKNOWN'
 				}
 			],
 			inferredRelationships: []
@@ -84,7 +88,9 @@ describe('PersonRelationshipsCard', () => {
 					relatedPersonId: SPOUSE_ID,
 					personDisplayName: 'Anna',
 					relatedPersonDisplayName: 'Bertha',
-					relationType: 'SPOUSE_OF'
+					relationType: 'SPOUSE_OF',
+					fromDatePrecision: 'UNKNOWN',
+					toDatePrecision: 'UNKNOWN'
 				}
 			],
 			inferredRelationships: [
@@ -113,7 +119,9 @@ describe('PersonRelationshipsCard', () => {
 					relatedPersonId: PERSON_ID,
 					personDisplayName: 'Eltern Müller',
 					relatedPersonDisplayName: 'Anna Müller',
-					relationType: 'PARENT_OF'
+					relationType: 'PARENT_OF',
+					fromDatePrecision: 'UNKNOWN',
+					toDatePrecision: 'UNKNOWN'
 				}
 			],
 			inferredRelationships: []
@@ -121,4 +129,74 @@ describe('PersonRelationshipsCard', () => {
 
 		await expect.element(page.getByText('Kind von')).toBeInTheDocument();
 	});
+
+	it('renders the date range at its stored precision', async () => {
+		render(PersonRelationshipsCard, {
+			personId: PERSON_ID,
+			relationships: [
+				{
+					id: 'r1',
+					personId: PERSON_ID,
+					relatedPersonId: SPOUSE_ID,
+					personDisplayName: 'Anna Müller',
+					relatedPersonDisplayName: 'Bertha Müller',
+					relationType: 'SPOUSE_OF',
+					fromDate: '1923-05-12',
+					fromDatePrecision: 'DAY',
+					toDatePrecision: 'UNKNOWN'
+				}
+			],
+			inferredRelationships: []
+		});
+
+		await expect
+			.element(page.getByTestId('relationship-date-range'))
+			.toHaveTextContent('12. Mai 1923');
+	});
+
+	it('shows the notes line', async () => {
+		render(PersonRelationshipsCard, {
+			personId: PERSON_ID,
+			relationships: [
+				{
+					id: 'r1',
+					personId: PERSON_ID,
+					relatedPersonId: SPOUSE_ID,
+					personDisplayName: 'Anna Müller',
+					relatedPersonDisplayName: 'Bertha Müller',
+					relationType: 'SPOUSE_OF',
+					fromDatePrecision: 'UNKNOWN',
+					toDatePrecision: 'UNKNOWN',
+					notes: 'Hochzeit in Berlin'
+				}
+			],
+			inferredRelationships: []
+		});
+
+		await expect
+			.element(page.getByTestId('relationship-notes'))
+			.toHaveTextContent('Hochzeit in Berlin');
+	});
+
+	it('renders no date line when the relationship has no dates', async () => {
+		render(PersonRelationshipsCard, {
+			personId: PERSON_ID,
+			relationships: [
+				{
+					id: 'r1',
+					personId: PERSON_ID,
+					relatedPersonId: SPOUSE_ID,
+					personDisplayName: 'Anna Müller',
+					relatedPersonDisplayName: 'Bertha Müller',
+					relationType: 'SPOUSE_OF',
+					fromDatePrecision: 'UNKNOWN',
+					toDatePrecision: 'UNKNOWN'
+				}
+			],
+			inferredRelationships: []
+		});
+
+		await expect.element(page.getByText('Bertha Müller')).toBeInTheDocument();
+		expect(document.querySelector('[data-testid="relationship-date-range"]')).toBeNull();
+	});
 });

frontend/src/routes/persons/[id]/edit/+page.server.ts

@@ -2,12 +2,40 @@ import { error, fail, redirect } from '@sveltejs/kit';
 import { createApiClient, extractErrorCode } from '$lib/shared/api.server';
 import { getErrorMessage } from '$lib/shared/errors';
 import type { DatePrecision } from '$lib/shared/utils/documentDate';
+import type { components } from '$lib/generated/api';
 import {
 	normalizePersonType,
 	validatePersonFields,
 	resolveValidationMessage
 } from '$lib/person/person-validation';
 
+type RelationType = NonNullable<components['schemas']['RelationshipUpsertRequest']['relationType']>;
+
+// Parses the shared relationship create/update form into a RelationshipUpsertRequest
+// body. An empty date omits date AND precision so the backend normalises the pair to
+// null/UNKNOWN — a lone precision would fail the coherence check (INVALID_DATE_PRECISION).
+function parseRelationshipForm(formData: FormData) {
+	const relatedPersonId = formData.get('relatedPersonId')?.toString();
+	const relationType = formData.get('relationType')?.toString();
+	const notes = formData.get('notes')?.toString().trim() || undefined;
+	const fromDate = formData.get('fromDate')?.toString().trim() || undefined;
+	const fromDatePrecision = fromDate
+		? (formData.get('fromDatePrecision')?.toString() as DatePrecision)
+		: undefined;
+	const toDate = formData.get('toDate')?.toString().trim() || undefined;
+	const toDatePrecision = toDate
+		? (formData.get('toDatePrecision')?.toString() as DatePrecision)
+		: undefined;
+	const body = {
+		relatedPersonId: relatedPersonId ?? '',
+		relationType: (relationType ?? 'OTHER') as RelationType,
+		...(fromDate ? { fromDate, fromDatePrecision } : {}),
+		...(toDate ? { toDate, toDatePrecision } : {}),
+		...(notes ? { notes } : {})
+	};
+	return { relatedPersonId, relationType, body };
+}
+
 export async function load({ params, fetch, locals }) {
 	const canWrite =
 		(locals.user as { groups?: { permissions: string[] }[] } | undefined)?.groups?.some((g) =>
@@ -193,40 +221,45 @@ export const actions = {
 
 	addRelationship: async ({ request, params, fetch }) => {
 		const formData = await request.formData();
-		const relatedPersonId = formData.get('relatedPersonId')?.toString();
-		const relationType = formData.get('relationType')?.toString();
-		const fromYearRaw = formData.get('fromYear')?.toString().trim();
-		const toYearRaw = formData.get('toYear')?.toString().trim();
-		const notes = formData.get('notes')?.toString().trim() || undefined;
+		const fields = parseRelationshipForm(formData);
 
-		if (!relatedPersonId || !relationType) {
+		if (!fields.relatedPersonId || !fields.relationType) {
 			return fail(400, { relationshipError: getErrorMessage('VALIDATION_ERROR') });
 		}
-		if (relatedPersonId === params.id) {
-			return fail(400, { relationshipError: getErrorMessage('VALIDATION_ERROR') });
-		}
-		const fromYear = fromYearRaw ? parseInt(fromYearRaw, 10) : undefined;
-		const toYear = toYearRaw ? parseInt(toYearRaw, 10) : undefined;
-		if (
-			fromYear !== undefined &&
-			toYear !== undefined &&
-			!Number.isNaN(fromYear) &&
-			!Number.isNaN(toYear) &&
-			toYear < fromYear
-		) {
+		if (fields.relatedPersonId === params.id) {
 			return fail(400, { relationshipError: getErrorMessage('VALIDATION_ERROR') });
 		}
 
 		const api = createApiClient(fetch);
 		const result = await api.POST('/api/persons/{id}/relationships', {
 			params: { path: { id: params.id } },
-			body: {
-				relatedPersonId,
-				relationType,
-				...(fromYear !== undefined && !Number.isNaN(fromYear) ? { fromYear } : {}),
-				...(toYear !== undefined && !Number.isNaN(toYear) ? { toYear } : {}),
-				...(notes ? { notes } : {})
-			}
+			body: fields.body
+		});
+
+		if (!result.response.ok) {
+			return fail(result.response.status, {
+				relationshipError: getErrorMessage(extractErrorCode(result.error))
+			});
+		}
+		return { relationshipSuccess: true };
+	},
+
+	updateRelationship: async ({ request, params, fetch }) => {
+		const formData = await request.formData();
+		const relId = formData.get('relId')?.toString();
+		const fields = parseRelationshipForm(formData);
+
+		if (!relId || !fields.relatedPersonId || !fields.relationType) {
+			return fail(400, { relationshipError: getErrorMessage('VALIDATION_ERROR') });
+		}
+		if (fields.relatedPersonId === params.id) {
+			return fail(400, { relationshipError: getErrorMessage('VALIDATION_ERROR') });
+		}
+
+		const api = createApiClient(fetch);
+		const result = await api.PUT('/api/persons/{id}/relationships/{relId}', {
+			params: { path: { id: params.id, relId } },
+			body: fields.body
 		});
 
 		if (!result.response.ok) {

frontend/src/routes/persons/[id]/edit/page.server.spec.ts

@@ -97,3 +97,98 @@ describe('persons/[id]/edit update action — generation (#689)', () => {
 		expect(body).toHaveProperty('generation', 3);
 	});
 });
+
+describe('persons/[id]/edit relationship actions (#837)', () => {
+	function relForm(overrides: Record<string, string | null> = {}): Request {
+		const fd = new FormData();
+		fd.set('relatedPersonId', 'p2');
+		fd.set('relationType', 'SPOUSE_OF');
+		for (const [k, v] of Object.entries(overrides)) {
+			if (v == null) fd.delete(k);
+			else fd.set(k, v);
+		}
+		return new Request('http://localhost/persons/p1/edit', { method: 'POST', body: fd });
+	}
+
+	it('addRelationship posts date + precision + notes', async () => {
+		const post = vi.fn().mockResolvedValue({ response: { ok: true, status: 200 }, data: {} });
+		vi.mocked(createApiClient).mockReturnValue({ POST: post } as unknown as ReturnType<
+			typeof createApiClient
+		>);
+		const request = relForm({
+			fromDate: '1923-05-12',
+			fromDatePrecision: 'DAY',
+			notes: 'Hochzeit'
+		});
+
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
+		await actions.addRelationship({ request, params: { id: 'p1' }, fetch: mockFetch } as any);
+
+		const [path, opts] = post.mock.calls[0];
+		expect(path).toBe('/api/persons/{id}/relationships');
+		expect(opts.body).toMatchObject({
+			relatedPersonId: 'p2',
+			relationType: 'SPOUSE_OF',
+			fromDate: '1923-05-12',
+			fromDatePrecision: 'DAY',
+			notes: 'Hochzeit'
+		});
+	});
+
+	it('addRelationship omits precision when the date is empty (coherence)', async () => {
+		const post = vi.fn().mockResolvedValue({ response: { ok: true, status: 200 }, data: {} });
+		vi.mocked(createApiClient).mockReturnValue({ POST: post } as unknown as ReturnType<
+			typeof createApiClient
+		>);
+		const request = relForm({ fromDatePrecision: 'DAY' }); // precision but no date
+
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
+		await actions.addRelationship({ request, params: { id: 'p1' }, fetch: mockFetch } as any);
+
+		const body = post.mock.calls[0][1].body;
+		expect(body).not.toHaveProperty('fromDate');
+		expect(body).not.toHaveProperty('fromDatePrecision');
+	});
+
+	it('updateRelationship PUTs to the relId path with the new body', async () => {
+		const put = vi.fn().mockResolvedValue({ response: { ok: true, status: 200 }, data: {} });
+		vi.mocked(createApiClient).mockReturnValue({ PUT: put } as unknown as ReturnType<
+			typeof createApiClient
+		>);
+		const request = relForm({ relId: 'rel-9', fromDate: '1923-05-12', fromDatePrecision: 'DAY' });
+
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
+		await actions.updateRelationship({ request, params: { id: 'p1' }, fetch: mockFetch } as any);
+
+		const [path, opts] = put.mock.calls[0];
+		expect(path).toBe('/api/persons/{id}/relationships/{relId}');
+		expect(opts.params.path).toMatchObject({ id: 'p1', relId: 'rel-9' });
+		expect(opts.body).toMatchObject({
+			relatedPersonId: 'p2',
+			relationType: 'SPOUSE_OF',
+			fromDate: '1923-05-12',
+			fromDatePrecision: 'DAY'
+		});
+	});
+
+	it('updateRelationship surfaces a backend error as a fail', async () => {
+		const put = vi.fn().mockResolvedValue({
+			response: { ok: false, status: 400 },
+			error: { code: 'INVALID_RELATIONSHIP_DATES' }
+		});
+		vi.mocked(createApiClient).mockReturnValue({ PUT: put } as unknown as ReturnType<
+			typeof createApiClient
+		>);
+		const request = relForm({ relId: 'rel-9' });
+
+		const result = (await actions.updateRelationship({
+			request,
+			params: { id: 'p1' },
+			fetch: mockFetch
+			// eslint-disable-next-line @typescript-eslint/no-explicit-any
+		} as any)) as { status: number; data: { relationshipError: string } };
+
+		expect(result.status).toBe(400);
+		expect(result.data.relationshipError).toBeTruthy();
+	});
+});

frontend/src/routes/zeitstrahl/+page.svelte

@@ -1,14 +1,40 @@
 <script lang="ts">
 import * as m from '$lib/paraglide/messages.js';
 import TimelineView from '$lib/timeline/TimelineView.svelte';
+import TimelineFilters from '$lib/timeline/TimelineFilters.svelte';
 import { timelineMeta } from '$lib/timeline/timelineMeta';
+import { filterTimeline } from '$lib/timeline/timelineFilter';
 import type { PageData } from './$types';
 
 let { data }: { data: PageData } = $props();
 
-const meta = $derived(timelineMeta(data.timeline));
 const hasContent = $derived(data.timeline.years.length > 0 || data.timeline.undated.length > 0);
 
+// Layer-filter state (#780). Layer hiding is client-side only — the whole
+// timeline is loaded once by #779's SSR load and we derive a filtered view of
+// it here; there is no goto, no URL param, and no extra fetch.
+let personalOn = $state(true);
+let historicalOn = $state(true);
+let lettersOn = $state(true);
+
+const filteredTimeline = $derived(
+	filterTimeline(data.timeline, { personalOn, historicalOn, lettersOn })
+);
+const filteredEmpty = $derived(
+	filteredTimeline.years.length === 0 && filteredTimeline.undated.length === 0
+);
+
+// Meta-line figures track the *filtered* view, so the header counts always
+// match what is actually on screen once layers are toggled off (#780 — this
+// closes the prior D1 limitation, where the counts stayed on the full timeline).
+const meta = $derived(timelineMeta(filteredTimeline));
+
+function resetFilters() {
+	personalOn = true;
+	historicalOn = true;
+	lettersOn = true;
+}
+
 // Compose the sub-line from segments joined by " · " so the range drops out
 // cleanly when there are no year bands; the whole line is absent when the
 // timeline is empty (REQ-002). Counts come from the route alone, never from
@@ -34,7 +60,7 @@ const metaLine = $derived.by(() => {
 				: m.timeline_events_count({ count: meta.eventCount })
 		);
 	}
-	segments.push(m.timeline_grouping_date());
+	// REQ-011: the toggle-free chronological view carries no grouping segment.
 	return segments.join(' · ');
 });
 </script>
@@ -48,10 +74,45 @@ const metaLine = $derived.by(() => {
 	     border is intentionally omitted (the page is already bg-canvas), per the
 	     review of REQ-001 — the sheet reads through its padding, not a frame line. -->
 	<div data-testid="timeline-canvas" class="rounded-[10px] bg-canvas p-6">
-		<h1 class="font-serif text-2xl font-bold text-brand-navy">{m.timeline_heading()}</h1>
+		<!-- Wrapping header so the CTA drops below the heading at narrow widths
+		     (≤360px) instead of overflowing — #842 REQ-001. -->
+		<header class="flex flex-wrap items-center justify-between gap-3">
+			<h1 class="font-serif text-2xl font-bold text-brand-navy">{m.timeline_heading()}</h1>
+			{#if data.canWrite}
+				<a
+					data-testid="timeline-add-event"
+					href="/zeitstrahl/events/new"
+					class="inline-flex h-11 items-center rounded bg-primary px-4 font-sans text-sm font-medium text-primary-fg hover:opacity-90 focus:outline-none focus-visible:ring-2 focus-visible:ring-focus-ring"
+				>
+					{m.timeline_add_event()}
+				</a>
+			{/if}
+		</header>
 		{#if hasContent}
 			<p data-testid="timeline-meta" class="mt-1 mb-6 font-sans text-xs text-ink-3">{metaLine}</p>
+			<TimelineFilters
+				bind:personalOn={personalOn}
+				bind:historicalOn={historicalOn}
+				bind:lettersOn={lettersOn}
+			/>
+		{/if}
+		{#if hasContent && filteredEmpty}
+			<!-- Filtered-empty: a calm message + one-click reset below the still-open
+			     filter bar — never a blank page, and never the generic "no events"
+			     state (which would imply the archive itself is empty). REQ-006. -->
+			<div data-testid="timeline-filter-empty" class="py-12 text-center">
+				<p class="font-serif text-base text-ink-2">{m.timeline_filter_empty_state()}</p>
+				<button
+					type="button"
+					data-testid="timeline-filter-empty-reset"
+					onclick={resetFilters}
+					class="mt-3 inline-flex min-h-[44px] items-center font-sans text-sm text-primary underline-offset-2 hover:underline"
+				>
+					{m.timeline_filter_reset()}
+				</button>
+			</div>
+		{:else}
+			<TimelineView timeline={filteredTimeline} canWrite={data.canWrite} />
 		{/if}
-		<TimelineView timeline={data.timeline} />
 	</div>
 </div>

frontend/src/routes/zeitstrahl/page.svelte.spec.ts

@@ -1,5 +1,6 @@
 import { describe, it, expect, afterEach } from 'vitest';
 import { cleanup, render } from 'vitest-browser-svelte';
+import { page } from 'vitest/browser';
 import * as m from '$lib/paraglide/messages.js';
 import Page from './+page.svelte';
 import { makeEntry, makeYear, makeTimelineDTO } from '$lib/timeline/test-factories';
@@ -42,7 +43,7 @@ describe('/zeitstrahl page', () => {
 		expect(canvas?.querySelector('ol')).not.toBeNull();
 	});
 
-	it('renders the meta sub-line with range, counts, and grouping (REQ-002)', () => {
+	it('renders the meta sub-line with range and counts, no grouping segment (REQ-011)', () => {
 		const dto = makeTimelineDTO({
 			years: [
 				makeYear(1909, [
@@ -58,7 +59,8 @@ describe('/zeitstrahl page', () => {
 		expect(sub?.textContent).toContain('1909–1924');
 		expect(sub?.textContent).toContain(m.timeline_letters_count({ count: 3 }));
 		expect(sub?.textContent).toContain(m.timeline_events_count({ count: 2 }));
-		expect(sub?.textContent).toContain(m.timeline_grouping_date());
+		// REQ-011: the toggle-free view drops the grouping meta segment.
+		expect(sub?.textContent).not.toContain('Gruppierung');
 	});
 
 	it('omits the range segment when there are no year bands (REQ-002)', () => {
@@ -83,7 +85,7 @@ describe('/zeitstrahl page', () => {
 		const sub = document.querySelector('[data-testid="timeline-meta"]');
 		expect(sub).not.toBeNull();
 		expect(sub?.textContent).not.toContain(m.timeline_letters_count({ count: 0 }));
-		expect(sub?.textContent).toContain(m.timeline_grouping_date());
+		expect(sub?.textContent).not.toContain('Gruppierung');
 	});
 
 	it('drops the events segment instead of showing "0 Ereignisse" (REQ-002)', () => {
@@ -111,3 +113,156 @@ describe('/zeitstrahl page', () => {
 		expect(sub?.textContent).not.toContain(m.timeline_events_count({ count: 1 }));
 	});
 });
+
+describe('/zeitstrahl layer filter (#780)', () => {
+	const letter = (title: string, documentId: string) => makeEntry({ documentId, title });
+	const historical = (title: string) =>
+		makeEntry({
+			kind: 'EVENT',
+			type: 'HISTORICAL',
+			derived: false,
+			eventId: 'h1',
+			documentId: undefined,
+			title,
+			senderName: '',
+			receiverName: ''
+		});
+	const personal = (title: string) =>
+		makeEntry({
+			kind: 'EVENT',
+			type: 'PERSONAL',
+			derived: false,
+			eventId: 'p1',
+			documentId: undefined,
+			title,
+			senderName: '',
+			receiverName: ''
+		});
+
+	const mixed = () =>
+		makeTimelineDTO({
+			years: [
+				makeYear(1915, [
+					letter('Brief Eins', 'd1'),
+					historical('Erster Weltkrieg'),
+					personal('Umzug nach Berlin')
+				])
+			]
+		});
+
+	async function openBar() {
+		await page.getByTestId('timeline-filter-trigger').click();
+	}
+
+	it('hides letter cards when the Letters layer is off and restores them, with no fetch (REQ-005/002)', async () => {
+		render(Page, { data: pageData(mixed()) });
+		await expect.element(page.getByText('Brief Eins')).toBeVisible();
+		await openBar();
+		await page.getByTestId('timeline-filter-letters').click();
+		await expect.poll(() => page.getByText('Brief Eins').query()).toBeNull();
+		await expect.element(page.getByText('Umzug nach Berlin')).toBeVisible();
+		await page.getByTestId('timeline-filter-letters').click();
+		await expect.element(page.getByText('Brief Eins')).toBeVisible();
+	});
+
+	it('hides historical event cards when the Historical layer is off (REQ-004)', async () => {
+		render(Page, { data: pageData(mixed()) });
+		await openBar();
+		await page.getByTestId('timeline-filter-historical').click();
+		await expect.poll(() => page.getByText('Erster Weltkrieg').query()).toBeNull();
+		await expect.element(page.getByText('Brief Eins')).toBeVisible();
+		await expect.element(page.getByText('Umzug nach Berlin')).toBeVisible();
+	});
+
+	it('hides personal event cards when the Personal layer is off (REQ-003)', async () => {
+		render(Page, { data: pageData(mixed()) });
+		await openBar();
+		await page.getByTestId('timeline-filter-personal').click();
+		await expect.poll(() => page.getByText('Umzug nach Berlin').query()).toBeNull();
+		await expect.element(page.getByText('Brief Eins')).toBeVisible();
+		await expect.element(page.getByText('Erster Weltkrieg')).toBeVisible();
+	});
+
+	it('shows the filtered-empty message + reset below the open bar when all layers are off (REQ-006)', async () => {
+		render(Page, { data: pageData(mixed()) });
+		await openBar();
+		await page.getByTestId('timeline-filter-personal').click();
+		await page.getByTestId('timeline-filter-historical').click();
+		await page.getByTestId('timeline-filter-letters').click();
+		await expect.element(page.getByText(m.timeline_filter_empty_state())).toBeVisible();
+		await expect.element(page.getByTestId('timeline-filter-empty-reset')).toBeVisible();
+		// the generic TimelineView empty state is never what shows for a filtered-empty view
+		expect(page.getByText(m.timeline_empty_state()).query()).toBeNull();
+		// the one-click reset restores every layer
+		await page.getByTestId('timeline-filter-empty-reset').click();
+		await expect.element(page.getByText('Brief Eins')).toBeVisible();
+	});
+
+	it('recomputes the meta-line counts from the filtered view, so a hidden layer drops out of the totals (#780, resolves D1)', async () => {
+		render(Page, { data: pageData(mixed()) });
+		const meta = page.getByTestId('timeline-meta');
+		// all layers on → the one letter and the two events are counted
+		await expect.element(meta).toHaveTextContent(m.timeline_letters_count_singular());
+		await expect.element(meta).toHaveTextContent(m.timeline_events_count({ count: 2 }));
+
+		await openBar();
+		await page.getByTestId('timeline-filter-letters').click();
+
+		// the hidden letter leaves the count instead of lingering as "1 Brief";
+		// the event total is untouched
+		await expect.element(meta).not.toHaveTextContent(m.timeline_letters_count_singular());
+		await expect.element(meta).toHaveTextContent(m.timeline_events_count({ count: 2 }));
+	});
+});
+
+describe('/zeitstrahl curator affordances (#842)', () => {
+	const curated = (eventId: string) =>
+		makeEntry({
+			kind: 'EVENT',
+			type: 'PERSONAL',
+			derived: false,
+			eventId,
+			title: 'Auswanderung',
+			senderName: '',
+			receiverName: '',
+			documentId: undefined
+		});
+
+	const withWrite = (timeline: ReturnType<typeof makeTimelineDTO>) => ({
+		...pageData(timeline),
+		canWrite: true
+	});
+
+	it('renders the add-event CTA in a wrapping header when the viewer can write (REQ-001)', () => {
+		render(Page, { data: withWrite(makeTimelineDTO({ years: [makeYear(1909, [makeEntry()])] })) });
+		const add = document.querySelector(
+			'[data-testid="timeline-add-event"]'
+		) as HTMLAnchorElement | null;
+		expect(add).not.toBeNull();
+		expect(add?.getAttribute('href')).toBe('/zeitstrahl/events/new');
+		// The header wraps so the CTA drops below the heading at narrow widths (≤360px)
+		// rather than overflowing — REQ-001.
+		expect(add?.closest('header')?.classList.contains('flex-wrap')).toBe(true);
+	});
+
+	it('renders no add-event CTA when the viewer cannot write (REQ-002)', () => {
+		render(Page, {
+			data: pageData(makeTimelineDTO({ years: [makeYear(1909, [makeEntry()])] }))
+		});
+		expect(document.querySelector('[data-testid="timeline-add-event"]')).toBeNull();
+	});
+
+	it('threads canWrite to the timeline so a curator sees an event edit link (REQ-001/009)', () => {
+		render(Page, {
+			data: withWrite(makeTimelineDTO({ years: [makeYear(1924, [curated('p9')])] }))
+		});
+		expect(document.querySelector('a[href="/zeitstrahl/events/p9/edit"]')).not.toBeNull();
+	});
+
+	it('shows no event edit link to a reader (REQ-007)', () => {
+		render(Page, {
+			data: pageData(makeTimelineDTO({ years: [makeYear(1924, [curated('p9')])] }))
+		});
+		expect(document.querySelector('[data-testid="event-edit"]')).toBeNull();
+	});
+});