promptkit/engine.go

package promptkit

import (
	"context"
	"errors"
	"fmt"
	"io/fs"
	"net/http"
	"time"

	"gitea.maximumdirect.net/eric/promptkit/internal/domain"
	internalengine "gitea.maximumdirect.net/eric/promptkit/internal/engine"
	"gitea.maximumdirect.net/eric/promptkit/internal/observation"
	"gitea.maximumdirect.net/eric/promptkit/internal/usecase"
)

// ErrInvalidConfig identifies invalid engine construction, including missing
// required configuration, invalid options or backend registrations, and a nil
// Engine receiver.
var ErrInvalidConfig = errors.New("invalid engine configuration")

var (
	// ErrInvalidRequest identifies a request whose required values, overrides,
	// credentials, or effective settings are invalid.
	ErrInvalidRequest = errors.New("invalid run request")
	// ErrPromptNotFound identifies a requested prompt ID or version that is not
	// present in the selected prompt source. It does not also match
	// ErrPromptLoad.
	ErrPromptNotFound = errors.New("prompt not found")
	// ErrProfileNotFound identifies a selected profile ID that is absent from
	// every configured profile source. It does not also match ErrProfileLoad.
	ErrProfileNotFound = errors.New("profile not found")
	// ErrProfileRequired identifies a request for which neither RunRequest.ProfileID
	// nor the selected prompt's default profile is present. Such an error also
	// matches ErrInvalidRequest.
	ErrProfileRequired = errors.New("profile selection is required")
	// ErrPromptLoad identifies a failure to read, decode, validate, select, or
	// hash a prompt definition, except for the not-found case represented by
	// ErrPromptNotFound.
	ErrPromptLoad = errors.New("failed to load prompt definition")
	// ErrProfileLoad identifies a failure to read, decode, validate, or select
	// an execution profile or resolve its backend, except for the profile
	// not-found case represented by ErrProfileNotFound.
	ErrProfileLoad = errors.New("failed to load execution profile")
	// ErrAPIKeyEnvMissing identifies an explicitly required APIKeyEnv whose
	// environment variable is unset or empty after direct RunRequest.APIKey
	// precedence is applied. Such an error also matches ErrInvalidRequest.
	ErrAPIKeyEnvMissing = errors.New("api_key_env points to an unset environment variable")
	// ErrArtifactLoad identifies a failure to resolve an input artifact. Errors
	// returned by an injected ArtifactReader remain available through errors.Is.
	ErrArtifactLoad = errors.New("failed to load artifact")
	// ErrPromptRender identifies a failure to render prompt messages or the
	// session ID from the resolved inputs and variables.
	ErrPromptRender = errors.New("failed to render prompt")
	// ErrCapacityExceeded identifies a Run or RunPrepared rejected because the
	// selected backend already admitted ConcurrencyLimit + QueueCapacity calls.
	// 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. A built-in OpenAI-compatible non-2xx response is available as a
	// [GenerationError]. Errors returned by an injected LLMClient remain
	// available through errors.Is.
	ErrLLMGenerate = errors.New("failed to generate output")
	// ErrTransport identifies a failed HTTP request by the built-in model
	// client. Generation errors in this category also match ErrLLMGenerate and
	// retain the transport cause for errors.Is and errors.As. It does not imply
	// that the provider received no work.
	ErrTransport = errors.New("model transport failed")
	// ErrMalformedResponse identifies an invalid successful model response or
	// a nil successful response from an injected client. Generation errors in
	// this category also match ErrLLMGenerate.
	ErrMalformedResponse = errors.New("malformed model response")
	// ErrRetriesExhausted identifies a built-in generation sequence whose
	// positive transient retry budget ended with another eligible HTTP status.
	// RetryExhaustedError retains the final cause and actual attempt count.
	ErrRetriesExhausted = errors.New("transient model retries exhausted")
	// ErrValidation identifies an operational failure to load or compile a
	// schema or validate output. A completed validation whose Status is
	// ValidationFailed is returned in RunResult without this error.
	ErrValidation = errors.New("failed to validate output")
)

