From 3ebb848eadf6e61275ecec6e35838ad6576cdd3a Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Tue, 27 Oct 2026 14:10:51 +0000 Subject: [PATCH] Accept direct source lookup on results --- docs/roadmap/api.md | 28 +++++++++++++++++++++------- 1 file changed, 21 insertions(+), 7 deletions(-) diff --git a/docs/roadmap/api.md b/docs/roadmap/api.md index 46025d5..10b4487 100644 --- a/docs/roadmap/api.md +++ b/docs/roadmap/api.md @@ -4,9 +4,9 @@ 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 and recording methods before v1.0.0, preserving existing -behavior. The review remains the catalog and analysis; its other assessments -are not automatically adopted by these decisions. +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 Changes @@ -20,6 +20,7 @@ are not automatically adopted by these decisions. | D6 | Replace `Resolution.Record` with the two intent-specific methods below. 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. | ### Recording Methods (D6) @@ -53,14 +54,27 @@ Document the modes together, preserving these distinctions: 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) +``` + +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. + ## 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 above. +contracts except for the expressly selected API replacements/removals and addition +above. This record does not authorize release publication or a broader API redesign. -A1 (`Result.Source(id)`) and A2 (public path comparison) are not selected for this -cleanup. Both can be considered separately as compatible additions; path -comparison needs a concrete use case and an explicit equality definition. +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.