119 lines
6.4 KiB
Markdown
119 lines
6.4 KiB
Markdown
# 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](../config.md#strict-document-composition) 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](../adr/0017-collection-sequence-policy.md).
|
|
|
|
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](../config.md#shared-source-version-checks).
|
|
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?
|
|
|
|
## 4. Clone traversal review
|
|
|
|
Status: deferred. Review typed configuration cloning after the projection and
|
|
schema consolidation work, when the resulting structure can inform the review.
|
|
This is future maintenance work, not a prerequisite for completing consolidation.
|
|
|
|
The complexity audit identified `valueOperation.clone` in
|
|
[clone.go](../../internal/engine/clone.go) as a candidate for cleanup. Much of its
|
|
size is straightforward type dispatch. Focused handlers may clarify allocation,
|
|
recursive copying, cycle tracking, secret-state handling, or text-codec
|
|
reconstruction, but extraction may also add indirection without making the code
|
|
easier to understand.
|
|
|
|
When this work is taken up, assess the traversal and record whether changes are
|
|
worthwhile; a conclusion that no refactor is needed is valid. Make focused
|
|
changes only where the maintenance benefit justifies the code movement. Keep
|
|
cloning's typed-copy semantics distinct from projection's document-building
|
|
semantics. Preserve detached values, nil/empty distinctions, physical inline
|
|
fields, cycle/depth checks, and unresolved versus validated secret handling.
|
|
Reuse existing ownership, codec, secret, and traversal tests, adding coverage for
|
|
consequential gaps. No performance improvement is assumed.
|
|
|
|
### Questions to resolve before implementation
|
|
|
|
- After projection and schema consolidation, which clone branches still mix
|
|
responsibilities enough to benefit from extraction?
|
|
- Would a proposed helper keep allocation, recursive copying, and cycle cleanup
|
|
easier to follow together, or merely move a short loop out of sight?
|
|
- Are any small shared operations semantically identical across traversals, or
|
|
would sharing require special cases that obscure their different purposes?
|
|
- Which ownership or special-value risks, if any, lack sufficient existing test
|
|
coverage for the proposed changes?
|