// Engine inspects prompts and profiles and prepares and runs Promptkit prompt
// requests.
//
// An Engine is safe for concurrent calls to [Engine.InspectPrompt],
// [Engine.InspectProfile], [Engine.Prepare], [Engine.PrepareExecution],
// [Engine.Run], and [Engine.RunPrepared]. Each Engine owns independent
// backend-capacity pools that coordinate Run and RunPrepared admission and
// model generation. Injected collaborators may still be invoked concurrently
// across different backend pools or for unlimited backends.
type Engine struct {
	internal *internalengine.Engine
}

// Config selects the directory-backed sources and built-in model-client
// transport used by [NewEngine]. Config has no stable JSON representation.
type Config struct {
	// PromptDir is the directory searched recursively for prompt definitions.
	// It is required unless a WithPromptFS or WithPromptFile option supplies the
	// prompt source.
	PromptDir string
	// ProfileDir is an optional ordinary configured source whose profiles take
	// precedence over application fallback and maintained catalog profiles. An
	// empty value selects the lower-precedence sources unless a profile-source
	// option supplies the ordinary source.
	ProfileDir string
	// SchemaDir is the root for JSON Schema files. An empty value uses the
	// current directory. WithSchemaFS or WithSchemaFile replaces this source.
	SchemaDir string
	// Timeout is the transport-wide safety cap for the built-in LLM client
	// when HTTPClient is absent or has a non-positive timeout. A zero or negative
	// value selects the 10-minute default.
	Timeout time.Duration
	// HTTPClient is cloned for the built-in LLM client. Its positive Timeout
	// takes precedence over Timeout. A zero or negative client Timeout inherits
	// Timeout or the 10-minute default. The supplied client is not mutated. This
	// field is ignored when WithLLMClient is used.
	HTTPClient *http.Client
	// TransientRetries selects additional built-in HTTP attempts after eligible
	// provider statuses. Nil defaults to two; zero disables retries. Negative
	// values are invalid. Injected LLMClient implementations are never retried
	// automatically.
	TransientRetries *int
}

// Option customizes engine construction.
//
// NewEngine applies options in argument order and ignores nil options. Within
// each prompt-source, ordinary-profile-source, fallback-profile-source,
// in-memory-profile, schema-source, model-client, and artifact-reader
// category, the last non-nil valid option replaces earlier options in that
// category. WithBackend is the additive exception: unique registrations
// accumulate, and a repeated backend ID is an error rather than a replacement.
// An invalid option fails construction even if a later option would replace it.
type Option interface {
	apply(*engineOptions) error
}

type optionFunc func(*engineOptions) error

func (f optionFunc) apply(options *engineOptions) error {
	return f(options)
}

type engineOptions struct {
	internal internalengine.Options
}

// WithLLMClient replaces the built-in model client used by [Engine.Run] and
// [Engine.RunPrepared].
//
// A nil client makes NewEngine fail with ErrInvalidConfig. The Engine schedules
// Generate calls according to the selected backend's capacity policy, but the
// client may still be called concurrently across different backend pools or for
// unlimited backends. The client is not used by [Engine.Prepare] or
// [Engine.PrepareExecution].
func WithLLMClient(client LLMClient) Option {
	return optionFunc(func(options *engineOptions) error {
		if client == nil {
			return ErrInvalidConfig
		}
		options.internal.SetLLMClient(publicLLMClientAdapter{client: client})
		return nil
	})
}

// WithArtifactReader replaces the default reader for every input artifact
// reference, regardless of its ArtifactRef.Type.
//
// A nil reader makes NewEngine fail with ErrInvalidConfig. The reader may be
// called concurrently.
func WithArtifactReader(reader ArtifactReader) Option {
	return optionFunc(func(options *engineOptions) error {
		if reader == nil {
			return ErrInvalidConfig
		}
		options.internal.SetArtifactReader(publicArtifactReaderAdapter{reader: reader})
		return nil
	})
}

