Add typed spell validation strategies

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

@@ -2,59 +2,104 @@ package shape
 
 import (
 	"context"
+	"fmt"
+	"strings"
 
 	"gitea.maximumdirect.net/eric/notarius/internal/framework/contracts"
 	"gitea.maximumdirect.net/eric/notarius/internal/framework/pipeline"
-	"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/validate/spells/spellpayload"
+	"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd"
 )
 
 const Key = "extract/dnd/spells/shape"
 const ReasonCode = "invalid_spell_shape"
 
-var _ contracts.LegacyRawValidator = (*Validator)(nil)
-
+type Options struct{}
 type Validator struct{}
-
-func New() *Validator {
-	return &Validator{}
+type legacyValidator struct{ codec decoder }
+type decoder interface {
+	DecodeCandidate([]byte) (dnd.SpellList, error)
 }
 
-func (v *Validator) Name() string {
-	return Key
-}
+var _ contracts.TypedValidator[dnd.SpellList] = (*Validator)(nil)
 
+func New(Options) *Validator      { return &Validator{} }
+func (v *Validator) Name() string { return Key }
 func (v *Validator) ExecutionClass() contracts.ExecutionClass {
 	return contracts.ExecutionClassDeterministic
 }
-
-func (v *Validator) Validate(ctx context.Context, req contracts.ValidationRequest) (contracts.ValidationResult, error) {
-	payload, err := spellpayload.ValidationRequestPayload(req)
-	if err != nil {
-		return rejection(err.Error()), nil
-	}
-	if err := spellpayload.ValidateShape(payload); err != nil {
+func (v *Validator) Validate(_ context.Context, req contracts.TypedValidationRequest[dnd.SpellList]) (contracts.ValidationResult, error) {
+	if err := Validate(req.Value); err != nil {
 		return rejection(err.Error()), nil
 	}
 	return contracts.ValidationResult{Approved: true}, nil
 }
 
-func Spec() pipeline.ValidatorSpec {
-	return pipeline.ValidatorSpec{
-		Key:            Key,
-		ExecutionClass: contracts.ExecutionClassDeterministic,
+func Validate(value dnd.SpellList) error {
+	if value.SpellCasts == nil {
+		return fmt.Errorf("spell_casts must be present")
 	}
+	for index, spell := range value.SpellCasts {
+		if strings.TrimSpace(spell.Caster) == "" {
+			return fmt.Errorf("spell_casts[%d].caster must not be empty", index)
+		}
+		if strings.TrimSpace(spell.Spell) == "" {
+			return fmt.Errorf("spell_casts[%d].spell must not be empty", index)
+		}
+		if strings.TrimSpace(spell.Effect) == "" {
+			return fmt.Errorf("spell_casts[%d].effect must not be empty", index)
+		}
+		if strings.TrimSpace(spell.NarrativeDescription) == "" {
+			return fmt.Errorf("spell_casts[%d].narrative_description must not be empty", index)
+		}
+		if len(spell.SourceRefs) == 0 {
+			return fmt.Errorf("spell_casts[%d].source_refs must not be empty", index)
+		}
+	}
+	return nil
 }
 
+func (v *legacyValidator) Name() string { return Key }
+func (v *legacyValidator) ExecutionClass() contracts.ExecutionClass {
+	return contracts.ExecutionClassDeterministic
+}
+func (v *legacyValidator) Validate(ctx context.Context, req contracts.ValidationRequest) (contracts.ValidationResult, error) {
+	value, err := v.codec.DecodeCandidate(req.Payload.Content)
+	if err != nil {
+		return rejection(err.Error()), nil
+	}
+	return New(Options{}).Validate(ctx, contracts.TypedValidationRequest[dnd.SpellList]{Value: value})
+}
+
+func Spec() pipeline.ValidatorSpec {
+	return pipeline.ValidatorSpec{Key: Key, ExecutionClass: contracts.ExecutionClassDeterministic}
+}
 func Register(registry *pipeline.ValidatorRegistry) error {
-	return registry.RegisterLegacyRawWithSpec(Spec(), func() (contracts.LegacyRawValidator, error) {
-		return New(), nil
+	return pipeline.RegisterTypedValidatorBuilder(registry, dnd.SpellListKind, Spec(), validateOptions, func(request pipeline.BuildRequest) (contracts.TypedValidator[dnd.SpellList], error) {
+		options, err := DecodeOptions(request.Options)
+		if err != nil {
+			return nil, err
+		}
+		return New(options), nil
 	})
 }
-
-func rejection(message string) contracts.ValidationResult {
-	return contracts.ValidationResult{
-		Approved:   false,
-		ReasonCode: ReasonCode,
-		Message:    message,
+func RegisterLegacy(registry *pipeline.ValidatorRegistry, codec decoder) error {
+	if codec == nil {
+		return fmt.Errorf("spell shape validator codec must not be nil")
 	}
+	return registry.RegisterLegacyRawBuilderWithSpec(Spec(), validateOptions, func(request pipeline.BuildRequest) (contracts.LegacyRawValidator, error) {
+		if _, err := DecodeOptions(request.Options); err != nil {
+			return nil, err
+		}
+		return &legacyValidator{codec: codec}, nil
+	})
+}
+func DecodeOptions(options map[string]any) (Options, error) {
+	if err := pipeline.RejectUnknownOptions(options); err != nil {
+		return Options{}, err
+	}
+	return Options{}, nil
+}
+func validateOptions(options map[string]any) error { _, err := DecodeOptions(options); return err }
+func rejection(message string) contracts.ValidationResult {
+	return contracts.ValidationResult{Approved: false, ReasonCode: ReasonCode, Message: message}
 }

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

@@ -4,12 +4,14 @@ import (
 	"context"
 	"testing"
 
+	"gitea.maximumdirect.net/eric/notarius/internal/core/source"
 	"gitea.maximumdirect.net/eric/notarius/internal/framework/contracts"
 	"gitea.maximumdirect.net/eric/notarius/internal/framework/pipeline"
+	"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd"
 )
 
 func TestValidatorApprovesWellFormedSpellPayload(t *testing.T) {
-	result, err := New().Validate(context.Background(), requestWithPayload(`{"spell_casts":[{"caster":"Aria","spell":"Cure Wounds","effect":"heals","narrative_description":"Aria heals Borin.","source_refs":[{"source_id":"session","start_unit_id":1,"end_unit_id":1}]}]}`))
+	result, err := New(Options{}).Validate(context.Background(), requestWithValue(validSpellList()))
 	if err != nil {
 		t.Fatalf("Validate() error = %v, want nil", err)
 	}
@@ -18,8 +20,8 @@ func TestValidatorApprovesWellFormedSpellPayload(t *testing.T) {
 	}
 }
 
-func TestValidatorRejectsMalformedPayload(t *testing.T) {
-	result, err := New().Validate(context.Background(), requestWithPayload(`{"spell_casts":`))
+func TestValidatorRejectsMissingSpellList(t *testing.T) {
+	result, err := New(Options{}).Validate(context.Background(), requestWithValue(dnd.SpellList{}))
 	if err != nil {
 		t.Fatalf("Validate() error = %v, want nil", err)
 	}
@@ -32,7 +34,9 @@ func TestValidatorRejectsMalformedPayload(t *testing.T) {
 }
 
 func TestValidatorRejectsMissingRequiredSpellFields(t *testing.T) {
-	result, err := New().Validate(context.Background(), requestWithPayload(`{"spell_casts":[{"caster":"Aria","effect":"heals","narrative_description":"Aria heals Borin.","source_refs":[{"source_id":"session","start_unit_id":1,"end_unit_id":1}]}]}`))
+	value := validSpellList()
+	value.SpellCasts[0].Spell = ""
+	result, err := New(Options{}).Validate(context.Background(), requestWithValue(value))
 	if err != nil {
 		t.Fatalf("Validate() error = %v, want nil", err)
 	}
@@ -49,20 +53,15 @@ func TestSpecAndRegister(t *testing.T) {
 	if err := Register(registry); err != nil {
 		t.Fatalf("Register() error = %v, want nil", err)
 	}
-	validator, err := registry.BuildLegacyRaw(Key)
-	if err != nil {
-		t.Fatalf("Build(%q) error = %v, want nil", Key, err)
-	}
-	if validator.Name() != Key || validator.ExecutionClass() != contracts.ExecutionClassDeterministic {
-		t.Fatalf("validator = %q/%q, want key and deterministic execution", validator.Name(), validator.ExecutionClass())
+	if _, err := DecodeOptions(map[string]any{"unexpected": true}); err == nil {
+		t.Fatal("DecodeOptions() error = nil, want unknown option error")
 	}
 }
 
-func requestWithPayload(payload string) contracts.ValidationRequest {
-	return contracts.ValidationRequest{
-		Payload: contracts.RawPayload{
-			Content:   []byte(payload),
-			MediaType: "application/json",
-		},
-	}
+func requestWithValue(value dnd.SpellList) contracts.TypedValidationRequest[dnd.SpellList] {
+	return contracts.TypedValidationRequest[dnd.SpellList]{Value: value}
+}
+
+func validSpellList() dnd.SpellList {
+	return dnd.SpellList{SpellCasts: []dnd.SpellCast{{Caster: "Aria", Spell: "Cure Wounds", Effect: "heals", NarrativeDescription: "Aria heals Borin.", SourceRefs: []source.SourceRef{{SourceID: "session", StartUnitID: 1, EndUnitID: 1}}}}}
 }

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

@@ -7,38 +7,33 @@ import (
 	"gitea.maximumdirect.net/eric/notarius/internal/core/source"
 	"gitea.maximumdirect.net/eric/notarius/internal/framework/contracts"
 	"gitea.maximumdirect.net/eric/notarius/internal/framework/pipeline"
-	"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/validate/spells/spellpayload"
+	"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd"
+	spellshape "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/validate/spells/shape"
 )
 
 const Key = "extract/dnd/spells/source_refs"
 const ReasonCode = "invalid_source_refs"
 
-var _ contracts.LegacyRawValidator = (*Validator)(nil)
-
+type Options struct{}
 type Validator struct{}
-
-func New() *Validator {
-	return &Validator{}
+type legacyValidator struct{ codec decoder }
+type decoder interface {
+	DecodeCandidate([]byte) (dnd.SpellList, error)
 }
 
-func (v *Validator) Name() string {
-	return Key
-}
+var _ contracts.TypedValidator[dnd.SpellList] = (*Validator)(nil)
 
+func New(Options) *Validator      { return &Validator{} }
+func (v *Validator) Name() string { return Key }
 func (v *Validator) ExecutionClass() contracts.ExecutionClass {
 	return contracts.ExecutionClassDeterministic
 }
-
-func (v *Validator) Validate(ctx context.Context, req contracts.ValidationRequest) (contracts.ValidationResult, error) {
-	payload, err := spellpayload.ValidationRequestPayload(req)
-	if err != nil {
+func (v *Validator) Validate(_ context.Context, req contracts.TypedValidationRequest[dnd.SpellList]) (contracts.ValidationResult, error) {
+	if err := spellshape.Validate(req.Value); err != nil {
 		return rejection(err.Error()), nil
 	}
-	if err := spellpayload.ValidateShape(payload); err != nil {
-		return rejection(err.Error()), nil
-	}
-	for spellIndex, spell := range payload.SpellCasts {
-		for refIndex, ref := range spellpayload.SourceRefCandidates(req.Source, spell) {
+	for spellIndex, spell := range req.Value.SpellCasts {
+		for refIndex, ref := range spell.SourceRefs {
 			if err := source.ValidateRef(req.Source, ref); err != nil {
 				return rejection(fmt.Sprintf("spell_casts[%d].source_refs[%d]: %v", spellIndex, refIndex, err)), nil
 			}
@@ -46,24 +41,50 @@ func (v *Validator) Validate(ctx context.Context, req contracts.ValidationReques
 	}
 	return contracts.ValidationResult{Approved: true}, nil
 }
-
-func Spec() pipeline.ValidatorSpec {
-	return pipeline.ValidatorSpec{
-		Key:            Key,
-		ExecutionClass: contracts.ExecutionClassDeterministic,
-	}
+func (v *legacyValidator) Name() string { return Key }
+func (v *legacyValidator) ExecutionClass() contracts.ExecutionClass {
+	return contracts.ExecutionClassDeterministic
+}
+func (v *legacyValidator) Validate(ctx context.Context, req contracts.ValidationRequest) (contracts.ValidationResult, error) {
+	value, err := v.codec.DecodeCandidate(req.Payload.Content)
+	if err != nil {
+		return rejection(err.Error()), nil
+	}
+	if err := spellshape.Validate(value); err != nil {
+		return rejection(err.Error()), nil
+	}
+	return New(Options{}).Validate(ctx, contracts.TypedValidationRequest[dnd.SpellList]{Source: req.Source, Value: value})
+}
+func Spec() pipeline.ValidatorSpec {
+	return pipeline.ValidatorSpec{Key: Key, ExecutionClass: contracts.ExecutionClassDeterministic}
 }
-
 func Register(registry *pipeline.ValidatorRegistry) error {
-	return registry.RegisterLegacyRawWithSpec(Spec(), func() (contracts.LegacyRawValidator, error) {
-		return New(), nil
+	return pipeline.RegisterTypedValidatorBuilder(registry, dnd.SpellListKind, Spec(), validateOptions, func(request pipeline.BuildRequest) (contracts.TypedValidator[dnd.SpellList], error) {
+		options, err := DecodeOptions(request.Options)
+		if err != nil {
+			return nil, err
+		}
+		return New(options), nil
 	})
 }
-
-func rejection(message string) contracts.ValidationResult {
-	return contracts.ValidationResult{
-		Approved:   false,
-		ReasonCode: ReasonCode,
-		Message:    message,
+func RegisterLegacy(registry *pipeline.ValidatorRegistry, codec decoder) error {
+	if codec == nil {
+		return fmt.Errorf("spell source references validator codec must not be nil")
 	}
+	return registry.RegisterLegacyRawBuilderWithSpec(Spec(), validateOptions, func(request pipeline.BuildRequest) (contracts.LegacyRawValidator, error) {
+		if _, err := DecodeOptions(request.Options); err != nil {
+			return nil, err
+		}
+		return &legacyValidator{codec: codec}, nil
+	})
+}
+func DecodeOptions(options map[string]any) (Options, error) {
+	if err := pipeline.RejectUnknownOptions(options); err != nil {
+		return Options{}, err
+	}
+	return Options{}, nil
+}
+func validateOptions(options map[string]any) error { _, err := DecodeOptions(options); return err }
+func rejection(message string) contracts.ValidationResult {
+	return contracts.ValidationResult{Approved: false, ReasonCode: ReasonCode, Message: message}
 }

internal/modules/dnd/validate/spells/source_refs/validator_test.go

@@ -7,10 +7,11 @@ import (
 	"gitea.maximumdirect.net/eric/notarius/internal/core/source"
 	"gitea.maximumdirect.net/eric/notarius/internal/framework/contracts"
 	"gitea.maximumdirect.net/eric/notarius/internal/framework/pipeline"
+	"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd"
 )
 
 func TestValidatorApprovesValidSourceRefs(t *testing.T) {
-	result, err := New().Validate(context.Background(), requestWithPayload(validDocument(), `{"spell_casts":[{"caster":"Aria","spell":"Cure Wounds","effect":"heals","narrative_description":"Aria casts Cure Wounds.","source_refs":[{"source_id":"session","start_unit_id":1,"end_unit_id":2}]}]}`))
+	result, err := New(Options{}).Validate(context.Background(), requestWithValue(validDocument(), source.SourceRef{SourceID: "session", StartUnitID: 1, EndUnitID: 2}))
 	if err != nil {
 		t.Fatalf("Validate() error = %v, want nil", err)
 	}
@@ -20,7 +21,7 @@ func TestValidatorApprovesValidSourceRefs(t *testing.T) {
 }
 
 func TestValidatorRejectsInvalidSourceRefs(t *testing.T) {
-	result, err := New().Validate(context.Background(), requestWithPayload(validDocument(), `{"spell_casts":[{"caster":"Aria","spell":"Cure Wounds","effect":"heals","narrative_description":"Aria casts Cure Wounds.","source_refs":[{"source_id":"session","start_unit_id":99,"end_unit_id":99}]}]}`))
+	result, err := New(Options{}).Validate(context.Background(), requestWithValue(validDocument(), source.SourceRef{SourceID: "session", StartUnitID: 99, EndUnitID: 99}))
 	if err != nil {
 		t.Fatalf("Validate() error = %v, want nil", err)
 	}
@@ -33,7 +34,7 @@ func TestValidatorRejectsInvalidSourceRefs(t *testing.T) {
 }
 
 func TestValidatorRejectsMissingSourceDocument(t *testing.T) {
-	result, err := New().Validate(context.Background(), requestWithPayload(nil, `{"spell_casts":[{"caster":"Aria","spell":"Cure Wounds","effect":"heals","narrative_description":"Aria casts Cure Wounds.","source_refs":[{"source_id":"session","start_unit_id":1,"end_unit_id":1}]}]}`))
+	result, err := New(Options{}).Validate(context.Background(), requestWithValue(nil, source.SourceRef{SourceID: "session", StartUnitID: 1, EndUnitID: 1}))
 	if err != nil {
 		t.Fatalf("Validate() error = %v, want nil", err)
 	}
@@ -50,23 +51,15 @@ func TestSpecAndRegister(t *testing.T) {
 	if err := Register(registry); err != nil {
 		t.Fatalf("Register() error = %v, want nil", err)
 	}
-	validator, err := registry.BuildLegacyRaw(Key)
-	if err != nil {
-		t.Fatalf("Build(%q) error = %v, want nil", Key, err)
-	}
-	if validator.Name() != Key || validator.ExecutionClass() != contracts.ExecutionClassDeterministic {
-		t.Fatalf("validator = %q/%q, want key and deterministic execution", validator.Name(), validator.ExecutionClass())
+	if _, err := DecodeOptions(map[string]any{"unexpected": true}); err == nil {
+		t.Fatal("DecodeOptions() error = nil, want unknown option error")
 	}
 }
 
-func requestWithPayload(doc *source.SourceDocument, payload string) contracts.ValidationRequest {
-	return contracts.ValidationRequest{
-		Source: doc,
-		Payload: contracts.RawPayload{
-			Content:   []byte(payload),
-			MediaType: "application/json",
-		},
-	}
+func requestWithValue(doc *source.SourceDocument, ref source.SourceRef) contracts.TypedValidationRequest[dnd.SpellList] {
+	return contracts.TypedValidationRequest[dnd.SpellList]{Source: doc, Value: dnd.SpellList{SpellCasts: []dnd.SpellCast{{
+		Caster: "Aria", Spell: "Cure Wounds", Effect: "heals", NarrativeDescription: "Aria casts Cure Wounds.", SourceRefs: []source.SourceRef{ref},
+	}}}}
 }
 
 func validDocument() *source.SourceDocument {

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

@@ -8,76 +8,113 @@ import (
 	"gitea.maximumdirect.net/eric/notarius/internal/core/source"
 	"gitea.maximumdirect.net/eric/notarius/internal/framework/contracts"
 	"gitea.maximumdirect.net/eric/notarius/internal/framework/pipeline"
-	"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/validate/spells/spellpayload"
+	"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd"
+	spellshape "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/validate/spells/shape"
 )
 
 const Key = "extract/dnd/spells/source_relatedness"
 const WarningReasonCode = "spell_not_near_source"
 
-var _ contracts.LegacyRawValidator = (*Validator)(nil)
-
+type Options struct{}
 type Validator struct{}
-
-func New() *Validator {
-	return &Validator{}
+type legacyValidator struct{ codec decoder }
+type decoder interface {
+	DecodeCandidate([]byte) (dnd.SpellList, error)
 }
 
-func (v *Validator) Name() string {
-	return Key
-}
+var _ contracts.TypedValidator[dnd.SpellList] = (*Validator)(nil)
 
+func New(Options) *Validator      { return &Validator{} }
+func (v *Validator) Name() string { return Key }
 func (v *Validator) ExecutionClass() contracts.ExecutionClass {
 	return contracts.ExecutionClassDeterministic
 }
-
-func (v *Validator) Validate(ctx context.Context, req contracts.ValidationRequest) (contracts.ValidationResult, error) {
-	payload, err := spellpayload.ValidationRequestPayload(req)
-	if err != nil {
+func (v *Validator) Validate(_ context.Context, req contracts.TypedValidationRequest[dnd.SpellList]) (contracts.ValidationResult, error) {
+	if err := spellshape.Validate(req.Value); err != nil {
 		return contracts.ValidationResult{Approved: true}, nil
 	}
-	if err := spellpayload.ValidateShape(payload); err != nil {
-		return contracts.ValidationResult{Approved: true}, nil
-	}
-
 	var warnings []contracts.Warning
-	for spellIndex, spell := range payload.SpellCasts {
+	for spellIndex, spell := range req.Value.SpellCasts {
 		if !spellAppearsInCitedText(req.Source, spell) {
-			warnings = append(warnings, contracts.Warning{
-				Scope:      fmt.Sprintf("spell_casts[%d]", spellIndex),
-				ReasonCode: WarningReasonCode,
-				Message:    fmt.Sprintf("spell %q was not found in cited source text", strings.TrimSpace(spell.Spell)),
-			})
+			warnings = append(warnings, contracts.Warning{Scope: fmt.Sprintf("spell_casts[%d]", spellIndex), ReasonCode: WarningReasonCode, Message: fmt.Sprintf("spell %q was not found in cited source text", strings.TrimSpace(spell.Spell))})
 		}
 	}
 	return contracts.ValidationResult{Approved: true, Warnings: warnings}, nil
 }
-
-func Spec() pipeline.ValidatorSpec {
-	return pipeline.ValidatorSpec{
-		Key:            Key,
-		ExecutionClass: contracts.ExecutionClassDeterministic,
+func (v *legacyValidator) Name() string { return Key }
+func (v *legacyValidator) ExecutionClass() contracts.ExecutionClass {
+	return contracts.ExecutionClassDeterministic
+}
+func (v *legacyValidator) Validate(ctx context.Context, req contracts.ValidationRequest) (contracts.ValidationResult, error) {
+	value, err := v.codec.DecodeCandidate(req.Payload.Content)
+	if err != nil {
+		return contracts.ValidationResult{Approved: true}, nil
 	}
+	if err := spellshape.Validate(value); err != nil {
+		return contracts.ValidationResult{Approved: true}, nil
+	}
+	return New(Options{}).Validate(ctx, contracts.TypedValidationRequest[dnd.SpellList]{Source: req.Source, Value: value})
 }
-
-func Register(registry *pipeline.ValidatorRegistry) error {
-	return registry.RegisterLegacyRawWithSpec(Spec(), func() (contracts.LegacyRawValidator, error) {
-		return New(), nil
-	})
-}
-
-func spellAppearsInCitedText(doc *source.SourceDocument, spell spellpayload.SpellCast) bool {
+func spellAppearsInCitedText(doc *source.SourceDocument, spell dnd.SpellCast) bool {
 	name := strings.ToLower(strings.TrimSpace(spell.Spell))
 	if name == "" {
 		return true
 	}
-	for _, ref := range spellpayload.SourceRefCandidates(doc, spell) {
-		text, ok := spellpayload.CitedText(doc, ref)
-		if !ok {
-			continue
-		}
-		if strings.Contains(strings.ToLower(text), name) {
+	for _, ref := range spell.SourceRefs {
+		if text, ok := citedText(doc, ref); ok && strings.Contains(strings.ToLower(text), name) {
 			return true
 		}
 	}
 	return false
 }
+func citedText(doc *source.SourceDocument, ref source.SourceRef) (string, bool) {
+	if doc == nil {
+		return "", false
+	}
+	start, ok := source.UnitIndex(doc, ref.StartUnitID)
+	if !ok {
+		return "", false
+	}
+	end, ok := source.UnitIndex(doc, ref.EndUnitID)
+	if !ok || start > end {
+		return "", false
+	}
+	var b strings.Builder
+	for i := start; i <= end; i++ {
+		if b.Len() > 0 {
+			b.WriteByte('\n')
+		}
+		b.WriteString(doc.Units[i].Text)
+	}
+	return b.String(), true
+}
+func Spec() pipeline.ValidatorSpec {
+	return pipeline.ValidatorSpec{Key: Key, ExecutionClass: contracts.ExecutionClassDeterministic}
+}
+func Register(registry *pipeline.ValidatorRegistry) error {
+	return pipeline.RegisterTypedValidatorBuilder(registry, dnd.SpellListKind, Spec(), validateOptions, func(request pipeline.BuildRequest) (contracts.TypedValidator[dnd.SpellList], error) {
+		options, err := DecodeOptions(request.Options)
+		if err != nil {
+			return nil, err
+		}
+		return New(options), nil
+	})
+}
+func RegisterLegacy(registry *pipeline.ValidatorRegistry, codec decoder) error {
+	if codec == nil {
+		return fmt.Errorf("spell source relatedness validator codec must not be nil")
+	}
+	return registry.RegisterLegacyRawBuilderWithSpec(Spec(), validateOptions, func(request pipeline.BuildRequest) (contracts.LegacyRawValidator, error) {
+		if _, err := DecodeOptions(request.Options); err != nil {
+			return nil, err
+		}
+		return &legacyValidator{codec: codec}, nil
+	})
+}
+func DecodeOptions(options map[string]any) (Options, error) {
+	if err := pipeline.RejectUnknownOptions(options); err != nil {
+		return Options{}, err
+	}
+	return Options{}, nil
+}
+func validateOptions(options map[string]any) error { _, err := DecodeOptions(options); return err }

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

@@ -7,10 +7,11 @@ import (
 	"gitea.maximumdirect.net/eric/notarius/internal/core/source"
 	"gitea.maximumdirect.net/eric/notarius/internal/framework/contracts"
 	"gitea.maximumdirect.net/eric/notarius/internal/framework/pipeline"
+	"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd"
 )
 
 func TestValidatorApprovesWithoutWarningWhenSpellAppearsInCitedText(t *testing.T) {
-	result, err := New().Validate(context.Background(), requestWithPayload(validDocument(), `{"spell_casts":[{"caster":"Aria","spell":"Cure Wounds","effect":"heals","narrative_description":"Aria casts Cure Wounds.","source_refs":[{"source_id":"session","start_unit_id":2,"end_unit_id":2}]}]}`))
+	result, err := New(Options{}).Validate(context.Background(), requestWithSpell(validDocument(), "Cure Wounds", 2))
 	if err != nil {
 		t.Fatalf("Validate() error = %v, want nil", err)
 	}
@@ -23,7 +24,7 @@ func TestValidatorApprovesWithoutWarningWhenSpellAppearsInCitedText(t *testing.T
 }
 
 func TestValidatorWarnsWhenSpellDoesNotAppearInCitedText(t *testing.T) {
-	result, err := New().Validate(context.Background(), requestWithPayload(validDocument(), `{"spell_casts":[{"caster":"Borin","spell":"Fire Bolt","effect":"scorches","narrative_description":"Borin casts Fire Bolt.","source_refs":[{"source_id":"session","start_unit_id":1,"end_unit_id":1}]}]}`))
+	result, err := New(Options{}).Validate(context.Background(), requestWithSpell(validDocument(), "Fire Bolt", 1))
 	if err != nil {
 		t.Fatalf("Validate() error = %v, want nil", err)
 	}
@@ -38,8 +39,8 @@ func TestValidatorWarnsWhenSpellDoesNotAppearInCitedText(t *testing.T) {
 	}
 }
 
-func TestValidatorApprovesMalformedPayloadWithoutWarning(t *testing.T) {
-	result, err := New().Validate(context.Background(), requestWithPayload(validDocument(), `{"spell_casts":`))
+func TestValidatorApprovesEmptySpellListWithoutWarning(t *testing.T) {
+	result, err := New(Options{}).Validate(context.Background(), contracts.TypedValidationRequest[dnd.SpellList]{Source: validDocument(), Value: dnd.SpellList{SpellCasts: []dnd.SpellCast{}}})
 	if err != nil {
 		t.Fatalf("Validate() error = %v, want nil", err)
 	}
@@ -53,23 +54,16 @@ func TestSpecAndRegister(t *testing.T) {
 	if err := Register(registry); err != nil {
 		t.Fatalf("Register() error = %v, want nil", err)
 	}
-	validator, err := registry.BuildLegacyRaw(Key)
-	if err != nil {
-		t.Fatalf("Build(%q) error = %v, want nil", Key, err)
-	}
-	if validator.Name() != Key || validator.ExecutionClass() != contracts.ExecutionClassDeterministic {
-		t.Fatalf("validator = %q/%q, want key and deterministic execution", validator.Name(), validator.ExecutionClass())
+	if _, err := DecodeOptions(map[string]any{"unexpected": true}); err == nil {
+		t.Fatal("DecodeOptions() error = nil, want unknown option error")
 	}
 }
 
-func requestWithPayload(doc *source.SourceDocument, payload string) contracts.ValidationRequest {
-	return contracts.ValidationRequest{
-		Source: doc,
-		Payload: contracts.RawPayload{
-			Content:   []byte(payload),
-			MediaType: "application/json",
-		},
-	}
+func requestWithSpell(doc *source.SourceDocument, name string, unitID int) contracts.TypedValidationRequest[dnd.SpellList] {
+	return contracts.TypedValidationRequest[dnd.SpellList]{Source: doc, Value: dnd.SpellList{SpellCasts: []dnd.SpellCast{{
+		Caster: "Aria", Spell: name, Effect: "effect", NarrativeDescription: "description",
+		SourceRefs: []source.SourceRef{{SourceID: "session", StartUnitID: unitID, EndUnitID: unitID}},
+	}}}}
 }
 
 func validDocument() *source.SourceDocument {

internal/modules/dnd/validate/spells/spellpayload/payload.go

@@ -1,98 +0,0 @@
-package spellpayload
-
-import (
-	"bytes"
-	"encoding/json"
-	"fmt"
-	"io"
-	"strings"
-
-	"gitea.maximumdirect.net/eric/notarius/internal/core/source"
-	"gitea.maximumdirect.net/eric/notarius/internal/framework/contracts"
-	"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/shared"
-)
-
-type Payload struct {
-	SpellCasts []SpellCast `json:"spell_casts"`
-}
-
-type SpellCast struct {
-	Caster               string                     `json:"caster"`
-	Spell                string                     `json:"spell"`
-	Effect               string                     `json:"effect"`
-	NarrativeDescription string                     `json:"narrative_description"`
-	SourceRefs           []shared.SourceRefResponse `json:"source_refs"`
-}
-
-func Parse(raw []byte) (Payload, error) {
-	decoder := json.NewDecoder(bytes.NewReader(raw))
-	decoder.DisallowUnknownFields()
-
-	var payload Payload
-	if err := decoder.Decode(&payload); err != nil {
-		return Payload{}, fmt.Errorf("parse spell payload: %w", err)
-	}
-	var extra any
-	if err := decoder.Decode(&extra); err != io.EOF {
-		return Payload{}, fmt.Errorf("parse spell payload: multiple JSON values")
-	}
-	return payload, nil
-}
-
-func ValidateShape(payload Payload) error {
-	if payload.SpellCasts == nil {
-		return fmt.Errorf("spell_casts must be present")
-	}
-	for index, spell := range payload.SpellCasts {
-		if strings.TrimSpace(spell.Caster) == "" {
-			return fmt.Errorf("spell_casts[%d].caster must not be empty", index)
-		}
-		if strings.TrimSpace(spell.Spell) == "" {
-			return fmt.Errorf("spell_casts[%d].spell must not be empty", index)
-		}
-		if strings.TrimSpace(spell.Effect) == "" {
-			return fmt.Errorf("spell_casts[%d].effect must not be empty", index)
-		}
-		if strings.TrimSpace(spell.NarrativeDescription) == "" {
-			return fmt.Errorf("spell_casts[%d].narrative_description must not be empty", index)
-		}
-		if len(spell.SourceRefs) == 0 {
-			return fmt.Errorf("spell_casts[%d].source_refs must not be empty", index)
-		}
-	}
-	return nil
-}
-
-func SourceRefCandidates(doc *source.SourceDocument, spell SpellCast) []source.SourceRef {
-	refs := make([]source.SourceRef, 0, len(spell.SourceRefs))
-	for _, ref := range spell.SourceRefs {
-		refs = append(refs, shared.SourceRefCandidate(doc, ref))
-	}
-	return refs
-}
-
-func CitedText(doc *source.SourceDocument, ref source.SourceRef) (string, bool) {
-	if doc == nil {
-		return "", false
-	}
-	startIndex, ok := source.UnitIndex(doc, ref.StartUnitID)
-	if !ok {
-		return "", false
-	}
-	endIndex, ok := source.UnitIndex(doc, ref.EndUnitID)
-	if !ok || startIndex > endIndex {
-		return "", false
-	}
-	var b strings.Builder
-	for i := startIndex; i <= endIndex; i++ {
-		if b.Len() > 0 {
-			b.WriteByte('\n')
-		}
-		b.WriteString(doc.Units[i].Text)
-	}
-	return b.String(), true
-}
-
-func ValidationRequestPayload(req contracts.ValidationRequest) (Payload, error) {
-	return Parse(req.Payload.Content)
-}