Add D&D enemy event normalizer

This commit is contained in:
2026-08-03 20:49:32 +00:00
parent 9dd57dbfa4
commit 02ec10d66b
2 changed files with 504 additions and 0 deletions

View File

@@ -0,0 +1,297 @@
// Package enemyevents normalizes merged D&D enemy-event candidates.
package enemyevents
import (
"context"
"fmt"
"sort"
"gitea.maximumdirect.net/eric/notarius/internal/core/source"
"gitea.maximumdirect.net/eric/notarius/internal/framework/contracts"
"gitea.maximumdirect.net/eric/notarius/internal/framework/pipeline"
"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd"
enemyeventmodel "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/enemyevents"
npcregistry "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/npcs/registry"
"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/shared"
"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/shared/diagnostics"
)
const (
Key = "dnd/enemy-events"
normalizationPolicy = "dnd.enemy_events.normalize.v1"
NormalizationPolicy = normalizationPolicy
ReasonCodeNameCanonicalized = "enemy_event_name_canonicalized"
ReasonCodeSourceRefsNormalized = "source_references_normalized"
ReasonCodeEventsReordered = "enemy_events_reordered"
ReasonCodeDuplicateCollapsed = "duplicate_enemy_event_collapsed"
ReasonCodeWarningsOmitted = "enemy_event_normalization_warnings_omitted"
)
const (
NPCRegistryReferenceSlot = npcregistry.ReferenceSlot
NPCRegistryMaxBytes = npcregistry.MaxBytes
)
var requiredCapabilities = []string{"merged"}
var providedCapabilities = []string{"normalized"}
var _ contracts.Normalizer[dnd.EnemyEventList] = (*Normalizer)(nil)
var _ contracts.ManifestMetadataProvider = (*Normalizer)(nil)
var _ pipeline.CheckpointFingerprintProvider = (*Normalizer)(nil)
type Options struct{}
type Normalizer struct {
npcResolver *npcregistry.Resolver
}
func New(_ Options, references ...contracts.ReferenceSet) (*Normalizer, error) {
if len(references) > 1 {
return nil, normalizerErrorf("at most one reference set may be supplied")
}
var referenceSet contracts.ReferenceSet
if len(references) == 1 {
referenceSet = references[0]
}
resolver, err := npcregistry.NewResolver(referenceSet)
if err != nil {
return nil, normalizerErrorf("prepare NPC registry: %w", err)
}
return &Normalizer{npcResolver: resolver}, nil
}
func (n *Normalizer) Key() string { return Key }
func (n *Normalizer) ReferenceSlots() []contracts.ReferenceSlot { return referenceSlots() }
func (n *Normalizer) ManifestMetadata() map[string]any {
if n == nil || n.npcResolver == nil {
return nil
}
metadata := map[string]any{"normalization_policy": normalizationPolicy}
if seeded := n.npcResolver.Seeded(); seeded.Bound() {
metadata["npc_registry_digest"] = seeded.Digest()
}
return metadata
}
func (n *Normalizer) CheckpointFingerprints() []pipeline.CheckpointFingerprint {
if n == nil || n.npcResolver == nil {
return nil
}
return []pipeline.CheckpointFingerprint{
{Name: "normalization_policy", Value: normalizationPolicy},
{Name: "npc_registry", Value: n.npcResolver.Seeded().ProjectionDigest()},
}
}
func (n *Normalizer) Normalize(ctx context.Context, req contracts.TypedNormalizeRequest[dnd.EnemyEventList]) (contracts.TypedNormalizeResult[dnd.EnemyEventList], error) {
if n == nil || n.npcResolver == nil {
return contracts.TypedNormalizeResult[dnd.EnemyEventList]{}, normalizerErrorf("normalizer must not be nil")
}
if ctx == nil {
return contracts.TypedNormalizeResult[dnd.EnemyEventList]{}, normalizerErrorf("context must not be nil")
}
if err := ctx.Err(); err != nil {
return contracts.TypedNormalizeResult[dnd.EnemyEventList]{}, normalizerErrorf("context error before normalize: %w", err)
}
registry, err := n.npcResolver.Resolve(req.References)
if err != nil {
return contracts.TypedNormalizeResult[dnd.EnemyEventList]{}, normalizerErrorf("resolve NPC registry: %w", err)
}
if !registry.Bound() {
return contracts.TypedNormalizeResult[dnd.EnemyEventList]{}, normalizerErrorf("NPC registry reference is required")
}
index := source.NewDocumentIndex(req.Source)
order := shared.NewSourceRefOrderFromIndex(index)
value, warnings := normalizeList(req.MergeOutput.Value, order, registry)
return contracts.TypedNormalizeResult[dnd.EnemyEventList]{Value: value, Warnings: warnings}, nil
}
type normalizedRecord struct {
event dnd.EnemyEvent
inputIndex int
}
type nameCanonicalization struct {
from string
to string
}
func normalizeList(input dnd.EnemyEventList, order shared.SourceRefOrder, registry *npcregistry.Registry) (dnd.EnemyEventList, []contracts.Warning) {
if input.Events == nil {
return dnd.EnemyEventList{}, nil
}
records := make([]normalizedRecord, len(input.Events))
warnings := make([]contracts.Warning, 0)
for index, inputEvent := range input.Events {
event, nameChange, refsChanged := normalizeEvent(inputEvent, order, registry)
records[index] = normalizedRecord{event: event, inputIndex: index}
if nameChange != nil {
warnings = append(warnings, contracts.Warning{
Scope: eventScope(index),
ReasonCode: ReasonCodeNameCanonicalized,
Message: fmt.Sprintf("input index %d: subject canonicalized from %s to %s",
index, diagnostics.Quote(nameChange.from), diagnostics.Quote(nameChange.to)),
})
}
if refsChanged {
warnings = append(warnings, contracts.Warning{
Scope: eventScope(index),
ReasonCode: ReasonCodeSourceRefsNormalized,
Message: fmt.Sprintf("input index %d: source references normalized (original count %d, final count %d)",
index, len(inputEvent.SourceRefs), len(event.SourceRefs)),
})
}
}
sort.SliceStable(records, func(left, right int) bool {
return enemyeventmodel.Less(order, records[left].event, records[right].event)
})
for position, record := range records {
if position == record.inputIndex {
continue
}
warnings = append(warnings, contracts.Warning{
Scope: eventScope(record.inputIndex),
ReasonCode: ReasonCodeEventsReordered,
Message: fmt.Sprintf("input index %d moved to normalized position %d", record.inputIndex, position),
})
}
output, duplicateWarnings := collapseDuplicates(records, order)
warnings = append(warnings, duplicateWarnings...)
return dnd.EnemyEventList{Events: output}, diagnostics.LimitWarnings(warnings, "enemy_events", ReasonCodeWarningsOmitted)
}
func normalizeEvent(input dnd.EnemyEvent, order shared.SourceRefOrder, registry *npcregistry.Registry) (dnd.EnemyEvent, *nameCanonicalization, bool) {
output := cloneEvent(input)
output.Name = enemyeventmodel.NormalizeDisplay(input.Name)
if canonical, ok := registry.Lookup(output.Name); ok {
output.Name = enemyeventmodel.NormalizeDisplay(canonical.Name)
}
var nameChange *nameCanonicalization
if input.Name != output.Name {
nameChange = &nameCanonicalization{from: input.Name, to: output.Name}
}
output.SourceRefs = order.Canonicalize(input.SourceRefs)
return output, nameChange, !rawSourceRefsEqual(input.SourceRefs, output.SourceRefs)
}
func cloneEvent(input dnd.EnemyEvent) dnd.EnemyEvent {
output := input
if input.SourceRefs != nil {
output.SourceRefs = append([]source.SourceRef(nil), input.SourceRefs...)
}
return output
}
func rawSourceRefsEqual(left, right []source.SourceRef) bool {
if (left == nil) != (right == nil) || len(left) != len(right) {
return false
}
for index := range left {
if left[index] != right[index] {
return false
}
}
return true
}
type duplicateGroup struct {
retainedIndex int
removed []int
}
func collapseDuplicates(records []normalizedRecord, order shared.SourceRefOrder) ([]dnd.EnemyEvent, []contracts.Warning) {
if len(records) == 0 {
return make([]dnd.EnemyEvent, 0), nil
}
kept := make([]normalizedRecord, 0, len(records))
groups := make([]duplicateGroup, 0)
for _, record := range records {
match := -1
for index := range kept {
if enemyeventmodel.ExactEqual(order, kept[index].event, record.event) {
match = index
break
}
}
if match < 0 {
kept = append(kept, record)
groups = append(groups, duplicateGroup{retainedIndex: record.inputIndex})
continue
}
groups[match].removed = append(groups[match].removed, record.inputIndex)
}
output := make([]dnd.EnemyEvent, len(kept))
for index, record := range kept {
output[index] = cloneEvent(record.event)
}
warnings := make([]contracts.Warning, 0)
for _, group := range groups {
if len(group.removed) == 0 {
continue
}
issues := make([]string, len(group.removed))
for index, removed := range group.removed {
issues[index] = fmt.Sprintf("removed input index %d", removed)
}
warnings = append(warnings, contracts.Warning{
Scope: eventScope(group.retainedIndex),
ReasonCode: ReasonCodeDuplicateCollapsed,
Message: diagnostics.Aggregate(
fmt.Sprintf("duplicate enemy event collapsed; retained input index %d", group.retainedIndex), issues),
})
}
return output, warnings
}
func eventScope(index int) string { return fmt.Sprintf("events[%d]", index) }
func referenceSlots() []contracts.ReferenceSlot {
return contracts.CloneReferenceSlots([]contracts.ReferenceSlot{{
Name: NPCRegistryReferenceSlot,
Description: "Required normalized NPC registry used only to canonicalize enemy-subject names, never as event evidence.",
Required: true,
AcceptedMediaTypes: []string{"application/json"},
AcceptedArtifactKinds: []contracts.ArtifactKind{dnd.NPCListKind},
MaxBytes: NPCRegistryMaxBytes,
}})
}
func ModuleSpec() pipeline.ModuleSpec {
return pipeline.ModuleSpec{
Key: Key,
Stage: pipeline.StageNormalize,
ExecutionClass: contracts.ExecutionClassDeterministic,
Requires: append([]string(nil), requiredCapabilities...),
Provides: append([]string(nil), providedCapabilities...),
ArtifactKind: dnd.EnemyEventListKind,
ReferenceSlots: referenceSlots(),
}
}
func Register(registry *pipeline.NormalizerRegistry) error {
return pipeline.RegisterNormalizerBuilder(registry, ModuleSpec(), validateOptions, func(request pipeline.BuildRequest) (contracts.Normalizer[dnd.EnemyEventList], error) {
options, err := DecodeOptions(request.Options)
if err != nil {
return nil, err
}
return New(options, request.References)
})
}
func DecodeOptions(options map[string]any) (Options, error) {
if err := pipeline.RejectUnknownOptions(options); err != nil {
return Options{}, normalizerErrorf("%w", err)
}
return Options{}, nil
}
func validateOptions(options map[string]any) error { _, err := DecodeOptions(options); return err }
func normalizerErrorf(format string, args ...any) error {
return fmt.Errorf("dnd enemy events normalizer: "+format, args...)
}