// WithPromptFS loads prompt definitions from fsys under root.
//
// The source uses the same strict prompt YAML rules as configured prompt
// directories, and prompt content_file paths resolve within this source.
// fsys must be non-nil and root must be non-empty; otherwise NewEngine fails
// with ErrInvalidConfig. This option replaces Config.PromptDir and earlier
// prompt-source options.
func WithPromptFS(fsys fs.FS, root string) Option {
	return optionFunc(func(options *engineOptions) error {
		return options.internal.SetPromptFS(fsys, root)
	})
}

// WithPromptFile loads prompt definitions from the single prompt file at path.
//
// Relative prompt content_file paths resolve from the file's directory. path
// must name an existing non-directory file when NewEngine applies the option.
// This option replaces Config.PromptDir and earlier prompt-source options.
func WithPromptFile(path string) Option {
	return optionFunc(func(options *engineOptions) error {
		return options.internal.SetPromptFile(path)
	})
}

// WithProfileFS loads execution profiles from fsys under root.
//
// Profiles from this ordinary configured source take precedence over
// application fallback and built-in profiles. Profile YAML must use api_key_env
// for environment-based credentials; raw API keys are rejected. fsys must be
// non-nil and root must be non-empty; otherwise NewEngine fails with
// ErrInvalidConfig. This option replaces Config.ProfileDir and earlier file or
// FS profile-source options, but remains below WithProfiles in precedence.
func WithProfileFS(fsys fs.FS, root string) Option {
	return optionFunc(func(options *engineOptions) error {
		return options.internal.SetProfileFS(fsys, root)
	})
}

// WithProfileFile loads execution profiles from the single profile file at path.
//
// The profile takes precedence over application fallback and built-in profiles.
// Profile YAML must use api_key_env for environment-based credentials; raw API
// keys are rejected. path must name an existing non-directory file when
// NewEngine applies the option. This option replaces Config.ProfileDir and
// earlier file or FS profile-source options, but remains below WithProfiles in
// precedence.
func WithProfileFile(path string) Option {
	return optionFunc(func(options *engineOptions) error {
		return options.internal.SetProfileFile(path)
	})
}

// WithFallbackProfileFS supplies application-owned fallback profile
// definitions from fsys under root.
//
// Profile lookup checks, in order, profiles supplied by WithProfiles; the
// ordinary configured source selected by WithProfileFile, WithProfileFS, or
// Config.ProfileDir; this fallback source; and Promptkit's maintained catalog
// profiles. Each source supplies a complete profile definition; profile fields
// are not merged between sources. Only an absent profile ID proceeds to the
// next source. A matching read, parse, duplicate, validation, or credential
// format failure stops resolution.
//
// Files use the ordinary strict profile YAML and api_key_env credential rules.
// Loading and validation are lazy: NewEngine validates this option's arguments
// but does not read profile files. fsys must be non-nil and root must be
// nonblank; otherwise NewEngine returns an error matching ErrInvalidConfig.
// Repeating this option replaces the earlier valid fallback source.
//
// This option controls profile-definition lookup, not provider or generation
// failover.
func WithFallbackProfileFS(fsys fs.FS, root string) Option {
	return optionFunc(func(options *engineOptions) error {
		return options.internal.SetFallbackProfileFS(fsys, root)
	})
}

// WithProfiles configures in-memory profiles that take precedence over
// ordinary configured, application fallback, and built-in profiles.
//
// NewEngine locally validates and copies every profile. IDs must be unique
// within one call. An invalid local definition, duplicate ID, or unsupported
// ExtraParams value makes construction fail with ErrInvalidConfig. A derived
// profile's base reference and resolved target completeness are checked when it
// is selected or inspected. Repeating WithProfiles replaces the complete
// earlier in-memory set rather than merging it.
func WithProfiles(profiles ...Profile) Option {
	return optionFunc(func(options *engineOptions) error {
		definitions := make([]domain.ExecutionProfile, len(profiles))
		for index, publicProfile := range profiles {
			definitions[index] = toDomainProfile(publicProfile)
		}
		return options.internal.SetMemoryProfiles(definitions)
	})
}

