eric/ConfigKit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Record final identity guarantees for application registrations

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-20 14:03:26 +00:00
parent cba3a0efb0
commit f3d0fe6411
1 changed files with 49 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files

74
docs/roadmap/sequences.md
View File

@@ -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 only fills an omission. Configuration can define identity for collections
without an application-owned constraint. The recommendation is for omitted without an application-owned constraint. The recommendation is for omitted
configuration identity to inherit a registered definition and for an explicit configuration identity to inherit a registered definition and for an explicit
matching declaration to be accepted. Enforcement timing, including whether the matching declaration to be accepted. The final-result guarantee for
constraint guarantees uniqueness in the final published result, remains OD-1. 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 ## Initial Architectural Direction
@@ -186,28 +215,22 @@ design and test sequencing belong to that later plan.
## Open Decisions ## 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 Application-registered collections have the settled final-result guarantee
settled above. Does that registration govern assembly alone, or also guarantee above. Should a configuration-only identity declaration carry the same
valid, unique identities in the final published collection? The existing guarantee, or govern structural assembly alone?
registration checks strict-composition contributions; later defaults,
inheritance, overrides, and application callbacks have separate lifecycle roles.
**Initial recommendation:** Enforce an application-owned identity constraint **Initial recommendation:** Settle this after choosing declaration scope in
during participating collection assembly and validate it again on the final OD-2 and identity-policy lifetime across replacement in OD-3. Final enforcement
effective collection before publication. This makes the application's constraint needs an unambiguous effective policy for each retained collection. The
meaningful even when a later operation creates or changes records. It does not application-owned guarantee can proceed independently of this choice.
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.
**Alternative:** Limit registration to structural assembly and leave final **Alternatives:** Applying the same final check to YAML-declared identities
uniqueness checks to application validation. This preserves the current phase would give both declaration forms consistent enforcement, but requires resolving
boundary and reduces built-in validation work, but the registration alone would which policy survives replacement or follows nested records. Limiting YAML-only
not establish a final-result invariant. Its public contract would need to state identity to assembly keeps policy lifetime narrower, but later operations could
that limitation clearly. Decide enforcement separately from the combination produce a final collection that no longer satisfies that identity declaration.
scope in OD-7.
### OD-2. Where Does Configuration Declare Collection Policy? ### 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 item-local helpers and source-version consumption before deciding identity is
available, consistent with the current lifecycle. available, consistent with the current lifecycle.
OD-1 separately addresses final validation of application constraints. Validating The settled OD-1 guarantee covers final validation of application constraints.
the final collection does not itself change how defaults, inheritance, CLI Validating the final collection does not itself change how defaults, inheritance,
overrides, or callbacks combine values. CLI overrides, or callbacks combine values.
**Alternative:** Extend the combination operations through defaulting, **Alternative:** Extend the combination operations through defaulting,
inheritance, overrides, and application resolution. This would support inheritance, overrides, and application resolution. This would support
progressively extending collections across more of the lifecycle, but requires progressively extending collections across more of the lifecycle, but requires
additional combination, callback, and inspection rules. Supporting typed default additional combination, callback, and inspection rules. Supporting typed default
lists is a separate scope choice from extending source-backed baseline 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.