Accepted (2026-10-08), planned — EPIC-21 (UX restructure, #2190). Partly implemented: §4 W1, W3 and W4 shipped in #2209 (story 1.3) on the existing diaryAutoEventService.ts writer (see the Deviation Log); the rest is not implemented yet. Plan stories 0.8 (part 1: no repeat milestone-delay events), 1.3 (A→B→A with Undo), 2.4 (this ADR's core) and 2.5 (the History page) implement it. Contract 17 of API Contract › EPIC-21 is its read API.

Story 0.8 part (W2 for milestone delays) implemented in #2199: completed and not-later milestones write nothing; the same projected date as the latest event writes nothing (read from the legacy body until #2223 writes metadata).

Owner decisions: Q6 (automatic events leave the diary for History), Q20 (backfill, collapse exact repeats when shown, delete nothing), Q3 (no schema change).

Supersedes in part ADR-020 §3 ("Fire-and-Forget Automatic Events"): the fire-and-forget principle stays; what is written, and where it is shown, changes.

Automatic events are rows of diary_entries with is_automatic = 1, written by server/src/services/diaryAutoEventService.ts through createAutomaticDiaryEntry (server/src/services/diaryService.ts). Today:

System events stay in diary_entries (is_automatic = 1). No column is added or changed — Q3 holds. The existing nullable metadata TEXT column carries the event's parameters as JSON (ADR-020 already reserved it for "type-specific structured fields"). created_by (existing column) records the acting user when there is one; scheduler-originated events keep NULL.

The site diary list stops showing them (the client passes automatic=false); they appear on the object's History tab, on the History page (/history) and, when actionable, as one attention row.

// shared/src/types/systemEvent.ts (new)
type SystemEventMetadataV1 =
  | { v: 1; event: 'status_changed'; from: string; to: string; subjectLabel: string;
      depositId?: string; batchId?: string; revertOf?: string }
  | { v: 1; event: 'milestone_delayed'; targetDate: string; projectedDate: string;
      delayDays: number; subjectLabel: string }
  | { v: 1; event: 'invoice_created'; subjectLabel: string; vendorId: string | null;
      vendorName: string | null }
  | { v: 1; event: 'legacy' };          // backfill could not parse the stored text

• from / to are stored values (in_progress, claimed), never labels; the client renders labels through the status key sets in I18N_UNION_KEYS (CLAUDE.md › Union-derived keys).
• subjectLabel is a snapshot of the object's name at write time (task title, invoice number, grant name). The read API returns the live name when the subject still exists and falls back to the snapshot when it was deleted (ADR-020: events survive their subject).
• entry_type keeps its current values (work_item_status, invoice_status, subsidy_status, milestone_delay, invoice_created); event is the render template, entry_type the filter.
• The English title and body are still written (the body column is NOT NULL, and exports and older clients read them) but are never the primary rendering.

Deposit (progress payment) status events are written with source_entity_type = 'invoice', source_entity_id = <invoice id> and metadata.depositId = <deposit id>. The source-entity union stays as documented; the History row opens the invoice page on its Payments tab.

The single writer (systemEventService, replacing the on* functions of diaryAutoEventService.ts) applies, in order:

• UNDO_WINDOW_MS is one constant in shared/ (30 000 ms, owner decision); the client's Undo toast must close before it.
• W3/W4 are the only deletions of event rows, and they can only reach a row younger than the Undo window that the same user's undone action created. Legacy rows are never deleted (Q20).
• Fire-and-forget stays (ADR-020 §3): the de-dup reads, the retraction and the insert run inside the writer's own try; a failure is logged and never fails the primary write.
• System events are always written (owner decision, EPIC-21 approval). The DIARY_AUTO_EVENTS environment variable is removed in #2223 (story 2.4); after that, a stale value left in a deployment has no effect. Every bank-report batch therefore carries events and can be reverted through History. A batch submitted before #2223 while the variable was false has no events and stays unrevertable (404 on contract 14).

A SQL migration (the runner, server/src/db/migrate.ts, applies .sql files only) fills metadata for every row with is_automatic = 1 AND metadata IS NULL:

• Parsing: the legacy texts are generated from a small, closed set of templates (current and former versions of diaryAutoEventService.ts in git history). The migration extracts the parameters with SQLite string functions (instr, substr) and maps English labels back to stored values with CASE expressions built from the writer's STATUS_LABELS table, then writes the JSON with json_object.
• Deposits: rows with source_entity_type = 'invoice_deposit' are rewritten per §3 when the deposit still exists (invoice_deposits.invoice_id); when it does not, source_entity_type and source_entity_id become NULL and metadata.depositId keeps the old id.
• Unparseable rows get {"v":1,"event":"legacy"} and render their stored English text.
• Idempotent (the metadata IS NULL guard), non-destructive (no DELETE; title/body are untouched), and run inside the runner's transaction.
• Tested with synthetic rows covering every known template. Checking the result against a real backup is done locally and never committed (Q18).

R1 and R2 run in SQL (window functions, LAG over created_at per subject) so paging counts are correct.

No migration changes the schema. Schema › diary_entries documents the metadata v1 shapes for automatic rows and the data-only backfill (migration number assigned when story 2.4 lands; the next free number at the time of writing is 0047).

• History reads in the user's language with locale dates, and every row links to its object.
• "≤ 1 event per real state change, none after a milestone is reached" becomes a testable invariant.
• The site diary shows only what people wrote.
• A bank-report submission is one recognisable batch that can be reverted.

• Two renderings exist for a while: v1 metadata and the legacy text fallback. The fallback is permanent for legacy rows and must stay tested.
• W3 makes the event writer read before it writes; the reads use the existing idx_diary_entries_source_entity index.
• Retracting rows (W3/W4) is a deliberate, narrow exception to "events are immutable"; it is the only reading of "A→B→A writes nothing" that does not need a pending-event buffer or a schema change.

• New system_events table: cleaner separation, but a schema change (Q3 forbids it) and a data copy of every legacy row.
• Delete exact repeats: irreversible; rejected by the owner (Q20).
• Defer event writes until the Undo window closes: needs a durable pending buffer (schema) or loses events on restart.
• Backfill in a TypeScript data migration: the runner is SQL-only; adding a second migration kind for one backfill is not worth the mechanism. If the template set proves too irregular for SQL during story 2.4, raise it with the architect before adding a TS runner.