Record accepted public API cleanup decisions

docs/roadmap/api.md

@@ -0,0 +1,66 @@
+# 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 and recording methods 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 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. |
+
+### 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.
+
+## 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 above.
+This record does not authorize release publication or a broader API redesign.
+
+A1 (`Result.Source(id)`) and A2 (public path comparison) are not selected for this
+cleanup. Both can be considered separately as compatible additions; path
+comparison needs a concrete use case and an explicit equality definition.