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

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).