Implement operation-time D&D NPC artifact handoff

internal/modules/dnd/npcs/registry/registry.go

@@ -8,6 +8,7 @@ import (
 	"fmt"
 	"mime"
 	"strings"
+	"sync"
 
 	"gitea.maximumdirect.net/eric/notarius/internal/core/source"
 	"gitea.maximumdirect.net/eric/notarius/internal/framework/contracts"
@@ -34,6 +35,106 @@ type Registry struct {
 	lookupByKey map[string]int
 }
 
+// Resolver retains only the validated construction-time registry and immutable
+// canonical registries keyed by their semantic digest. Operation references
+// are resolved on demand; caller-owned reference bytes are never retained.
+type Resolver struct {
+	seeded *Registry
+
+	mu       sync.Mutex
+	cache    map[string]*Registry
+	rawCache map[string]*Registry
+}
+
+// NewResolver validates the optional construction-time NPC reference and
+// prepares the operation-time registry cache. A malformed static reference
+// therefore fails before any operation starts.
+func NewResolver(references contracts.ReferenceSet) (*Resolver, error) {
+	seeded, err := Resolve(constructionReferences(references))
+	if err != nil {
+		return nil, err
+	}
+	return &Resolver{seeded: seeded, cache: make(map[string]*Registry), rawCache: make(map[string]*Registry)}, nil
+}
+
+func constructionReferences(references contracts.ReferenceSet) contracts.ReferenceSet {
+	slot, ok := references.Slots[ReferenceSlot]
+	if !ok || len(slot.Items) > 0 {
+		return references
+	}
+	cloned := contracts.ReferenceSet{Slots: make(map[string]contracts.ResolvedReferenceSlot, len(references.Slots))}
+	for name, value := range references.Slots {
+		cloned.Slots[name] = value
+	}
+	delete(cloned.Slots, ReferenceSlot)
+	return cloned
+}
+
+// Seeded returns the immutable construction-time registry. Its accessors are
+// defensive, so callers may safely use the returned view for static metadata.
+func (r *Resolver) Seeded() *Registry {
+	if r == nil {
+		return nil
+	}
+	return r.seeded
+}
+
+// Resolve returns the effective registry for one operation. An operation
+// without an NPC item uses the construction-time registry. A canonical item
+// matching that registry reuses it; other canonical registries are cached by
+// digest for concurrent chunk operations.
+func (r *Resolver) Resolve(references contracts.ReferenceSet) (*Registry, error) {
+	if r == nil {
+		return Resolve(references)
+	}
+	if _, ok := references.Slots[ReferenceSlot]; !ok {
+		return r.seeded, nil
+	}
+
+	slot := references.Slots[ReferenceSlot]
+	rawKey := ""
+	if len(slot.Items) == 1 {
+		rawKey = strings.ToLower(strings.TrimSpace(slot.Items[0].MediaType)) + "\x00" + semanticDigest(slot.Items[0].Content)
+	}
+
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	if rawKey != "" {
+		if cached, ok := r.rawCache[rawKey]; ok {
+			return cached, nil
+		}
+	}
+	resolved, err := Resolve(references)
+	if err != nil {
+		return nil, err
+	}
+	if sameRegistryIdentity(r.seeded, resolved) {
+		if rawKey != "" {
+			r.rawCache[rawKey] = r.seeded
+		}
+		return r.seeded, nil
+	}
+
+	if cached, ok := r.cache[resolved.Digest()]; ok {
+		if rawKey != "" {
+			r.rawCache[rawKey] = cached
+		}
+		return cached, nil
+	}
+	r.cache[resolved.Digest()] = resolved
+	if rawKey != "" {
+		r.rawCache[rawKey] = resolved
+	}
+	return resolved, nil
+}
+
+func sameRegistryIdentity(first, second *Registry) bool {
+	if first == nil || second == nil {
+		return first == second
+	}
+	return first.bound == second.bound && first.digest == second.digest
+}
+
 // Resolve prepares the optional NPC registry reference. An absent slot
 // produces the exact empty prompt input and no semantic registry identity.
 func Resolve(references contracts.ReferenceSet) (*Registry, error) {