From 1408001fce55b8ac09b6aa75ab2e9d1025773556 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sat, 21 Nov 2026 17:51:36 +0000 Subject: [PATCH] Clarify configuration handoff consistency guidance --- docs/consumers/pkg-promptkit.md | 4 ++-- docs/roadmap/remediation.md | 5 ++++- engine.go | 4 ++-- 3 files changed, 8 insertions(+), 5 deletions(-) diff --git a/docs/consumers/pkg-promptkit.md b/docs/consumers/pkg-promptkit.md index 4f70274..591fee3 100644 --- a/docs/consumers/pkg-promptkit.md +++ b/docs/consumers/pkg-promptkit.md @@ -129,8 +129,8 @@ nil result, or unavailable inspection view returns `ErrInvalidConfig`. It does not load sources, rerun callbacks, or add a bundle. Select `BundledOpenRouterUnderlay()` before the application load if desired; `WithBundledOpenRouter` affects only `NewEngine`. `RuntimeConfig` supplies only -client timeout, HTTP client, and transient-retry settings. Do not mutate the -resolved settings before handoff; subsequent mutation does not change captured +client timeout, HTTP client, and transient-retry settings. Keep resolved settings +consistent with the load's frozen inspection evidence at handoff; subsequent mutation does not change captured resources. Applications may register equivalent callbacks explicitly instead of using `Configure`. Construction errors retain their underlying causes; on the standalone path, a ConfigKit `LoadError` remains available through diff --git a/docs/roadmap/remediation.md b/docs/roadmap/remediation.md index 32cdd90..d4113b6 100644 --- a/docs/roadmap/remediation.md +++ b/docs/roadmap/remediation.md @@ -12,7 +12,10 @@ reviewed changes begin after `248d0db`. ### 1. Narrow The Pre-Handoff Mutation Wording To The Accepted Expectation -Status: open. Priority: P3. Implementation stage: 16. +Status: complete. Priority: P3. Implementation stage: 16. + +Completion: narrowed constructor GoDoc and consumer guidance to the consistency +expectation; reviewed against the roadmap. No runtime behavior changed. Locations: `engine.go:280` and `docs/consumers/pkg-promptkit.md:132`. diff --git a/engine.go b/engine.go index 7f98882..c758f11 100644 --- a/engine.go +++ b/engine.go @@ -277,8 +277,8 @@ type RuntimeConfig struct { // or equivalent explicit composition. Missing or nil selected settings contribute // no resources; Settings and *Settings are accepted, while other nonnil types, // nil results, and unavailable inspection views fail with ErrInvalidConfig. -// Callers must -// not mutate its selected settings between loading and this handoff. After +// Construction consumes resolved settings while inspection retains the load's +// frozen evidence. Callers should keep those consistent at handoff. After // construction, later settings mutations do not alter the engine. This method // does not load sources, rerun callbacks, or select bundled underlays. func NewFromConfig(result Configuration, cfg RuntimeConfig, opts ...Option) (*Engine, error) {