Add D&D item event artifact contract

internal/modules/dnd/itemevents/itemevents.go

@@ -0,0 +1,209 @@
+// Package itemevents owns canonical ordering and durable domain rules for D&D
+// item-event artifacts.
+package itemevents
+
+import (
+	"strconv"
+	"strings"
+
+	"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"
+)
+
+const partyHolder = "party"
+
+// SupportedKind reports whether kind is one of the durable item-event kinds.
+func SupportedKind(kind dnd.ItemEventKind) bool {
+	switch kind {
+	case dnd.ItemEventKindDiscovered,
+		dnd.ItemEventKindAcquired,
+		dnd.ItemEventKindLost,
+		dnd.ItemEventKindConsumed,
+		dnd.ItemEventKindTransferred:
+		return true
+	default:
+		return false
+	}
+}
+
+// DisplayValue returns the durable display form used for item and holder
+// comparisons without changing the observed internal spelling.
+func DisplayValue(value string) string { return strings.TrimSpace(value) }
+
+// ComparisonKey returns the shared D&D Unicode- and case-insensitive key for
+// a trimmed item or holder display value.
+func ComparisonKey(value string) string { return identity.ComparisonKey(DisplayValue(value)) }
+
+// HolderPresent reports whether value is a nonblank optional holder.
+func HolderPresent(value string) bool { return DisplayValue(value) != "" }
+
+// IsPartyHolder reports whether value denotes collective party possession.
+func IsPartyHolder(value string) bool { return ComparisonKey(value) == partyHolder }
+
+// ValidHolderCombination reports whether the optional holder fields satisfy
+// the durable rules for kind. Blank holders are treated as absent so callers
+// can preserve invalid extraction candidates for their owning validators.
+func ValidHolderCombination(kind dnd.ItemEventKind, from, to string) bool {
+	hasFrom := HolderPresent(from)
+	hasTo := HolderPresent(to)
+
+	switch kind {
+	case dnd.ItemEventKindDiscovered:
+		return !hasFrom && !hasTo
+	case dnd.ItemEventKindAcquired:
+		return !hasFrom && hasTo
+	case dnd.ItemEventKindLost, dnd.ItemEventKindConsumed:
+		return hasFrom && !hasTo
+	case dnd.ItemEventKindTransferred:
+		return hasFrom && hasTo && !IsPartyHolder(from) && !IsPartyHolder(to) && ComparisonKey(from) != ComparisonKey(to)
+	default:
+		return false
+	}
+}
+
+// SourceRefsEqual reports whether two source-reference sequences have the
+// same representation and values, including nil-versus-empty distinction.
+func SourceRefsEqual(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
+}
+
+// ValidSourceRefs reports whether refs are non-empty and valid for index.
+func ValidSourceRefs(index source.DocumentIndex, refs []source.SourceRef) bool {
+	if len(refs) == 0 {
+		return false
+	}
+	for _, ref := range refs {
+		if index.ValidateRef(ref) != nil {
+			return false
+		}
+	}
+	return true
+}
+
+// Less defines the canonical event order. Invalid source references remain
+// comparable through SourceRefOrder's literal fallback so malformed candidates
+// are still safe to sort and diagnose.
+func Less(order shared.SourceRefOrder, left, right dnd.ItemEvent) 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 := DisplayValue(left.Name), DisplayValue(right.Name); leftName != rightName {
+		return leftName < rightName
+	}
+	if left.Kind != right.Kind {
+		return left.Kind < right.Kind
+	}
+	if less, decided := optionalStringLess(left.From, right.From); decided {
+		return less
+	}
+	if less, decided := optionalStringLess(left.To, right.To); decided {
+		return less
+	}
+	if less, decided := optionalQuantityLess(left.Quantity, right.Quantity); decided {
+		return less
+	}
+	return sourceRefsLess(order, order.Canonicalize(left.SourceRefs), order.Canonicalize(right.SourceRefs))
+}
+
+// ExactEqual reports whether events are exact duplicates after their display
+// fields and evidence have been canonicalized for the supplied source order.
+func ExactEqual(order shared.SourceRefOrder, left, right dnd.ItemEvent) bool {
+	if DisplayValue(left.Name) != DisplayValue(right.Name) || left.Kind != right.Kind ||
+		DisplayValue(left.From) != DisplayValue(right.From) || DisplayValue(left.To) != DisplayValue(right.To) ||
+		(left.Quantity == nil) != (right.Quantity == nil) {
+		return false
+	}
+	if left.Quantity != nil && *left.Quantity != *right.Quantity {
+		return false
+	}
+	return SourceRefsEqual(order.Canonicalize(left.SourceRefs), order.Canonicalize(right.SourceRefs))
+}
+
+// ExactIdentity returns a collision-safe duplicate key after display and
+// evidence canonicalization. It is intended for callers that have already
+// decided the event is eligible for duplicate handling.
+func ExactIdentity(order shared.SourceRefOrder, event dnd.ItemEvent) string {
+	var key strings.Builder
+	writeKeyString(&key, DisplayValue(event.Name))
+	writeKeyString(&key, string(event.Kind))
+	writeKeyString(&key, DisplayValue(event.From))
+	writeKeyString(&key, DisplayValue(event.To))
+	if event.Quantity == nil {
+		key.WriteByte('0')
+	} else {
+		key.WriteByte('1')
+		writeKeyInt(&key, *event.Quantity)
+	}
+	for _, ref := range order.Canonicalize(event.SourceRefs) {
+		writeKeyString(&key, ref.SourceID)
+		writeKeyInt(&key, ref.StartUnitID)
+		writeKeyInt(&key, ref.EndUnitID)
+	}
+	return key.String()
+}
+
+func optionalStringLess(left, right string) (bool, bool) {
+	leftPresent, rightPresent := HolderPresent(left), HolderPresent(right)
+	if leftPresent != rightPresent {
+		return !leftPresent, true
+	}
+	if !leftPresent {
+		return false, false
+	}
+	if leftKey, rightKey := ComparisonKey(left), ComparisonKey(right); leftKey != rightKey {
+		return leftKey < rightKey, true
+	}
+	if leftValue, rightValue := DisplayValue(left), DisplayValue(right); leftValue != rightValue {
+		return leftValue < rightValue, true
+	}
+	return false, false
+}
+
+func optionalQuantityLess(left, right *int) (bool, bool) {
+	if (left == nil) != (right == nil) {
+		return left == nil, true
+	}
+	if left != nil && *left != *right {
+		return *left < *right, true
+	}
+	return false, false
+}
+
+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)
+}
+
+func writeKeyString(builder *strings.Builder, value string) {
+	builder.WriteString(strconv.Itoa(len(value)))
+	builder.WriteByte(':')
+	builder.WriteString(value)
+}
+
+func writeKeyInt(builder *strings.Builder, value int) {
+	builder.WriteString(strconv.Itoa(value))
+	builder.WriteByte(';')
+}