Add D&D enemy event artifact contract

internal/modules/dnd/enemyevents/enemyevents.go

@@ -0,0 +1,107 @@
+// Package enemyevents owns canonical ordering and identity policy for D&D
+// enemy-event artifacts.
+package enemyevents
+
+import (
+	"gitea.maximumdirect.net/eric/notarius/internal/core/source"
+	"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd"
+	"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/npcs/identity"
+	"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/shared"
+)
+
+// NormalizeDisplay returns the durable display form for an enemy subject.
+func NormalizeDisplay(value string) string { return identity.NormalizeDisplay(value) }
+
+// ComparisonKey returns the shared D&D identity key for an enemy subject.
+func ComparisonKey(value string) string { return identity.ComparisonKey(NormalizeDisplay(value)) }
+
+// SupportedKind reports whether kind belongs to the durable enemy-event vocabulary.
+func SupportedKind(kind dnd.EnemyEventKind) bool {
+	_, ok := KindRank(kind)
+	return ok
+}
+
+// KindRank returns the explicit chronological tie-break order for event kinds.
+func KindRank(kind dnd.EnemyEventKind) (int, bool) {
+	switch kind {
+	case dnd.EnemyEventKindEngaged:
+		return 0, true
+	case dnd.EnemyEventKindIncapacitated:
+		return 1, true
+	case dnd.EnemyEventKindCaptured:
+		return 2, true
+	case dnd.EnemyEventKindFled:
+		return 3, true
+	case dnd.EnemyEventKindKilled:
+		return 4, true
+	default:
+		return 0, false
+	}
+}
+
+// SourceRefsEqual reports whether two reference sequences are equal after
+// canonical ordering and exact duplicate removal.
+func SourceRefsEqual(order shared.SourceRefOrder, left, right []source.SourceRef) bool {
+	left = order.Canonicalize(left)
+	right = order.Canonicalize(right)
+	if (left == nil) != (right == nil) || len(left) != len(right) {
+		return false
+	}
+	for index := range left {
+		if left[index] != right[index] {
+			return false
+		}
+	}
+	return true
+}
+
+// ExactEqual reports whether events have the same subject identity, kind, and
+// complete canonical evidence sequence.
+func ExactEqual(order shared.SourceRefOrder, left, right dnd.EnemyEvent) bool {
+	return ComparisonKey(left.Name) == ComparisonKey(right.Name) &&
+		left.Kind == right.Kind &&
+		SourceRefsEqual(order, left.SourceRefs, right.SourceRefs)
+}
+
+// Less defines the canonical stable event order. Invalid source references
+// remain comparable through SourceRefOrder's literal fallback so malformed
+// candidates can still be sorted for later validation.
+func Less(order shared.SourceRefOrder, left, right dnd.EnemyEvent) bool {
+	leftPosition, leftHasEvidence := order.EarliestValid(left.SourceRefs)
+	rightPosition, rightHasEvidence := order.EarliestValid(right.SourceRefs)
+	if leftHasEvidence != rightHasEvidence {
+		return leftHasEvidence
+	}
+	if leftHasEvidence && leftPosition != rightPosition {
+		return leftPosition < rightPosition
+	}
+	if leftKey, rightKey := ComparisonKey(left.Name), ComparisonKey(right.Name); leftKey != rightKey {
+		return leftKey < rightKey
+	}
+	if leftName, rightName := NormalizeDisplay(left.Name), NormalizeDisplay(right.Name); leftName != rightName {
+		return leftName < rightName
+	}
+	if leftRank, leftKnown := KindRank(left.Kind); leftKnown {
+		if rightRank, rightKnown := KindRank(right.Kind); rightKnown && leftRank != rightRank {
+			return leftRank < rightRank
+		} else if !rightKnown {
+			return true
+		}
+	} else if _, rightKnown := KindRank(right.Kind); rightKnown {
+		return false
+	}
+	if left.Kind != right.Kind {
+		return left.Kind < right.Kind
+	}
+	return sourceRefsLess(order, order.Canonicalize(left.SourceRefs), order.Canonicalize(right.SourceRefs))
+}
+
+func sourceRefsLess(order shared.SourceRefOrder, left, right []source.SourceRef) bool {
+	for index := 0; index < len(left) && index < len(right); index++ {
+		if left[index] == right[index] {
+			continue
+		}
+		return order.Less(left[index], right[index])
+	}
+	return len(left) < len(right)
+}

internal/modules/dnd/enemyevents/enemyevents_test.go

