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

Settle CLI ordering before application resolution

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-22 23:41:06 +00:00
parent c563f80934
commit 8691a93ebf
1 changed files with 58 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files

95
docs/roadmap/sequences.md
View File

@@ -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