Expose structured capacity errors

engine.go

@@ -65,8 +65,8 @@ var (
 	ErrPromptRender = errors.New("failed to render prompt")
 	// ErrCapacityExceeded identifies a Run or RunPrepared rejected because the
 	// selected backend already admitted ConcurrencyLimit + QueueCapacity calls.
-	// It is not an invalid request, an LLM or provider rate-limit response, or
-	// ErrLLMGenerate.
+	// A [CapacityError] reports the selected backend ID. It is not an invalid
+	// request, an LLM or provider rate-limit response, or ErrLLMGenerate.
 	ErrCapacityExceeded = errors.New("backend capacity exceeded")
 	// ErrLLMGenerate identifies a model-client failure or a nil successful
 	// response. Errors returned by an injected LLMClient remain available
@@ -592,9 +592,10 @@ func (e *Engine) PrepareExecution(ctx context.Context, req RunRequest) (*Prepare
 // single-pass even when OutputContract.RepairAttempts is positive.
 //
 // Run can return every error category documented by [Engine.Prepare], plus
-// ErrCapacityExceeded and ErrLLMGenerate. ErrCapacityExceeded identifies
-// rejection before artifacts, schemas, rendering, or model generation because
-// the selected backend's admission capacity is full; it does not match
+// ErrCapacityExceeded and ErrLLMGenerate. An engine admission rejection is
+// discoverable as [CapacityError] and still matches ErrCapacityExceeded. It
+// occurs before artifacts, schemas, rendering, or model generation because the
+// selected backend's admission capacity is full; it does not match
 // ErrInvalidRequest or ErrLLMGenerate. Errors from injected clients remain
 // available through errors.Is. Cancellation while waiting for model-generation
 // capacity matches both ErrLLMGenerate and the context error. Cancellation
@@ -635,9 +636,11 @@ func (e *Engine) Run(ctx context.Context, req RunRequest) (*RunResult, error) {
 //
 // RunPrepared can return ErrInvalidRequest, ErrAPIKeyEnvMissing,
 // ErrCapacityExceeded, ErrLLMGenerate, or ErrValidation as applicable while
-// preserving documented collaborator and context identities. A completed
-// content-validation rejection is returned in RunResult, not as an
-// operational error. An operational error returns no partial RunResult.
+// preserving documented collaborator and context identities. An engine
+// admission rejection is discoverable as [CapacityError] and still matches
+// ErrCapacityExceeded. A completed content-validation rejection is returned
+// in RunResult, not as an operational error. An operational error returns no
+// partial RunResult.
 func (e *Engine) RunPrepared(ctx context.Context, prepared *PreparedExecution) (*RunResult, error) {
 	if e == nil || e.runner == nil {
 		return nil, fmt.Errorf("%w: engine is nil", ErrInvalidConfig)