@@ -0,0 +1,90 @@
+package enemyevents
+
+import (
+	"sort"
+	"testing"
+
+	"gitea.maximumdirect.net/eric/notarius/internal/core/source"
+	"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd"
+	"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/shared"
+)
+
+func TestSupportedKindAndRank(t *testing.T) {
+	tests := []struct {
+		kind dnd.EnemyEventKind
+		rank int
+	}{
+		{dnd.EnemyEventKindEngaged, 0},
+		{dnd.EnemyEventKindIncapacitated, 1},
+		{dnd.EnemyEventKindCaptured, 2},
+		{dnd.EnemyEventKindFled, 3},
+		{dnd.EnemyEventKindKilled, 4},
+	}
+	for _, test := range tests {
+		if rank, ok := KindRank(test.kind); !ok || rank != test.rank || !SupportedKind(test.kind) {
+			t.Fatalf("kind %q = (%d, %t), supported %t", test.kind, rank, ok, SupportedKind(test.kind))
+		}
+	}
+	if _, ok := KindRank("unknown"); ok || SupportedKind("unknown") {
+		t.Fatal("unsupported kind was accepted")
+	}
+}
+
+func TestLessOrdersChronologyThenKind(t *testing.T) {
+	order := testOrder()
+	events := []dnd.EnemyEvent{
+		{Name: "Ashfang", Kind: dnd.EnemyEventKindKilled, SourceRefs: refs(20)},
+		{Name: "Ashfang", Kind: dnd.EnemyEventKindFled, SourceRefs: refs(20)},
+		{Name: "Ashfang", Kind: dnd.EnemyEventKindCaptured, SourceRefs: refs(20)},
+		{Name: "Ashfang", Kind: dnd.EnemyEventKindIncapacitated, SourceRefs: refs(20)},
+		{Name: "Ashfang", Kind: dnd.EnemyEventKindEngaged, SourceRefs: refs(20)},
+		{Name: "Later", Kind: dnd.EnemyEventKindEngaged, SourceRefs: refs(30)},
+		{Name: "Earlier", Kind: dnd.EnemyEventKindKilled, SourceRefs: refs(10)},
+	}
+	sort.SliceStable(events, func(left, right int) bool { return Less(order, events[left], events[right]) })
+	want := []dnd.EnemyEventKind{
+		dnd.EnemyEventKindKilled,
+		dnd.EnemyEventKindEngaged,
+		dnd.EnemyEventKindIncapacitated,
+		dnd.EnemyEventKindCaptured,
+		dnd.EnemyEventKindFled,
+		dnd.EnemyEventKindKilled,
+		dnd.EnemyEventKindEngaged,
+	}
+	for index, kind := range want {
+		if events[index].Kind != kind {
+			t.Fatalf("event %d kind = %q, want %q", index, events[index].Kind, kind)
+		}
+	}
+}
+
+func TestExactEqualUsesSubjectIdentityAndCanonicalEvidence(t *testing.T) {
+	order := testOrder()
+	first := dnd.EnemyEvent{Name: "  ASHFANG ", Kind: dnd.EnemyEventKindFled, SourceRefs: []source.SourceRef{
+		{SourceID: "session", StartUnitID: 30, EndUnitID: 30},
+		{SourceID: "session", StartUnitID: 10, EndUnitID: 10},
+		{SourceID: "session", StartUnitID: 10, EndUnitID: 10},
+	}}
+	second := dnd.EnemyEvent{Name: "Ashfang", Kind: dnd.EnemyEventKindFled, SourceRefs: []source.SourceRef{
+		{SourceID: "session", StartUnitID: 10, EndUnitID: 10},
+		{SourceID: "session", StartUnitID: 30, EndUnitID: 30},
+	}}
+	if !ExactEqual(order, first, second) || !SourceRefsEqual(order, first.SourceRefs, second.SourceRefs) {
+		t.Fatal("canonical duplicate identity was not recognized")
+	}
+	differentKind := second
+	differentKind.Kind = dnd.EnemyEventKindKilled
+	differentEvidence := second
+	differentEvidence.SourceRefs = []source.SourceRef{{SourceID: "session", StartUnitID: 20, EndUnitID: 20}}
+	if ExactEqual(order, first, differentKind) || ExactEqual(order, first, differentEvidence) {
+		t.Fatal("distinct event was treated as an exact duplicate")
+	}
+}
+
+func refs(unitID int) []source.SourceRef {
+	return []source.SourceRef{{SourceID: "session", StartUnitID: unitID, EndUnitID: unitID}}
+}
+
+func testOrder() shared.SourceRefOrder {
+	return shared.NewSourceRefOrder(&source.SourceDocument{ID: "session", Units: []source.SourceUnit{{ID: 10}, {ID: 20}, {ID: 30}}})
+}