67 lines
4.2 KiB
Markdown
67 lines
4.2 KiB
Markdown
|
# 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.
|