Centralize candidate assessment and explicit producer fallback handling

This commit is contained in:
2026-11-21 23:20:17 +00:00
parent 797320b4da
commit c56c7d7ee9
13 changed files with 667 additions and 1570 deletions

View File

@@ -0,0 +1,71 @@
package contracts
import (
"errors"
"fmt"
"strings"
)
// ValidationUnavailableError marks an assessment that could not be performed,
// rather than a detected defect in the candidate. Its cause remains inspectable.
type ValidationUnavailableError struct{ Cause error }
func (e *ValidationUnavailableError) Error() string {
if e.Cause == nil {
return "validation unavailable"
}
return "validation unavailable: " + e.Cause.Error()
}
func (e *ValidationUnavailableError) Unwrap() error { return e.Cause }
// Accepted requires approval by every applicable validator. An empty configured
// chain has no additional acceptance criteria.
func (a CandidateAssessment) Accepted() bool {
for _, finding := range a.Validators {
if finding.Decision != AssessmentApproved {
return false
}
}
return true
}
// Guidance returns only actionable rejections, in validator order, with exact
// duplicates removed. Domain correction templates own the surrounding assignment.
func (a CandidateAssessment) Guidance() ([]string, error) {
var guidance []string
seen := make(map[string]bool)
for _, finding := range a.Validators {
if finding.Decision != AssessmentRejected {
continue
}
text := finding.Result.CorrectionGuidance
if strings.TrimSpace(text) == "" {
return nil, fmt.Errorf("validator %q rejected output without correction guidance", finding.ValidatorName)
}
if !seen[text] {
seen[text] = true
guidance = append(guidance, text)
}
}
return guidance, nil
}
// Err explains nonacceptance while preserving underlying operational causes.
// Neither this operator-facing text nor reason codes are correction instructions.
func (a CandidateAssessment) Err() error {
var failures []error
for _, finding := range a.Validators {
if finding.Decision == AssessmentApproved {
continue
}
if finding.Failure != nil {
failures = append(failures, fmt.Errorf("validator %q %s: %w", finding.ValidatorName, finding.Decision, finding.Failure))
} else if finding.Result.Message != "" {
failures = append(failures, fmt.Errorf("validator %q %s: %s", finding.ValidatorName, finding.Decision, finding.Result.Message))
} else {
failures = append(failures, fmt.Errorf("validator %q did not approve the candidate (%s)", finding.ValidatorName, finding.Decision))
}
}
return errors.Join(failures...)
}

View File

@@ -0,0 +1,57 @@
package contracts
import (
"errors"
"reflect"
"strings"
"testing"
)
func TestCandidateAssessmentKeepsGuidanceSeparateAndOrdered(t *testing.T) {
unavailable := errors.New("provider unavailable")
assessment := CandidateAssessment{Validators: []ValidatorAssessment{
{ValidatorName: "shape", Decision: AssessmentRejected, Result: ValidationResult{ReasonCode: "shape-code", Message: "operator prose", CorrectionGuidance: "Return the required shape."}},
{ValidatorName: "coverage", Decision: AssessmentRejected, Result: ValidationResult{ReasonCode: "coverage-code", CorrectionGuidance: "Include all supported events."}},
{ValidatorName: "duplicate", Decision: AssessmentRejected, Result: ValidationResult{CorrectionGuidance: "Return the required shape."}},
{ValidatorName: "remote", Decision: AssessmentUnavailable, Failure: &ValidationUnavailableError{Cause: unavailable}},
}}
guidance, err := assessment.Guidance()
if err != nil || !reflect.DeepEqual(guidance, []string{"Return the required shape.", "Include all supported events."}) {
t.Fatalf("guidance = %#v, %v", guidance, err)
}
if assessment.Accepted() || !errors.Is(assessment.Err(), unavailable) {
t.Fatalf("assessment = %#v, error = %v", assessment, assessment.Err())
}
for _, diagnostic := range []string{"shape-code", "coverage-code", "operator prose", "provider unavailable"} {
if strings.Contains(strings.Join(guidance, "\n"), diagnostic) {
t.Fatalf("diagnostic became correction instructions: %q", diagnostic)
}
}
}
func TestCandidateAssessmentRequiresEveryApproval(t *testing.T) {
if !(CandidateAssessment{}).Accepted() {
t.Fatal("empty validator chain rejected")
}
for _, decision := range []AssessmentDecision{AssessmentApproved, AssessmentRejected, AssessmentFailed, AssessmentUnavailable, ""} {
assessment := CandidateAssessment{Validators: []ValidatorAssessment{{Decision: AssessmentApproved}, {Decision: decision}}}
if got, want := assessment.Accepted(), decision == AssessmentApproved; got != want {
t.Fatalf("%s accepted = %t", decision, got)
}
}
}
func TestCandidateAssessmentDoesNotInventMissingGuidance(t *testing.T) {
for _, text := range []string{"", " \t\n"} {
assessment := CandidateAssessment{Validators: []ValidatorAssessment{{ValidatorName: "validator", Decision: AssessmentRejected, Result: ValidationResult{ReasonCode: "opaque", Message: "not instructions", CorrectionGuidance: text}}}}
if _, err := assessment.Guidance(); err == nil {
t.Fatal("missing actionable guidance accepted")
}
}
for _, decision := range []AssessmentDecision{AssessmentApproved, AssessmentFailed, AssessmentUnavailable} {
guidance, err := (CandidateAssessment{Validators: []ValidatorAssessment{{Decision: decision, Result: ValidationResult{Message: "not instructions"}}}}).Guidance()
if err != nil || len(guidance) != 0 {
t.Fatalf("nonrejection guidance = %#v, %v", guidance, err)
}
}
}