notarius/internal/modules/dnd/itemevents/itemevents.go

// 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(';')
}