65 lines
3.1 KiB
Markdown
65 lines
3.1 KiB
Markdown
# ADR 0021: Match Registered Records During Resolution Inspection
|
|
|
|
## Status
|
|
|
|
Accepted.
|
|
|
|
## Date
|
|
|
|
2026-11-02
|
|
|
|
## Context
|
|
|
|
Application resolution can change fields within sequences. Treating every
|
|
sequence change as atomic prevents a field record from covering an individual
|
|
edit. Registered collection identities also provide a way to relate a final
|
|
record to its entry value when positions change, so inspection can retain the
|
|
correct source evidence without confusing it with a prior index occupant.
|
|
|
|
## Decision
|
|
|
|
Compare equal-length ordinary lists recursively by position during resolution
|
|
auditing. A length change requires coverage of the list or an ancestor. For a
|
|
collection with an applicable application identity registration, match entry and
|
|
final records only when both endpoints have valid, unique identities. A change
|
|
in identity order or membership requires list or ancestor coverage, while
|
|
surviving records retain their matched entry evidence. When matching is not
|
|
available, audit a changed list as a whole without introducing an early identity
|
|
failure. Final registration validation remains at its existing boundary.
|
|
|
|
Match only the resolution-entry and final snapshots, within the same registered
|
|
destination. Identity changes are removals and additions, not inferred renames.
|
|
Records and helpers address final positions; entry queries remain fixed to entry
|
|
coordinates, and helpers do not follow later moves automatically. A surviving
|
|
record takes precedence at a reused position; collection inspection retains
|
|
removed records' evidence, and absent historical positions remain inspectable.
|
|
New records do not inherit a previous occupant's history or explicitness.
|
|
|
|
Preserve recorded operations, source coordinates, sensitivity, and safe detached
|
|
inspection. Resolution comparison is separate from public effective diff, which
|
|
continues to present sequence changes atomically.
|
|
|
|
This extends resolution inspection under [ADR 0003](0003-preserve-presence-and-resolution-history.md)
|
|
while preserving the diff decision in [ADR 0010](0010-effective-configuration-diff.md),
|
|
source combination and identity rules in [ADR 0017](0017-collection-sequence-policy.md),
|
|
and lifecycle ordering in [ADR 0018](0018-cli-after-structural-resolution.md).
|
|
|
|
## Alternatives Considered
|
|
|
|
- **Keep all sequence changes atomic during resolution.** This forces whole-list
|
|
records for independent field edits and does not identify a moved record's
|
|
earlier evidence.
|
|
- **Infer identities for every list.** Similar values or conventional field
|
|
names do not establish an application identity and could attach unrelated
|
|
history to a final record.
|
|
- **Reconstruct every intermediate callback mutation.** This requires a new
|
|
mutation history and implies an ordering that endpoint snapshots cannot prove.
|
|
|
|
## Consequences
|
|
|
|
Resolution auditing and inspection must share entry-to-final correspondence,
|
|
including explicit unmatched records, while preserving historical coordinates
|
|
and conservative sensitivity masking. Source assembly and public path types do
|
|
not change. The [implementation plan](../roadmap/implementation.md) tracks the
|
|
work; the [configuration contract](../config.md) owns implemented behavior.
|