84 lines
5.2 KiB
Markdown
84 lines
5.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, 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. |
|
|
|
|
### 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.
|