diff --git a/docs/roadmap/remediation.md b/docs/roadmap/remediation.md index aaf687c..496d41f 100644 --- a/docs/roadmap/remediation.md +++ b/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`: diff --git a/engine.go b/engine.go index 8f573a8..04d185c 100644 --- a/engine.go +++ b/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 -// may still be invoked concurrently across different backend pools or for -// unlimited backends. +// inference SmokeTest admission and model generation. Namespace views returned +// by [Engine.WithNamespaces] share their underlying engine's pools, clients, +// 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 -// [Engine.RunPrepared] invocation. Preparation freezes the selected sources, +// The returned opaque handle is bound to this Engine's underlying execution +// 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 diff --git a/namespaces.go b/namespaces.go index 5f441df..a1971de 100644 --- a/namespaces.go +++ b/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) diff --git a/prepared_execution.go b/prepared_execution.go index 8572cc5..26bac49 100644 --- a/prepared_execution.go +++ b/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 -// permits one [Engine.RunPrepared] invocation. +// prepared execution. A handle is bound to the underlying execution owner shared +// 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