Add D&D scene description codec

internal/modules/dnd/codec/scenedescriptions/assets/schemas/dnd_scene_descriptions.v1.json

@@ -0,0 +1,54 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "notarius.dnd.scene_descriptions",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["scenes"],
+  "properties": {
+    "scenes": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "source_ref", "kind", "title", "summary"],
+        "properties": {
+          "id": {
+            "type": "string",
+            "minLength": 1
+          },
+          "source_ref": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["source_id", "start_unit_id", "end_unit_id"],
+            "properties": {
+              "source_id": {
+                "type": "string",
+                "minLength": 1
+              },
+              "start_unit_id": {
+                "type": "integer",
+                "minimum": 1
+              },
+              "end_unit_id": {
+                "type": "integer",
+                "minimum": 1
+              }
+            }
+          },
+          "kind": {
+            "type": "string",
+            "enum": ["combat", "narrative", "recap", "meta"]
+          },
+          "title": {
+            "type": "string",
+            "minLength": 1
+          },
+          "summary": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      }
+    }
+  }
+}

internal/modules/dnd/codec/scenedescriptions/codec.go

@@ -0,0 +1,134 @@
+package scenedescriptions
+
+import (
+	"bytes"
+	"embed"
+	"encoding/json"
+	"fmt"
+	"io"
+	"strings"
+
+	"gitea.maximumdirect.net/eric/notarius/internal/framework/contracts"
+	"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd"
+)
+
+const (
+	SchemaID      = "notarius.dnd.scene_descriptions"
+	SchemaName    = "notarius_dnd_scene_descriptions_v1"
+	SchemaVersion = "v1"
+	MediaType     = "application/json"
+)
+
+//go:embed assets/schemas/dnd_scene_descriptions.v1.json
+var schemaAssets embed.FS
+
+var _ contracts.ArtifactCodec[dnd.SceneDescriptionList] = (*Codec)(nil)
+
+type Codec struct{}
+
+func New() *Codec { return &Codec{} }
+
+func (c *Codec) Kind() contracts.ArtifactKind { return dnd.SceneDescriptionListKind }
+
+func (c *Codec) Schema() contracts.ArtifactSchema {
+	raw, err := schemaAssets.ReadFile("assets/schemas/dnd_scene_descriptions.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.SceneDescriptionList) map[string]any {
+	return map[string]any{"scene_count": len(value.Scenes)}
+}
+
+func (c *Codec) Encode(value dnd.SceneDescriptionList) ([]byte, error) {
+	if err := validate(value); err != nil {
+		return nil, fmt.Errorf("encode dnd scene description list: %w", err)
+	}
+	return c.EncodeCandidate(value)
+}
+
+// EncodeCandidate provides the durable representation before typed validators
+// have approved a value.
+func (c *Codec) EncodeCandidate(value dnd.SceneDescriptionList) ([]byte, error) {
+	content, err := json.Marshal(value)
+	if err != nil {
+		return nil, fmt.Errorf("encode dnd scene description list: %w", err)
+	}
+	return content, nil
+}
+
+func (c *Codec) Decode(content []byte) (dnd.SceneDescriptionList, error) {
+	value, err := c.DecodeCandidate(content)
+	if err != nil {
+		return dnd.SceneDescriptionList{}, err
+	}
+	if err := validate(value); err != nil {
+		return dnd.SceneDescriptionList{}, fmt.Errorf("decode dnd scene description list: %w", err)
+	}
+	return value, nil
+}
+
+// DecodeCandidate reads one strict durable JSON value before typed validators
+// have approved it.
+func (c *Codec) DecodeCandidate(content []byte) (dnd.SceneDescriptionList, error) {
+	decoder := json.NewDecoder(bytes.NewReader(content))
+	decoder.DisallowUnknownFields()
+	var value dnd.SceneDescriptionList
+	if err := decoder.Decode(&value); err != nil {
+		return dnd.SceneDescriptionList{}, fmt.Errorf("decode dnd scene description list: %w", err)
+	}
+	var trailing any
+	if err := decoder.Decode(&trailing); err != io.EOF {
+		return dnd.SceneDescriptionList{}, fmt.Errorf("decode dnd scene description list: multiple JSON values")
+	}
+	return value, nil
+}
+
+func validate(value dnd.SceneDescriptionList) error {
+	if value.Scenes == nil {
+		return fmt.Errorf("scenes must be present")
+	}
+	for index, scene := range value.Scenes {
+		prefix := fmt.Sprintf("scenes[%d]", index)
+		if strings.TrimSpace(scene.ID) == "" {
+			return fmt.Errorf("%s.id must not be empty", prefix)
+		}
+		if !validSceneKind(scene.Kind) {
+			return fmt.Errorf("%s.kind must be supported", prefix)
+		}
+		if strings.TrimSpace(scene.Title) == "" {
+			return fmt.Errorf("%s.title must not be empty", prefix)
+		}
+		if strings.TrimSpace(scene.Summary) == "" {
+			return fmt.Errorf("%s.summary must not be empty", prefix)
+		}
+		if strings.TrimSpace(scene.SourceRef.SourceID) == "" {
+			return fmt.Errorf("%s.source_ref.source_id must not be empty", prefix)
+		}
+		if scene.SourceRef.StartUnitID <= 0 {
+			return fmt.Errorf("%s.source_ref.start_unit_id must be positive", prefix)
+		}
+		if scene.SourceRef.EndUnitID <= 0 {
+			return fmt.Errorf("%s.source_ref.end_unit_id must be positive", prefix)
+		}
+	}
+	return nil
+}
+
+func validSceneKind(value dnd.SceneKind) bool {
+	switch value {
+	case dnd.SceneKindCombat, dnd.SceneKindNarrative, dnd.SceneKindRecap, dnd.SceneKindMeta:
+		return true
+	default:
+		return false
+	}
+}

internal/modules/dnd/codec/scenedescriptions/codec_test.go

@@ -0,0 +1,161 @@
+package scenedescriptions
+
+import (
+	"bytes"
+	"encoding/json"
+	"os"
+	"reflect"
+	"strings"
+	"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 validList() dnd.SceneDescriptionList {
+	return dnd.SceneDescriptionList{Scenes: []dnd.SceneDescription{{
+		ID:        "chunk-000001",
+		SourceRef: source.SourceRef{SourceID: "session-alpha", StartUnitID: 1, EndUnitID: 2},
+		Kind:      dnd.SceneKindNarrative,
+		Title:     "At the city gate",
+		Summary:   "The party enters the city after speaking with its guard.",
+	}}}
+}
+
+func TestCodecMatchesMaintainedDurableFixture(t *testing.T) {
+	raw, err := os.ReadFile("testdata/dnd_scene_descriptions.v1.json")
+	if err != nil {
+		t.Fatal(err)
+	}
+	codec := New()
+	value, err := codec.Decode(raw)
+	if err != nil {
+		t.Fatalf("Decode() error = %v", err)
+	}
+	if want := validList(); !reflect.DeepEqual(value, want) {
+		t.Fatalf("Decode() = %#v, want %#v", value, want)
+	}
+	encoded, err := codec.Encode(value)
+	if err != nil {
+		t.Fatalf("Encode() error = %v", err)
+	}
+	var compact bytes.Buffer
+	if err := json.Compact(&compact, raw); err != nil {
+		t.Fatal(err)
+	}
+	if !bytes.Equal(encoded, compact.Bytes()) {
+		t.Fatalf("Encode() = %s, want %s", encoded, compact.Bytes())
+	}
+}
+
+func TestCodecOwnsDurableSchemaAndMetadata(t *testing.T) {
+	codec := New()
+	schema := codec.Schema()
+	if codec.Kind() != dnd.SceneDescriptionListKind || codec.MediaType() != MediaType {
+		t.Fatalf("codec identity = %q/%q", codec.Kind(), codec.MediaType())
+	}
+	if schema.ID != SchemaID || schema.Name != SchemaName || schema.Version != SchemaVersion || !json.Valid(schema.JSONSchema) {
+		t.Fatalf("schema = %#v", schema)
+	}
+	registry := pipeline.NewArtifactCodecRegistry()
+	if err := pipeline.RegisterArtifactCodec(registry, codec); err != nil {
+		t.Fatal(err)
+	}
+	spec, ok := registry.Spec(dnd.SceneDescriptionListKind)
+	if !ok || spec.SchemaDigest != contracts.DigestArtifactSchema(schema) {
+		t.Fatalf("registered spec = %#v, %t", spec, ok)
+	}
+	schema.JSONSchema[0] = '['
+	if next := codec.Schema(); !json.Valid(next.JSONSchema) || next.JSONSchema[0] == '[' {
+		t.Fatal("Schema() returned shared bytes")
+	}
+	metadata := codec.Metadata(validList())
+	metadata["other"] = true
+	if next := codec.Metadata(validList()); len(next) != 1 || next["scene_count"] != 1 {
+		t.Fatalf("Metadata() = %#v", next)
+	}
+	encoded, err := codec.Encode(validList())
+	if err != nil {
+		t.Fatal(err)
+	}
+	encoded[0] = '['
+	if next, err := codec.Encode(validList()); err != nil || !json.Valid(next) || next[0] == '[' {
+		t.Fatalf("Encode() returned shared bytes: %s, %v", next, err)
+	}
+}
+
+func TestCodecStrictlyRejectsInvalidDurableBoundaries(t *testing.T) {
+	validJSON := `{"scenes":[{"id":"chunk-000001","source_ref":{"source_id":"session","start_unit_id":1,"end_unit_id":1},"kind":"narrative","title":"Arrival","summary":"The party arrives."}]}`
+	tests := []struct{ name, raw, want string }{
+		{"malformed", `{`, "decode dnd scene description list"},
+		{"unknown top-level", `{"scenes":[],"unexpected":true}`, "unknown field"},
+		{"unknown scene field", strings.Replace(validJSON, `"kind":"narrative"`, `"kind":"narrative","unexpected":true`, 1), "unknown field"},
+		{"unknown source field", strings.Replace(validJSON, `"end_unit_id":1`, `"end_unit_id":1,"unexpected":true`, 1), "unknown field"},
+		{"trailing", `{"scenes":[]} {}`, "multiple JSON values"},
+		{"missing scenes", `{}`, "scenes must be present"},
+		{"invalid kind", strings.Replace(validJSON, `"kind":"narrative"`, `"kind":"other"`, 1), "kind must be supported"},
+		{"blank title", strings.Replace(validJSON, `"title":"Arrival"`, `"title":" "`, 1), "title must not be empty"},
+		{"blank summary", strings.Replace(validJSON, `"summary":"The party arrives."`, `"summary":" "`, 1), "summary must not be empty"},
+		{"blank ID", strings.Replace(validJSON, `"id":"chunk-000001"`, `"id":" "`, 1), "id must not be empty"},
+		{"blank source ID", strings.Replace(validJSON, `"source_id":"session"`, `"source_id":" "`, 1), "source_id must not be empty"},
+		{"invalid source start", strings.Replace(validJSON, `"start_unit_id":1`, `"start_unit_id":0`, 1), "start_unit_id must be positive"},
+		{"invalid source end", strings.Replace(validJSON, `"end_unit_id":1`, `"end_unit_id":0`, 1), "end_unit_id must be positive"},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			if _, err := New().Decode([]byte(test.raw)); err == nil || !strings.Contains(err.Error(), test.want) {
+				t.Fatalf("Decode() error = %v, want %q", err, test.want)
+			}
+		})
+	}
+}
+
+func TestCodecCandidatePreservesValidatorOwnedValues(t *testing.T) {
+	candidates := []dnd.SceneDescriptionList{
+		{},
+		{Scenes: []dnd.SceneDescription{}},
+		{Scenes: []dnd.SceneDescription{{ID: " ", Kind: "unsupported", Title: " ", Summary: " ", SourceRef: source.SourceRef{}}}},
+		{Scenes: []dnd.SceneDescription{{ID: " ", Kind: "unsupported", Title: " ", Summary: " ", SourceRef: source.SourceRef{StartUnitID: 0, EndUnitID: -1}}}},
+	}
+	for _, candidate := range candidates {
+		content, err := New().EncodeCandidate(candidate)
+		if err != nil || !json.Valid(content) {
+			t.Fatalf("EncodeCandidate() = %s, %v", content, err)
+		}
+		decoded, err := New().DecodeCandidate(content)
+		if err != nil || !reflect.DeepEqual(decoded, candidate) {
+			t.Fatalf("DecodeCandidate() = %#v, %v; want %#v", decoded, err, candidate)
+		}
+	}
+}
+
+func TestCodecRejectsRequiredApprovedValues(t *testing.T) {
+	tests := []struct {
+		name  string
+		value dnd.SceneDescriptionList
+		want  string
+	}{
+		{"nil scenes", dnd.SceneDescriptionList{}, "scenes must be present"},
+		{"empty ID", mutate(validList(), func(value *dnd.SceneDescriptionList) { value.Scenes[0].ID = " " }), "id must not be empty"},
+		{"unsupported kind", mutate(validList(), func(value *dnd.SceneDescriptionList) { value.Scenes[0].Kind = "unsupported" }), "kind must be supported"},
+		{"empty title", mutate(validList(), func(value *dnd.SceneDescriptionList) { value.Scenes[0].Title = " " }), "title must not be empty"},
+		{"empty summary", mutate(validList(), func(value *dnd.SceneDescriptionList) { value.Scenes[0].Summary = " " }), "summary must not be empty"},
+		{"empty source ID", mutate(validList(), func(value *dnd.SceneDescriptionList) { value.Scenes[0].SourceRef.SourceID = " " }), "source_id must not be empty"},
+		{"non-positive start", mutate(validList(), func(value *dnd.SceneDescriptionList) { value.Scenes[0].SourceRef.StartUnitID = 0 }), "start_unit_id must be positive"},
+		{"non-positive end", mutate(validList(), func(value *dnd.SceneDescriptionList) { value.Scenes[0].SourceRef.EndUnitID = 0 }), "end_unit_id must be positive"},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			if _, err := New().Encode(test.value); err == nil || !strings.Contains(err.Error(), test.want) {
+				t.Fatalf("Encode() error = %v, want %q", err, test.want)
+			}
+		})
+	}
+}
+
+func mutate(value dnd.SceneDescriptionList, change func(*dnd.SceneDescriptionList)) dnd.SceneDescriptionList {
+	change(&value)
+	return value
+}