// WithSchemaFS loads JSON Schema documents from fsys under root.
//
// Prompt schema_path values resolve within this source when schema validation
// or structured output is requested. fsys must be non-nil and root must be
// non-empty; otherwise NewEngine fails with ErrInvalidConfig. This option
// replaces Config.SchemaDir and earlier schema-source options.
func WithSchemaFS(fsys fs.FS, root string) Option {
	return optionFunc(func(options *engineOptions) error {
		return options.internal.SetSchemaFS(fsys, root)
	})
}

// WithSchemaFile loads JSON Schema documents from the single schema file at path.
//
// Prompt schema_path values refer to the file's base name. path must name an
// existing non-directory file when NewEngine applies the option. This option
// replaces Config.SchemaDir and earlier schema-source options.
func WithSchemaFile(path string) Option {
	return optionFunc(func(options *engineOptions) error {
		return options.internal.SetSchemaFile(path)
	})
}

// NewEngine constructs an Engine from configuration and options.
//
// Options are applied in order according to [Option]. PromptDir is required
// unless a prompt-source option is present. Construction validates option
// arguments, in-memory profiles, and backend registrations but defers reading
// and validating prompt, file-backed profile, and schema contents until Prepare
// or Run needs them.
//
// NewEngine returns an error matching ErrInvalidConfig for invalid
// configuration, options, or backend-capacity policies. Each constructed
// Engine has independent backend-capacity pools. Construction does not perform
// model requests or require credentials. A negative Config.TransientRetries
// is invalid.
func NewEngine(cfg Config, opts ...Option) (*Engine, error) {
	var options engineOptions
	for _, opt := range opts {
		if opt == nil {
			continue
		}
		if err := opt.apply(&options); err != nil {
			return nil, fmt.Errorf("%w: %v", ErrInvalidConfig, err)
		}
	}

	assembled, err := internalengine.New(
		internalengine.Config{PromptDir: cfg.PromptDir, ProfileDir: cfg.ProfileDir, SchemaDir: cfg.SchemaDir, Timeout: cfg.Timeout, HTTPClient: cfg.HTTPClient, TransientRetries: copyIntPtr(cfg.TransientRetries)},
		options.internal,
	)
	if err != nil {
		return nil, fmt.Errorf("%w: %v", ErrInvalidConfig, err)
	}
	return &Engine{internal: assembled}, nil
}

// InspectPrompt resolves one explicit prompt definition without selecting a
// profile or starting execution work.
//
// InspectPrompt requires a nonblank promptID. It passes nonblank promptID and
// promptVersion values unchanged to the engine's ordinary, case-sensitive
// prompt selection. An empty version succeeds only when that source has one
// selected ID; a nonempty version selects one exact ID/version pair. The
// configured prompt source is used without merging, fallback, or enumeration.
//
// A successful result proves that the selected definition and any referenced
// message content files were structurally loaded. Inputs are returned in
// definition order. DefaultProfileID is declared metadata only and is not
// resolved. OutputContract is the normalized declared contract, with a JSON
// Schema path when declared but without loading or compiling that schema.
// PromptHash is the same opaque equality value as PreparedRun.PromptHash for
// the selected definition and observed source state; its spelling, length,
// encoding, algorithm, and security properties are not contracts.
//
// This method does not return prompt bodies, templates, source paths, schemas,
// rendered messages, or execution settings. It does not resolve a profile or
// credential, read artifacts or schemas, render, validate, admit capacity,
// contact a provider, or generate model output. The returned PromptInspection
// and its input slice are caller-owned. Filesystem-backed inspection is a
// point-in-time lookup and does not freeze a definition for later execution.
//
// A nil Engine returns an error matching ErrInvalidConfig. A blank prompt ID
// matches ErrInvalidRequest. An absent exact ID or version matches
// ErrPromptNotFound and not ErrPromptLoad. Malformed, unreadable, duplicate,
// ambiguous, referenced-content, or hashing failures match ErrPromptLoad.
// Cancellation during lookup matches ErrPromptLoad while preserving the
// context error. InspectPrompt returns no partial result on error.
func (e *Engine) InspectPrompt(
	ctx context.Context,
	promptID string,
	promptVersion string,
) (*PromptInspection, error) {
	if e == nil || e.internal == nil {
		return nil, fmt.Errorf("%w: engine is nil", ErrInvalidConfig)
	}

	inspection, err := e.internal.InspectPrompt(ctx, promptID, promptVersion)
	if err != nil {
		return nil, mapPublicError(err)
	}
	return fromDomainPromptInspection(inspection), nil
}

