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 } // 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:"-"` } 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 } 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"` }