Move NPC occurrences to their canonical namespace

internal/modules/dnd/codec/npcoccurrences/codec.go

@@ -0,0 +1,127 @@
+// Package npcoccurrences encodes durable D&D NPC occurrence artifacts.
+package npcoccurrences
+
+import (
+	"embed"
+	"fmt"
+	"strings"
+
+	"gitea.maximumdirect.net/eric/notarius/internal/framework/contracts"
+	"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd"
+	"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/codec/candidatejson"
+)
+
+const (
+	SchemaID      = "notarius.dnd.npc_occurrences"
+	SchemaName    = "notarius_dnd_npc_occurrences_v1"
+	SchemaVersion = "v1"
+	MediaType     = "application/json"
+)
+
+//go:embed assets/schemas/dnd_npc_occurrences.v1.json
+var schemaAssets embed.FS
+
+var _ contracts.ArtifactCodec[dnd.NPCOccurrenceList] = (*Codec)(nil)
+
+type Codec struct{}
+
+func New() *Codec { return &Codec{} }
+
+func (c *Codec) Kind() contracts.ArtifactKind { return dnd.NPCOccurrenceListKind }
+
+func (c *Codec) Schema() contracts.ArtifactSchema {
+	raw, err := schemaAssets.ReadFile("assets/schemas/dnd_npc_occurrences.v1.json")
+	if err != nil {
+		return contracts.ArtifactSchema{}
+	}
+	return contracts.ArtifactSchema{
+		ID:         SchemaID,
+		Name:       SchemaName,
+		Version:    SchemaVersion,
+		JSONSchema: append([]byte(nil), raw...),
+	}
+}
+
+func (c *Codec) MediaType() string { return MediaType }
+
+func (c *Codec) Metadata(value dnd.NPCOccurrenceList) map[string]any {
+	return map[string]any{"occurrence_count": len(value.Occurrences)}
+}
+
+func (c *Codec) Encode(value dnd.NPCOccurrenceList) ([]byte, error) {
+	if err := validate(value); err != nil {
+		return nil, fmt.Errorf("encode dnd npc occurrence list: %w", err)
+	}
+	return c.EncodeCandidate(value)
+}
+
+// EncodeCandidate provides the durable representation before semantic
+// validators have approved a value.
+func (c *Codec) EncodeCandidate(value dnd.NPCOccurrenceList) ([]byte, error) {
+	return candidatejson.EncodeCandidate("dnd npc occurrence list", value)
+}
+
+func (c *Codec) Decode(content []byte) (dnd.NPCOccurrenceList, error) {
+	value, err := c.DecodeCandidate(content)
+	if err != nil {
+		return dnd.NPCOccurrenceList{}, err
+	}
+	if err := validate(value); err != nil {
+		return dnd.NPCOccurrenceList{}, fmt.Errorf("decode dnd npc occurrence list: %w", err)
+	}
+	return value, nil
+}
+
+// DecodeCandidate reads one strict durable JSON value before semantic
+// validators have approved it.
+func (c *Codec) DecodeCandidate(content []byte) (dnd.NPCOccurrenceList, error) {
+	return candidatejson.DecodeCandidate[dnd.NPCOccurrenceList]("dnd npc occurrence list", content)
+}
+
+func validate(value dnd.NPCOccurrenceList) error {
+	if value.Occurrences == nil {
+		return fmt.Errorf("occurrences must be present")
+	}
+	for index, occurrence := range value.Occurrences {
+		prefix := fmt.Sprintf("occurrences[%d]", index)
+		if strings.TrimSpace(occurrence.NPCID) == "" {
+			return fmt.Errorf("%s.npc_id must not be empty", prefix)
+		}
+		if strings.TrimSpace(occurrence.Name) == "" {
+			return fmt.Errorf("%s.name must not be empty", prefix)
+		}
+		if !validOccurrenceKind(occurrence.Kind) {
+			return fmt.Errorf("%s.kind must be supported", prefix)
+		}
+		if len(occurrence.SourceRefs) == 0 {
+			return fmt.Errorf("%s.source_refs must contain at least one reference", prefix)
+		}
+		for refIndex, ref := range occurrence.SourceRefs {
+			refPrefix := fmt.Sprintf("%s.source_refs[%d]", prefix, refIndex)
+			if strings.TrimSpace(ref.SourceID) == "" {
+				return fmt.Errorf("%s.source_id must not be empty", refPrefix)
+			}
+			if ref.StartUnitID <= 0 {
+				return fmt.Errorf("%s.start_unit_id must be positive", refPrefix)
+			}
+			if ref.EndUnitID <= 0 {
+				return fmt.Errorf("%s.end_unit_id must be positive", refPrefix)
+			}
+		}
+	}
+	return nil
+}
+
+func validOccurrenceKind(value dnd.NPCOccurrenceKind) bool {
+	switch value {
+	case dnd.NPCOccurrenceKindMentioned,
+		dnd.NPCOccurrenceKindNoncombatPresence,
+		dnd.NPCOccurrenceKindDialogue,
+		dnd.NPCOccurrenceKindCombatAlly,
+		dnd.NPCOccurrenceKindCombatOpponent,
+		dnd.NPCOccurrenceKindOther:
+		return true
+	default:
+		return false
+	}
+}