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

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

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

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.