ConfigKit/docs/roadmap/future.md

# Potential Future Work

This document lists potential enhancements and maintenance work 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. Separate glob entry preparation from traversal

Status: deferred; consider after the selected work in the
[consolidated audit roadmap](audit.md) is complete. Audit ID: C03.
Original source: complexity finding 4 at
`ecd5d5d:docs/roadmap/complexity.md`; assessed priority: medium.

The patterned branch of `selectGlobImportCandidates` in
[glob.go](../../internal/engine/glob.go) interleaves component traversal and
union/sorting with hidden/match rules, lexical/access paths, containment, links,
directory eligibility, namespace differences, labels, and candidate construction.
Directory selection already has a named entry-preparation operation.

Consider a glob-specific preparation helper returning an admitted candidate,
ordinary skip, or diagnostic. Keep literal segments, component advancement,
union/sorting, exclusions, and requiredness in the selector. Preserve inspection
and error order, budgets, native namespace spelling, and selected-file validation.
Share low-level filesystem facts only where semantics agree; the proposal does
not require a general visitor framework, discovery-algorithm change, or caching.
The selected directory-failure and link-resolution fixes do not depend on this
readability refactor.

### Questions to resolve before implementation

- After the selected import fixes, does the entry-preparation boundary still
  reduce complexity and clarify lexical versus canonical path handling?
- Which low-level operations can be shared with directory selection while
  keeping their distinct admission and traversal rules explicit?
- Can existing behavioral tests protect ordering, diagnostics, and resource
  accounting without assertions about the new private helper structure?

## 2. Simplify redundant facade-to-engine transport

Status: deferred; consider after the selected work in the
[consolidated audit roadmap](audit.md) is complete. Audit ID: F07.
Original source: complexity finding 5 at
`ecd5d5d:docs/roadmap/complexity.md`; assessed priority: low. The unused placement
bridge removal is separately selected as audit F05.

Root conversion, engine facade-transport records, engine private defaults,
decorators, and load normalization provide several mapping sites for the same
import-default fields. Placement likewise uses a record plus a setter-style
bridge. See [conversion.go](../../conversion.go),
[lifecycle.go](../../lifecycle.go), [layered.go](../../layered.go),
[import_spec.go](../../internal/engine/import_spec.go), and
[destination.go](../../internal/engine/destination.go).

Consider one engine representation for import-default input and straightforward
construction on existing option/input records, only if this reduces total
concepts and mapping sites. Keep domain-rule and ownership conversions and
separate registration compilation. Preserve root-owned types/signatures, both
loading APIs, invalid-enum validation, nil-versus-empty patterns, and pointer/slice
snapshots. A universal request DTO, generated mapper, public internal aliases,
or adapter framework is not part of this proposal.

### Questions to resolve before implementation

- After unused bridges and fields are removed, does the remaining transport
  duplication still justify a refactor?
- Which representations can be combined without losing ownership snapshots,
  presence distinctions, validation, or root-owned public types?
- Would the proposed construction surface reduce total concepts and conversion
  sites, rather than relocate the same work behind another abstraction?

## 3. 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.

## 4. 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.

## 5. 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?