eric/notarius
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Improve D&D validation reliability

Browse Source
This commit is contained in:
Eric Rakestraw
2026-08-29 01:24:45 +00:00
parent 4da9360d74
commit 917d150279
55 changed files with 1300 additions and 565 deletions
Download Patch File Download Diff File Expand all files Collapse all files

32
internal/modules/dnd/validate/npcregistry/identity/validator.go
View File

@@ -14,9 +14,10 @@ import (
)
const (
Key = "normalize/dnd/npc-registry/identity"
ReasonCode = "invalid_npc_identity"
policy = domainidentity.Policy
Key = "normalize/dnd/npc-registry/identity"
ReasonCode = "invalid_npc_identity"
policy = domainidentity.Policy
correctionPolicy = "dnd.npc_registry.validator.identity.v2"
)
type Options struct{}
@@ -33,7 +34,7 @@ func (v *Validator) ExecutionClass() contracts.ExecutionClass {
}
func (v *Validator) CheckpointFingerprints() []pipeline.CheckpointFingerprint {
return []pipeline.CheckpointFingerprint{{Name: "policy", Value: policy}}
return []pipeline.CheckpointFingerprint{{Name: "policy", Value: policy}, {Name: "correction_policy", Value: correctionPolicy}}
}
func (v *Validator) Validate(_ context.Context, req contracts.TypedValidationRequest[dnd.NPCRegistry]) (contracts.ValidationResult, error) {
@@ -46,18 +47,39 @@ func (v *Validator) Validate(_ context.Context, req contracts.TypedValidationReq
}
issues := make([]string, len(identityIssues))
var corrections diagnostics.Corrections
for index, issue := range identityIssues {
location := fmt.Sprintf("npcs[%d]", issue.RecordIndex)
issues[index] = fmt.Sprintf("%s %s: %s", location, issue.Code, diagnostics.Quote(issue.Value))
if issue.RecordIndex < 0 || issue.RecordIndex >= len(req.Value.NPCs) {
continue
}
npc := req.Value.NPCs[issue.RecordIndex]
corrections.Add(string(issue.Code), npcIdentityCorrection(issue.Code), fmt.Sprintf("Affected NPC %s %s.", diagnostics.Quote(npc.Name), diagnostics.SourceRange(npc.SourceRefs)))
}
return contracts.ValidationResult{
Approved: false,
ReasonCode: ReasonCode,
Message: diagnostics.Aggregate("invalid NPC identity", issues),
CorrectionGuidance: "Return one canonical registry entry per distinct properly named NPC, combining duplicate mentions under the same transcript-supported name.",
CorrectionGuidance: corrections.Guidance("Correct the duplicate-group proposals and return the complete replacement proposal response"),
}, nil
}
func npcIdentityCorrection(code domainidentity.IssueCode) string {
switch code {
case domainidentity.IssueEmptyCanonicalName:
return "Select a canonical proposal member with a nonblank, transcript-supported proper NPC name."
case domainidentity.IssueDuplicateCanonical:
return "Put duplicate mentions of the same NPC in one proposal group and select one transcript-supported canonical member."
case domainidentity.IssueInvalidID, domainidentity.IssueIDMismatch:
return "Revise the proposal so its canonical NPC member has a valid transcript-supported name; Notarius derives durable identity without model input."
case domainidentity.IssueDuplicateID:
return "Do not use proposals that collapse distinct NPCs into one canonical identity; group only records that describe the same NPC."
default:
return "Revise the duplicate-group proposal so every canonical NPC is transcript-supported and distinct."
}
}
func Spec() pipeline.ValidatorSpec {
return pipeline.ValidatorSpec{Key: Key, ExecutionClass: contracts.ExecutionClassDeterministic}
}

5
internal/modules/dnd/validate/npcregistry/identity/validator_test.go
View File

