Update guidance for the cleaned public API

This commit is contained in:
2026-10-27 15:40:22 +00:00
parent c96197c417
commit 2ff588eb64
11 changed files with 127 additions and 66 deletions

View File

@@ -1,6 +1,6 @@
# Pre-v1 Public API Cleanup Implementation Plan
Status: in progress; Stages 1–9 are complete and Stages 10–11 are pending.
Status: in progress; Stages 1–10 are complete and Stage 11 is pending.
Baseline: `07e4ae5d9236935389e81b207d4a8f00543fafce`.
Audience: a Luna coding agent executing the stages sequentially.
@@ -400,7 +400,9 @@ preserve success/failure evidence without new load activity.
## Stage 10 — Complete Guidance And Consumer Migration Information
Status: pending. Covers all accepted changes' documentation and maintained usage.
Status: complete. Consumer guidance, current contracts, declaration comments, and
maintained examples use the selected API; historical report references identify
their completed plan revision.
1. Review declaration comments and [config.md](../config.md)'s owning sections:
discovery, import defaults/evidence, source versions, layered metadata,
@@ -434,6 +436,8 @@ go test . -run '^Example|TestLocalDocumentationLinks' -count=1
git diff --check
```
Validation passed with the commands above.
Completion: current guidance/examples use the selected API, migration information
is complete, and historical evidence remains accurate.

View File

@@ -1,13 +1,14 @@
# Interface Contract Remediation Roadmap
Status: implemented. The shared history owner and all four audit corrections
are complete; validation is recorded in [implementation.md](implementation.md).
are complete; validation is recorded in the completed plan at
`07e4ae5:docs/roadmap/implementation.md`.
Planning baseline: `1f64673` (v0.10.2 implementation plus documentation changes).
This roadmap covers the four findings in the [interface audit](interfaces.md).
The audit owns reproductions, evidence, and finding numbers. This document owns
the combined target, required changes, and design intent. The
[implementation plan](implementation.md) owns concrete stages, private
the combined target, required changes, and design intent. The completed plan at
`07e4ae5:docs/roadmap/implementation.md` records concrete stages, private
implementation choices, validation commands, and progress.
## Purpose And Scope
@@ -196,8 +197,9 @@ by metadata.
#### Replace Existing Attribution Machinery
The common model must replace independent historical attribution, rather than
become another representation alongside it. The implementation plan should map
the following owners to their replacements:
become another representation alongside it. The completed plan at
`07e4ae5:docs/roadmap/implementation.md` mapped the following owners to their
replacements:
| Current owner | Required change |
| --- | --- |
@@ -330,5 +332,6 @@ The selected common underlying model addresses both concerns. This accepts a
larger internal refactor than a local shape-filtering fix.
No significant open decision remains at roadmap level. Private representation,
indexing, and helper choices are recorded in the completed implementation plan.
indexing, and helper choices are recorded in the completed plan at
`07e4ae5:docs/roadmap/implementation.md`.
This roadmap does not revise accepted ADRs.

View File

@@ -8,7 +8,8 @@ implementation plan; resolution evidence is recorded with each finding.
The [interface remediation roadmap](interface-remediation.md) describes the
settled target and its dependencies, including a shared internal history model
for metadata history and explanation. The completed implementation and
integrated validation are recorded in [implementation.md](implementation.md).
integrated validation are recorded at
`07e4ae5:docs/roadmap/implementation.md`.
This audit retains the findings and original reproduction evidence.
## Scope and evidence
@@ -39,7 +40,7 @@ existing contracts rather than introduce new API restrictions or guarantees.
Priority: P2. Status: resolved. Evidence: `TestFacadeResolutionPresenceUsesDynamicEntryShape`,
the engine resolution/provenance/default regressions, and the integrated checks
recorded in [implementation.md](implementation.md).
recorded at `07e4ae5:docs/roadmap/implementation.md`.
Relevant code:
@@ -86,8 +87,8 @@ documented treatment of invalid schema paths.
## 2. Resolution can transfer explicitness to a different semantic path
Priority: P2. Status: resolved. Evidence: the engine resolution/metadata/provenance
regressions, the full engine suite, and the integrated checks recorded in
[implementation.md](implementation.md).
regressions, the full engine suite, and the integrated checks recorded at
`07e4ae5:docs/roadmap/implementation.md`.
Relevant code: `applyResolutionMetadata`, `applyResolutionFieldOrigins`, and
`refreshResolutionFields` in
@@ -129,8 +130,8 @@ repair this publication path.
Priority: P2. Status: resolved. Evidence: `TestPublicHistoryUsesResolutionShapeAttribution`,
`TestPublicHistoricalPathsEnumerateContextualShapes`, shared history-selection
and explanation regressions, and the integrated checks recorded in
[implementation.md](implementation.md).
and explanation regressions, and the integrated checks recorded at
`07e4ae5:docs/roadmap/implementation.md`.
Relevant code:
@@ -172,8 +173,8 @@ and compare metadata history with explanation.
## 4. Diagnostic canonicalization breaks composition claimant ordering
Priority: P3. Status: resolved. Evidence: `TestFacadeCompositionConflictKeepsClaimantOrder`,
the engine diagnostic-order regression, and the integrated checks recorded in
[implementation.md](implementation.md).
the engine diagnostic-order regression, and the integrated checks recorded at
`07e4ae5:docs/roadmap/implementation.md`.
Relevant code: `compositionConflictDiagnostic` in
[compose.go](../../internal/engine/compose.go) and `canonicalDiagnostics` in

View File

@@ -5,7 +5,8 @@ Algorithmic follow-up: `91769e9` (unchanged production code).
Comparison baseline: `0dd16aa8a935645ae2847d32edd86461dc4618f0`
(the planning commit, before the implementation sprint).
Scope: the completed [implementation plan](implementation.md) and
Scope: the completed implementation plan at
`07e4ae5:docs/roadmap/implementation.md` and
[interface remediation roadmap](interface-remediation.md). This report records
remaining defects and newly introduced scalability problems; it does not change
the selected architecture or public contracts. All eight findings are complete;