View File

@@ -0,0 +1,207 @@
package enemyevents
import (
"context"
"encoding/json"
"reflect"
"strings"
"testing"
"gitea.maximumdirect.net/eric/notarius/internal/core/source"
"gitea.maximumdirect.net/eric/notarius/internal/framework/contracts"
"gitea.maximumdirect.net/eric/notarius/internal/framework/pipeline"
"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd"
npccodec "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/codec/npcs"
"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/npcs/identity"
"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/shared/diagnostics"
)
func TestNormalizeCanonicalizesSubjectsEvidenceOrderAndDuplicates(t *testing.T) {
document := &source.SourceDocument{ID: "session", Units: []source.SourceUnit{{ID: 30}, {ID: 10}, {ID: 20}, {ID: 40}}}
ref := func(unitID int) []source.SourceRef {
return []source.SourceRef{{SourceID: document.ID, StartUnitID: unitID, EndUnitID: unitID}}
}
input := dnd.EnemyEventList{Events: []dnd.EnemyEvent{
{Name: " áRIA ", Kind: dnd.EnemyEventKindKilled, SourceRefs: append(ref(30), ref(10)...)},
{Name: " Remaining Orcs ", Kind: dnd.EnemyEventKindEngaged, SourceRefs: ref(20)},
{Name: "Ária", Kind: dnd.EnemyEventKindKilled, SourceRefs: []source.SourceRef{{SourceID: document.ID, StartUnitID: 10, EndUnitID: 10}, {SourceID: document.ID, StartUnitID: 30, EndUnitID: 30}}},
{Name: "Ária", Kind: dnd.EnemyEventKindFled, SourceRefs: ref(40)},
}}
originalRefs := append([]source.SourceRef(nil), input.Events[0].SourceRefs...)
normalizer := newNormalizer(t, npcReferences(t))
result, err := normalizer.Normalize(context.Background(), normalizeRequest(document, input, contracts.ReferenceSet{}))
if err != nil {
t.Fatal(err)
}
got := result.Value.Events
if len(got) != 3 || got[0].Name != "Ária" || got[0].Kind != dnd.EnemyEventKindKilled || !reflect.DeepEqual(got[0].SourceRefs, []source.SourceRef{{SourceID: document.ID, StartUnitID: 30, EndUnitID: 30}, {SourceID: document.ID, StartUnitID: 10, EndUnitID: 10}}) || got[1].Name != "Remaining Orcs" || got[2].Kind != dnd.EnemyEventKindFled {
t.Fatalf("normalized events = %#v", got)
}
for _, reason := range []string{ReasonCodeNameCanonicalized, ReasonCodeSourceRefsNormalized, ReasonCodeEventsReordered, ReasonCodeDuplicateCollapsed} {
if !hasWarning(result.Warnings, reason) {
t.Fatalf("warnings = %#v, missing %q", result.Warnings, reason)
}
}
if !reflect.DeepEqual(input.Events[0].SourceRefs, originalRefs) {
t.Fatalf("Normalize() mutated input: %#v", input)
}
got[0].SourceRefs[0].StartUnitID = 999
if input.Events[0].SourceRefs[0].StartUnitID == 999 {
t.Fatal("normalized source references alias input")
}
}
func TestNormalizeUsesExplicitKindOrderAndPreservesDistinctObservations(t *testing.T) {
document := &source.SourceDocument{ID: "session", Units: []source.SourceUnit{{ID: 1}, {ID: 2}, {ID: 3}}}
ref := func(unitID int) []source.SourceRef {
return []source.SourceRef{{SourceID: document.ID, StartUnitID: unitID, EndUnitID: unitID}}
}
input := dnd.EnemyEventList{Events: []dnd.EnemyEvent{
{Name: "Ashfang", Kind: dnd.EnemyEventKindKilled, SourceRefs: ref(1)},
{Name: "Ashfang", Kind: dnd.EnemyEventKindFled, SourceRefs: ref(1)},
{Name: "Ashfang", Kind: dnd.EnemyEventKindCaptured, SourceRefs: ref(1)},
{Name: "Ashfang", Kind: dnd.EnemyEventKindIncapacitated, SourceRefs: ref(1)},
{Name: "Ashfang", Kind: dnd.EnemyEventKindEngaged, SourceRefs: ref(1)},
{Name: "Ashfang", Kind: dnd.EnemyEventKindEngaged, SourceRefs: ref(3)},
}}
result, err := newNormalizer(t, npcReferences(t)).Normalize(context.Background(), normalizeRequest(document, input, contracts.ReferenceSet{}))
if err != nil {
t.Fatal(err)
}
want := []dnd.EnemyEventKind{
dnd.EnemyEventKindEngaged,
dnd.EnemyEventKindIncapacitated,
dnd.EnemyEventKindCaptured,
dnd.EnemyEventKindFled,
dnd.EnemyEventKindKilled,
dnd.EnemyEventKindEngaged,
}
for index, kind := range want {
if result.Value.Events[index].Kind != kind {
t.Fatalf("event %d kind = %q, want %q", index, result.Value.Events[index].Kind, kind)
}
}
}
func TestNormalizeIsIdempotentAndPreservesEmptyRepresentation(t *testing.T) {
normalizer := newNormalizer(t, npcReferences(t))
for _, input := range []dnd.EnemyEventList{{}, {Events: []dnd.EnemyEvent{}}} {
result, err := normalizer.Normalize(context.Background(), normalizeRequest(testDocument(), input, contracts.ReferenceSet{}))
if err != nil || (result.Value.Events == nil) != (input.Events == nil) {
t.Fatalf("Normalize() = %#v, %v for %#v", result, err, input)
}
}
input := dnd.EnemyEventList{Events: []dnd.EnemyEvent{{Name: " Remaining orcs ", Kind: dnd.EnemyEventKindEngaged, SourceRefs: []source.SourceRef{{SourceID: "session", StartUnitID: 20, EndUnitID: 20}}}}}
first, err := normalizer.Normalize(context.Background(), normalizeRequest(testDocument(), input, contracts.ReferenceSet{}))
if err != nil {
t.Fatal(err)
}
second, err := normalizer.Normalize(context.Background(), normalizeRequest(testDocument(), first.Value, contracts.ReferenceSet{}))
if err != nil || !reflect.DeepEqual(second.Value, first.Value) || len(second.Warnings) != 0 {
t.Fatalf("second normalization = %#v, %v", second, err)
}
}
func TestNormalizeRequiresRegistryAndKeepsOperationContentOutOfMetadata(t *testing.T) {
normalizer, err := New(Options{})
if err != nil {
t.Fatal(err)
}
if _, err := normalizer.Normalize(context.Background(), normalizeRequest(testDocument(), dnd.EnemyEventList{}, contracts.ReferenceSet{})); err == nil || !strings.Contains(err.Error(), "NPC registry") {
t.Fatalf("Normalize() error = %v", err)
}
operationReferences := npcReferences(t)
result, err := normalizer.Normalize(context.Background(), normalizeRequest(testDocument(), dnd.EnemyEventList{Events: []dnd.EnemyEvent{}}, operationReferences))
if err != nil || result.Value.Events == nil {
t.Fatalf("Normalize() = %#v, %v", result, err)
}
if metadata := normalizer.ManifestMetadata(); metadata["npc_registry_digest"] != nil {
t.Fatalf("operation registry leaked into metadata: %#v", metadata)
}
}
func TestNormalizerContractAndWarningBound(t *testing.T) {
normalizer := newNormalizer(t, npcReferences(t))
if _, err := DecodeOptions(map[string]any{"unexpected": true}); err == nil {
t.Fatal("DecodeOptions() accepted an unknown option")
}
first := ModuleSpec()
first.ReferenceSlots[0].AcceptedMediaTypes[0] = "changed"
second := ModuleSpec()
if second.Key != Key || second.Stage != pipeline.StageNormalize || second.ExecutionClass != contracts.ExecutionClassDeterministic || second.ArtifactKind != dnd.EnemyEventListKind || second.ReferenceSlots[0].AcceptedMediaTypes[0] != "application/json" {
t.Fatalf("ModuleSpec() = %#v", second)
}
registry := pipeline.NewNormalizerRegistry()
if err := Register(registry); err != nil {
t.Fatal(err)
}
if spec, ok := registry.Spec(Key); !ok || spec.ArtifactKind != dnd.EnemyEventListKind {
t.Fatalf("registered spec = %#v, %t", spec, ok)
}
metadata := normalizer.ManifestMetadata()
if metadata["normalization_policy"] != normalizationPolicy || !strings.HasPrefix(metadata["npc_registry_digest"].(string), "sha256:") {
t.Fatalf("metadata = %#v", metadata)
}
encoded, err := json.Marshal(metadata)
if err != nil || strings.Contains(string(encoded), "Ária") {
t.Fatalf("unsafe metadata = %s, %v", encoded, err)
}
count := diagnostics.MaxWarnings + 5
document := &source.SourceDocument{ID: "session", Units: make([]source.SourceUnit, count)}
input := dnd.EnemyEventList{Events: make([]dnd.EnemyEvent, count)}
for index := range document.Units {
document.Units[index].ID = index + 1
input.Events[index] = dnd.EnemyEvent{Name: " ÁRIA ", Kind: dnd.EnemyEventKindEngaged, SourceRefs: []source.SourceRef{{SourceID: document.ID, StartUnitID: count - index, EndUnitID: count - index}}}
}
result, err := normalizer.Normalize(context.Background(), normalizeRequest(document, input, contracts.ReferenceSet{}))
if err != nil || len(result.Warnings) != diagnostics.MaxWarnings || result.Warnings[len(result.Warnings)-1].ReasonCode != ReasonCodeWarningsOmitted {
t.Fatalf("warnings = %#v, %v", result.Warnings, err)
}
}
func newNormalizer(t *testing.T, references contracts.ReferenceSet) *Normalizer {
t.Helper()
normalizer, err := New(Options{}, references)
if err != nil {
t.Fatal(err)
}
return normalizer
}
func normalizeRequest(document *source.SourceDocument, value dnd.EnemyEventList, references contracts.ReferenceSet) contracts.TypedNormalizeRequest[dnd.EnemyEventList] {
return contracts.TypedNormalizeRequest[dnd.EnemyEventList]{
Source: document,
MergeOutput: contracts.MergeArtifact[dnd.EnemyEventList]{Value: value},
References: references,
}
}
func testDocument() *source.SourceDocument {
return &source.SourceDocument{ID: "session", Units: []source.SourceUnit{{ID: 10}, {ID: 20}, {ID: 30}}}
}
func npcReferences(t *testing.T) contracts.ReferenceSet {
t.Helper()
value := dnd.NPCList{NPCs: []dnd.NPC{{
ID: identity.DeriveID("Ária"), Name: "Ária",
SourceRefs: []source.SourceRef{{SourceID: "registry", StartUnitID: 1, EndUnitID: 1}},
}}}
content, err := npccodec.New().Encode(value)
if err != nil {
t.Fatal(err)
}
return contracts.ReferenceSet{Slots: map[string]contracts.ResolvedReferenceSlot{NPCRegistryReferenceSlot: {
Slot: contracts.ReferenceSlot{Name: NPCRegistryReferenceSlot},
Items: []contracts.ReferenceItem{{SlotName: NPCRegistryReferenceSlot, MediaType: npccodec.MediaType, Content: content}},
}}}
}
func hasWarning(warnings []contracts.Warning, reason string) bool {
for _, warning := range warnings {
if warning.ReasonCode == reason {
return true
}
}
return false
}