Expand accepted API decisions into an implementation roadmap
This commit is contained in:
@@ -1,16 +1,58 @@
|
|||||||
# Pre-v1 Public API Cleanup
|
# Pre-v1 Public API Cleanup Roadmap
|
||||||
|
|
||||||
Status: decisions accepted; implementation has not begun.
|
Status: target settled; implementation has not begun.
|
||||||
Baseline: `a050986` and the revision-pinned [API review](review.md).
|
Planning baseline: `7548fa1` (accepted decisions, with the v0.10.2 implementation
|
||||||
|
and subsequent interface/history remediation already present).
|
||||||
|
|
||||||
This document records the accepted cleanup from that review. The goal is clearer
|
This roadmap owns the targeted end state, required changes, general dependency
|
||||||
public vocabulary, recording methods, and direct source lookup before v1.0.0,
|
order, and completion criteria. The [preliminary review](review.md) retains the
|
||||||
preserving existing behavior. The review remains the catalog and analysis; its
|
API catalog and original proposals; the [additional review](audit.md) retains
|
||||||
other assessments are not automatically adopted by these decisions.
|
its evidence and alternatives. Proposal IDs below provide traceability. A later
|
||||||
Accepted findings from the [additional API review](audit.md) are recorded here
|
implementation plan should select concrete edits, stages, validation commands,
|
||||||
as well.
|
and progress tracking.
|
||||||
|
|
||||||
## Accepted Changes
|
## Purpose And Scope
|
||||||
|
|
||||||
|
Make the public API clearer before v1.0.0 through the accepted renames, narrower
|
||||||
|
recording methods, redundant-state removal, and direct source lookups. Preserve
|
||||||
|
existing configuration behavior except for the selected public replacements,
|
||||||
|
removals, and observable string changes. The root package remains the supported
|
||||||
|
facade; private engine structure can evolve within that boundary.
|
||||||
|
|
||||||
|
This is a breaking pre-v1 cleanup, not a compatibility-shim rollout. The renamed
|
||||||
|
or replaced public declarations give way to their selected forms. Existing Go
|
||||||
|
declaration comments and the [configuration contract](../config.md) continue to
|
||||||
|
own behavior that this roadmap does not change. No redesign of loading,
|
||||||
|
composition, history ownership, or YAML syntax is selected.
|
||||||
|
|
||||||
|
## Current Baseline
|
||||||
|
|
||||||
|
- [lifecycle.go](../../lifecycle.go), [records.go](../../records.go),
|
||||||
|
[discovery.go](../../discovery.go), and [secrets.go](../../secrets.go) expose
|
||||||
|
the old declarations listed below. There are corresponding engine declarations
|
||||||
|
and facade conversions, including [conversion.go](../../conversion.go).
|
||||||
|
- `Resolution.Record` accepts the inspection `ChangeKind` type, then rejects
|
||||||
|
kinds other than derived-default and normalization during loading. The generic
|
||||||
|
assignment helpers already select their own supported intent.
|
||||||
|
- `ImportSelection` represents only empty selections, but still carries a
|
||||||
|
single-valued outcome. Source records expose version and destination evidence
|
||||||
|
through names that do not fully describe that evidence.
|
||||||
|
- `Resolution.Source(id)` already performs passive, detached lookup during a
|
||||||
|
callback. `Result` and `LoadError` expose ordered `Sources()` lists but no
|
||||||
|
direct lookup. Failure records contain only the evidence available at failure.
|
||||||
|
- The shared history implementation and its admission boundary are already in
|
||||||
|
place. Provenance still uses `"base"`, and retained-history failures still use
|
||||||
|
`"explain.limit_exceeded"`.
|
||||||
|
- Current production-reference checks find only declarations for
|
||||||
|
`CodeOptionsUnavailable`, and the kind guard in `resolutionState.addRecord`
|
||||||
|
produces `CodeResolveInvalidKind`. Their removal requires the checks described
|
||||||
|
below, rather than inventing a new supported use for either code.
|
||||||
|
|
||||||
|
## Targeted Public API
|
||||||
|
|
||||||
|
The following table is the complete accepted change set. Unless stated otherwise,
|
||||||
|
renames retain the existing signature/type and behavior. Internal names are not
|
||||||
|
part of this public replacement list.
|
||||||
|
|
||||||
| Review item | Decision |
|
| Review item | Decision |
|
||||||
| --- | --- |
|
| --- | --- |
|
||||||
@@ -86,15 +128,177 @@ existing failed-load redaction and the evidence available at failure, including
|
|||||||
incomplete placement information. Lookup neither completes acquisition nor
|
incomplete placement information. Lookup neither completes acquisition nor
|
||||||
promises a record for every attempted source. This incorporates N5 into A1.
|
promises a record for every attempted source. This incorporates N5 into A1.
|
||||||
|
|
||||||
## Scope And Follow-Up
|
## Work Required From The Baseline
|
||||||
|
|
||||||
Implement the selected changes with corresponding declaration comments, owning
|
### 1. Migrate Public Declarations And Facade Conversions
|
||||||
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
|
Update the public declarations, comments, wrappers, and conversions as a coherent
|
||||||
compatible addition once a concrete use case and an explicit equality definition
|
surface. Useful existing owners are:
|
||||||
are established.
|
|
||||||
|
| Area | Baseline owners and required work |
|
||||||
|
| --- | --- |
|
||||||
|
| Entry metadata, sensitivity, version mode, and import defaults | [lifecycle.go](../../lifecycle.go), [layered.go](../../layered.go), and [conversion.go](../../conversion.go): update both ordinary and layered loading paths, callback wrappers, and definition/default conversions. |
|
||||||
|
| Source evidence | [records.go](../../records.go) and [conversion.go](../../conversion.go): rename records/fields and remove the empty-selection outcome. Cover source records returned through results, callbacks, and load errors. |
|
||||||
|
| Recording intents | [lifecycle.go](../../lifecycle.go) and [engine resolution](../../internal/engine/resolution.go): provide the two methods, route them to the existing recording/auditing machinery, and remove the public kind-selecting method. |
|
||||||
|
| Discovery and bootstrap | [discovery.go](../../discovery.go) and [secrets.go](../../secrets.go): replace constructor/function names and migrate their callers without changing acquisition or environment mutation behavior. |
|
||||||
|
| Provenance and diagnostic values | [records.go](../../records.go), [engine records](../../internal/engine/records.go), producers, conversions, and renderers: apply the selected labels and codes consistently. |
|
||||||
|
| Direct lookup | [lifecycle.go](../../lifecycle.go), [diagnostic.go](../../diagnostic.go), and their engine collaborators: expose the existing retained source evidence through the new result/error methods. |
|
||||||
|
|
||||||
|
Use explicit root/engine conversion as needed; no public aliases or engine types
|
||||||
|
are needed to implement these replacements. Private naming and helper placement
|
||||||
|
belong to implementation planning. Avoid unrelated internal renames merely to
|
||||||
|
make every private identifier match the facade.
|
||||||
|
|
||||||
|
Preserve distinctions that the new names clarify:
|
||||||
|
|
||||||
|
- `EntryInfo` remains a fixed, detached entry-state lookup with its current
|
||||||
|
unknown/invalid/shape-mismatch behavior. `IsExplicit` retains its own existing
|
||||||
|
validation behavior; the rename does not unify those two query contracts.
|
||||||
|
- `Sensitive` remains the classification predicate, separate from typed secret
|
||||||
|
references. Existing tag/predicate/dependency classification and redaction
|
||||||
|
still apply.
|
||||||
|
- `DestinationIsFallback` still describes the nearest resolved enclosing
|
||||||
|
container when the full destination is unavailable. It does not promise an
|
||||||
|
item's exact coordinates or upgrade evidence retained at an earlier stage.
|
||||||
|
- Empty-selection records keep their existing scope, order, and declaration-local
|
||||||
|
coordinates. Removing `Outcome` does not create a complete import ledger.
|
||||||
|
- `FollowSymlinks` and `IncludeHidden` retain pointer defaulting and load-preflight
|
||||||
|
snapshot behavior. Do not mechanically rename YAML `follow` or `hidden` keys.
|
||||||
|
|
||||||
|
### 2. Replace Recording Entry Points And Retire Obsolete Diagnostics
|
||||||
|
|
||||||
|
Implement the two recording methods over the existing resolution lifecycle.
|
||||||
|
Migrate manual-record callers according to the intent they currently supply;
|
||||||
|
keep assignment helper calls as helpers. Tests of container coverage, overlapping
|
||||||
|
records, dependencies, equal-valued intent, and net-change auditing continue to
|
||||||
|
protect the same behavior through the new entry points.
|
||||||
|
|
||||||
|
Complete the N4 check after replacing `Record`: trace supported recording routes,
|
||||||
|
then remove the obsolete exported invalid-kind code if its public trigger is
|
||||||
|
gone. Update tests of the removed input mechanism without weakening unrelated
|
||||||
|
record validation. Do not introduce a different public diagnostic solely to
|
||||||
|
represent an unreachable kind.
|
||||||
|
|
||||||
|
For D8, confirm both producer references and any documented intentional role for
|
||||||
|
`CodeOptionsUnavailable`, then remove the unused declaration and associated
|
||||||
|
active documentation. A concrete supported role discovered during this check
|
||||||
|
should be brought back for discussion. These are verification tasks for accepted
|
||||||
|
removals, not permission to delete other diagnostics that happen to be uncommon.
|
||||||
|
|
||||||
|
### 3. Add Direct Lookup Without Changing Source Evidence
|
||||||
|
|
||||||
|
Implement the result and error methods against each receiver's retained source
|
||||||
|
inventory. Reuse source-copying and facade-conversion helpers where practical so
|
||||||
|
lookup and enumeration agree, including nested locations, version evidence,
|
||||||
|
empty-selection evidence, and detached paths. Follow existing result-query
|
||||||
|
nil/zero conventions; failed-load nil/zero behavior is specified above.
|
||||||
|
|
||||||
|
Keep `Sources()` enumeration and `SourceContext(id)` responsibilities intact.
|
||||||
|
Lookup must not repeat acquisition, finalize failure evidence, or change source
|
||||||
|
IDs. A slice search or a suitable existing index can satisfy the contract; no
|
||||||
|
new lookup complexity promise or shared lazy cache is selected.
|
||||||
|
|
||||||
|
### 4. Carry The Two String Changes Through Their Producers And Readers
|
||||||
|
|
||||||
|
Replace the main-tier category's `"base"` spelling with `"main"` wherever that
|
||||||
|
category crosses the public boundary or is rendered. Imported contributions keep
|
||||||
|
their owning tier and ordinary source-location attribution. Other uses of the
|
||||||
|
word "base", such as filesystem base directories, are unrelated.
|
||||||
|
|
||||||
|
Change every retained-history-limit diagnostic producer and relevant reader to
|
||||||
|
`"history.limit_exceeded"`, including inheritance and final load admission.
|
||||||
|
Preserve the quota, accounting, and failure timing. This rename does not make
|
||||||
|
history optional or add a new limit control.
|
||||||
|
|
||||||
|
Review Go constant references and literal comparisons/expected output separately:
|
||||||
|
compilation catches old symbols but not stale diagnostic or provenance strings.
|
||||||
|
Other codes and layer values retain their existing meaning and spelling.
|
||||||
|
|
||||||
|
### 5. Update Consumer Guidance And Migration Information
|
||||||
|
|
||||||
|
Update declaration comments, applicable sections of [config.md](../config.md),
|
||||||
|
the [consumer guide](../consumers/README.md), README examples, and maintained
|
||||||
|
consumer code/fixtures under `examples/`. Use the new recording methods and source
|
||||||
|
lookups in relevant existing examples without expanding unrelated workflows.
|
||||||
|
Update internal documentation only where implemented ownership or terminology
|
||||||
|
changes. Accepted ADR decisions do not need revision for this cleanup.
|
||||||
|
|
||||||
|
Record the old-to-new Go names, removed outcome fields/codes, recording-call
|
||||||
|
replacements, and the two observable string changes as migration information.
|
||||||
|
Downstream applications may need to update literal comparisons and serialized
|
||||||
|
expectations as well as Go references. Version-specific release notes and
|
||||||
|
publication remain part of the normal [release process](../release.md); this
|
||||||
|
roadmap does not select a release version or authorize publication.
|
||||||
|
|
||||||
|
Keep revision-pinned review evidence and historical release records accurate for
|
||||||
|
their original revisions. Old names in those records are not stale active API
|
||||||
|
usage. Do not rewrite history or require external consumer migrations to claim
|
||||||
|
the repository implementation is complete.
|
||||||
|
|
||||||
|
## General Implementation Order
|
||||||
|
|
||||||
|
1. Map the accepted public changes to declarations, conversions, producers,
|
||||||
|
existing tests, and maintained consumer call sites. Confirm D8's intended-use
|
||||||
|
evidence and identify the D6/N4 dependency.
|
||||||
|
2. Apply the declaration and source-record changes across the facade and engine
|
||||||
|
boundary, preserving the existing semantics described above. Implement D6
|
||||||
|
with its associated N4 cleanup. Ordinary and layered paths must converge on
|
||||||
|
the same selected public vocabulary.
|
||||||
|
3. Add both source-lookup methods using the renamed source-evidence representation.
|
||||||
|
Complete the provenance and diagnostic string migration across production
|
||||||
|
sites and their readers.
|
||||||
|
4. Migrate maintained examples, documentation, and affected tests alongside the
|
||||||
|
relevant changes; finish consumer migration guidance after the public surface
|
||||||
|
is coherent.
|
||||||
|
5. Review the integrated public API and behavior, run applicable development
|
||||||
|
checks, and record completion evidence.
|
||||||
|
|
||||||
|
This is dependency ordering, not a prescribed commit count or a requirement for
|
||||||
|
intermediate releases. Independent renames can proceed together. The later
|
||||||
|
implementation plan should choose concrete work units without adding temporary
|
||||||
|
public compatibility machinery.
|
||||||
|
|
||||||
|
## Validation And Completion
|
||||||
|
|
||||||
|
Follow the [testing policy](../policy/testing.md) and
|
||||||
|
[development guide](../development.md#baseline-validation). Reuse existing
|
||||||
|
behavioral tests for mechanical renames; new tests should protect the changed
|
||||||
|
entry points and added lookups, rather than duplicate implementation details.
|
||||||
|
|
||||||
|
- Check the root API exposes every selected replacement/addition and no obsolete
|
||||||
|
public declarations from the accepted removals. Preserve root-owned type
|
||||||
|
identity and the existing public/dependency boundary checks. Historical
|
||||||
|
references and useful private implementation names do not invalidate this check.
|
||||||
|
- Exercise both recording intents through the new public methods. Preserve
|
||||||
|
helper assignment behavior, validation, recorded origins, and history under
|
||||||
|
the existing resolution tests; update the old invalid-kind case when its input
|
||||||
|
mechanism is removed.
|
||||||
|
- Cover successful and failed source lookup against each receiver's enumeration,
|
||||||
|
missing IDs, applicable nil/zero cases, detachment of nested evidence, and
|
||||||
|
unchanged records after caller mutation. Reuse existing source/version/resource
|
||||||
|
fixtures for redaction, partial failure evidence, and passive access behavior.
|
||||||
|
Do not add source-completeness, performance, or concurrency guarantees.
|
||||||
|
- Retain the existing entry-shape, sensitivity, version-mode, empty-selection,
|
||||||
|
placement, import-default snapshot, discovery, and secrets-bootstrap coverage.
|
||||||
|
In particular, Go field renames must leave YAML declarations and tri-state
|
||||||
|
defaulting behavior intact.
|
||||||
|
- Update relevant provenance and diagnostic assertions for the selected strings.
|
||||||
|
Existing history-budget cases should continue to check rejection before secret
|
||||||
|
lookup and application validation, using the new code and unchanged accounting.
|
||||||
|
- Run the applicable focused checks during development and the everyday check
|
||||||
|
for the integrated code changes. Apply existing race-check guidance if the
|
||||||
|
implementation changes ownership/concurrency behavior. Validate documentation
|
||||||
|
links and maintained examples. No benchmark campaign or additional release
|
||||||
|
gate is introduced.
|
||||||
|
|
||||||
|
Completion means all accepted proposals are implemented, the diagnostic-removal
|
||||||
|
checks are resolved, maintained consumers and current documentation use the new
|
||||||
|
surface, and applicable checks pass with behavior preserved except for the
|
||||||
|
expressly selected changes. Update roadmap/review status with the actual evidence;
|
||||||
|
passing the current baseline suite is not evidence of future implementation.
|
||||||
|
|
||||||
|
No significant open design decision remains. D8's role check and D6/N4's public
|
||||||
|
reachability check are implementation verification tasks; unexpected evidence of
|
||||||
|
a legitimate public use should be discussed before changing that use. Private
|
||||||
|
helper choices and indexing belong to the implementation plan. Public path
|
||||||
|
comparison (A2) remains deferred and outside this scope.
|
||||||
|
|||||||
Reference in New Issue
Block a user