Add item registry domain foundation

internal/modules/dnd/codec/itemregistry/assets/schemas/dnd_item_registry.v1.json

@@ -0,0 +1,50 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "notarius.dnd.item_registry",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["items"],
+  "properties": {
+    "items": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "name", "source_refs"],
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^item:sha256:[0-9a-f]{64}$"
+          },
+          "name": {
+            "type": "string",
+            "minLength": 1
+          },
+          "source_refs": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "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
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

internal/modules/dnd/codec/itemregistry/codec.go

@@ -0,0 +1,111 @@
+// Package itemregistry encodes durable D&D item-registry artifacts.
+package itemregistry
+
+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"
+	"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/items/identity"
+)
+
+const (
+	SchemaID      = "notarius.dnd.item_registry"
+	SchemaName    = "notarius_dnd_item_registry_v1"
+	SchemaVersion = "v1"
+	MediaType     = "application/json"
+)
+
+//go:embed assets/schemas/dnd_item_registry.v1.json
+var schemaAssets embed.FS
+
+var _ contracts.ArtifactCodec[dnd.ItemRegistry] = (*Codec)(nil)
+
+type Codec struct{}
+
+func New() *Codec { return &Codec{} }
+
+func (c *Codec) Kind() contracts.ArtifactKind { return dnd.ItemRegistryKind }
+
+func (c *Codec) Schema() contracts.ArtifactSchema {
+	raw, err := schemaAssets.ReadFile("assets/schemas/dnd_item_registry.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.ItemRegistry) map[string]any {
+	return map[string]any{"item_count": len(value.Items)}
+}
+
+func (c *Codec) Encode(value dnd.ItemRegistry) ([]byte, error) {
+	if err := validate(value); err != nil {
+		return nil, fmt.Errorf("encode dnd item registry: %w", err)
+	}
+	return c.EncodeCandidate(value)
+}
+
+// EncodeCandidate provides the durable representation before semantic
+// validators have approved a value.
+func (c *Codec) EncodeCandidate(value dnd.ItemRegistry) ([]byte, error) {
+	return candidatejson.EncodeCandidate("dnd item registry", value)
+}
+
+func (c *Codec) Decode(content []byte) (dnd.ItemRegistry, error) {
+	value, err := c.DecodeCandidate(content)
+	if err != nil {
+		return dnd.ItemRegistry{}, err
+	}
+	if err := validate(value); err != nil {
+		return dnd.ItemRegistry{}, fmt.Errorf("decode dnd item registry: %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.ItemRegistry, error) {
+	return candidatejson.DecodeCandidate[dnd.ItemRegistry]("dnd item registry", content)
+}
+
+func validate(value dnd.ItemRegistry) error {
+	if value.Items == nil {
+		return fmt.Errorf("items must be present")
+	}
+	for index, item := range value.Items {
+		prefix := fmt.Sprintf("items[%d]", index)
+		if !identity.IsValidID(item.ID) {
+			return fmt.Errorf("%s.id must match item ID pattern", prefix)
+		}
+		if strings.TrimSpace(item.Name) == "" {
+			return fmt.Errorf("%s.name must not be empty", prefix)
+		}
+		if len(item.SourceRefs) == 0 {
+			return fmt.Errorf("%s.source_refs must not be empty", prefix)
+		}
+		for refIndex, ref := range item.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
+}

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

@@ -0,0 +1,97 @@
+package itemregistry
+
+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/modules/dnd"
+	"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/items/identity"
+)
+
+func validRegistry() dnd.ItemRegistry {
+	return dnd.ItemRegistry{Items: []dnd.Item{{
+		ID:         identity.DeriveID("Silver Key"),
+		Name:       "Silver Key",
+		SourceRefs: []source.SourceRef{{SourceID: "session-alpha", StartUnitID: 1, EndUnitID: 2}},
+	}}}
+}
+
+func TestCodecMatchesMaintainedDurableFixture(t *testing.T) {
+	raw, err := os.ReadFile("testdata/dnd_item_registry.v1.json")
+	if err != nil {
+		t.Fatalf("read durable fixture: %v", err)
+	}
+	codec := New()
+	value, err := codec.Decode(raw)
+	if err != nil {
+		t.Fatalf("Decode() error = %v", err)
+	}
+	if want := validRegistry(); !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 TestCodecOwnsDurableSchemaAndExactType(t *testing.T) {
+	codec := New()
+	schema := codec.Schema()
+	if codec.Kind() != dnd.ItemRegistryKind || codec.MediaType() != MediaType || schema.ID != SchemaID || schema.Name != SchemaName || schema.Version != SchemaVersion || !json.Valid(schema.JSONSchema) {
+		t.Fatalf("codec contract = %#v / %#v", codec, schema)
+	}
+}
+
+func TestCodecCandidateEncodingMetadataAndStrictDecode(t *testing.T) {
+	codec := New()
+	candidate := dnd.ItemRegistry{Items: []dnd.Item{{Name: "Silver Key"}}}
+	if content, err := codec.EncodeCandidate(candidate); err != nil || string(content) != `{"items":[{"id":"","name":"Silver Key","source_refs":null}]}` {
+		t.Fatalf("EncodeCandidate() = %s, %v", content, err)
+	}
+	if _, err := codec.Encode(candidate); err == nil || !strings.Contains(err.Error(), "item ID pattern") {
+		t.Fatalf("Encode() error = %v, want durable validation", err)
+	}
+	metadata := codec.Metadata(validRegistry())
+	if metadata["item_count"] != 1 {
+		t.Fatalf("Metadata() = %#v", metadata)
+	}
+	for _, content := range []string{
+		`{"items":[],"unexpected":true}`,
+		`{"items":[{"id":"` + identity.DeriveID("Silver Key") + `","name":"Silver Key","source_refs":[{"source_id":"s","start_unit_id":1,"end_unit_id":1,"unexpected":true}]}]}`,
+		`{"items":[]} {}`,
+	} {
+		if _, err := codec.Decode([]byte(content)); err == nil {
+			t.Fatalf("Decode(%s) error = nil", content)
+		}
+	}
+}
+
+func TestCodecSchemaAndMetadataAreDefensive(t *testing.T) {
+	codec := New()
+	first := codec.Schema()
+	first.JSONSchema[0] = '['
+	if next := codec.Schema(); !json.Valid(next.JSONSchema) || next.JSONSchema[0] == '[' {
+		t.Fatal("Schema() returned shared bytes")
+	}
+	metadata := codec.Metadata(validRegistry())
+	metadata["other"] = true
+	if next := codec.Metadata(validRegistry()); len(next) != 1 || next["item_count"] != 1 {
+		t.Fatalf("Metadata() = %#v", next)
+	}
+}
+
+var _ contracts.ArtifactCodec[dnd.ItemRegistry] = (*Codec)(nil)

internal/modules/dnd/codec/itemregistry/testdata/dnd_item_registry.v1.json

@@ -0,0 +1,11 @@
+{
+  "items": [
+    {
+      "id": "item:sha256:2f211c60b9bdcf3a6dd64086cc4c05df5b3357ae02cb462f7ef8988d9bd2fa4f",
+      "name": "Silver Key",
+      "source_refs": [
+        {"source_id": "session-alpha", "start_unit_id": 1, "end_unit_id": 2}
+      ]
+    }
+  ]
+}