diff --git a/docs/roadmap/deferred.md b/docs/roadmap/deferred.md index 305c3e3..b996e27 100644 --- a/docs/roadmap/deferred.md +++ b/docs/roadmap/deferred.md @@ -1,6 +1,8 @@ # Deferred Scope This document owns intentionally excluded features, not a committed delivery plan. +The [future feature list](future.md) preserves candidate enhancements and open +questions without changing these exclusions. The [architecture policy](../policy/architecture.md) governs changes to these boundaries. Implemented behavior belongs in the [configuration contract](../config.md) and consumer adoption in the [consumer guide](../consumers/README.md). diff --git a/docs/roadmap/future.md b/docs/roadmap/future.md new file mode 100644 index 0000000..eb3df2b --- /dev/null +++ b/docs/roadmap/future.md @@ -0,0 +1,96 @@ +# Potential Future Features + +This document lists potential enhancements for consideration in future ConfigKit +releases. Entries are not accepted contracts, implementation plans, or release +commitments. [Deferred scope](deferred.md) remains the owner of current exclusions; +adopting a candidate requires an explicit design decision and a separate plan. + +## 1. Identified record sequences + +Status: deferred. PromptKit proposed this capability from its retired proposal 2, +**Namespaced Collections As Identified Records**. The original proposal is in the +PromptKit repository at +`b5866dd:docs/roadmap/configuration-collections-identified-records.md`. +PromptKit selected mounted mappings instead; this feature is not a dependency +of that design or a request to restore multiple installed prompt versions. + +### Motivation and proposed behavior + +Allow applications to declare that selected sequences contain records identified +by explicit fields, while retaining sequence-shaped output for slice decoding +and effective YAML. This could make composite identities and independently +authored catalogs more convenient than encoding identity in nested mapping keys. +Current [composition](../config.md#strict-document-composition) and +[overlay](../config.md#selected-overlays) treat sequences atomically. + +The proposed opt-in registration belongs in the reusable application definition: +an exact effective sequence path after input/import placement, plus an ordered, +nonempty set of distinct direct string-field names. For example, records at +`profiles` could be identified by `(namespace, id)`. Records `(provider, brief)` +and `(application, brief)` would coexist, and a later layer could update the +provider record's temperature while retaining its backend and model. + +The requested semantics, all still subject to design review, are: + +- Match exact string tuples, preserving component boundaries and spelling, + including empty strings. Every contribution supplies its complete identity; + defaults, inheritance, filenames, and normalization do not supply it. +- Retain distinct identities. Matching records from strict peers recursively + compose disjoint body fields and conflict on overlapping non-mapping body + values, even equal values. Equal identity fields act as structural keys rather + than conflicts and retain their contributing source evidence. +- Higher layers recursively overlay matching bodies. A changed identity denotes + a different record, not a rename. Proposed ordering is first contribution in + precedence-assembly order; matching records keep position and new ones append. +- Reject malformed identities, non-mapping records, non-null non-sequence values + at registered paths, and duplicate tuples within one source sequence. Later + layers cannot repair malformed structural identity in an acquired contribution. +- Treat an empty registered sequence as contributing no records; whole-path null + retains ordinary conflict/replacement semantics. Unregistered sequences, + including nested message lists, retain existing atomic behavior. +- Support record inheritance within the same registered sequence using an + `extends` mapping containing the complete parent tuple. Resolve only final + active relationships after precedence, preserve the child's identity, overlay + its body on the parent's body, and consume the directive before decoding. + Preserve cancellation, missing-parent/cycle errors, and declaring resource + contexts. Existing string-based mapping-sibling inheritance stays unchanged. + +Integrate ordinary and layered loads, imports, mounted paths, selected overlays, +and whole-sequence CLI overrides. Keep origins, presence, history, sensitivity, +and resource contexts attached to the correct record despite different source +and final indexes. Diagnostics must retain source locations without exposing +sensitive identity values. Final inspection may use snapshot-specific sequence +indexes; existing atomic sequence diffs need not become identity-aware. + +Successful results would have valid, unique identities, including after defaults +and application resolution, without a second merge or inheritance pass. Existing +source-version checks remain independent; consumed headers cannot supply missing +record identities. No identity-selector path syntax, arbitrary merge callbacks, +wildcard registration, per-record deletion/rename operator, multiple inheritance, +or cross-path parent references are requested. + +### Questions to resolve before implementation + +- **Need and delivery scope:** does an active consumer benefit enough to justify + the added semantics over keyed mappings? Are composite identities required? + Staging composition before inheritance is possible but would leave part of + the request incomplete. +- **Defaults and callbacks:** do default records merge by identity or retain + existing sequence-replacement behavior? How are callback-created duplicates, + identity edits, and reordering validated and reflected in provenance? +- **Null, empty, and order:** what happens when null clears a collection and a + later layer reintroduces records? How do absent and explicitly empty sequences + interact with defaults and first-contribution order? +- **Inheritance references:** how do peers compose relationship declarations, + and how are complete references enforced without assembling partial tuples + accidentally? What happens if identity fields overlap structural controls? +- **Registration paths:** how do overlapping registrations and paths beneath + sequence indexes behave when assembly changes those indexes? +- **Evidence and lifecycle:** how are record identities mapped between source + trees, history, inheritance, callback snapshots, and final indexes without + mixing records' provenance or sensitivity? Where do identity checks run relative + to header consumption and other structural processing? + +Keep the feature deferred until its consumer value and full lifecycle design +justify reconsidering the sequence-merging exclusion. A correct final sequence +alone would not establish correct inspection or disclosure behavior.