---
id: ADR-COM-CAT-004
title: Versioned Replacement with Patch Exceptions
product_area: commerce
module: catalog
revision: 1
status: proposed
design_intent: proposed
source_sha:
  services-commerce: c8b66a98e2490617aec38ba5c8165dd9bd0a8f9b
  react-console: baf6dae382d6f41dce976c7f848667ccc37e076f
decision: >-
  Most configuration saves replace a complete record at its read version; campaigns, codes and recommendation
  rules accept versioned named-field changes.
constrains:
  - DOM-COM-CAT-001
  - DOM-COM-CAT-002
  - DOM-COM-CAT-003
  - DOM-COM-CAT-004
  - DOM-COM-CAT-005
  - DOM-COM-CAT-006
  - SVC-COM-CAT-configuration
  - SVC-COM-CAT-catalog
  - SVC-COM-CAT-merchandise
  - SVC-COM-CAT-pricing
  - SVC-COM-CAT-promotions
  - SVC-COM-CAT-recommendations
origin: Platform persistence standard as cited by every Commerce persistence service
alternatives:
  - option: Make every operation a partial merge
    why_not: Complete replacement gives omitted purchasing settings a defined return to defaults.
  - option: Accept the last arriving write
    why_not: That would silently replace another editor’s changes.
consequences:
  - 'Replacement forms submit the full saved configuration, including values not currently edited.'
  - 'Owned collections reconcile with their parent, retaining row identities where dependencies need them.'
  - Operational counters can change without advancing the staff edit version.
supersedes: []
evidence:
  - >-
    services-commerce at c8b66a98: modules/*/services/persistence/*.ts (the versioned replacement in each);
    db/system-values.ts.
---

# Versioned Replacement with Patch Exceptions

## Context

Staff edits need clear treatment of omitted fields and protection from overwriting another editor’s work.

## Decision

Most configuration saves replace a complete record at its read version; campaigns, codes and recommendation rules accept versioned named-field changes.

## Alternatives Considered

Make every operation a partial merge. Complete replacement gives omitted purchasing settings a defined return to defaults.

Accept the last arriving write. That would silently replace another editor’s changes.

## Consequences

Replacement forms submit the full saved configuration, including values not currently edited. Owned collections reconcile with their parent, retaining row identities where dependencies need them. Operational counters can change without advancing the staff edit version.