# ADR-040 — Timeline domain data model

**Status:** Accepted
**Date:** 2026-06-12
**Issue:** #774 (Zeitstrahl milestone, foundational)

## Context

The Zeitstrahl (family timeline) needs a home for *curated* events — births,
weddings, moves, and world-historical context a curator types in by hand, distinct
from the OCR-derived `Document` letters. This ADR commits the new `timeline` domain's
data model: the `TimelineEvent` entity, the `EventType` enum, a repository, and the
V77 migration. No service, controller, or DTO ships here — those land in later issues.

A `TimelineEvent` carries the same date block as `Document` (`eventDate` +
`precision` + `eventDateEnd`) so events and letters render through one path, but its
audit footprint deliberately diverges (see below).

## Decisions

### 1. New `timeline` domain package, separate from `geschichte`

Curated timeline events are their own concern, not a Lesereise/`Geschichte` subtype.
The domain owns `TimelineEvent`, `EventType`, and `TimelineEventRepository`.

### 2. Responses (#775) will be views, not serialized entities

`TimelineEvent` has two LAZY `ManyToMany` collections (`persons`, `documents`) and
`open-in-view` is `false` — exactly the shape that motivated ADR-036 for `geschichte`.
#775 must assemble `TimelineEventView`/`TimelineEventSummary` inside the service
transaction; a serialized entity is a 500 waiting to happen. Decided up front so it is
not retrofitted later.

### 3. `precision` reuses `document.DatePrecision` — imported, not duplicated

The `timeline` package imports `org.raddatz.familienarchiv.document.DatePrecision`
directly, the same cross-domain value-type sharing ADR-039 established for `person`.
An enum has no behaviour and no persistence side effects, so the layering rule
(services → own repository) does not govern it. The enum stays a verbatim mirror of the
import normalizer's `Precision` values (ADR-025); changes must stay in sync with
`tools/import-normalizer/dates.py`. Moving `DatePrecision` into a shared package is a
wider refactor (touching `Document`, `importing`, `person`) and its own future ADR.

### 4. `precision = UNKNOWN` is forbidden; every other value is legal

`eventDate` is NOT NULL — a curated event always has at least a year, so only OCR letters
fall into the "Ohne Datum" bucket. The CHECK `chk_timeline_event_precision`
(`date_precision <> 'UNKNOWN'`) forbids exactly that one value. `SEASON` ("Sommer 1914")
and `APPROX` ("ca. 1914") are explicitly legal — family memory is full of both, and the
spec's rendering table covers them. Do not narrow the CHECK to an allow-list; an
over-tight constraint would force curators to fake `YEAR` and render dishonest dates.

### 5. RANGE invariant is a strict biconditional at the DB, intentionally tighter than `Document`

`chk_timeline_event_range` enforces `(date_precision = 'RANGE') = (event_date_end IS NOT
NULL)` — `eventDateEnd` is non-null **iff** precision is `RANGE`, both directions. This is
*stricter* than `Document`'s open-ended ranges (which allow a null end on a RANGE) because a
curated event always has a known, closed end when it spans a range — it is authored, not
inferred. This divergence is deliberate: a future "bug fix" must not relax it to match
`Document`.

### 6. Audit trail: `@Version` + NOT NULL `createdBy`/`updatedBy`, diverging from `Document`

`Document` has neither a version nor a creator. A curated entity edited by multiple curators
warrants real protection, so `TimelineEvent` adds:

- `@Version Long version` — optimistic locking for the multi-curator edit flow (#775).
  Object `Long` (not primitive) so it is `null` before first persist; Hibernate sets `0` on
  insert. The service **must** catch `ObjectOptimisticLockingFailureException` and translate
  it to `DomainException.conflict(...)`. Without that translation a concurrent-write conflict
  surfaces as HTTP 500 with Hibernate internals in the body — information disclosure (CWE-209).
- `createdBy`/`updatedBy` as bare `UUID`, `NOT NULL`, no FK to `app_users` (sidecar pattern,
  matching `DocumentAnnotation`/`OcrJob`; keeps `timeline` decoupled from `user`, avoids
  lazy-load surprises in the read-heavy assembly path). NOT NULL makes a curated event with no
  author impossible — an audit gap closed at the schema level. `DocumentAnnotation.createdBy`
  is nullable and has no `updatedBy`; the escalation here is deliberate because curated events
  are multi-author. Curator display names resolve through `UserService` at render time.

`updatedBy` is **not** advanced by `@UpdateTimestamp` — the service must set it from the
session principal before every `save()`, or the timestamp moves while the "who" goes stale.

### 7. `createdBy`/`updatedBy` are server-populated only — never bound from client input

Both are set from the session principal in the service, never from a request body. Binding
them from client input is an authorship-forgery / mass-assignment vector (CWE-639). #775's
regression suite must include forgery cases on **both** write paths (`POST` body with
`createdBy`, `PUT` body with `updatedBy`) — create and update are separate binding paths, so
testing only one leaves half the vector open. The update test must assert `updatedBy` equals
the *second* editor's UUID, not merely non-null.

### 8. `EventType` string values are a stable frontend styling contract

The Tailwind class map in the timeline Svelte components hard-codes `PERSONAL` (family accent)
and `HISTORICAL` (muted world accent) as strings. There is no mapping layer — renaming either
value requires a coordinated frontend change. Recorded here to prevent a silent regression.

### 9. Explicit `@JoinTable` on both ManyToMany fields

Without explicit `@JoinTable(name, joinColumns, inverseJoinColumns)`, Hibernate's naming
strategy could diverge from the V77 DDL's explicit table/column names. Explicit mapping
guarantees alignment and makes future column renames a deliberate, visible change. All four FK
columns are `ON DELETE CASCADE`: deleting a Person or Document drops the join row and leaves
the event intact (V71/ADR-032 hardening — a person delete must never 500).

## Consequences

- V77 is forward-only; rollback is manual DDL (`DROP TABLE` the two join tables, then
  `timeline_events`). No rollback script, no rollback test.
- The `timeline → document.DatePrecision` compile coupling is permanent until a shared-package
  refactor; precedent already exists (`importing/DocumentImporter`, `person`).
- The service/controller/DTO layer (#775) inherits the view-assembly, optimistic-lock
  translation, forgery-guard, and permission obligations recorded above. It must also add a
  service-level title-length check (new `ErrorCode`, e.g. `TIMELINE_TITLE_TOO_LONG`, mirroring
  `GESCHICHTE_TITLE_TOO_LONG`) — `title` is `VARCHAR(255)`, and without the guard an over-long
  title surfaces as a raw `DataIntegrityViolationException` → HTTP 500.