Move item occurrences to canonical namespace

internal/modules/dnd/validate/itemoccurrences/invariants/validator.go

@@ -1,4 +1,4 @@
-// Package invariants validates normalized D&D item-event artifacts.
+// Package invariants validates normalized D&D item-occurrence artifacts.
 package invariants
 
 import (
@@ -9,16 +9,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"
-	itemeventmodel "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/itemevents"
+	itemoccurrencemodel "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/itemoccurrences"
 	"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/shared"
 	"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/shared/diagnostics"
-	itemeventshape "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/validate/itemevents/shape"
+	itemoccurrenceshape "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/validate/itemoccurrences/shape"
 )
 
 const (
-	Key        = "normalize/dnd/item-events/invariants"
-	ReasonCode = "invalid_normalized_item_event_invariants"
-	policy     = "dnd.item_events.normalize_invariants.v1"
+	Key        = "normalize/dnd/item-occurrences/invariants"
+	ReasonCode = "invalid_normalized_item_occurrence_invariants"
+	policy     = "dnd.item_occurrences.normalize_invariants.v1"
 )
 
 type Options struct{}
@@ -43,10 +43,10 @@ func (v *Validator) Validate(_ context.Context, req contracts.TypedValidationReq
 	return contracts.ValidationResult{Approved: true}, nil
 }
 
