From 9adcf149667bfc0d964e8103af90fb31750699fe Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Mon, 2 Nov 2026 14:20:58 +0000 Subject: [PATCH] Clarify history for removed records and reused positions --- docs/roadmap/resolution-sequences.md | 36 +++++++++++++++++++++++----- 1 file changed, 30 insertions(+), 6 deletions(-) diff --git a/docs/roadmap/resolution-sequences.md b/docs/roadmap/resolution-sequences.md index 99d49dd..6d1fe4d 100644 --- a/docs/roadmap/resolution-sequences.md +++ b/docs/roadmap/resolution-sequences.md @@ -174,8 +174,8 @@ A history query at a final record's position includes the matched record's earlier evidence from its entry position. Preserve original source coordinates and include the recorded collection operation explaining the move. Recorded normalization and derivation retain their resolution origins; following prior -evidence does not erase the application operation. Keep removed evidence -available under the historical inspection contract. +evidence does not erase the application operation. Removed evidence remains +available as described below. Explicit structural records remain the explanation of application-owned list restructuring. Dependency paths retain their existing recording semantics; @@ -188,6 +188,29 @@ Public effective-configuration diff output remains atomic for lists. Resolution comparison may need a dedicated internal operation or comparison mode so that its new behavior does not alter unrelated callers. +### Removed records and reused positions + +For eligible registered collections, inspection distinguishes a surviving +record's lineage from evidence of records removed during resolution: + +- Queries at surviving positions describe the surviving record's lineage, + including its matched entry evidence and the recorded collection operation. + A removed record that previously occupied that position does not become part + of the survivor's individual history. +- Collection-level history and explanation retain the removal and the removed + record's evidence, including available source attribution and before values. +- Historical positions that no longer exist remain inspectable under the + existing historical-path rules. Their availability does not give a reused + position a second, identity-addressed meaning. + +For example, if `[reports, invoices]` becomes `[invoices]`, a query at +`/resources/0` follows `invoices` back to its entry position 1. The removal of +`reports` and its earlier evidence remain inspectable at `/resources`, rather +than being mixed into the individual history of `invoices`. The now-absent +position `/resources/1` remains available under the historical-path contract. +Original source coordinates are preserved, and existing sensitivity rules apply +to all retained evidence. + ## Work needed from the baseline - Trace resolution comparison, record coverage, helper verification, metadata @@ -211,8 +234,9 @@ its new behavior does not alter unrelated callers. sensitivity; combined reorders and field edits; removed values; repaired entry identities; and dynamic registration selectors. Check agreement between final metadata and explanation while retaining entry-query behavior and atomic public - diff output. Review historical queries at removed and reused positions against - the existing historical-path contract. + diff output. Verify the removal-and-position-reuse example above: surviving + record queries follow their own lineage, collection queries retain removed + evidence, and absent historical positions remain inspectable. - Update the resolution contract and relevant API comments when implemented. Review ADR and policy follow-up for registered identity as the correspondence used during resolution inspection, as well as the distinction between @@ -226,5 +250,5 @@ design objective, not a new public performance guarantee. No configuration syntax, dependency, release gate, or new mutation-history system is proposed. Existing callbacks that record a whole list should continue to work. -The matching-eligibility and final-position-addressing decisions are settled and -integrated above. +The matching-eligibility, final-position-addressing, and removed-record inspection +decisions are settled and integrated above.