---
id: ADR-CRM-ENT-013
title: The Database Writes Record History
product_area: crm
module: entities
revision: 1
status: proposed
design_intent: confirmed
source_sha:
  services-crm: 7ea48a414c42eade10d60753b8bcc323b1dd726f
  services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1
decision: >-
  A changed contact or organization transaction leaves one database-written,
  application-read-only revision with actor and source context; revisions
  survive owner deletion and remain until workspace purge.
constrains:
  - DOM-CRM-ENT-033
  - SVC-CRM-ENT-entities
  - WF-CRM-ENT-001
  - WF-CRM-ENT-002
  - WF-CRM-ENT-009
origin: >-
  record change history plan approved by Andrew 2026-10-11 (services-platform
  docs/proposals/record-change-history.md); D1 of that plan (history permission
  at tier read)
alternatives:
  - option: Write audit history from each application path.
    why_not: >-
      A path could omit capture, and writable application history would allow
      forgery or alteration.
  - option: Retain delivery events as the history store.
    why_not: >-
      Delivery events are transient and removed after queue acceptance;
      revisions require independent retention.
consequences:
  - >-
    Application permissions permit history reads but not revision mutation,
    including after owner deletion.
  - >-
    Missing required attribution prevents the corresponding change from
    committing.
  - History access uses the reader-tier permission defined by the approved plan.
evidence:
  - >-
    services-crm at 7ea48a41: docs/record-history.md;
    modules/entities/db/record-revisions.table.ts
  - 'services-platform at ad3f6a65: docs/record-history.md'
---
# The Database Writes Record History

## Context

The approved history plan separates durable revisions from transient delivery events. Contact and organization capture settles one aggregate revision with the transaction’s attribution.

## Decision

A changed contact or organization transaction leaves one database-written, application-read-only revision with actor and source context; revisions survive owner deletion and remain until workspace purge.

## Alternatives Considered

Write audit history from each application path. A path could omit capture, and writable application history would allow forgery or alteration.

Retain delivery events as the history store. Delivery events are transient and removed after queue acceptance; revisions require independent retention.

## Consequences

Application read-only access preserves that record of change, including after deletion. Classification records do not use this mechanism, and the console still lacks an organization-history entry despite available service operations.

Application permissions permit history reads but not revision mutation, including after owner deletion. Missing required attribution prevents the corresponding change from committing. History access uses the reader-tier permission defined by the approved plan.