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

Bound D&D normalization diagnostics

Browse Source
This commit is contained in:
Eric Rakestraw
2026-08-09 02:22:23 +00:00
parent a705ba74a1
commit 2a75f40871
8 changed files with 218 additions and 30 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
internal/modules/dnd/normalize/combatturns/normalizer.go
View File

@@ -27,6 +27,7 @@ const (
ReasonCodeSourceRefsNormalized = "source_references_normalized"
ReasonCodeTurnsReordered = "combat_turns_reordered"
ReasonCodeDuplicateCollapsed = "duplicate_combat_turn_collapsed"
ReasonCodeWarningsOmitted = "combat_turn_normalization_warnings_omitted"
)
const (
@@ -113,7 +114,10 @@ func (n *Normalizer) Normalize(ctx context.Context, req contracts.TypedNormalize
index := source.NewDocumentIndex(req.Source)
order := shared.NewSourceRefOrderFromIndex(index)
value, warnings := normalizeList(req.MergeOutput.Value, index, order, npcRegistry)
return contracts.TypedNormalizeResult[dnd.CombatTurnList]{Value: value, Warnings: warnings}, nil
return contracts.TypedNormalizeResult[dnd.CombatTurnList]{
Value: value,
Warnings: diagnostics.LimitWarnings(warnings, "combat_turns", ReasonCodeWarningsOmitted),
}, nil
}
type normalizedRecord struct {

35
internal/modules/dnd/normalize/combatturns/normalizer_test.go
View File

@@ -15,6 +15,7 @@ import (
"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd"
npccodec "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/codec/npcregistry"
"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/npcs/identity"
"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/shared/diagnostics"
)
func TestNormalizeCanonicalizesFieldsAndRegistryIdentities(t *testing.T) {
@@ -59,6 +60,40 @@ func TestNormalizeCanonicalizesFieldsAndRegistryIdentities(t *testing.T) {
}
}
func TestNormalizeLimitsWarningsWithoutChangingCombatTurnValues(t *testing.T) {
units := make([]source.SourceUnit, diagnostics.MaxWarnings+1)
turns := make([]dnd.CombatTurn, len(units))
for index := range units {
unitID := index + 1
units[index] = source.SourceUnit{ID: unitID}
turns[index] = validTurn(" Aria ", source.SourceRef{SourceID: "session", StartUnitID: unitID, EndUnitID: unitID})
}
normalizer, err := New(Options{})
if err != nil {
t.Fatal(err)
}
result, err := normalizer.Normalize(context.Background(), contracts.TypedNormalizeRequest[dnd.CombatTurnList]{
Source: &source.SourceDocument{ID: "session", Units: units},
MergeOutput: contracts.MergeArtifact[dnd.CombatTurnList]{Value: dnd.CombatTurnList{CombatTurns: turns}},
})
if err != nil {
t.Fatalf("Normalize() error = %v", err)
}
if len(result.Value.CombatTurns) != len(turns) || result.Value.CombatTurns[0].Actor != "Aria" {
t.Fatalf("normalized turns = %#v, want canonicalized values", result.Value.CombatTurns)
}
if len(result.Warnings) != diagnostics.MaxWarnings {
t.Fatalf("warning count = %d, want %d", len(result.Warnings), diagnostics.MaxWarnings)
}
if first := result.Warnings[0]; first.Scope != "combat_turns[0]" || first.ReasonCode != ReasonCodeActorCanonicalized {
t.Fatalf("first warning = %#v, want first input warning", first)
}
summary := result.Warnings[len(result.Warnings)-1]
if summary.Scope != "combat_turns" || summary.ReasonCode != ReasonCodeWarningsOmitted || summary.Message != "2 additional warning(s) omitted" {
t.Fatalf("warning summary = %#v", summary)
}
}
func TestNormalizeResolvesOperationNPCOverrideWithoutSingletonMetadata(t *testing.T) {
doc := testDocument()
normalizer, err := New(Options{})

94
internal/modules/dnd/normalize/scenedescriptions/normalizer.go
View File

@@ -16,8 +16,12 @@ import (
)
const (
Key = "dnd/scene-descriptions"
normalizerPolicy = "dnd.scene_descriptions.normalizer.v1"
Key = "dnd/scene-descriptions"
normalizerPolicy = "dnd.scene_descriptions.normalizer.v1"
ReasonCodeProseNormalized = "scene_description_prose_normalized"
ReasonCodeOrderNormalized = "scene_description_order_normalized"
ReasonCodeDuplicateCollapsed = "scene_description_duplicate_collapsed"
ReasonCodeNormalizationWarningsOmitted = "scene_description_normalization_warnings_omitted"
)
var requiredCapabilities = []string{"merged"}
@@ -60,70 +64,106 @@ func (n *Normalizer) Normalize(ctx context.Context, req contracts.TypedNormalize
if err := ctx.Err(); err != nil {
return contracts.TypedNormalizeResult[dnd.SceneDescriptionList]{}, normalizerErrorf("context error before normalize: %w", err)
}
value, err := normalizeList(req.MergeOutput.Value, req.Source)
value, warnings, err := normalizeList(req.MergeOutput.Value, req.Source)
if err != nil {
return contracts.TypedNormalizeResult[dnd.SceneDescriptionList]{}, normalizerErrorf("normalize scenes: %w", err)
}
return contracts.TypedNormalizeResult[dnd.SceneDescriptionList]{Value: value}, nil
return contracts.TypedNormalizeResult[dnd.SceneDescriptionList]{
Value: value,
Warnings: diagnostics.LimitWarnings(warnings, "scenes", ReasonCodeNormalizationWarningsOmitted),
}, nil
}
func normalizeList(input dnd.SceneDescriptionList, doc *source.SourceDocument) (dnd.SceneDescriptionList, error) {
type normalizedScene struct {
scene dnd.SceneDescription
inputIndex int
}
func normalizeList(input dnd.SceneDescriptionList, doc *source.SourceDocument) (dnd.SceneDescriptionList, []contracts.Warning, error) {
if doc == nil {
return dnd.SceneDescriptionList{}, fmt.Errorf("source document must not be nil")
return dnd.SceneDescriptionList{}, nil, fmt.Errorf("source document must not be nil")
}
if input.Scenes == nil {
return dnd.SceneDescriptionList{}, fmt.Errorf("scenes must be present")
return dnd.SceneDescriptionList{}, nil, fmt.Errorf("scenes must be present")
}
if len(input.Scenes) == 0 {
return dnd.SceneDescriptionList{}, fmt.Errorf("scenes must not be empty")
return dnd.SceneDescriptionList{}, nil, fmt.Errorf("scenes must not be empty")
}
documentIndex := source.NewDocumentIndex(doc)
output := dnd.SceneDescriptionList{Scenes: make([]dnd.SceneDescription, len(input.Scenes))}
records := make([]normalizedScene, len(input.Scenes))
warnings := make([]contracts.Warning, 0)
for sceneIndex, scene := range input.Scenes {
originalTitle, originalSummary := scene.Title, scene.Summary
scene.Title = strings.TrimSpace(scene.Title)
scene.Summary = strings.TrimSpace(scene.Summary)
if err := shape.Validate(dnd.SceneDescriptionList{Scenes: []dnd.SceneDescription{scene}}); err != nil {
return dnd.SceneDescriptionList{}, fmt.Errorf("scenes[%d]: %w", sceneIndex, err)
return dnd.SceneDescriptionList{}, nil, fmt.Errorf("scenes[%d]: %w", sceneIndex, err)
}
if err := documentIndex.ValidateRef(scene.SourceRef); err != nil {
return dnd.SceneDescriptionList{}, fmt.Errorf("scenes[%d].source_ref: %s", sceneIndex, diagnostics.Truncate(err.Error()))
return dnd.SceneDescriptionList{}, nil, fmt.Errorf("scenes[%d].source_ref: %s", sceneIndex, diagnostics.Truncate(err.Error()))
}
output.Scenes[sceneIndex] = scene
if originalTitle != scene.Title || originalSummary != scene.Summary {
warnings = append(warnings, contracts.Warning{
Scope: sceneScope(sceneIndex),
ReasonCode: ReasonCodeProseNormalized,
Message: fmt.Sprintf("input index %d: title and/or summary whitespace normalized", sceneIndex),
})
}
records[sceneIndex] = normalizedScene{scene: scene, inputIndex: sceneIndex}
}
sort.SliceStable(output.Scenes, func(left, right int) bool {
leftStart, _ := documentIndex.Position(output.Scenes[left].SourceRef.StartUnitID)
rightStart, _ := documentIndex.Position(output.Scenes[right].SourceRef.StartUnitID)
sort.SliceStable(records, func(left, right int) bool {
leftStart, _ := documentIndex.Position(records[left].scene.SourceRef.StartUnitID)
rightStart, _ := documentIndex.Position(records[right].scene.SourceRef.StartUnitID)
if leftStart != rightStart {
return leftStart < rightStart
}
return output.Scenes[left].ID < output.Scenes[right].ID
return records[left].scene.ID < records[right].scene.ID
})
for position, record := range records {
if position == record.inputIndex {
continue
}
warnings = append(warnings, contracts.Warning{
Scope: sceneScope(record.inputIndex),
ReasonCode: ReasonCodeOrderNormalized,
Message: fmt.Sprintf("input index %d moved to normalized position %d by canonical scene order",
record.inputIndex, position),
})
}
unique := make([]dnd.SceneDescription, 0, len(output.Scenes))
byID := make(map[string]dnd.SceneDescription, len(output.Scenes))
byRange := make(map[source.SourceRef]dnd.SceneDescription, len(output.Scenes))
seen := make(map[dnd.SceneDescription]struct{}, len(output.Scenes))
for _, scene := range output.Scenes {
unique := make([]dnd.SceneDescription, 0, len(records))
byID := make(map[string]dnd.SceneDescription, len(records))
byRange := make(map[source.SourceRef]dnd.SceneDescription, len(records))
seen := make(map[dnd.SceneDescription]int, len(records))
for _, record := range records {
scene := record.scene
if previous, ok := byID[scene.ID]; ok && !identical(previous, scene) {
return dnd.SceneDescriptionList{}, fmt.Errorf("scene ID %s has conflicting records", diagnostics.Quote(scene.ID))
return dnd.SceneDescriptionList{}, nil, fmt.Errorf("scene ID %s has conflicting records", diagnostics.Quote(scene.ID))
}
if previous, ok := byRange[scene.SourceRef]; ok && !sameModelContent(previous, scene) {
return dnd.SceneDescriptionList{}, fmt.Errorf("source range %s has conflicting records", sourceRefLabel(scene.SourceRef))
return dnd.SceneDescriptionList{}, nil, fmt.Errorf("source range %s has conflicting records", sourceRefLabel(scene.SourceRef))
}
if _, ok := seen[scene]; ok {
if retainedIndex, ok := seen[scene]; ok {
warnings = append(warnings, contracts.Warning{
Scope: sceneScope(record.inputIndex),
ReasonCode: ReasonCodeDuplicateCollapsed,
Message: fmt.Sprintf("input index %d: exact duplicate scene collapsed; retained input index %d",
record.inputIndex, retainedIndex),
})
continue
}
byID[scene.ID] = scene
byRange[scene.SourceRef] = scene
seen[scene] = struct{}{}
seen[scene] = record.inputIndex
unique = append(unique, scene)
}
output.Scenes = unique
return output, nil
return dnd.SceneDescriptionList{Scenes: unique}, warnings, nil
}
func sceneScope(index int) string { return fmt.Sprintf("scenes[%d]", index) }
func identical(left, right dnd.SceneDescription) bool {
return left == right
}

46
internal/modules/dnd/normalize/scenedescriptions/normalizer_test.go
View File

@@ -2,6 +2,7 @@ package scenedescriptions
import (
"context"
"fmt"
"reflect"
"strings"
"testing"
@@ -10,6 +11,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/diagnostics"
)
func TestNormalizeTrimsOrdersDeduplicatesAndOwnsOutput(t *testing.T) {
@@ -33,6 +35,15 @@ func TestNormalizeTrimsOrdersDeduplicatesAndOwnsOutput(t *testing.T) {
if !reflect.DeepEqual(result.Value.Scenes, want) {
t.Fatalf("scenes = %#v, want %#v", result.Value.Scenes, want)
}
if got := result.Warnings; len(got) != 7 || !reflect.DeepEqual(
[]string{got[0].ReasonCode, got[1].ReasonCode, got[2].ReasonCode, got[3].ReasonCode, got[4].ReasonCode, got[5].ReasonCode, got[6].ReasonCode},
[]string{ReasonCodeProseNormalized, ReasonCodeProseNormalized, ReasonCodeProseNormalized, ReasonCodeProseNormalized, ReasonCodeOrderNormalized, ReasonCodeOrderNormalized, ReasonCodeDuplicateCollapsed},
) || !reflect.DeepEqual(
[]string{got[0].Scope, got[1].Scope, got[2].Scope, got[3].Scope, got[4].Scope, got[5].Scope, got[6].Scope},
[]string{"scenes[0]", "scenes[1]", "scenes[2]", "scenes[3]", "scenes[2]", "scenes[0]", "scenes[3]"},
) {
t.Fatalf("warnings = %#v, want prose, order, then duplicate mutation diagnostics", got)
}
if !reflect.DeepEqual(input, before) {
t.Fatalf("Normalize() mutated input: %#v", input)
}
@@ -40,6 +51,41 @@ func TestNormalizeTrimsOrdersDeduplicatesAndOwnsOutput(t *testing.T) {
if input.Scenes[0].Title == "changed" {
t.Fatal("normalized output aliases input storage")
}
second, err := New(Options{}).Normalize(context.Background(), normalizeRequest(dnd.SceneDescriptionList{Scenes: want}, doc))
if err != nil {
t.Fatalf("second Normalize() error = %v", err)
}
if !reflect.DeepEqual(second.Value.Scenes, want) || len(second.Warnings) != 0 {
t.Fatalf("second normalization = %#v, want unchanged value without warnings", second)
}
}
func TestNormalizeLimitsCombinedSceneMutationWarnings(t *testing.T) {
count := diagnostics.MaxWarnings - 8
doc := &source.SourceDocument{ID: "session", Units: make([]source.SourceUnit, count)}
input := dnd.SceneDescriptionList{Scenes: make([]dnd.SceneDescription, count)}
for index := range input.Scenes {
unitID := count - index
doc.Units[index] = source.SourceUnit{ID: index + 1}
input.Scenes[index] = scene(fmt.Sprintf("scene-%02d", unitID), unitID, unitID, dnd.SceneKindNarrative, " Arrival ", " The party arrives. ")
}
result, err := New(Options{}).Normalize(context.Background(), normalizeRequest(input, doc))
if err != nil {
t.Fatalf("Normalize() error = %v", err)
}
if len(result.Value.Scenes) != count || result.Value.Scenes[0].SourceRef.StartUnitID != 1 {
t.Fatalf("normalized scenes = %#v, want unchanged canonical values", result.Value.Scenes)
}
if len(result.Warnings) != diagnostics.MaxWarnings {
t.Fatalf("warning count = %d, want %d", len(result.Warnings), diagnostics.MaxWarnings)
}
if first := result.Warnings[0]; first.Scope != "scenes[0]" || first.ReasonCode != ReasonCodeProseNormalized {
t.Fatalf("first warning = %#v, want first prose warning", first)
}
summary := result.Warnings[len(result.Warnings)-1]
if summary.Scope != "scenes" || summary.ReasonCode != ReasonCodeNormalizationWarningsOmitted || summary.Message != "5 additional warning(s) omitted" {
t.Fatalf("warning summary = %#v", summary)
}
}
func TestNormalizeRejectsInvalidCandidatesAndConflicts(t *testing.T) {

7
internal/modules/dnd/normalize/spells/normalizer.go
View File

@@ -11,6 +11,7 @@ import (
"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"
spellcatalog "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/spells/catalog"
"golang.org/x/text/cases"
)
@@ -26,6 +27,7 @@ const (
ReasonCodeSpellNameUnresolved = "spell_name_unresolved"
ReasonCodeSourceReferencesNormalized = "source_references_normalized"
ReasonCodeDuplicateSpellCastCollapsed = "duplicate_spell_cast_collapsed"
ReasonCodeWarningsOmitted = "spell_normalization_warnings_omitted"
)
var requiredCapabilities = []string{"merged"}
@@ -102,7 +104,10 @@ func (n *Normalizer) Normalize(ctx context.Context, req contracts.TypedNormalize
value, warnings := normalizeSpellList(req.MergeOutput.Value, n.effectiveCatalog, order)
value, duplicateWarnings := collapseDuplicateSpellCasts(value, index, n.effectiveCatalog)
warnings = append(warnings, duplicateWarnings...)
return contracts.TypedNormalizeResult[dnd.SpellList]{Value: value, Warnings: warnings}, nil
return contracts.TypedNormalizeResult[dnd.SpellList]{
Value: value,
Warnings: diagnostics.LimitWarnings(warnings, "spell_casts", ReasonCodeWarningsOmitted),
}, nil
}
func normalizeSpellList(input dnd.SpellList, catalog spellcatalog.EffectiveCatalog, order shared.SourceRefOrder) (dnd.SpellList, []contracts.Warning) {

25
internal/modules/dnd/normalize/spells/normalizer_test.go
View File

@@ -12,6 +12,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/diagnostics"
spellcatalog "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/spells/catalog"
)
@@ -162,6 +163,30 @@ func TestNormalizeCanonicalizesNamesAndReportsUnresolvedNames(t *testing.T) {
}
}
func TestNormalizeLimitsWarningsWithoutChangingSpellValues(t *testing.T) {
input := dnd.SpellList{SpellCasts: make([]dnd.SpellCast, diagnostics.MaxWarnings+1)}
for index := range input.SpellCasts {
input.SpellCasts[index].Spell = fmt.Sprintf("Unknown Spell %d", index)
}
result, err := newNormalizer(t).Normalize(context.Background(), normalizeRequest(input))
if err != nil {
t.Fatalf("Normalize() error = %v", err)
}
if !reflect.DeepEqual(result.Value, input) {
t.Fatalf("normalized value = %#v, want unresolved spell values preserved", result.Value)
}
if len(result.Warnings) != diagnostics.MaxWarnings {
t.Fatalf("warning count = %d, want %d", len(result.Warnings), diagnostics.MaxWarnings)
}
if first := result.Warnings[0]; first.Scope != "spell_casts[0]" || first.ReasonCode != ReasonCodeSpellNameUnresolved {
t.Fatalf("first warning = %#v, want first input warning", first)
}
summary := result.Warnings[len(result.Warnings)-1]
if summary.Scope != "spell_casts" || summary.ReasonCode != ReasonCodeWarningsOmitted || summary.Message != "2 additional warning(s) omitted" {
t.Fatalf("warning summary = %#v", summary)
}
}
func TestNormalizeBoundsUnicodeNamesAndQuotesCanonicalReplacement(t *testing.T) {
longName := strings.Repeat("火", 140)
reference := spellCatalogReference(fmt.Sprintf(`{"schema_version":"notarius.dnd.spell-catalog-overlay.v1","catalogs":[{"id":"campaign.long","ruleset":"dnd-5e-2014","source":{"title":"Private campaign source"},"spells":[{"name":%q,"aliases":["long alias"]}]}]}`, longName))

6
internal/modules/dnd/validate/combatturns/source_relatedness/validator.go
View File

@@ -15,6 +15,7 @@ import (
const (
Key = "extract/dnd/combat-turns/source_relatedness"
WarningReasonCode = "combat_turn_not_near_source"
OmittedReasonCode = "combat_turn_relatedness_warnings_omitted"
policy = "dnd.combat_turns.validator.source_relatedness.v2"
)
@@ -64,7 +65,10 @@ func (v *Validator) Validate(_ context.Context, req contracts.TypedValidationReq
}),
})
}
return contracts.ValidationResult{Approved: true, Warnings: warnings}, nil
return contracts.ValidationResult{
Approved: true,
Warnings: diagnostics.LimitWarnings(warnings, "combat_turns", OmittedReasonCode),
}, nil
}
func actorAppearsInCitedText(citedText string, actor string) bool {
return shared.ContainsTokenSequence(citedText, actor)

29
internal/modules/dnd/validate/combatturns/source_relatedness/validator_test.go
View File

@@ -10,6 +10,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/diagnostics"
)
func TestValidatorUsesDocumentOrderAndUnicodeComparisonForActor(t *testing.T) {
@@ -45,6 +46,34 @@ func TestValidatorWarnsOncePerTurnForUnrelatedActor(t *testing.T) {
}
}
func TestValidatorLimitsUnrelatedActorWarnings(t *testing.T) {
turns := make([]dnd.CombatTurn, diagnostics.MaxWarnings+1)
for index := range turns {
turns[index] = dnd.CombatTurn{
Actor: "Missing Actor",
TurnKind: dnd.CombatTurnKindTurn,
SourceRefs: []source.SourceRef{{SourceID: "session", StartUnitID: 1, EndUnitID: 1}},
}
}
result, err := New(Options{}).Validate(context.Background(), contracts.TypedValidationRequest[dnd.CombatTurnList]{
Source: relatednessDocument(),
Value: dnd.CombatTurnList{CombatTurns: turns},
})
if err != nil || !result.Approved {
t.Fatalf("Validate() = %#v, %v", result, err)
}
if len(result.Warnings) != diagnostics.MaxWarnings {
t.Fatalf("warning count = %d, want %d", len(result.Warnings), diagnostics.MaxWarnings)
}
if first := result.Warnings[0]; first.Scope != "combat_turns[0]" || first.ReasonCode != WarningReasonCode {
t.Fatalf("first warning = %#v, want first turn warning", first)
}
summary := result.Warnings[len(result.Warnings)-1]
if summary.Scope != "combat_turns" || summary.ReasonCode != OmittedReasonCode || summary.Message != "2 additional warning(s) omitted" {
t.Fatalf("warning summary = %#v", summary)
}
}
func TestValidatorDoesNotMatchShortActorSubstring(t *testing.T) {
value := dnd.CombatTurnList{CombatTurns: []dnd.CombatTurn{{
Actor: "Art", TurnKind: dnd.CombatTurnKindTurn,