// InspectProfile resolves one explicit profile without selecting a prompt or
// starting execution work.
//
// InspectProfile trims surrounding whitespace from profileID and looks up the
// resulting nonblank ID exactly and case-sensitively through the engine's
// in-memory, ordinary configured-source, application fallback, and built-in
// profile precedence. It applies the framework timeout baseline, selected
// backend, and then selected profile to EffectiveModelParams without a request
// override. BackendID is empty for an endpoint-only profile.
//
// APIKeyEnv in the returned target is an environment-variable name, never its
// value. APIKeyRequired instead reports a direct credential requirement and is
// mutually exclusive with a nonblank APIKeyEnv. InspectProfile neither derives
// an ID from a prompt default_profile nor checks credential availability, so an
// absent or blank named environment variable is not an error.
//
// The returned ProfileInspection and all nested mutable values are
// caller-owned. Filesystem-backed inspection is a point-in-time lookup and
// does not freeze the profile for a later execution. This method does not load
// a prompt, render, read artifacts or schemas, admit backend capacity, contact
// a provider, or generate model output.
//
// A nil Engine returns an error matching ErrInvalidConfig. A blank profile ID
// matches ErrInvalidRequest. An absent exact ID matches ErrProfileNotFound and
// not ErrProfileLoad. Malformed or unreadable profile data, an unknown backend,
// or an invalid resolved target matches ErrProfileLoad. Cancellation during
// profile loading matches ErrProfileLoad while preserving the context error.
// InspectProfile returns no partial result on error.
func (e *Engine) InspectProfile(ctx context.Context, profileID string) (*ProfileInspection, error) {
	if e == nil || e.internal == nil {
		return nil, fmt.Errorf("%w: engine is nil", ErrInvalidConfig)
	}

	inspection, err := e.internal.InspectProfile(ctx, profileID)
	if err != nil {
		return nil, mapPublicError(err)
	}
	return fromDomainProfileInspection(inspection), nil
}

// Prepare resolves and renders a prompt request without calling an LLM.
// It appends any validated RunRequest.AppendedMessages after rendered
// definition messages in the returned caller-owned snapshot.
//
// Prepare selects the prompt and profile, resolves any selected backend and
// effective execution settings, resolves the output contract, loads and hashes
// inputs, loads structured-output schema metadata when required, and renders
// the session ID and messages. The returned PreparedRun is owned by the caller
// and never contains a resolved API-key value, model output, or validation
// result.
//
// A nil Engine returns an error matching ErrInvalidConfig. Request and
// preparation failures may match ErrInvalidRequest, ErrPromptNotFound,
// ErrPromptLoad, ErrProfileNotFound, ErrProfileLoad, ErrProfileRequired,
// ErrAPIKeyEnvMissing, ErrArtifactLoad, ErrPromptRender, or ErrValidation as
// applicable. Cancellation is passed to the active collaborator and is
// reported in the applicable operation category; no general errors.Is
// relationship to ctx.Err is promised. Prepare returns no partial result on
// error. It validates RunRequest.TransientRetries but makes no model attempts.
func (e *Engine) Prepare(ctx context.Context, req RunRequest) (*PreparedRun, error) {
	if e == nil || e.internal == nil {
		return nil, fmt.Errorf("%w: engine is nil", ErrInvalidConfig)
	}

	domainReq, err := toDomainRunRequest(req)
	if err != nil {
		return nil, fmt.Errorf("%w: %v", ErrInvalidRequest, err)
	}

	prepared, err := e.internal.Prepare(ctx, domainReq)
	if err != nil {
		return nil, mapPublicError(err)
	}
	return fromDomainPreparedRun(prepared), nil
}

