From 4289f9ff7fc41cdf79e312d77ef842043f435487 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Tue, 27 Oct 2026 14:06:45 +0000 Subject: [PATCH] Record accepted public API cleanup decisions --- docs/roadmap/api.md | 66 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 66 insertions(+) create mode 100644 docs/roadmap/api.md diff --git a/docs/roadmap/api.md b/docs/roadmap/api.md new file mode 100644 index 0000000..46025d5 --- /dev/null +++ b/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.