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 (including N4)	Replace Resolution.Record with the two intent-specific methods below and remove CodeResolveInvalidKind once its public trigger is eliminated. 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 (including N5)	Add Result.Source(id) and LoadError.Source(id) for direct lookup of source evidence on successful and failed loads, alongside their existing Sources() enumeration. Keep source evidence distinct from passive resource access through SourceContext(id).
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.

Include N4's diagnostic cleanup in this change: confirm that no supported public input can still produce resolve.invalid_kind, then remove CodeResolveInvalidKind without a replacement or compatibility alias. Preserve other recording diagnostics. Internal defensive checks remain an implementation choice. If another legitimate public trigger is found, bring it back for discussion rather than silently reclassifying the failure.

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)
func (e *LoadError) 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.

The failed-load lookup returns records from LoadError.Sources()'s partial inventory and returns false for nil or zero-valued errors as well. Preserve existing failed-load redaction and the evidence available at failure, including incomplete placement information. Lookup neither completes acquisition nor promises a record for every attempted source. This incorporates N5 into A1.

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.