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](review.md).

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](audit.md) 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. |
| N6 | Rename `ImportDefaults.Follow` to `FollowSymlinks` and `ImportDefaults.Hidden` to `IncludeHidden`, replacing the old fields outright. Preserve `*bool` types, nil defaulting, explicit true/false, declaration overrides, traversal behavior, and search scope. Keep YAML keys `follow` and `hidden`, and Go fields `Required`, `Recursive`, and `Pattern`, unchanged. |

### Recording Methods (D6)

The selected signatures are:

```go
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)

```go
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.