frontendpipe

type CandidateAssessmentResult struct {
	// Assessment is the outcome returned by LargeBodyAssessor.AssessLargeBody.
	Assessment largebody.Assessment
	// PermitHeld reports whether the decode-admission permit was held during assessment.
	PermitHeld bool
	// Err is any error returned by AssessLargeBody or assessor resolution.
	Err error
}

type CandidateCaptureResult struct {
	// Outcome reports whether capture completed, declined, or failed.
	Outcome largebody.CaptureOutcome
	// Source is the completed replay source (non-nil on CaptureOutcomeCompleted).
	Source largebody.Source
	// Completed is the concrete CompletedSource (non-nil on CaptureOutcomeCompleted).
	Completed *largebody.CompletedSource
	// Continuation is the lossless continuation reader (non-nil on CaptureOutcomeDeclined).
	Continuation *largebody.CaptureReader
	// Digest is the replay source integrity digest computed incrementally during capture.
	Digest largebody.SourceDigest
	// BytesRead is the total client body bytes read during capture.
	BytesRead int64
	// ScannerResult carries token and depth facts from the shared streaming JSON scanner.
	ScannerResult jsonshape.Result
	// ScannerErr reports any syntax or limit error from the shared streaming JSON scanner.
	ScannerErr error
	// Err is any underlying error that caused decline or failure.
	Err error
}

type CandidateProofResult struct {
	// Output is the compiled proof output (valid when Err is nil).
	Output ProofOutput
	// PermitHeld indicates that the decode-admission permit was held during proof compilation.
	PermitHeld bool
	// Err is any proof compilation or validation error.
	Err error
}

type Config struct {
	Exec                    lipsdk.ExecutorView
	DefaultRouteSelector    string
	RoutePrefixes           routeselect.PrefixSet
	MaxRequestBodyBytes     int64
	Log                     *slog.Logger
	TrafficPorts            traffic.PortBundle
	DecodeAdmission         lipsdk.DecodeAdmission
	PreRequestKeepalive     lipsdk.FrontendKeepaliveConfig
	FrontendID              string
	HTTPHeaders             lipsdk.HTTPHeaders
	StreamKeepaliveInterval time.Duration
	LargePayload            LargePayloadConfig
}

type DecodeContext struct {
	Ctx              context.Context
	Body             []byte
	RouteSelector    string
	Headers          http.Header
	Path             PathMatch
	URLPath          string
	AnthropicVersion string
}

type Decoded struct {
	Call   *lipapi.Call
	Stream bool
	// RouteSelector is the resolved routing selector used for decode/logging.
	RouteSelector string
	// Extra holds per-request protocol state (continuation, response IDs).
	Extra any
}

type FrontendProfile interface {
	// ProfileID returns the static identifier for this certified profile
	// (e.g., "openai_responses_v1", "openai_chat_v1", "openresponses_v1").
	ProfileID() string

	// CompileProof compiles protocol proof and response seeds from the
	// captured request replay under decode admission. If the request shape
	// cannot be certified or exceeds semantic-fact bounds, it returns an error
	// to select canonical fallback under the held permit (Requirements 4, 16.7).
	CompileProof(ctx context.Context, in ProofInput) (ProofOutput, error)
}

type FrontendWireState struct {
	ProfileID string
	Proof     largebody.Proof
	Seeds     ResponseStateSeeds
	Extra     any
}

type HookErrorWriter interface {
	WriteHookError(w http.ResponseWriter, err error) error
}

type LargePayloadConfig = httpcontract.LargePayloadInput

type OpenAIWire struct{}

type PathMatch struct {
	Model  string
	Stream bool
	Extra  any
}

type PreCaptureGate uint8

type PreCaptureResult struct {
	// Candidate reports whether all cheap pre-capture gates passed.
	Candidate bool
	// Gate indicates which gate declined or completed evaluation.
	Gate PreCaptureGate
	// Reason reports the bounded decline reason (matches largebody.StaticWireReason).
	Reason largebody.StaticWireReason
	// Executor is the probed LargeBodyExecutor (non-nil when Candidate is true).
	Executor largebody.LargeBodyExecutor
}

type ProofInput struct {
	Ctx                  context.Context
	Headers              http.Header
	URLPath              string
	Path                 PathMatch
	RouteSelector        string
	RoutePrefixes        routeselect.PrefixSet
	DefaultRouteSelector string
	RouteFromBodyModel   bool
	Source               largebody.Source
	BodyBytes            int64
	AnthropicVersion     string
}

type ProofOutput struct {
	State FrontendWireState
}

type ResponseContext struct {
	// State is the frontend-owned proof state including response seeds and extra protocol state.
	State FrontendWireState
	// ResponseFacts contains bounded provider-neutral facts returned by ExecuteLargeBody.
	ResponseFacts largebody.ResponseFacts
	// Session carries sensitive session response carriers returned by ExecuteLargeBody.
	Session largebody.SessionResponseCarrier
	// Stream is the canonical event stream returned by ExecuteLargeBody.
	Stream lipapi.EventStream
}