// PrepareExecution completely prepares a prompt request without calling the
// 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,
// 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;
// [PreparedExecution.Details] is credential-redacted.
//
// The context governs preparation only. Cancellation after this method
// returns does not invalidate the handle or propagate to RunPrepared.
// PrepareExecution returns the same error categories as [Engine.Prepare] and
// returns no handle on error. A nil Engine returns an error matching
// ErrInvalidConfig. The effective transient retry budget is frozen privately
// for RunPrepared and is absent from Details. A supplied Observer is retained
// privately for RunPrepared; preparation itself emits no events.
func (e *Engine) PrepareExecution(ctx context.Context, req RunRequest) (*PreparedExecution, error) {
	if e == nil || e.internal == nil {
		return nil, fmt.Errorf("%w: engine is nil", ErrInvalidConfig)
	}

	domainReq, err := toDomainRunRequest(req)
	if err != nil {
		return nil, fmt.Errorf("%w: %v", ErrInvalidRequest, err)
	}

	prepared, err := e.internal.PrepareExecution(ctx, domainReq)
	if err != nil {
		return nil, mapPublicError(err)
	}
	return &PreparedExecution{internal: prepared}, nil
}

// Run prepares a request, invokes the configured LLMClient, and validates the
// generated output. Each call resolves current sources and composes a fresh,
// stateless effective prompt with any validated RunRequest.AppendedMessages.
//
// A content-validation failure is a successful run whose
// RunResult.Validation has Status ValidationFailed. When its output contract
// has a positive repair budget, a failed eligible validation can make bounded
// additional model calls and stops at the first valid candidate. Exhaustion
// returns the final failed validation result with cumulative usage and actual
// repair attempts. An inability to generate or validate returns an error and
// no partial result.
//
// The built-in client retries eligible provider statuses using the effective
// Config or request budget. With R additional transient attempts and P repair
// generations, one run can dispatch at most (R+1)×(P+1) Promptkit-controlled
// model attempts. Each dispatched attempt receives its own generation and
// HTTP-client timeout; the caller context governs the full operation.
// Injected LLMClient implementations are not retried automatically.
//
// Run can return every error category documented by [Engine.Prepare], plus
// ErrCapacityExceeded and ErrLLMGenerate. Built-in HTTP execution failures
// additionally match ErrTransport; malformed successful responses and nil
// successful injected responses additionally match ErrMalformedResponse.
// 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. A built-in OpenAI-compatible non-2xx
// response is discoverable as [GenerationError]. Eligible-status exhaustion
// with a positive budget is discoverable as [RetryExhaustedError]. Injected
// errors remain available through errors.Is. Cancellation while waiting for
// model-generation capacity matches both ErrLLMGenerate and the context error.
// Cancellation otherwise follows the active collaborator's documented
// behavior. A nil Engine returns ErrInvalidConfig. Run returns no partial
// result on error.
func (e *Engine) Run(ctx context.Context, req RunRequest) (*RunResult, error) {
	if req.Observer == nil {
		return e.run(ctx, req)
	}
	recorder, idErr := observation.New(func(event domain.ExecutionEvent) { req.Observer(fromDomainExecutionEvent(event)) })
	recorder.Start()
	if idErr != nil {
		err := fmt.Errorf("failed to create run id: %w", idErr)
		terminal := observedFinish(nil, err)
		recorder.Finish(observation.FinishData{Outcome: terminal.Outcome, Failure: terminal.Failure})
		return nil, err
	}
	result, err := e.run(observation.WithRecorder(ctx, recorder), req)
	terminal := observedFinish(result, err)
	recorder.Finish(observation.FinishData{Outcome: terminal.Outcome, Failure: terminal.Failure,
		StatusCode: terminal.StatusCode, RetriesExhausted: terminal.RetriesExhausted})
	return result, err
}