internal/modules/dnd/codec/scenedescriptions/testdata/dnd_scene_descriptions.v1.json

@@ -0,0 +1 @@
+{"scenes":[{"id":"chunk-000001","source_ref":{"source_id":"session-alpha","start_unit_id":1,"end_unit_id":2},"kind":"narrative","title":"At the city gate","summary":"The party enters the city after speaking with its guard."}]}

internal/modules/dnd/types.go

@@ -14,6 +14,8 @@ const CombatTurnListKind contracts.ArtifactKind = "dnd/combat-turn-list"
 
 const NPCInteractionListKind contracts.ArtifactKind = "dnd/npc-interaction-list"
 
+const SceneDescriptionListKind contracts.ArtifactKind = "dnd/scene-description-list"
+
 type SpellList struct {
 	SpellCasts []SpellCast `json:"spell_casts"`
 }
@@ -74,3 +76,24 @@ type NPCInteraction struct {
 	Kind       NPCInteractionKind `json:"kind"`
 	SourceRefs []source.SourceRef `json:"source_refs"`
 }
+
+type SceneKind string
+
+const (
+	SceneKindCombat    SceneKind = "combat"
+	SceneKindNarrative SceneKind = "narrative"
+	SceneKindRecap     SceneKind = "recap"
+	SceneKindMeta      SceneKind = "meta"
+)
+
+type SceneDescriptionList struct {
+	Scenes []SceneDescription `json:"scenes"`
+}
+
+type SceneDescription struct {
+	ID        string           `json:"id"`
+	SourceRef source.SourceRef `json:"source_ref"`
+	Kind      SceneKind        `json:"kind"`
+	Title     string           `json:"title"`
+	Summary   string           `json:"summary"`
+}