101 lines
7.3 KiB
Markdown
101 lines
7.3 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 (including N4) | Replace `Resolution.Record` with the two intent-specific methods below and remove `CodeResolveInvalidKind` once its public trigger is eliminated. 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 (including N5) | Add `Result.Source(id)` and `LoadError.Source(id)` for direct lookup of source evidence on successful and failed loads, alongside their existing `Sources()` enumeration. Keep source evidence distinct from passive resource access through `SourceContext(id)`. |
|
|
| 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. |
|
|
| N3 | Replace `CodeExplainLimitExceeded = "explain.limit_exceeded"` with `CodeHistoryLimitExceeded = "history.limit_exceeded"`, without a compatibility alias. Update Go references and affected diagnostic-code consumers. Preserve the existing quota, retained-node accounting, failure conditions, diagnostic locations, and admission timing before effective secret lookup and application validation. |
|
|
| N6 | Rename `ImportDefaults.Follow` to `FollowSymlinks` and `ImportDefaults.Hidden` to `IncludeHidden`, replacing the old fields outright. Preserve `*bool` types, nil defaulting, explicit true/false, declaration overrides, traversal behavior, and search scope. Keep YAML keys `follow` and `hidden`, and Go fields `Required`, `Recursive`, and `Pattern`, 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.
|
|
|
|
Include N4's diagnostic cleanup in this change: confirm that no supported public
|
|
input can still produce `resolve.invalid_kind`, then remove `CodeResolveInvalidKind`
|
|
without a replacement or compatibility alias. Preserve other recording diagnostics.
|
|
Internal defensive checks remain an implementation choice. If another legitimate
|
|
public trigger is found, bring it back for discussion rather than silently
|
|
reclassifying the failure.
|
|
|
|
### 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)
|
|
func (e *LoadError) 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.
|
|
|
|
The failed-load lookup returns records from `LoadError.Sources()`'s partial
|
|
inventory and returns false for nil or zero-valued errors as well. Preserve
|
|
existing failed-load redaction and the evidence available at failure, including
|
|
incomplete placement information. Lookup neither completes acquisition nor
|
|
promises a record for every attempted source. This incorporates N5 into A1.
|
|
|
|
## 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.
|