diff --git a/docs/adr/0021-sequence-resolution-correspondence.md b/docs/adr/0021-sequence-resolution-correspondence.md new file mode 100644 index 0000000..0ba9c63 --- /dev/null +++ b/docs/adr/0021-sequence-resolution-correspondence.md @@ -0,0 +1,64 @@ +# 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. diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index c96d055..403ef7c 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -74,6 +74,8 @@ framework, new public selectors, caches, or mutation logging for this feature. ## Stage 1 — Record the architectural extension and inspect the baseline +**Status:** Complete. The focused engine baseline and documentation-link checks passed. + **Scope:** decision documentation and a focused starting check. 1. Add `docs/adr/0021-sequence-resolution-correspondence.md` with Accepted status