func (e *Engine) run(ctx context.Context, req RunRequest) (*RunResult, error) {
	if e == nil || e.internal == nil {
		return nil, fmt.Errorf("%w: engine is nil", ErrInvalidConfig)
	}

	domainReq, err := toDomainRunRequest(req)
	if err != nil {
		return nil, fmt.Errorf("%w: %v", ErrInvalidRequest, err)
	}

	result, err := e.internal.Run(ctx, domainReq)
	if err != nil {
		return nil, mapPublicError(err)
	}
	return fromDomainRunResult(result), nil
}

// RunPrepared atomically claims and executes a handle created by
// [Engine.PrepareExecution].
//
// 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
// validation failure, and success all leave the handle unusable. A nil,
// zero-value, foreign-Engine, discarded, claimed, or used handle returns an
// error matching ErrInvalidRequest; a nil Engine returns ErrInvalidConfig and
// does not claim the handle.
//
// The supplied context governs this execution attempt independently of the
// preparation context. It covers credential revalidation, admission,
// generation, validation, and any bounded output repair. Result timing begins
// after the claim and excludes preparation and consumer-held delay.
//
// RunPrepared can return ErrInvalidRequest, ErrAPIKeyEnvMissing,
// ErrCapacityExceeded, ErrLLMGenerate, or ErrValidation as applicable while
// preserving documented collaborator and context identities. An engine
// admission rejection is discoverable as [CapacityError] and still matches
// ErrCapacityExceeded. A built-in OpenAI-compatible non-2xx response is
// discoverable as [GenerationError]. Built-in HTTP execution failures match
// ErrTransport; malformed successful responses and nil successful injected
// responses match ErrMalformedResponse. Positive-budget eligible-status
// exhaustion is discoverable as [RetryExhaustedError]. A completed
// content-validation rejection, including repair exhaustion, is returned in
// RunResult, not as an operational
// error. RunPrepared uses the retry choice frozen during PrepareExecution. An
// operational error returns no partial RunResult. A retained Observer begins
// only after a successful atomic claim, with identities from the frozen
// snapshot, and receives a terminal event on normal return after public error
// mapping. Invalid, foreign, discarded, or reused handles emit no events.
// Callbacks run outside the handle and capacity locks; panics propagate and
// do not promise a terminal event.
func (e *Engine) RunPrepared(ctx context.Context, prepared *PreparedExecution) (*RunResult, error) {
	if e == nil || e.internal == nil {
		return nil, fmt.Errorf("%w: engine is nil", ErrInvalidConfig)
	}

	var internal *usecase.PreparedExecution
	if prepared != nil {
		internal = prepared.internal
	}
	var recorder *observation.Recorder
	result, err := e.internal.RunPrepared(observation.WithClaimSink(ctx, &recorder), internal)
	if err != nil {
		mapped := mapPublicError(err)
		if recorder != nil {
			terminal := observedFinish(nil, mapped)
			recorder.Finish(observation.FinishData{Outcome: terminal.Outcome, Failure: terminal.Failure,
				StatusCode: terminal.StatusCode, RetriesExhausted: terminal.RetriesExhausted})
		}
		return nil, mapped
	}
	publicResult := fromDomainRunResult(result)
	if recorder != nil {
		terminal := observedFinish(publicResult, nil)
		recorder.Finish(observation.FinishData{Outcome: terminal.Outcome})
	}
	return publicResult, nil
}