Centralize D&D source reference ordering

internal/modules/dnd/normalize/spells/normalizer.go

@@ -3,7 +3,6 @@ package spells
 import (
 	"context"
 	"fmt"
-	"sort"
 	"strconv"
 	"strings"
 
@@ -11,11 +10,16 @@ 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"
 	spellcatalog "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/spells/catalog"
 	"golang.org/x/text/cases"
 )
 
-const Key = "dnd/spells"
+const (
+	Key                 = "dnd/spells"
+	normalizationPolicy = "dnd.spells.normalize.v1"
+	NormalizationPolicy = normalizationPolicy
+)
 
 const (
 	ReasonCodeSpellNameCanonicalized      = "spell_name_canonicalized"
@@ -65,9 +69,10 @@ func (n *Normalizer) ManifestMetadata() map[string]any {
 		return nil
 	}
 	return map[string]any{
-		"catalog_base_id":     n.effectiveCatalog.BaseID(),
-		"catalog_digest":      n.effectiveCatalog.Digest(),
-		"catalog_overlay_ids": append([]string(nil), n.effectiveCatalog.OverlayIDs()...),
+		"catalog_base_id":      n.effectiveCatalog.BaseID(),
+		"catalog_digest":       n.effectiveCatalog.Digest(),
+		"catalog_overlay_ids":  append([]string(nil), n.effectiveCatalog.OverlayIDs()...),
+		"normalization_policy": normalizationPolicy,
 	}
 }
 
@@ -75,7 +80,10 @@ func (n *Normalizer) CheckpointFingerprints() []pipeline.CheckpointFingerprint {
 	if n == nil {
 		return nil
 	}
-	return []pipeline.CheckpointFingerprint{{Name: "effective_catalog", Value: n.effectiveCatalog.Digest()}}
+	return []pipeline.CheckpointFingerprint{
+		{Name: "effective_catalog", Value: n.effectiveCatalog.Digest()},
+		{Name: "normalization_policy", Value: normalizationPolicy},
+	}
 }
 
 func (n *Normalizer) Normalize(ctx context.Context, req contracts.TypedNormalizeRequest[dnd.SpellList]) (contracts.TypedNormalizeResult[dnd.SpellList], error) {
@@ -89,13 +97,14 @@ func (n *Normalizer) Normalize(ctx context.Context, req contracts.TypedNormalize
 		return contracts.TypedNormalizeResult[dnd.SpellList]{}, normalizerErrorf("context error before normalize: %w", err)
 	}
 
-	value, warnings := normalizeSpellList(req.MergeOutput.Value, n.effectiveCatalog)
+	order := shared.NewSourceRefOrder(req.Source)
+	value, warnings := normalizeSpellList(req.MergeOutput.Value, n.effectiveCatalog, order)
 	value, duplicateWarnings := collapseDuplicateSpellCasts(value, req.Source, n.effectiveCatalog)
 	warnings = append(warnings, duplicateWarnings...)
 	return contracts.TypedNormalizeResult[dnd.SpellList]{Value: value, Warnings: warnings}, nil
 }
 
-func normalizeSpellList(input dnd.SpellList, catalog spellcatalog.EffectiveCatalog) (dnd.SpellList, []contracts.Warning) {
+func normalizeSpellList(input dnd.SpellList, catalog spellcatalog.EffectiveCatalog, order shared.SourceRefOrder) (dnd.SpellList, []contracts.Warning) {
 	var warnings []contracts.Warning
 	if input.SpellCasts == nil {
 		return dnd.SpellList{}, nil
@@ -123,7 +132,7 @@ func normalizeSpellList(input dnd.SpellList, catalog spellcatalog.EffectiveCatal
 			})
 		}
 
-		canonicalRefs, orderChanged, duplicateCount := canonicalizeSourceRefs(inputCast.SourceRefs)
+		canonicalRefs, orderChanged, duplicateCount := canonicalizeSourceRefs(order, inputCast.SourceRefs)
 		cast.SourceRefs = canonicalRefs
 		if orderChanged || duplicateCount > 0 {
 			warnings = append(warnings, contracts.Warning{
@@ -147,42 +156,21 @@ func cloneSpellCast(input dnd.SpellCast) dnd.SpellCast {
 	return output
 }
 
-func canonicalizeSourceRefs(input []source.SourceRef) ([]source.SourceRef, bool, int) {
-	if input == nil {
-		return nil, false, 0
-	}
-
-	canonical := make([]source.SourceRef, len(input))
-	copy(canonical, input)
-	sort.SliceStable(canonical, func(left, right int) bool {
-		return sourceRefLess(canonical[left], canonical[right])
-	})
-
-	orderChanged := false
-	for index := range input {
-		if input[index] != canonical[index] {
-			orderChanged = true
-			break
-		}
-	}
-
-	unique := make([]source.SourceRef, 0, len(canonical))
-	for _, ref := range canonical {
-		if len(unique) == 0 || unique[len(unique)-1] != ref {
-			unique = append(unique, ref)
-		}
-	}
-	return unique, orderChanged, len(input) - len(unique)
+func canonicalizeSourceRefs(order shared.SourceRefOrder, input []source.SourceRef) ([]source.SourceRef, bool, int) {
+	canonical := order.Canonicalize(input)
+	return canonical, !sourceRefsEqual(input, canonical), len(input) - len(canonical)
 }
 
-func sourceRefLess(left, right source.SourceRef) bool {
-	if left.SourceID != right.SourceID {
-		return left.SourceID < right.SourceID
+func sourceRefsEqual(left, right []source.SourceRef) bool {
+	if (left == nil) != (right == nil) || len(left) != len(right) {
+		return false
 	}
-	if left.StartUnitID != right.StartUnitID {
-		return left.StartUnitID < right.StartUnitID
+	for index := range left {
+		if left[index] != right[index] {
+			return false
+		}
 	}
-	return left.EndUnitID < right.EndUnitID
+	return true
 }
 
 type duplicateGroup struct {