configkit/docs/roadmap/api.md

Pre-v1 Public API Cleanup

Status: decisions accepted; implementation has not begun. Baseline: a050986 and the revision-pinned API review.

This document records the accepted cleanup from that review. The goal is clearer public vocabulary, recording methods, and direct source lookup before v1.0.0, preserving existing behavior. The review remains the catalog and analysis; its other assessments are not automatically adopted by these decisions. Accepted findings from the additional API review are recorded here as well.

Accepted Changes

Review item	Decision
D1	Rename Resolution.InputInfo to EntryInfo, describing the fixed resolution-entry metadata view, including retained defaults and CLI assignments. Preserve its return type and lookup behavior.
D2	Rename Definition.Secret to Sensitive. Preserve classification behavior, the configkit:"secret" tag, and typed Secret references.
D3	Rename SourceVersionModeDefault to SourceVersionModeMainOnly, SourceVersionCheck to SourceVersionEvidence, and SourceInfo.VersionCheck to VersionEvidence. Retain SourceVersionModeIfPresent and SourceVersionModeRequired.
D4	Rename ImportSelection to EmptyImportSelection and SourceInfo.ImportSelections to EmptyImportSelections. Retain path, location, and selector; remove Outcome, ImportSelectionOutcome, and ImportSelectionNone.
D5	Rename SourceInfo.DestinationUnresolved to DestinationIsFallback, preserving its existing meaning and destination coordinates.
D6	Replace Resolution.Record with the two intent-specific methods below. Retain ChangeKind and its inspection constants.
D7	Rename LoadSecretsDir to LoadSecretsIntoEnvironment, making process-environment mutation explicit. Preserve its signature apart from the name, report-plus-error behavior, and existing bootstrap semantics.
D8	Remove CodeOptionsUnavailable after confirming there is no intentional supported role. Do not introduce a failure merely to give the code a producer; a concrete reason to retain it should be brought back for discussion.
A1	Add Result.Source(id) for direct lookup of acquired-source evidence, alongside ordered Sources() enumeration and passive SourceContext(id) resource access.
N1	Rename Paths(paths ...string) Search to SearchPaths(paths ...string) Search, replacing the old name outright. Preserve literal file candidates, ordering, deferred acquisition, and selection/failure behavior. Leave semantic Path APIs and Searches unchanged.
N2	Replace LayerBase = "base" with LayerMain = "main", without a compatibility alias. Update Go references and affected string comparisons, serialization, and rendered labels. Preserve the existing main-tier category, imported contributions' owning tiers, precedence, and acquisition order.
N3	Replace CodeExplainLimitExceeded = "explain.limit_exceeded" with CodeHistoryLimitExceeded = "history.limit_exceeded", without a compatibility alias. Update Go references and affected diagnostic-code consumers. Preserve the existing quota, retained-node accounting, failure conditions, diagnostic locations, and admission timing before effective secret lookup and application validation.

Recording Methods (D6)

The selected signatures are:

func (r *Resolution) RecordDerivedDefault(path Path, reason string, dependencies ...Path)
func (r *Resolution) RecordNormalization(path Path, reason string, dependencies ...Path)

Both record intent for work already performed by application code. They do not assign values; RecordDerivedDefault does not check absence or suppress work on explicit input. Keep Default and Normalize as the assignment-and-recording helpers. Preserve path/reason/dependency validation, container coverage, coalescing, net-change auditing, and callback lifetime. Replace the old Record method outright rather than retain parallel public recording interfaces.

Version Policy And Evidence (D3)

MainOnly remains the zero mode and does not enable checking without a configured version rule. The broader modes retain their requirement for a usable rule. Document the modes together, preserving these distinctions:

• MainOnly retains the existing main-version check at its effective path. Broader modes inspect each participating document in source-local coordinates before placement and composition.
• IfPresent passes an absent main declaration to the application checker, while absent non-main declarations skip the checker. Required rejects missing declarations in participating documents. Existing NoSource behavior remains.
• Version evidence describes observed declarations or absence, not checker invocation or acceptance. Preserve nil-versus-observed-absence meaning, explicit null, locations, consumption, and redaction. No acceptance flag is added.

Direct Source Lookup (A1)

func (r *Result[T]) Source(id string) (SourceInfo, bool)

Look up an acquired source by its load-local ID, returning the same information represented in Sources() as a detached record. Empty or unknown IDs return false. The query performs no source acquisition, filesystem access, or credential lookup. Reuse existing source lookup and conversion machinery where practical; no public registry, indexing strategy, or constant-time guarantee is required.

Scope And Follow-Up

Implement the selected changes with corresponding declaration comments, owning documentation, examples, tests, and affected consumer call sites. Preserve the existing loading, composition, presence, inspection, ownership, and diagnostic contracts except for the expressly selected API replacements/removals and addition above. This record does not authorize release publication or a broader API redesign.

A2 (public path comparison) is deferred. It can be considered separately as a compatible addition once a concrete use case and an explicit equality definition are established.