@@ -21,7 +21,7 @@ func TestValidatorContractAndRegistration(t *testing.T) {
if _, err := DecodeOptions(map[string]any{"unexpected": true}); err == nil || !strings.Contains(err.Error(), "unknown option") {
t.Fatalf("DecodeOptions() error = %v, want unknown option error", err)
}
if got := New(Options{}).CheckpointFingerprints(); len(got) != 1 || got[0].Name != "policy" || got[0].Value != policy {
if got := New(Options{}).CheckpointFingerprints(); len(got) != 2 || got[0].Name != "policy" || got[0].Value != policy || got[1].Name != "correction_policy" || got[1].Value != correctionPolicy {
t.Fatalf("fingerprints = %#v, want identity policy", got)
}
@@ -65,6 +65,9 @@ func TestValidatorDefersShapeAndRejectsIdentityIssues(t *testing.T) {
t.Fatalf("identity message %q missing %q", result.Message, want)
}
}
if !strings.Contains(result.CorrectionGuidance, "duplicate-group proposals") || !strings.Contains(result.CorrectionGuidance, value.NPCs[0].Name) || strings.Contains(result.CorrectionGuidance, value.NPCs[0].ID) || strings.Contains(result.CorrectionGuidance, "npcs[") {
t.Fatalf("CorrectionGuidance = %q, want contextual proposal guidance without IDs or operator paths", result.CorrectionGuidance)
}
}
func TestValidatorBoundsUnicodeDiagnostics(t *testing.T) {

37
internal/modules/dnd/validate/npcregistry/shape/validator.go
View File

@@ -14,7 +14,7 @@ import (
const (
Key = "extract/dnd/npc-registry/shape"
ReasonCode = "invalid_npc_shape"
policy = "dnd.npc_registry.validator.shape.v1"
policy = "dnd.npc_registry.validator.shape.v2"
)
type Options struct{}
@@ -33,39 +33,58 @@ func (v *Validator) CheckpointFingerprints() []pipeline.CheckpointFingerprint {
}
func (v *Validator) Validate(_ context.Context, req contracts.TypedValidationRequest[dnd.NPCRegistry]) (contracts.ValidationResult, error) {
issues := issuesFor(req.Value)
normalization := req.Stage == string(pipeline.StageNormalize)
issues, corrections := assess(req.Value, normalization)
if len(issues) > 0 {
return rejection(diagnostics.Aggregate("invalid NPC shape", issues)), nil
prefix := "Correct every rejected NPC and return the complete replacement registry"
if normalization {
prefix = "Correct the duplicate-group proposals and return the complete replacement proposal response"
}
return rejection(diagnostics.Aggregate("invalid NPC shape", issues), corrections.Guidance(prefix)), nil
}
return contracts.ValidationResult{Approved: true}, nil
}
func Validate(value dnd.NPCRegistry) error {
issues := issuesFor(value)
issues, _ := assess(value, false)
if len(issues) == 0 {
return nil
}
return fmt.Errorf("%s", diagnostics.Aggregate("invalid NPC shape", issues))
}
func issuesFor(value dnd.NPCRegistry) []string {
func assess(value dnd.NPCRegistry, normalization bool) ([]string, diagnostics.Corrections) {
var corrections diagnostics.Corrections
nameRule := "Provide one nonblank, transcript-supported proper NPC name for every registry entry."
refRule := "Provide at least one transcript source range that directly supports every named NPC."
listRule := "Return an `npcs` array; use an empty array when the transcript establishes no named NPCs."
if normalization {
nameRule = "Revise the duplicate-group proposals so every selected canonical NPC has a nonblank, transcript-supported proper name."
refRule = "Revise the duplicate-group proposals so every selected canonical NPC preserves direct transcript evidence."
listRule = "Revise the duplicate-group proposals so normalization retains the complete NPC candidate registry."
}
issues := make([]string, 0)
if value.NPCs == nil {
return []string{"npcs must be present"}
corrections.Add("list", listRule, "")
return []string{"npcs must be present"}, corrections
}
for index, npc := range value.NPCs {
prefix := fmt.Sprintf("npcs[%d]", index)
record := "Affected NPC " + diagnostics.Quote(strings.TrimSpace(npc.Name)) + " " + diagnostics.SourceRange(npc.SourceRefs) + "."
if strings.TrimSpace(npc.ID) == "" {
issues = append(issues, prefix+".id must not be empty")
corrections.Add("name", nameRule, record)
}
if strings.TrimSpace(npc.Name) == "" {
issues = append(issues, prefix+".name must not be empty")
corrections.Add("name", nameRule, record)
}
if len(npc.SourceRefs) == 0 {
issues = append(issues, prefix+".source_refs must not be empty")
corrections.Add("source-refs", refRule, record)
}
}
return issues
return issues, corrections
}
func Spec() pipeline.ValidatorSpec {
@@ -91,6 +110,6 @@ func DecodeOptions(options map[string]any) (Options, error) {
func validateOptions(options map[string]any) error { _, err := DecodeOptions(options); return err }
func rejection(message string) contracts.ValidationResult {
return contracts.ValidationResult{Approved: false, ReasonCode: ReasonCode, Message: message, CorrectionGuidance: "Return a complete NPC registry containing only properly named NPCs with valid source references."}
func rejection(message, guidance string) contracts.ValidationResult {
return contracts.ValidationResult{Approved: false, ReasonCode: ReasonCode, Message: message, CorrectionGuidance: guidance}
}

17
internal/modules/dnd/validate/npcregistry/shape/validator_test.go
View File

@@ -50,7 +50,7 @@ func TestValidatorBoundsDiagnosticsAndQuotesUnicode(t *testing.T) {
}
func TestValidatorSpecCheckpointAndRegistration(t *testing.T) {
if got := New(Options{}).CheckpointFingerprints(); len(got) != 1 || got[0].Name != "policy" || got[0].Value != "dnd.npc_registry.validator.shape.v1" {
if got := New(Options{}).CheckpointFingerprints(); len(got) != 1 || got[0].Name != "policy" || got[0].Value != policy {
t.Fatalf("CheckpointFingerprints() = %#v, want local policy", got)
}
if spec := Spec(); spec.Key != Key || spec.ExecutionClass != contracts.ExecutionClassDeterministic {
@@ -74,6 +74,21 @@ func TestValidatorDoesNotMutateValue(t *testing.T) {
}
}
func TestValidatorUsesProposalGuidanceDuringNormalization(t *testing.T) {
value := validNPCRegistry()
value.NPCs[0].ID = "npc:sha256:opaque"
value.NPCs[0].Name = ""
req := requestWithValue(value)
req.Stage = string(pipeline.StageNormalize)
result, err := New(Options{}).Validate(context.Background(), req)
if err != nil || result.Approved {
t.Fatalf("Validate() = %#v, %v; want rejection", result, err)
}
if !strings.Contains(result.CorrectionGuidance, "duplicate-group proposals") || strings.Contains(result.CorrectionGuidance, value.NPCs[0].ID) || strings.Contains(result.CorrectionGuidance, "npcs[") {
t.Fatalf("CorrectionGuidance = %q, want proposal guidance without IDs or operator paths", result.CorrectionGuidance)
}
}
func requestWithValue(value dnd.NPCRegistry) contracts.TypedValidationRequest[dnd.NPCRegistry] {
return contracts.TypedValidationRequest[dnd.NPCRegistry]{Value: value}
}

59
internal/modules/dnd/validate/npcregistry/source_refs/validator.go
View File

@@ -8,6 +8,7 @@ import (
"gitea.maximumdirect.net/eric/notarius/internal/framework/contracts"
"gitea.maximumdirect.net/eric/notarius/internal/framework/pipeline"
"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd"
"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/shared"
"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/shared/diagnostics"
npcshape "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/validate/npcregistry/shape"
)
@@ -15,7 +16,7 @@ import (
const (
Key = "extract/dnd/npc-registry/source_refs"
ReasonCode = "invalid_npc_source_refs"
policy = "dnd.npc_registry.validator.source_refs.v2"
policy = "dnd.npc_registry.validator.source_refs.v3"
)
type Options struct{}
@@ -41,56 +42,40 @@ func (v *Validator) Validate(_ context.Context, req contracts.TypedValidationReq
return contracts.ValidationResult{Approved: true}, nil
}
index := source.NewDocumentIndex(req.Source)
var coverage *chunkCoverage
var coverage shared.ChunkCoverage
if req.Stage == string(pipeline.StageExtract) {
coverage = newChunkCoverage(req.Chunk)
coverage = shared.NewChunkCoverage(req.Chunk)
}
issues := make([]string, 0)
var corrections diagnostics.Corrections
normalization := req.Stage == string(pipeline.StageNormalize)
validRangeRule := "Use positive source range endpoints that occur in the supplied transcript, with the earlier unit first."
guidancePrefix := "Correct every rejected NPC citation and return the complete replacement NPC registry"
if normalization {
validRangeRule = "Revise the duplicate-group proposals so every selected canonical NPC preserves valid transcript evidence; do not reproduce application IDs."
guidancePrefix = "Correct the duplicate-group proposals and return the complete replacement proposal response"
}
for npcIndex, npc := range req.Value.NPCs {
for refIndex, ref := range npc.SourceRefs {
record := fmt.Sprintf("Affected NPC %s, citing %s.", diagnostics.Quote(npc.Name), diagnostics.SourceRefRange(ref))
if err := index.ValidateRef(ref); err != nil {
issues = append(issues, fmt.Sprintf("npcs[%d].source_refs[%d]: %s", npcIndex, refIndex, diagnostics.Truncate(err.Error())))
corrections.Add("valid-range", validRangeRule, record)
continue
}
if coverage != nil && !coverage.contains(req.Source, ref) {
if req.Stage == string(pipeline.StageExtract) && !coverage.Contains(index, req.Source, ref) {
issues = append(issues, fmt.Sprintf("npcs[%d].source_refs[%d]: source reference is outside the current extraction chunk", npcIndex, refIndex))
corrections.Add("chunk-range", "Use only source ranges wholly contained in the supplied extraction chunk.", record)
}
}
}
if len(issues) == 0 {
return contracts.ValidationResult{Approved: true}, nil
}
return rejection(diagnostics.Aggregate("invalid NPC source references", issues)), nil
}
type chunkCoverage struct {
sourceID string
unitIDs map[int]struct{}
}
func newChunkCoverage(chunk *source.Chunk) *chunkCoverage {
coverage := &chunkCoverage{sourceID: chunk.SourceID, unitIDs: make(map[int]struct{}, len(chunk.Units))}
for _, unit := range chunk.Units {
coverage.unitIDs[unit.ID] = struct{}{}
}
return coverage
}
func (coverage *chunkCoverage) contains(doc *source.SourceDocument, ref source.SourceRef) bool {
if coverage == nil || doc == nil || ref.SourceID != coverage.sourceID {
return false
}
start, startOK := source.UnitIndex(doc, ref.StartUnitID)
end, endOK := source.UnitIndex(doc, ref.EndUnitID)
if !startOK || !endOK || start > end {
return false
}
for position := start; position <= end; position++ {
if _, found := coverage.unitIDs[doc.Units[position].ID]; !found {
return false
}
}
return true
return rejection(
diagnostics.Aggregate("invalid NPC source references", issues),
corrections.Guidance(guidancePrefix),
), nil
}
func Spec() pipeline.ValidatorSpec {
@@ -116,6 +101,6 @@ func DecodeOptions(options map[string]any) (Options, error) {
func validateOptions(options map[string]any) error { _, err := DecodeOptions(options); return err }
func rejection(message string) contracts.ValidationResult {
return contracts.ValidationResult{Approved: false, ReasonCode: ReasonCode, Message: message, CorrectionGuidance: "Return registry NPCs whose source references identify valid transcript ranges within the supplied extraction chunk and directly support each proper NPC name."}
func rejection(message, guidance string) contracts.ValidationResult {
return contracts.ValidationResult{Approved: false, ReasonCode: ReasonCode, Message: message, CorrectionGuidance: guidance}
}

16
internal/modules/dnd/validate/npcregistry/source_refs/validator_test.go
View File

@@ -70,6 +70,20 @@ func TestValidatorDefersMalformedShape(t *testing.T) {
}
}
func TestValidatorUsesProposalGuidanceDuringNormalization(t *testing.T) {
value := validNPCRegistry()
value.NPCs[0].SourceRefs = []source.SourceRef{{SourceID: "session", StartUnitID: 99, EndUnitID: 99}}
req := requestWithValue(validDocument(), value)
req.Stage = string(pipeline.StageNormalize)
result, err := New(Options{}).Validate(context.Background(), req)
if err != nil || result.Approved {
t.Fatalf("Validate() = %#v, %v; want rejection", result, err)
}
if !strings.Contains(result.CorrectionGuidance, "duplicate-group proposals") || !strings.Contains(result.CorrectionGuidance, "Mira Thorn") || strings.Contains(result.CorrectionGuidance, "npcs[") {
t.Fatalf("CorrectionGuidance = %q, want contextual proposal guidance", result.CorrectionGuidance)
}
}
func TestValidatorBoundsDiagnosticsAndHandlesMissingDocument(t *testing.T) {
value := validNPCRegistry()
value.NPCs[0].SourceRefs = make([]source.SourceRef, 24)
@@ -86,7 +100,7 @@ func TestValidatorBoundsDiagnosticsAndHandlesMissingDocument(t *testing.T) {
}
func TestValidatorSpecCheckpointAndRegistration(t *testing.T) {
if got := New(Options{}).CheckpointFingerprints(); len(got) != 1 || got[0].Name != "policy" || got[0].Value != "dnd.npc_registry.validator.source_refs.v2" {
if got := New(Options{}).CheckpointFingerprints(); len(got) != 1 || got[0].Name != "policy" || got[0].Value != policy {
t.Fatalf("CheckpointFingerprints() = %#v, want local policy", got)
}
if Spec().ExecutionClass != contracts.ExecutionClassDeterministic {