Improve semantic reconciliation retries

internal/framework/semanticreconcile/proposal.go

@@ -3,6 +3,10 @@ package semanticreconcile
 import (
 	"fmt"
 	"sort"
+	"strings"
+	"unicode/utf8"
+
+	"gitea.maximumdirect.net/eric/notarius/internal/framework/contracts"
 )
 
 // ProposalResponse is the complete private structured response contract.
@@ -31,6 +35,28 @@ const (
 	IssueOverlappingMember    IssueCategory = "overlapping_member"
 )
 
+var allIssueCategories = []IssueCategory{
+	IssueMemberNonPositive,
+	IssueMemberUnknown,
+	IssueRepeatedMember,
+	IssueFewerThanTwoMembers,
+	IssueCanonicalNonPositive,
+	IssueCanonicalUnknown,
+	IssueCanonicalNotMember,
+	IssueOverlappingMember,
+}
+
+var issueCorrectionProse = map[IssueCategory]string{
+	IssueMemberNonPositive:    "Use only positive candidate IDs from the supplied candidate list.",
+	IssueMemberUnknown:        "Remove every candidate ID that is not present in the supplied candidate list.",
+	IssueRepeatedMember:       "List each candidate ID at most once within the duplicate group.",
+	IssueFewerThanTwoMembers:  "Include at least two distinct candidate IDs, or omit the duplicate group.",
+	IssueCanonicalNonPositive: "Choose a positive canonical_candidate_id from the supplied candidate list.",
+	IssueCanonicalUnknown:     "Choose canonical_candidate_id from the supplied candidate list.",
+	IssueCanonicalNotMember:   "Make canonical_candidate_id one of the candidate_ids in the same duplicate group.",
+	IssueOverlappingMember:    "Place each candidate ID in at most one duplicate group.",
+}
+
 // Issue identifies an unsafe proposal category at its original response group
 // index without prescribing caller diagnostic text.
 type Issue struct {
@@ -38,8 +64,8 @@ type Issue struct {
 	Category   IssueCategory
 }
 
-// IssueDetails renders stable, domain-neutral proposal diagnostics for an
-// adapter's retry message.
+// IssueDetails renders stable, domain-neutral proposal diagnostics for
+// operators and debug records. Its internal categories are not model guidance.
 func IssueDetails(issues []Issue) []string {
 	details := make([]string, len(issues))
 	for index, issue := range issues {
@@ -48,6 +74,94 @@ func IssueDetails(issues []Issue) []string {
 	return details
 }
 
+// CorrectionDetails translates proposal issues into stable model-facing prose.
+// The response-local group ordinals help the model find the defective group in
+// the exact response appended to the correction request.
+func CorrectionDetails(issues []Issue) ([]string, error) {
+	groupsByCategory := make(map[IssueCategory][]int)
+	seen := make(map[IssueCategory]map[int]struct{})
+	for _, issue := range issues {
+		if issue.GroupIndex < 0 {
+			return nil, fmt.Errorf("semantic reconciliation issue group index must not be negative")
+		}
+		if _, exists := issueCorrectionProse[issue.Category]; !exists {
+			return nil, fmt.Errorf("semantic reconciliation issue category %q has no correction guidance", issue.Category)
+		}
+		if seen[issue.Category] == nil {
+			seen[issue.Category] = make(map[int]struct{})
+		}
+		if _, exists := seen[issue.Category][issue.GroupIndex]; exists {
+			continue
+		}
+		seen[issue.Category][issue.GroupIndex] = struct{}{}
+		groupsByCategory[issue.Category] = append(groupsByCategory[issue.Category], issue.GroupIndex)
+	}
+
+	details := make([]string, 0, len(groupsByCategory))
+	for _, category := range allIssueCategories {
+		groups := groupsByCategory[category]
+		if len(groups) == 0 {
+			continue
+		}
+		sort.Ints(groups)
+		details = append(details, fmt.Sprintf("%s: %s", correctionGroupLabel(groups), issueCorrectionProse[category]))
+	}
+	return details, nil
+}
+
+// CorrectionGuidance builds one bounded request for a complete corrected
+// proposal. Additional details let a typed owner append a domain rule without
+// weakening or duplicating the shared protocol guidance.
+func CorrectionGuidance(issues []Issue, additionalDetails ...string) (string, error) {
+	details, err := CorrectionDetails(issues)
+	if err != nil {
+		return "", err
+	}
+	for _, detail := range additionalDetails {
+		if !utf8.ValidString(detail) {
+			return "", fmt.Errorf("semantic reconciliation additional correction detail has invalid UTF-8")
+		}
+		detail = strings.TrimSpace(detail)
+		if detail == "" {
+			return "", fmt.Errorf("semantic reconciliation additional correction detail must not be blank")
+		}
+		details = append(details, detail)
+	}
+	if len(details) == 0 {
+		return "", fmt.Errorf("semantic reconciliation correction guidance requires at least one detail")
+	}
+
+	parts := make([]string, 0, len(details)+2)
+	parts = append(parts, "The previous semantic-duplicate proposal was invalid.")
+	parts = append(parts, details...)
+	parts = append(parts, "Return one complete corrected JSON response that follows the original instructions; do not return a patch or commentary.")
+	guidance := strings.Join(parts, " ")
+	if len(guidance) > contracts.MaxNormalizeRetryCorrectionGuidanceBytes {
+		return "", fmt.Errorf("semantic reconciliation correction guidance exceeds maximum length")
+	}
+	return guidance, nil
+}
+
+func correctionGroupLabel(groupIndexes []int) string {
+	const maximumDisplayedGroups = 12
+	displayed := groupIndexes
+	if len(displayed) > maximumDisplayedGroups {
+		displayed = displayed[:maximumDisplayedGroups]
+	}
+	ordinals := make([]string, len(displayed))
+	for index, groupIndex := range displayed {
+		ordinals[index] = fmt.Sprintf("%d", groupIndex+1)
+	}
+	if len(groupIndexes) == 1 {
+		return "Duplicate group " + ordinals[0]
+	}
+	label := "Duplicate groups " + strings.Join(ordinals, ", ")
+	if omitted := len(groupIndexes) - len(displayed); omitted > 0 {
+		label += fmt.Sprintf(", and %d additional affected group(s)", omitted)
+	}
+	return label
+}
+
 // PlanGroup identifies one validated group using original candidate positions.
 type PlanGroup struct {
 	memberPositions   []int