diff --git a/docs/roadmap/api.md b/docs/roadmap/api.md index 6af3f63..529e33a 100644 --- a/docs/roadmap/api.md +++ b/docs/roadmap/api.md @@ -19,7 +19,7 @@ as well. | 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. | +| 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 | Add `Result.Source(id)` for direct lookup of acquired-source evidence, alongside ordered `Sources()` enumeration and passive `SourceContext(id)` resource access. | @@ -43,6 +43,13 @@ 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 diff --git a/docs/roadmap/audit.md b/docs/roadmap/audit.md index 35d22ca..d944bd5 100644 --- a/docs/roadmap/audit.md +++ b/docs/roadmap/audit.md @@ -1,7 +1,8 @@ # Additional Public API Review Reviewed revision: `3ebb848eadf6e61275ecec6e35838ad6576cdd3a`. -Status: N1–N3 accepted; N4–N6 remain discussion findings. Implementation has not begun. +Status: N1–N4 accepted, with N4 incorporated into D6; N5–N6 remain discussion +findings. Implementation has not begun. ## Scope And Assessment @@ -12,7 +13,7 @@ It covers loading/discovery, source and resource ownership, paths and collection registration, callbacks, inspection/diffs, secrets, and diagnostics. It does not repeat the symbol inventory or conduct a correctness/performance audit. -[api.md](api.md) owns the accepted D1–D8, A1, and N1–N3 changes. Those decisions remain +[api.md](api.md) owns the accepted D1–D8, A1, and N1–N4 changes. Those decisions remain settled; public path comparison (A2) remains deferred. The findings here are additional opportunities, including consequences of the accepted cleanup. @@ -26,7 +27,7 @@ obsolete input-error category, and a missing convenience on failed loads. | N1: discovery `Paths` (accepted) | Rename to `SearchPaths`; decision recorded in [api.md](api.md). | Go function rename. | | N2: main-tier provenance (accepted) | Rename `LayerBase` to `LayerMain`, with value `"main"`; decision recorded in [api.md](api.md). | Go constant rename and observable string change. | | N3: shared-history quota (accepted) | Rename `CodeExplainLimitExceeded` to `CodeHistoryLimitExceeded`, with value `"history.limit_exceeded"`; decision recorded in [api.md](api.md). | Go constant rename and machine-readable code change. | -| N4: recording-kind diagnostic | Retire `CodeResolveInvalidKind` if D6 removes its public trigger. | Conditional constant removal. | +| N4: recording-kind diagnostic (accepted through D6) | Incorporated into [D6 in api.md](api.md#recording-methods-d6). | Conditional constant removal. | | N5: failed-load source lookup | Add `LoadError.Source(id)` alongside accepted A1. | Compatible addition. | | N6: import-default field names | Consider `FollowSymlinks` and `IncludeHidden`; lower priority. | Go field renames; YAML keys unchanged. | @@ -112,6 +113,9 @@ pre-v1 change is preferable if the new terminology is accepted. ## N4. Review The Diagnostic Made Obsolete By D6 +Status: accepted and incorporated into [D6](api.md#recording-methods-d6). The +discussion below preserves the rationale and alternative. + Evidence: the production use of `CodeResolveInvalidKind` is the kind guard in `resolutionState.addRecord` in [resolution.go](../../internal/engine/resolution.go). Today, public `Record` can