-// Validate checks only invariants introduced by item-event normalization.
+// Validate checks only invariants introduced by item-occurrence normalization.
 // Shape and source-reference failures remain owned by their earlier validators.
 func Validate(doc *source.SourceDocument, value dnd.ItemOccurrenceList) error {
-	if itemeventshape.Validate(value) != nil {
+	if itemoccurrenceshape.Validate(value) != nil {
 		return nil
 	}
 	index := source.NewDocumentIndex(doc)
@@ -63,44 +63,44 @@ func Validate(doc *source.SourceDocument, value dnd.ItemOccurrenceList) error {
 func issuesFor(order shared.SourceRefOrder, value dnd.ItemOccurrenceList) []string {
 	issues := make([]string, 0)
 	seenIdentity := make(map[string]int)
-	for eventIndex, event := range value.Occurrences {
-		prefix := fmt.Sprintf("occurrences[%d]", eventIndex)
-		if event.Name != itemeventmodel.DisplayValue(event.Name) {
+	for occurrenceIndex, occurrence := range value.Occurrences {
+		prefix := fmt.Sprintf("occurrences[%d]", occurrenceIndex)
+		if occurrence.Name != itemoccurrencemodel.DisplayValue(occurrence.Name) {
 			issues = append(issues, prefix+".name is not display-normalized")
 		}
-		if event.From != itemeventmodel.DisplayValue(event.From) {
+		if occurrence.From != itemoccurrencemodel.DisplayValue(occurrence.From) {
 			issues = append(issues, prefix+".from is not display-normalized")
 		}
-		if event.To != itemeventmodel.DisplayValue(event.To) {
+		if occurrence.To != itemoccurrencemodel.DisplayValue(occurrence.To) {
 			issues = append(issues, prefix+".to is not display-normalized")
 		}
-		for refIndex := 1; refIndex < len(event.SourceRefs); refIndex++ {
-			previous := event.SourceRefs[refIndex-1]
-			current := event.SourceRefs[refIndex]
+		for refIndex := 1; refIndex < len(occurrence.SourceRefs); refIndex++ {
+			previous := occurrence.SourceRefs[refIndex-1]
+			current := occurrence.SourceRefs[refIndex]
 			if order.Less(current, previous) {
 				issues = append(issues, fmt.Sprintf("%s.source_refs are not in canonical order at index %d", prefix, refIndex))
 			} else if current == previous {
 				issues = append(issues, fmt.Sprintf("%s.source_refs[%d] duplicates the previous reference", prefix, refIndex))
 			}
 		}
-		key := itemeventmodel.ExactIdentity(order, event)
+		key := itemoccurrencemodel.ExactIdentity(order, occurrence)
 		if previous, exists := seenIdentity[key]; exists {
 			issues = append(issues, fmt.Sprintf("%s duplicates item occurrence %d under normalized identity", prefix, previous))
 		} else {
-			seenIdentity[key] = eventIndex
+			seenIdentity[key] = occurrenceIndex
 		}
 	}
-	for eventIndex := 1; eventIndex < len(value.Occurrences); eventIndex++ {
-		if itemeventmodel.Less(order, value.Occurrences[eventIndex], value.Occurrences[eventIndex-1]) {
-			issues = append(issues, fmt.Sprintf("occurrences[%d] is out of canonical order", eventIndex))
+	for occurrenceIndex := 1; occurrenceIndex < len(value.Occurrences); occurrenceIndex++ {
+		if itemoccurrencemodel.Less(order, value.Occurrences[occurrenceIndex], value.Occurrences[occurrenceIndex-1]) {
+			issues = append(issues, fmt.Sprintf("occurrences[%d] is out of canonical order", occurrenceIndex))
 		}
 	}
 	return issues
 }
 
 func sourceRefsValid(index source.DocumentIndex, value dnd.ItemOccurrenceList) bool {
-	for _, event := range value.Occurrences {
-		if !itemeventmodel.ValidSourceRefs(index, event.SourceRefs) {
+	for _, occurrence := range value.Occurrences {
+		if !itemoccurrencemodel.ValidSourceRefs(index, occurrence.SourceRefs) {
 			return false
 		}
 	}

internal/modules/dnd/validate/itemoccurrences/invariants/validator_test.go

@@ -45,7 +45,7 @@ func TestValidateRejectsOwnedNormalizedInvariants(t *testing.T) {
 		{name: "list order", mutate: func(value *dnd.ItemOccurrenceList) {
 			value.Occurrences = []dnd.ItemOccurrence{value.Occurrences[1], value.Occurrences[0]}
 		}, want: "out of canonical order"},
-		{name: "duplicate event", mutate: func(value *dnd.ItemOccurrenceList) {
+		{name: "duplicate occurrence", mutate: func(value *dnd.ItemOccurrenceList) {
 			value.Occurrences = append(value.Occurrences, value.Occurrences[0])
 		}, want: "duplicates item occurrence"},
 	}

internal/modules/dnd/validate/itemoccurrences/registry/validator.go

@@ -10,11 +10,11 @@ import (
 	"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd"
 	itemregistry "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/items/registry"
 	"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/shared/diagnostics"
-	occurrenceshape "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/validate/itemevents/shape"
+	occurrenceshape "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/validate/itemoccurrences/shape"
 )
 
 const (
-	Key        = "extract/dnd/item-events/registry"
+	Key        = "extract/dnd/item-occurrences/registry"
 	ReasonCode = "invalid_item_occurrence_registry"
 	policy     = "dnd.item_occurrences.validator.registry.v1"
 )

internal/modules/dnd/validate/itemoccurrences/shape/validator.go

@@ -1,4 +1,4 @@
-// Package shape validates required D&D item-event candidate fields.
+// Package shape validates required D&D item-occurrence candidate fields.
 package shape
 
 import (
@@ -9,14 +9,14 @@ 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/itemevents"
+	"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/itemoccurrences"
 	"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/shared/diagnostics"
 )
 
 const (
-	Key        = "extract/dnd/item-events/shape"
-	ReasonCode = "invalid_item_event_shape"
-	policy     = "dnd.item_events.shape.v1"
+	Key        = "extract/dnd/item-occurrences/shape"
+	ReasonCode = "invalid_item_occurrence_shape"
+	policy     = "dnd.item_occurrences.shape.v1"
 )
 
 type Options struct{}
@@ -41,7 +41,7 @@ func (v *Validator) Validate(_ context.Context, req contracts.TypedValidationReq
 	return contracts.ValidationResult{Approved: true}, nil
 }
 
-// Validate returns one bounded error for every owned item-event shape issue.
+// Validate returns one bounded error for every owned item-occurrence shape issue.
 func Validate(value dnd.ItemOccurrenceList) error {
 	issues := issuesFor(value)
 	if len(issues) == 0 {
@@ -55,23 +55,23 @@ func issuesFor(value dnd.ItemOccurrenceList) []string {
 		return []string{"occurrences must be present"}
 	}
 	issues := make([]string, 0)
-	for index, event := range value.Occurrences {
+	for index, occurrence := range value.Occurrences {
 		prefix := fmt.Sprintf("occurrences[%d]", index)
-		if strings.TrimSpace(event.ItemID) == "" {
-			issues = append(issues, prefix+".item_id must not be empty: "+diagnostics.Quote(event.ItemID))
+		if strings.TrimSpace(occurrence.ItemID) == "" {
+			issues = append(issues, prefix+".item_id must not be empty: "+diagnostics.Quote(occurrence.ItemID))
 		}
-		if strings.TrimSpace(event.Name) == "" {
-			issues = append(issues, prefix+".name must not be empty: "+diagnostics.Quote(event.Name))
+		if strings.TrimSpace(occurrence.Name) == "" {
+			issues = append(issues, prefix+".name must not be empty: "+diagnostics.Quote(occurrence.Name))
 		}
-		if !itemevents.SupportedKind(event.Kind) {
-			issues = append(issues, prefix+".kind is unsupported: "+diagnostics.Quote(string(event.Kind)))
-		} else if !itemevents.ValidHolderCombination(event.Kind, event.From, event.To) {
-			issues = append(issues, prefix+".from and .to are incompatible with "+diagnostics.Quote(string(event.Kind)))
+		if !itemoccurrences.SupportedKind(occurrence.Kind) {
+			issues = append(issues, prefix+".kind is unsupported: "+diagnostics.Quote(string(occurrence.Kind)))
+		} else if !itemoccurrences.ValidHolderCombination(occurrence.Kind, occurrence.From, occurrence.To) {
+			issues = append(issues, prefix+".from and .to are incompatible with "+diagnostics.Quote(string(occurrence.Kind)))
 		}
-		if event.Quantity != nil && *event.Quantity < 1 {
+		if occurrence.Quantity != nil && *occurrence.Quantity < 1 {
 			issues = append(issues, prefix+".quantity must be positive when present")
 		}
-		if len(event.SourceRefs) == 0 {
+		if len(occurrence.SourceRefs) == 0 {
 			issues = append(issues, prefix+".source_refs must contain at least one reference")
 		}
 	}

internal/modules/dnd/validate/itemoccurrences/shape/validator_test.go

@@ -13,7 +13,7 @@ import (
 	"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd"
 )
 
-func TestValidatorAcceptsEveryEventRuleAndNormalizableWhitespace(t *testing.T) {
+func TestValidatorAcceptsEveryOccurrenceRuleAndNormalizableWhitespace(t *testing.T) {
 	quantity := 1
 	value := dnd.ItemOccurrenceList{Occurrences: []dnd.ItemOccurrence{{ItemID: "item", Name: "  Hidden Cache  ", Kind: dnd.ItemOccurrenceKindDiscovered, From: " ", To: " ", SourceRefs: refs(1, 1)},
 		{ItemID: "item", Name: "Gold Pieces", Kind: dnd.ItemOccurrenceKindAcquired, Quantity: &quantity, To: " party ", SourceRefs: refs(2, 2)},
@@ -40,7 +40,7 @@ func TestValidatorRejectsOwnedSemanticBoundaries(t *testing.T) {
 		value dnd.ItemOccurrenceList
 		want  string
 	}{
-		{"missing events", dnd.ItemOccurrenceList{}, "occurrences must be present"},
+		{"missing occurrences", dnd.ItemOccurrenceList{}, "occurrences must be present"},
 		{"blank name", listWith(dnd.ItemOccurrence{ItemID: "item", Name: " \t", Kind: dnd.ItemOccurrenceKindDiscovered, SourceRefs: refs(1, 1)}), "name must not be empty"},
 		{"unsupported kind", listWith(dnd.ItemOccurrence{ItemID: "item", Name: "Ring", Kind: "unknown", SourceRefs: refs(1, 1)}), "kind is unsupported"},
 		{"discovered holder", listWith(dnd.ItemOccurrence{ItemID: "item", Name: "Ring", Kind: dnd.ItemOccurrenceKindDiscovered, From: "Aria", SourceRefs: refs(1, 1)}), "incompatible"},
@@ -99,8 +99,8 @@ func validList() dnd.ItemOccurrenceList {
 	return dnd.ItemOccurrenceList{Occurrences: []dnd.ItemOccurrence{{ItemID: "item", Name: "Ring", Kind: dnd.ItemOccurrenceKindAcquired, To: "party", SourceRefs: refs(1, 1)}}}
 }
 
-func listWith(event dnd.ItemOccurrence) dnd.ItemOccurrenceList {
-	return dnd.ItemOccurrenceList{Occurrences: []dnd.ItemOccurrence{event}}
+func listWith(occurrence dnd.ItemOccurrence) dnd.ItemOccurrenceList {
+	return dnd.ItemOccurrenceList{Occurrences: []dnd.ItemOccurrence{occurrence}}
 }
 
 func refs(start, end int) []source.SourceRef {

internal/modules/dnd/validate/itemoccurrences/source_refs/validator.go

@@ -1,4 +1,4 @@
-// Package sourcerefs validates D&D item-event transcript evidence.
+// Package sourcerefs validates D&D item-occurrence transcript evidence.
 package sourcerefs
 
 import (
@@ -10,13 +10,13 @@ import (
 	"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/diagnostics"
-	itemeventshape "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/validate/itemevents/shape"
+	itemoccurrenceshape "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/validate/itemoccurrences/shape"
 )
 
 const (
-	Key        = "extract/dnd/item-events/source_refs"
-	ReasonCode = "invalid_item_event_source_references"
-	policy     = "dnd.item_events.source_refs.v1"
+	Key        = "extract/dnd/item-occurrences/source_refs"
+	ReasonCode = "invalid_item_occurrence_source_references"
+	policy     = "dnd.item_occurrences.source_refs.v1"
 )
 
 type Options struct{}
@@ -38,7 +38,7 @@ func (v *Validator) Validate(_ context.Context, req contracts.TypedValidationReq
 	if req.Stage == string(pipeline.StageExtract) && req.Chunk == nil {
 		return contracts.ValidationResult{}, fmt.Errorf("item occurrence source-reference validator requires the current extraction chunk")
 	}
-	if itemeventshape.Validate(req.Value) != nil {
+	if itemoccurrenceshape.Validate(req.Value) != nil {
 		return contracts.ValidationResult{Approved: true}, nil
 	}
 	index := source.NewDocumentIndex(req.Source)
@@ -47,14 +47,14 @@ func (v *Validator) Validate(_ context.Context, req contracts.TypedValidationReq
 		coverage = newChunkCoverage(req.Chunk)
 	}
 	issues := make([]string, 0)
-	for eventIndex, event := range req.Value.Occurrences {
-		for refIndex, ref := range event.SourceRefs {
+	for occurrenceIndex, occurrence := range req.Value.Occurrences {
+		for refIndex, ref := range occurrence.SourceRefs {
 			if err := index.ValidateRef(ref); err != nil {
-				issues = append(issues, fmt.Sprintf("occurrences[%d].source_refs[%d]: %s", eventIndex, refIndex, diagnostics.Truncate(err.Error())))
+				issues = append(issues, fmt.Sprintf("occurrences[%d].source_refs[%d]: %s", occurrenceIndex, refIndex, diagnostics.Truncate(err.Error())))
 				continue
 			}
 			if coverage != nil && !coverage.contains(req.Source, ref) {
-				issues = append(issues, fmt.Sprintf("occurrences[%d].source_refs[%d]: source reference is outside the current extraction chunk", eventIndex, refIndex))
+				issues = append(issues, fmt.Sprintf("occurrences[%d].source_refs[%d]: source reference is outside the current extraction chunk", occurrenceIndex, refIndex))
 			}
 		}
 	}

internal/modules/dnd/validate/itemoccurrences/source_relatedness/validator.go

@@ -1,4 +1,4 @@
-// Package sourcerelatedness warns when item-event evidence does not mention its item.
+// Package sourcerelatedness warns when item-occurrence evidence does not mention its item.
 package sourcerelatedness
 
 import (
@@ -10,14 +10,14 @@ import (
 	"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd"
 	"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/shared"
 	"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/shared/diagnostics"
-	itemeventshape "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/validate/itemevents/shape"
+	itemoccurrenceshape "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/validate/itemoccurrences/shape"
 )
 
 const (
-	Key               = "extract/dnd/item-events/source_relatedness"
-	WarningReasonCode = "item_event_source_unrelated"
-	OmittedReasonCode = "item_event_relatedness_warnings_omitted"
-	policy            = "dnd.item_events.source_relatedness.v1"
+	Key               = "extract/dnd/item-occurrences/source_relatedness"
+	WarningReasonCode = "item_occurrence_source_unrelated"
+	OmittedReasonCode = "item_occurrence_relatedness_warnings_omitted"
+	policy            = "dnd.item_occurrences.source_relatedness.v1"
 )
 
 type Options struct{}
@@ -38,7 +38,7 @@ func (v *Validator) CheckpointFingerprints() []pipeline.CheckpointFingerprint {
 // Validate performs advisory source grounding only. Shape and range failures
 // are intentionally left to their blocking owners.
 func (v *Validator) Validate(_ context.Context, req contracts.TypedValidationRequest[dnd.ItemOccurrenceList]) (contracts.ValidationResult, error) {
-	if itemeventshape.Validate(req.Value) != nil {
+	if itemoccurrenceshape.Validate(req.Value) != nil {
 		return contracts.ValidationResult{Approved: true}, nil
 	}
 	resolver, err := shared.NewCitationResolver(req.Source)
@@ -47,20 +47,20 @@ func (v *Validator) Validate(_ context.Context, req contracts.TypedValidationReq
 	}
 
 	warnings := make([]contracts.Warning, 0)
-	for index, event := range req.Value.Occurrences {
-		citedText, err := resolver.CitedText(event.SourceRefs)
-		if err != nil || shared.ContainsTokenSequence(citedText, event.Name) {
+	for index, occurrence := range req.Value.Occurrences {
+		citedText, err := resolver.CitedText(occurrence.SourceRefs)
+		if err != nil || shared.ContainsTokenSequence(citedText, occurrence.Name) {
 			continue
 		}
 		warnings = append(warnings, contracts.Warning{
 			Scope:      fmt.Sprintf("occurrences[%d]", index),
 			ReasonCode: WarningReasonCode,
-			Message:    fmt.Sprintf("item occurrence name %s was not found in cited source text", diagnostics.Quote(event.Name)),
+			Message:    fmt.Sprintf("item occurrence name %s was not found in cited source text", diagnostics.Quote(occurrence.Name)),
 		})
 	}
 	return contracts.ValidationResult{
 		Approved: true,
-		Warnings: diagnostics.LimitWarnings(warnings, "item_events", OmittedReasonCode),
+		Warnings: diagnostics.LimitWarnings(warnings, "item_occurrences", OmittedReasonCode),
 	}, nil
 }
 

internal/modules/dnd/validate/itemoccurrences/source_relatedness/validator_test.go

@@ -49,13 +49,13 @@ func TestValidatorDefersMalformedAndUnreadableEvidence(t *testing.T) {
 
 func TestValidatorBoundsWarningsAndRegistersPolicy(t *testing.T) {
 	count := diagnostics.MaxWarnings + 5
-	events := make([]dnd.ItemOccurrence, count)
-	for index := range events {
-		events[index] = dnd.ItemOccurrence{ItemID: "item", Name: "missing item", Kind: dnd.ItemOccurrenceKindDiscovered, SourceRefs: []source.SourceRef{{SourceID: "session", StartUnitID: 1, EndUnitID: 1}}}
+	occurrences := make([]dnd.ItemOccurrence, count)
+	for index := range occurrences {
+		occurrences[index] = dnd.ItemOccurrence{ItemID: "item", Name: "missing item", Kind: dnd.ItemOccurrenceKindDiscovered, SourceRefs: []source.SourceRef{{SourceID: "session", StartUnitID: 1, EndUnitID: 1}}}
 	}
 	result, err := New(Options{}).Validate(context.Background(), contracts.TypedValidationRequest[dnd.ItemOccurrenceList]{
 		Source: &source.SourceDocument{ID: "session", Units: []source.SourceUnit{{ID: 1, Text: "nothing useful"}}},
-		Value:  dnd.ItemOccurrenceList{Occurrences: events},
+		Value:  dnd.ItemOccurrenceList{Occurrences: occurrences},
 	})
 	if err != nil || !result.Approved || len(result.Warnings) != diagnostics.MaxWarnings || result.Warnings[len(result.Warnings)-1].ReasonCode != OmittedReasonCode {
 		t.Fatalf("Validate() = %#v, %v", result, err)