ConfigKit/docs/roadmap/future.md

Potential Future Features

This document lists potential enhancements for consideration in future ConfigKit releases. Entries are not accepted contracts, implementation plans, or release commitments. Adopting a candidate requires an explicit design decision and a separate plan. Significant architectural exclusions and their rationale belong in ADRs; this document does not maintain a list of rejected proposals.

1. Recursive body merging for identified records

Status: deferred. The implemented collection policy uses upsert to replace a complete matched record. Recursive merging of fields inside matching records remains a separate candidate and would revisit the whole-record update boundary selected by ADR 0017.

Consider this only in response to a concrete consumer need. A proposal would need to define conflicts for overlapping body fields, removal of omitted fields, presence and ordering, and how provenance, history, sensitivity, and resource context follow partially retained records. Any change requires a new decision and implementation plan; this entry does not alter current upsert behavior.

2. Required version declarations for selected sources

Status: deferred. PromptKit requested a way to require version declarations on a selected subset of source files while permitting other fragments to omit them.

Motivation and proposed behavior

PromptKit could require each collection's root file (for example, collection.yml or meta.yml, with naming still undecided) to declare an accepted specification version. Other files would use the existing check-when-present behavior. This would enforce a rule that otherwise remains a documentation convention.

All declarations would use the same application-owned Definition.Version path and acceptance policy. The proposal concerns where declarations are required; it does not introduce independently versioned collections or subtrees. A root declaration would not prove that headerless descendants declare a compatible version or replace final configuration validation.

Questions to resolve before implementation

• Selection API: should callers mark explicit inputs, select sources by path or predicate, or annotate imports? An input-level requirement is simpler, but cannot by itself select a root reached only through an import.
• Scope: does a requirement apply only to the selected document or also to its imports? Applying it only to that document best fits PromptKit's request; imported fragments could still declare versions checked by the shared policy.
• Mode interaction: how should selection interact with disabled source checks? Require an enabled mode, or activate checking for selected sources? Selection would strengthen check-when-present behavior and add no requirement beyond the load-wide required mode.
• Source handling and evidence: how should selection work across file, reader, byte, and mapping inputs, glob matches, and repeated imports? Define behavior for absent optional inputs and preserve source-local diagnostics, inspection evidence, and existing sensitivity handling.

3. Performance experiments

Status: deferred pending evidence. The completed performance audit identified four internal optimization candidates for separate investigation:

• Branch-local explanation replay instead of the current whole-tree replay.
• Redesigning the private metadata-copy handoff while preserving detached public records.
• Caching schema descriptors across loads.
• Indexing complex contributor-trace membership while preserving its equality rules and compact linked traces.

These are experiments, not committed implementation work or promised speedups. Reconsider them with evidence that the benefit justifies the ownership, retained-memory, or equivalence risks. The completed audit and implementation evidence are preserved in Git history at 8e91a2b under docs/roadmap/.

Questions to resolve before implementation

• Which representative workloads show enough remaining cost to justify each optimization, and what measurements would establish a useful improvement?
• Can narrower replay and membership indexes preserve explanation results, ordering, provenance, and sensitivity behavior?
• Can metadata handoff changes preserve detached public records and ownership across loads without introducing aliasing?
• What cache lifetime and concurrency design would make schema reuse worthwhile without excessive retained memory?