---
id: ADR-ACC-BKS-002
title: Versioned replacements with explicit omission rules
product_area: accounting
module: books
revision: 1
status: proposed
design_intent: proposed
source_sha:
  services-accounting: f47cb263875bbc0c5640fba7dae6785ec32695f8
  react-console: baf6dae382d6f41dce976c7f848667ccc37e076f
decision: >-
  Record replacement requires the version read and applies the supplied record
  with documented omission exceptions. Default-purpose assignment and clearing
  are separate writes without an expected version.
constrains:
  - DOM-ACC-BKS-001
  - DOM-ACC-BKS-002
  - DOM-ACC-BKS-003
  - DOM-ACC-BKS-004
  - DOM-ACC-BKS-006
  - SVC-ACC-BKS-books
  - WF-ACC-BKS-002
  - WF-ACC-BKS-006
origin: >-
  services-accounting docs/milestones/plans/ACCT-M1-plan.md#D12 (replacement at
  the version read); the keep-when-omitted groups are observed only
alternatives:
  - option: Offer partial configuration updates.
    why_not: >-
      The examined configuration routes provide replacement operations, and
      existing editors and status actions send complete records.
  - option: Preserve all omitted values.
    why_not: >-
      This proposed approach would require another explicit mechanism to clear
      optional settings.
  - option: Clear every omitted value.
    why_not: >-
      An editor that lacks newer fee and write-off controls would otherwise
      erase those stored choices.
consequences:
  - A stale replacement is refused so staff can reload the current record.
  - >-
    Omitted unit and statement template choices restore built-in selection;
    wholly omitted fee groups and policy switches preserve their stored values.
  - >-
    Clients may return accepted read-only properties; the service ignores those
    properties when saving.
supersedes: []
evidence:
  - >-
    services-accounting at f47cb263:
    modules/books/services/persistence/business-units.ts:updateBusinessUnit,
    cardFeeSettingsOf
  - >-
    services-accounting at f47cb263:
    modules/books/services/persistence/settings.ts:updateSettings
  - >-
    react-console at baf6dae3:
    components/document-templates/statement-default-setting.tsx
---

# Versioned replacements with explicit omission rules

## Context

Staff editors replace records they have read. Some newer fields must survive saves from editors that do not expose them, while other optional fields need a way to be cleared.

## Decision

Record replacement requires the version read and applies the supplied record with documented omission exceptions. Default-purpose assignment and clearing are separate writes without an expected version.

## Alternatives Considered

Offer partial configuration updates. The examined configuration routes provide replacement operations, and existing editors and status actions send complete records.

Preserve all omitted values. This proposed approach would require another explicit mechanism to clear optional settings.

Clear every omitted value. An editor that lacks newer fee and write-off controls would otherwise erase those stored choices.

## Consequences

A stale replacement is refused so staff can reload the current record.

Omitted unit and statement template choices restore built-in selection; wholly omitted fee groups and policy switches preserve their stored values.

Clients may return accepted read-only properties; the service ignores those properties when saving.