From 8691a93ebf29d1fc0df5b0ce19f285bc95abca2e Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Thu, 22 Oct 2026 23:41:06 +0000 Subject: [PATCH] Settle CLI ordering before application resolution --- docs/roadmap/sequences.md | 95 ++++++++++++++++++++++++--------------- 1 file changed, 58 insertions(+), 37 deletions(-) diff --git a/docs/roadmap/sequences.md b/docs/roadmap/sequences.md index 354979c..639eb42 100644 --- a/docs/roadmap/sequences.md +++ b/docs/roadmap/sequences.md @@ -1,7 +1,7 @@ # Sequence Identity And Combination -Status: feature roadmap with OD-1 through OD-7 settled and follow-up interaction -decisions OD-8 through OD-11 open. The original decisions establish the intended +Status: feature roadmap with OD-1 through OD-8 settled and follow-up interaction +decisions OD-9 through OD-11 open. The original decisions establish the intended operations; the new questions address their lifecycle and policy-scope boundaries. Resolve these questions before preparing a staged implementation plan. This is not an implementation plan or an implemented contract. @@ -608,11 +608,12 @@ application-supplied mapping sources. Typed `Definition.Defaults` remain the initial decoded state: supplied sequences replace default sequences. Source `mode: append` does not append to a typed default list. -CLI overrides retain explicit replacement for supplied sequences. OD-8 addresses -how that intent interacts with inheritance, which currently runs afterward. +CLI overrides retain explicit replacement for supplied sequences. OD-8 moves +their application after inheritance and typed defaulting, before application +resolution, secret lookup, and final validation. Application resolution retains its existing assignment and recorded-transformation -semantics; ConfigKit does not automatically combine a callback's assigned sequence with -its previous value. Application-registered identities still receive final +semantics; ConfigKit does not automatically combine a callback's assigned sequence +with its previous value. Application-registered identities still receive final validation under OD-1, independently of how these stages produce their values. #### Validation Timing @@ -631,6 +632,55 @@ at an earlier assembly boundary. Final application-registered validation examine the final effective typed collection, while YAML-only enforcement remains limited to the structural operations described above. +### CLI Precedence And Application Resolution + +**OD-8: settled.** + +CLI overrides are the highest-precedence input to application resolution. Use +this lifecycle order: + +1. Assemble source tiers and selected overlays. +2. Resolve sibling inheritance, then apply typed defaults and decode the assembled + configuration. +3. Apply explicit CLI overrides to that configuration and check supplied values + against the application schema. +4. Run application resolution against the overridden configuration. +5. Resolve effective secret references, validate the final configuration including + application-registered identities, and publish it. + +Sequence values supplied by the CLI replace whole sequences, including sequences +inside supplied mappings. Mappings retain ordinary recursive override behavior; +empty sequences and permitted nulls retain their explicit replacement meaning. +Configuration-selected append or upsert does not reinterpret CLI assignments. +Inheritance and defaulting do not run again after CLI application. For inherited +and assembled `[A, B]` overridden by CLI `[C]`, application resolution receives +`[C]`; inheritance cannot reintroduce `[A, B]` afterward. + +Application resolution sees CLI values and their explicit-presence and source +metadata. Existing `Resolution.Default` behavior preserves explicit CLI values, +while normalization and recorded application transformations may still change +them. CLI input is authoritative over sources, inheritance, and typed defaults; +it is not immutable during application-owned resolution. For example, a derived +URL can use a CLI-supplied hostname, while an explicitly supplied CLI URL can be +preserved by an absence-based default. Retain existing recording and provenance +requirements for those transformations. + +Secret lookup uses the effective references after both overrides and resolution. +Final validation remains after these stages; neither CLI replacement nor +application resolution bypasses identity constraints or semantic validation. + +Reject structural directives such as `extends` and `configkit` in CLI override +paths or supplied values. CLI overrides supply application values after structural +processing; they do not initiate a second inheritance pass. This deliberately +changes the current ability to supply or cancel `extends` through CLI input. +CLI changes cannot prevent an earlier inheritance failure or change which +relationships that completed pass resolved. + +This ordering supersedes the current CLI-before-inheritance lifecycle described +in [ADR 0009](../adr/0009-sibling-inheritance.md). It avoids special replacement +markers carried through inheritance. Current contracts remain the implemented +baseline until the architectural and implementation work lands. + ## Architectural Direction The settled collection declaration gives imported and inline records at the same @@ -660,7 +710,8 @@ The proposal would extend identity declaration ownership and revise the cross-tier replacement decision in [ADR 0014](../adr/0014-sequence-placement-and-composition.md), as well as sequence replacement during inheritance in -[ADR 0009](../adr/0009-sibling-inheritance.md). Record +[ADR 0009](../adr/0009-sibling-inheritance.md), including its CLI-before-inheritance +lifecycle ordering. Record the architectural change in a superseding decision and reconcile affected architecture policy before implementation. The current ADR and contracts remain authoritative until that decision is made. This draft neither changes them nor @@ -674,36 +725,6 @@ Public API design and test sequencing belong to that later plan. ## Open Decisions -### OD-8. CLI Replacement And Subsequent Inheritance - -The current lifecycle applies CLI overrides before resolving inheritance, as -specified in [ADR 0009](../adr/0009-sibling-inheritance.md). OD-7 preserves CLI -sequence replacement while introducing identity-aware inheritance. Without an -explicit interaction rule, inherited `[A, B]` and a CLI-supplied local `[C]` could -produce `[A, B, C]` under inferred upsert, undoing the CLI's replacement intent. -An application registration can supply identity even if replacement discards a -lower YAML-only declaration. - -**Recommendation:** Preserve lifecycle ordering and carry explicit CLI sequence -replacement intent through inheritance at the overridden destination. The result -in this example should remain `[C]`, including when a YAML declaration selects -append or upsert. No additional caller flag should be needed. Identity constraints -and ordinary validation still apply; replacement intent does not bypass them. -This preserves CLI authority while allowing CLI-supplied `extends` directives to -participate in the existing inheritance pass. - -Define coverage for sequences supplied directly and sequences inside a supplied -mapping, as well as empty sequences and explicit null replacements. Coordinate -with OD-11 when overridden content is subsequently inherited elsewhere; avoid -turning a destination's override into a load-wide replacement policy. - -**Alternative:** Resolve inheritance before applying CLI overrides. CLI values -would then naturally be last and would need no inheritance replacement marker. -However, this changes the established lifecycle: CLI-supplied or cancelled -relationships would no longer affect that inheritance pass, and relationships -that the CLI would supersede could be resolved or rejected prematurely. Supporting -those cases would require additional lifecycle design beyond sequence combination. - ### OD-9. Which Controls Survive Until Inheritance? OD-4 prevents a lower tier's mode from selecting a later tier's operation, while