package contracts import ( "context" "go.maximumdirect.net/promptkit" ) type ExecutionMode string const ( ModeStrict ExecutionMode = "strict" ModePermissive ExecutionMode = "permissive" ) type CacheMode string const ( CacheAuto CacheMode = "auto" CacheBypass CacheMode = "bypass" CacheRefresh CacheMode = "refresh" ) // ArtifactCache stores accepted artifact bytes under an opaque native message // hash. A nil lookup is a miss. Other lookup/write errors are diagnostic data, // not reasons to fail otherwise successful production. Callers own typed codec // and source-usability checks and must never store rejected or fallback output. type ArtifactCache interface { Lookup(context.Context, CacheMode, string) ([]byte, error) Store(context.Context, CacheMode, string, []byte) error } // CacheObservation is transient operation evidence, not a persisted record or // public report format. Prepared details are available even when lookup hits // and native execution (and its OnPrepared callback) never happens. type CacheObservation struct { Decision string MessageContentHash string Prepared *promptkit.PreparedRun Artifact []byte `json:"-"` Err error ChunkID string ChunkIndex *int } // ProducerCache binds the expected artifact codec and ordinary source usability // to a store. Decode must not invoke the configured semantic validator chain. type ProducerCache[T any] struct { Store ArtifactCache Encode func(T) ([]byte, error) Decode func([]byte) (T, error) Observe func(context.Context, CacheObservation) error } // ProducerControls is resolved before execution; modules do not inherit settings. type ProducerControls struct { Mode ExecutionMode `json:"mode"` MaxAdditionalTurns int `json:"max_additional_turns"` Cache CacheMode `json:"cache"` } // ExecutionOptions carries native request options, not a completion protocol. // Observer closures shared by concurrent operations must synchronize their state. type ExecutionOptions struct { Execution *promptkit.ExecutionTargetOverride TransientRetries *int Observer promptkit.ExecutionObserver `json:"-"` OnPrepared func(context.Context, promptkit.PreparedRun) `json:"-"` Capture EvidenceWriter `json:"-"` } // EvidenceWriter receives optional operation-scoped debug evidence. Modules get // no filesystem root and cannot use capture as an execution or reporting service. type EvidenceWriter interface { WriteJSON(string, any) error WriteBytes(string, []byte) error } // RecordEvidence writes available application-owned evidence at an ordinary // operation boundary. A recording failure must not become semantic fallback. func (options ExecutionOptions) RecordEvidence(name string, value any) error { if options.Capture == nil { return nil } if err := options.Capture.WriteJSON(name, value); err != nil { return &CaptureError{Cause: err} } return nil } // CaptureError is an ordinary framework failure, not a semantic assessment or a // reason to invoke a model again. Its cause remains available to the caller. type CaptureError struct{ Cause error } func (e *CaptureError) Error() string { return "record debug evidence: " + e.Cause.Error() } func (e *CaptureError) Unwrap() error { return e.Cause } type AssessmentDecision string const ( AssessmentApproved AssessmentDecision = "approved" AssessmentRejected AssessmentDecision = "rejected" AssessmentFailed AssessmentDecision = "failed" AssessmentUnavailable AssessmentDecision = "unavailable" ) // ValidatorAssessment keeps model-facing guidance in Result separate from // diagnostic reason codes, operator prose, and operational failures. type ValidatorAssessment struct { ValidatorName string Decision AssessmentDecision Result ValidationResult Failure error } // CandidateAssessment contains the complete ordered chain for one candidate. type CandidateAssessment struct { Validators []ValidatorAssessment } type CandidateAssessor[T any] func(context.Context, T) (CandidateAssessment, error) // ProducerOperation is supplied explicitly by the runner for one operation. // Validators receive ExecutionOptions, never a producer assessment callback. type ProducerOperation[T any] struct { Controls ProducerControls Assess CandidateAssessor[T] `json:"-"` Execution ExecutionOptions ReuseEligible bool Cache *ProducerCache[T] `json:"-"` } type ProducerDisposition string const ( ProducerAccepted ProducerDisposition = "accepted" ProducerFallback ProducerDisposition = "fallback" ) // ProducerOutcome qualifies a returned domain value without wrapping a native // execution result. A zero outcome is not accepted or eligible for reuse. type ProducerOutcome struct { Disposition ProducerDisposition `json:"disposition"` FallbackReason string `json:"fallback_reason,omitempty"` ReuseEligible bool `json:"reuse_eligible"` }