From 1ee508ba02f0ffbc98145ab20e49a016e4ed2167 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Tue, 27 Oct 2026 14:26:54 +0000 Subject: [PATCH] Accept main terminology for provenance --- docs/roadmap/api.md | 1 + docs/roadmap/audit.md | 13 ++++++++----- 2 files changed, 9 insertions(+), 5 deletions(-) diff --git a/docs/roadmap/api.md b/docs/roadmap/api.md index ddd65fc..dad14f2 100644 --- a/docs/roadmap/api.md +++ b/docs/roadmap/api.md @@ -24,6 +24,7 @@ as well. | 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. | +| 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. | ### Recording Methods (D6) diff --git a/docs/roadmap/audit.md b/docs/roadmap/audit.md index b902ba5..e2e398c 100644 --- a/docs/roadmap/audit.md +++ b/docs/roadmap/audit.md @@ -1,7 +1,7 @@ # Additional Public API Review Reviewed revision: `3ebb848eadf6e61275ecec6e35838ad6576cdd3a`. -Status: N1 accepted; N2–N6 remain discussion findings. Implementation has not begun. +Status: N1–N2 accepted; N3–N6 remain discussion findings. Implementation has not begun. ## Scope And Assessment @@ -12,7 +12,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 changes. Those decisions remain +[api.md](api.md) owns the accepted D1–D8, A1, and N1–N2 changes. Those decisions remain settled; public path comparison (A2) remains deferred. The findings here are additional opportunities, including consequences of the accepted cleanup. @@ -24,15 +24,15 @@ obsolete input-error category, and a missing convenience on failed loads. | Finding | Recommendation | Compatibility impact if accepted | | --- | --- | --- | | N1: discovery `Paths` (accepted) | Rename to `SearchPaths`; decision recorded in [api.md](api.md). | Go function rename. | -| N2: main-tier provenance | Rename `LayerBase` to `LayerMain`, with value `"main"`. | Go constant rename and observable string change. | +| 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 | Rename `CodeExplainLimitExceeded` to `CodeHistoryLimitExceeded`, with value `"history.limit_exceeded"`. | Go constant rename and machine-readable code change. | | N4: recording-kind diagnostic | Retire `CodeResolveInvalidKind` if D6 removes its public trigger. | 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. | These are design recommendations, not defect severities or additional release -gates. In particular, N2 and N3 require deliberate approval of their string-value -changes; accepting other naming cleanup does not authorize them automatically. +gates. N2's string-value change is accepted. N3's code-string change still requires +deliberate approval; accepting other naming cleanup does not authorize it. ## N1. Distinguish Discovery Paths From Semantic Paths @@ -60,6 +60,9 @@ although it is less consistent with `SearchDirectory`. ## N2. Use Main Consistently In Provenance +Status: accepted, including the string-value change. [api.md](api.md) owns the +selected change; the discussion below preserves its rationale and alternatives. + Evidence: `LoadLayered(main, ...)`, `SourceInfo.UnderlayIndex`, the configuration contract, and the accepted `SourceVersionModeMainOnly` name distinguish main input from lower-priority underlays. [records.go](../../records.go) instead exposes