type ResponseStateSeeds struct {
	// DeterministicCallID is the path-stable call ID derived from canonical semantic identity.
	DeterministicCallID string
	// DeterministicTimestamp is the Unix timestamp derived from canonical semantic identity.
	DeterministicTimestamp int64
	// DeterministicToken is the 16-hex-character token derived from canonical semantic identity.
	DeterministicToken string
	// ExplicitRequestID is any caller-provided or header-supplied request ID.
	ExplicitRequestID string
	// RouteSelector is the effective routing selector.
	RouteSelector string
	// ClientModel is the requested client model name.
	ClientModel string
	// Stream indicates whether streaming delivery was requested.
	Stream bool
	// CancellationID is the frontend cancellation identifier seed (e.g. for OpenAI Responses).
	CancellationID string
	// SessionID is the client/authoritative session identifier.
	SessionID string
	// ALegID is the authoritative A-leg identifier.
	ALegID string
}

type Spec[Opts any] struct {
	Config
	Wire WireErrors
	// Profile optionally enables large-payload fast-path candidate evaluation (Task 7.1).
	Profile FrontendProfile
	// OnPreCaptureGate optionally observes candidate gate decisions (Task 7.3).
	OnPreCaptureGate func(r *http.Request, res PreCaptureResult)
	// OnCandidateCapture optionally observes candidate capture outcomes (Task 7.4).
	OnCandidateCapture func(r *http.Request, res CandidateCaptureResult)
	// OnCandidateProof optionally observes candidate protocol proof outcomes (Task 7.5).
	OnCandidateProof func(r *http.Request, res CandidateProofResult)
	// OnCandidateAssessment optionally observes candidate assessment outcomes (Task 11.9).
	OnCandidateAssessment func(r *http.Request, res CandidateAssessmentResult)
	// OnWireCommit optionally observes wire commit execution outcomes (Task 11.9).
	OnWireCommit func(r *http.Request, res WireCommitResult)
	// MatchPath returns ok=false for 404. When AltServe is non-nil and invoked, the pipeline stops.
	MatchPath func(path string) (pm PathMatch, ok bool)
	AltServe  func(ctx context.Context, w http.ResponseWriter, r *http.Request) bool
	// ResolveRouteSelector runs after body read; pm is zero when MatchPath did not apply.
	ResolveRouteSelector func(r *http.Request, body []byte, pm PathMatch) string
	Decode               func(DecodeContext) (*Decoded, error)
	AfterDecode          func(ctx context.Context, decoded *Decoded) error
	WrapStream           func(ctx context.Context, decoded *Decoded, inner lipapi.EventStream) (lipapi.EventStream, error)
	OnExecuteError       func(ctx context.Context, decoded *Decoded, err error)
	ClassifyExecute      func(err error) execerr.Outcome
	BuildEncodeOpts      func(decoded *Decoded) Opts
	WriteStream          func(ctx context.Context, w http.ResponseWriter, call *lipapi.Call, es lipapi.EventStream, opts Opts) error
	WriteNonStream       func(ctx context.Context, w http.ResponseWriter, call *lipapi.Call, es lipapi.EventStream, opts Opts) error
	// WireWrapStream optionally wraps the canonical event stream on wire execution using bounded ResponseContext (Requirement 18.4).
	WireWrapStream func(ctx context.Context, rc ResponseContext, inner lipapi.EventStream) (lipapi.EventStream, error)
	// WireWriteStream writes streaming responses on wire execution using bounded ResponseContext (Requirement 18.4).
	WireWriteStream func(ctx context.Context, w http.ResponseWriter, rc ResponseContext, es lipapi.EventStream) error
	// WireWriteNonStream writes non-streaming responses on wire execution using bounded ResponseContext (Requirement 18.4).
	WireWriteNonStream func(ctx context.Context, w http.ResponseWriter, rc ResponseContext, es lipapi.EventStream) error
	// RouteFromBodyModel defaults route selector from JSON model field when header absent.
	RouteFromBodyModel bool
}

type StaticDispositionProvider interface {
	LargeBodyStaticDisposition(profileID string) (largebody.StaticWireDisposition, largebody.StaticWireReason)
}

type StatusError struct {
	Status  int
	Type    string
	Code    string
	Message string
	Err     error
}

type WireCommitResult struct {
	// Assessment is the accepted assessment that authorized the wire commit.
	Assessment largebody.Assessment
	// Result is the outcome returned by LargeBodyWireExecutor.ExecuteLargeBody.
	Result largebody.ExecutionResult
	// ResponseContext is the bounded frontend response context constructed on wire execution (Task 14.1).
	ResponseContext ResponseContext
	// PermitHeld reports whether the decode-admission permit was held during ExecuteLargeBody (must be false).
	PermitHeld bool
	// Err is any error returned by ExecuteLargeBody.
	Err error
}

type WireErrors interface {
	WriteBodyTooLarge(w http.ResponseWriter) error
	WriteReadBodyFailed(w http.ResponseWriter) error
	WriteExecutorNotConfigured(w http.ResponseWriter) error
	WritePreflightCanceled(w http.ResponseWriter) error
	WriteInvalidJSON(w http.ResponseWriter) error
	WriteAdmissionReject(w http.ResponseWriter, d decodeqos.Decision) error
	WriteInvalidRequest(w http.ResponseWriter) error
	WriteExecuteError(w http.ResponseWriter, out execerr.Outcome) error
	WriteEncodeFailed(w http.ResponseWriter) error
}