---
id: ADR-PFM-MTD-011
title: Version-checked complete record replacement
product_area: platform
module: metadata
revision: 1
status: proposed
design_intent: proposed
source_sha:
  services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1
  react-console: baf6dae382d6f41dce976c7f848667ccc37e076f
decision: Versioned replacements describe the complete mutable content and clear omissions, patches change named
  parts, and lifecycle actions use their own guards and concurrency contracts.
constrains:
- SVC-PFM-MTD-metadata
- SVC-PFM-MTD-layouts
- SVC-PFM-MTD-custom-objects
- SVC-PFM-MTD-associations
- DOM-PFM-MTD-005
- WF-PFM-MTD-012
origin: 'none: the rule is consistent across the module''s code and documentation but no product record names it;
  the shared record write contracts standard (services-platform:docs/standards/record-write-contracts.md) was not
  in this job''s reading scope'
alternatives:
- option: Merging omitted replacement fields
  why_not: Clients would lack predictable clearing semantics and retain content outside their intended complete
    replacement.
- option: Accepting unversioned overwrites
  why_not: Concurrent editors could silently replace changes they never read.
consequences:
- Replacement clears omitted position, group and requirement settings.
- Custom-record replacement clears omitted live properties.
- Load corrections can clear omitted link dates and reopen ended connections.
- Field archival, restoration and rule replacement are unversioned exceptions.
supersedes: []
evidence:
- 'services-platform at ad3f6a65: modules/metadata/services/persistence/custom-fields.ts; modules/layouts/services/persistence/layout-resources.ts;
  modules/custom-objects/services/persistence/custom-objects.ts, custom-object-records.ts; modules/associations/services/persistence/associations.ts'
---

# Version-checked complete record replacement

## Context

Editors and import adapters can hold stale or partial content. Replacement semantics need a clear distinction from partial changes.

## Decision

Versioned replacements describe the complete mutable content and clear omissions, patches change named parts, and lifecycle actions use their own guards and concurrency contracts.

## Alternatives Considered

Merging omitted replacement fields: Clients would lack predictable clearing semantics and retain content outside their intended complete replacement. Accepting unversioned overwrites: Concurrent editors could silently replace changes they never read.

## Consequences

Replacement clears omitted position, group and requirement settings. Custom-record replacement clears omitted live properties. Load corrections can clear omitted link dates and reopen ended connections. Field archival, restoration and rule replacement are unversioned exceptions.