Improve D&D validation reliability

internal/modules/dnd/shared/diagnostics/diagnostics.go

@@ -7,6 +7,7 @@ import (
 	"strconv"
 	"strings"
 
+	"gitea.maximumdirect.net/eric/notarius/internal/core/source"
 	"gitea.maximumdirect.net/eric/notarius/internal/framework/contracts"
 	frameworkdiagnostics "gitea.maximumdirect.net/eric/notarius/internal/framework/diagnostics"
 )
@@ -25,6 +26,79 @@ type Finding struct {
 	Message    string
 }
 
+// Corrections collects domain-owned model instructions and contextual record
+// descriptions without coupling them to operator-facing diagnostics. Rules are
+// emitted before affected records so the bounded result remains useful even
+// when a large candidate exceeds the display budget.
+type Corrections struct {
+	groups  []correctionGroup
+	indexes map[string]int
+}
+
+type correctionGroup struct {
+	rule        string
+	records     []string
+	recordsSeen map[string]struct{}
+}
+
+// Add records one semantic rule and, when non-empty, one contextual record to
+// which it applies. key is local grouping state and is never rendered.
+func (c *Corrections) Add(key, rule, record string) {
+	if c.indexes == nil {
+		c.indexes = make(map[string]int)
+	}
+	index, ok := c.indexes[key]
+	if !ok {
+		index = len(c.groups)
+		c.indexes[key] = index
+		c.groups = append(c.groups, correctionGroup{rule: rule, recordsSeen: make(map[string]struct{})})
+	}
+	if record == "" {
+		return
+	}
+	group := &c.groups[index]
+	if _, seen := group.recordsSeen[record]; seen {
+		return
+	}
+	group.recordsSeen[record] = struct{}{}
+	group.records = append(group.records, record)
+}
+
+// Guidance returns one bounded correction request. It deliberately renders
+// neither grouping keys nor operator diagnostics.
+func (c Corrections) Guidance(prefix string) string {
+	issues := make([]string, 0, len(c.groups)*2)
+	for _, group := range c.groups {
+		issues = append(issues, group.rule)
+	}
+	for _, group := range c.groups {
+		issues = append(issues, group.records...)
+	}
+	return Aggregate(prefix, issues)
+}
+
+// SourceRange describes cited transcript positions without exposing source
+// identities or application entity IDs.
+func SourceRange(refs []source.SourceRef) string {
+	if len(refs) == 0 {
+		return "without a cited source range"
+	}
+	description := SourceRefRange(refs[0])
+	if len(refs) > 1 {
+		description += fmt.Sprintf(" (first of %d cited ranges)", len(refs))
+	}
+	return description
+}
+
+// SourceRefRange describes one transcript range without exposing its source
+// identity.
+func SourceRefRange(ref source.SourceRef) string {
+	if ref.StartUnitID == ref.EndUnitID {
+		return "at source unit " + strconv.Itoa(ref.StartUnitID)
+	}
+	return fmt.Sprintf("at source units %d-%d", ref.StartUnitID, ref.EndUnitID)
+}
+
 // DataQualityResult converts accepted source-quality findings into bounded,
 // locally grouped advisories. These findings do not indicate process
 // degradation.

internal/modules/dnd/shared/diagnostics/diagnostics_test.go

@@ -6,9 +6,40 @@ import (
 	"testing"
 	"unicode/utf8"
 
+	"gitea.maximumdirect.net/eric/notarius/internal/core/source"
 	"gitea.maximumdirect.net/eric/notarius/internal/framework/contracts"
 )
 
+func TestCorrectionsGroupRulesBeforeContextAndHideKeys(t *testing.T) {
+	var corrections Corrections
+	corrections.Add("internal-kind", "Use a supported kind.", "Affected goblin at source unit 4.")
+	corrections.Add("internal-kind", "Use a supported kind.", "Affected ogre at source units 8-9.")
+	corrections.Add("internal-kind", "Use a supported kind.", "Affected goblin at source unit 4.")
+	corrections.Add("name", "Provide a contextual name.", "Affected unnamed record at source unit 12.")
+
+	guidance := corrections.Guidance("Correct every record")
+	if strings.Contains(guidance, "internal-kind") {
+		t.Fatalf("Guidance() exposed grouping key: %q", guidance)
+	}
+	if strings.Count(guidance, "Use a supported kind.") != 1 || strings.Count(guidance, "Affected goblin") != 1 {
+		t.Fatalf("Guidance() did not de-duplicate rules and records: %q", guidance)
+	}
+	if strings.Index(guidance, "Use a supported kind.") > strings.Index(guidance, "Affected goblin") {
+		t.Fatalf("Guidance() = %q, want rules before records", guidance)
+	}
+}
+
+func TestSourceRangeUsesOnlyTranscriptPositions(t *testing.T) {
+	refs := []source.SourceRef{
+		{SourceID: "opaque-source", StartUnitID: 8, EndUnitID: 10},
+		{SourceID: "opaque-source", StartUnitID: 12, EndUnitID: 12},
+	}
+	got := SourceRange(refs)
+	if strings.Contains(got, "opaque-source") || !strings.Contains(got, "8-10") || !strings.Contains(got, "first of 2") {
+		t.Fatalf("SourceRange() = %q", got)
+	}
+}
+
 func TestAggregateEnforcesByteBudgetAndReportsOmissions(t *testing.T) {
 	issues := make([]string, MaxIssues)
 	for index := range issues {