From f3d0fe64114a7981d2c8f722e28f1ed9f05ef1fe Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Tue, 20 Oct 2026 14:03:26 +0000 Subject: [PATCH] Record final identity guarantees for application registrations --- docs/roadmap/sequences.md | 74 ++++++++++++++++++++++++++------------- 1 file changed, 49 insertions(+), 25 deletions(-) diff --git a/docs/roadmap/sequences.md b/docs/roadmap/sequences.md index 2022202..d3fcdf5 100644 --- a/docs/roadmap/sequences.md +++ b/docs/roadmap/sequences.md @@ -130,8 +130,37 @@ This is an authoritative constraint, distinct from an application default that only fills an omission. Configuration can define identity for collections without an application-owned constraint. The recommendation is for omitted configuration identity to inherit a registered definition and for an explicit -matching declaration to be accepted. Enforcement timing, including whether the -constraint guarantees uniqueness in the final published result, remains OD-1. +matching declaration to be accepted. The final-result guarantee for +application-owned constraints is settled below; YAML-only enforcement remains +an open follow-up to OD-1. + +### Final-Result Guarantee For Application Registrations + +**OD-1: settled for application-owned constraints.** + +> On successful loading, the final effective collections covered by application +> registrations satisfy their declared identity constraints. + +Retain assembly-time identity checks and validate the final effective +collections before publication. This covers the loaded state after defaults, +inheritance, overrides, and application resolution have taken effect. Those +operations retain their separately defined combination semantics. The guarantee +does not require every intermediate callback state to satisfy the constraint +and does not extend to caller mutations after loading returns. + +Keep the promise limited to the declared identity constraints. It does not by +itself require registered paths to exist or settle null and non-sequence +handling; those boundaries remain under OD-3 and OD-6. Final validation examines +effective typed values, while assembly-time checks retain their role in +validating authored contributions. A final string value alone does not prove +that the field was explicitly supplied in a source. + +The existing canonical final-value representation and shared publication path +provide the implementation foundation. Diagnostics should identify the affected +collection and item paths, using available origin information without exposing +identity values. The guarantee requires neither a new mutation-history system +nor exact causal reconstruction for records supplied by defaults or callbacks. +Final enforcement for identities declared only in YAML is not settled here. ## Initial Architectural Direction @@ -186,28 +215,22 @@ design and test sequencing belong to that later plan. ## Open Decisions -### OD-1. When Is An Application Identity Constraint Enforced? +### OD-1 Follow-Up. Final Validation For YAML-Only Identity Declarations -Application authority over a registered collection's identity definition is -settled above. Does that registration govern assembly alone, or also guarantee -valid, unique identities in the final published collection? The existing -registration checks strict-composition contributions; later defaults, -inheritance, overrides, and application callbacks have separate lifecycle roles. +Application-registered collections have the settled final-result guarantee +above. Should a configuration-only identity declaration carry the same +guarantee, or govern structural assembly alone? -**Initial recommendation:** Enforce an application-owned identity constraint -during participating collection assembly and validate it again on the final -effective collection before publication. This makes the application's constraint -meaningful even when a later operation creates or changes records. It does not -require applying append or replacement-by-identity semantics during those later -operations, or validating every intermediate callback state. Whether YAML-only -identity declarations also imply final validation remains to be decided. +**Initial recommendation:** Settle this after choosing declaration scope in +OD-2 and identity-policy lifetime across replacement in OD-3. Final enforcement +needs an unambiguous effective policy for each retained collection. The +application-owned guarantee can proceed independently of this choice. -**Alternative:** Limit registration to structural assembly and leave final -uniqueness checks to application validation. This preserves the current phase -boundary and reduces built-in validation work, but the registration alone would -not establish a final-result invariant. Its public contract would need to state -that limitation clearly. Decide enforcement separately from the combination -scope in OD-7. +**Alternatives:** Applying the same final check to YAML-declared identities +would give both declaration forms consistent enforcement, but requires resolving +which policy survives replacement or follows nested records. Limiting YAML-only +identity to assembly keeps policy lifetime narrower, but later operations could +produce a final collection that no longer satisfies that identity declaration. ### OD-2. Where Does Configuration Declare Collection Policy? @@ -333,13 +356,14 @@ source precedence but currently has no import declaration site. Account for item-local helpers and source-version consumption before deciding identity is available, consistent with the current lifecycle. -OD-1 separately addresses final validation of application constraints. Validating -the final collection does not itself change how defaults, inheritance, CLI -overrides, or callbacks combine values. +The settled OD-1 guarantee covers final validation of application constraints. +Validating the final collection does not itself change how defaults, inheritance, +CLI overrides, or callbacks combine values. **Alternative:** Extend the combination operations through defaulting, inheritance, overrides, and application resolution. This would support progressively extending collections across more of the lifecycle, but requires additional combination, callback, and inspection rules. Supporting typed default lists is a separate scope choice from extending source-backed baseline -collections; final identity enforcement remains the separate OD-1 decision. +collections; the application-owned final-result guarantee remains independent +of this combination-scope decision.