package promptkit

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.
//
// PreparedExecution contains no supported serializable state and cannot be
// used as a restartable job. Copying the value preserves the same shared
// lifecycle; it does not create another execution attempt.
type PreparedExecution struct {
	internal *usecase.PreparedExecution
}

// Details returns a fresh caller-owned, credential-redacted copy of the
// prepared request details. Mutating the result cannot affect execution or a
// later Details call. Details remains available after execution or discard.
//
// A nil receiver or zero-value PreparedExecution returns a zero [PreparedRun].
func (p *PreparedExecution) Details() PreparedRun {
	if p == nil || p.internal == nil {
		return PreparedRun{}
	}
	details := fromDomainPreparedRun(p.internal.Details())
	if details == nil {
		return PreparedRun{}
	}
	return *details
}

// Discard invalidates an unclaimed handle and drops Promptkit's references to
// its execution-only state. Discard is nil-safe and idempotent. It does not
// cancel an execution that has already claimed the handle; use the
// [Engine.RunPrepared] context for cancellation.
func (p *PreparedExecution) Discard() {
	if p == nil || p.internal == nil {
		return
	}
	p.internal.Discard()
}

// String returns a constant representation that exposes no retained request,
// rendered content, or credential data.
func (p *PreparedExecution) String() string {
	return preparedExecutionString
}

// GoString returns a constant Go-syntax representation that exposes no
// retained request, rendered content, or credential data.
func (p *PreparedExecution) GoString() string {
	return preparedExecutionString
}