Clarify shared ownership of namespace views

docs/roadmap/remediation.md

@@ -1,6 +1,6 @@
 # Configuration Collections Implementation Review Findings
 
-Status: Findings 1–2 completed; Finding 3 open. Review completed 2026-10-17.
+Status: all three findings completed 2026-10-17.
 
 Reviewed implementation after `89af2a1` through `0221cd4` against the accepted
 [feature roadmap](configuration-collections.md), [implementation plan](implementation.md),
@@ -131,7 +131,7 @@ examples, and `git diff --check`.
 
 ## Finding 3: Document Engine Ownership In Terms Of The Shared Assembly
 
-Priority: P3. Status: open.
+Priority: P3. Status: completed 2026-10-17.
 
 Location: [Engine GoDoc](../../engine.go), lines 85–101; related
 [prepared-handle GoDoc](../../prepared_execution.go) and
@@ -160,6 +160,15 @@ scope-mismatch rejection.
 Validation: review the affected GoDoc together. Reuse the passing shared-capacity
 and cross-view prepared-handle tests; no new behavior or test matrix is needed.
 
+Completion: Engine, WithNamespaces, PrepareExecution, RunPrepared, and the
+prepared-handle GoDoc now distinguish independent constructions from shared
+namespace views. They describe shared clients/capacity and handle ownership,
+with captured selections unchanged by the invoking view. No runtime behavior
+was changed. Reviewed rendered `go doc` output; the existing shared-capacity and
+cross-view prepared-handle tests and `git diff --check` passed. The full
+race-enabled suite, vet, and offline examples from Finding 2 cover the unchanged
+implementation.
+
 ## Review Validation
 
 Passed on the reviewed committed tree with `GOWORK=off`:

engine.go

@@ -90,11 +90,12 @@ var (
 // [Engine.InspectRequirements], [Engine.InspectProfile], [Engine.Prepare], [Engine.PrepareExecution],
 // [Engine.Run], [Engine.RunPrepared], [Engine.SmokeTest], [Engine.ListProfiles],
 // [Engine.ListPrompts], [Engine.ListBackends], [Engine.ListNamespaces], and
-// [Engine.ListCollections]. Each Engine owns
+// [Engine.ListCollections]. Engines constructed separately by [NewEngine] own
 // independent backend-capacity pools that coordinate Run, RunPrepared, and
-// inference SmokeTest admission and model generation. Injected collaborators
+// inference SmokeTest admission and model generation. Namespace views returned
-// may still be invoked concurrently across different backend pools or for
+// by [Engine.WithNamespaces] share their underlying engine's pools, clients,
-// unlimited backends.
+// and prepared-execution owner. Injected collaborators may still be invoked
+// concurrently across different backend pools or for unlimited backends.
 type Engine struct {
 	internal *internalengine.Engine
 }
@@ -393,8 +394,9 @@ func (e *Engine) prepareRequest(ctx context.Context, req RunRequest) (*domain.Pr
 // configured LLMClient or reserving backend admission capacity. Validated
 // RunRequest.AppendedMessages are included in the frozen effective messages.
 //
-// The returned opaque handle is bound to this Engine and permits one
+// The returned opaque handle is bound to this Engine's underlying execution
-// [Engine.RunPrepared] invocation. Preparation freezes the selected sources,
+// owner, shared with its namespace views, and permits one [Engine.RunPrepared]
+// invocation in total. Preparation freezes the selected sources,
 // rendered messages, effective settings, inputs, provider structured-output
 // metadata, and validation resources needed by that invocation. The handle
 // retains a direct RunRequest.APIKey only in private execution state;
@@ -506,6 +508,11 @@ func (e *Engine) run(ctx context.Context, req RunRequest) (*RunResult, error) {
 // RunPrepared atomically claims and executes a handle created by
 // [Engine.PrepareExecution].
 //
+// The originating Engine and namespace views sharing its underlying owner may
+// claim the handle. Execution uses its captured selections without applying the
+// invoking view's namespaces. An Engine constructed separately by [NewEngine]
+// is a foreign owner.
+//
 // A valid owning-Engine invocation consumes the handle's one attempt before
 // credential revalidation, backend admission, generation, or validation.
 // Cancellation, capacity rejection, generation failure, operational

namespaces.go

@@ -23,6 +23,10 @@ type Namespaces struct {
 // inspection are not rewritten. [Engine.ListNamespaces] and
 // [Engine.ListCollections] remain global inventories. Invalid namespace syntax
 // or a nil engine returns an error matching ErrInvalidConfig.
+//
+// The view shares the receiver's captured configuration, clients, backend-capacity
+// pools, and prepared-execution owner. Prepared handles retain their captured
+// selections whichever related view executes them.
 func (e *Engine) WithNamespaces(namespaces Namespaces) (*Engine, error) {
 	if e == nil || e.internal == nil {
 		return nil, fmt.Errorf("%w: engine is nil", ErrInvalidConfig)

prepared_execution.go

@@ -5,8 +5,9 @@ import "gitea.maximumdirect.net/eric/promptkit/internal/usecase"
 const preparedExecutionString = "promptkit.PreparedExecution{opaque}"
 
 // PreparedExecution is an opaque, in-process handle for one completely
-// prepared execution. A handle is bound to the [Engine] that created it and
+// prepared execution. A handle is bound to the underlying execution owner shared
-// permits one [Engine.RunPrepared] invocation.
+// by its originating [Engine] and related namespace views. It permits one
+// [Engine.RunPrepared] invocation in total.
 //
 // PreparedExecution contains no supported serializable state and cannot be
 // used as a restartable job. Copying the value preserves the same shared