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) {

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

@@ -5,6 +5,7 @@ import (
 	"encoding/json"
 	"fmt"
 	"strings"
+	"sync"
 	"testing"
 	"unicode/utf8"
 
@@ -168,6 +169,95 @@ func TestRegistryAccessorsAndLookupAreDefensive(t *testing.T) {
 	}
 }
 
+func TestResolverUsesSeededFallbackAndCachesGeneratedCanonicalRegistry(t *testing.T) {
+	staticContent := encodeRegistry(t, validRegistryList())
+	resolver, err := NewResolver(registryReference(staticContent, "file:///static.json"))
+	if err != nil {
+		t.Fatalf("NewResolver() error = %v", err)
+	}
+	if got, err := resolver.Resolve(contracts.ReferenceSet{}); err != nil || got != resolver.Seeded() {
+		t.Fatalf("Resolve(absent) = %p, %v, want seeded %p", got, err, resolver.Seeded())
+	}
+
+	generated := registryReference(append([]byte("\n"), staticContent...), "file:///generated.json")
+	first, err := resolver.Resolve(generated)
+	if err != nil {
+		t.Fatalf("Resolve(generated) error = %v", err)
+	}
+	second, err := resolver.Resolve(generated)
+	if err != nil {
+		t.Fatalf("Resolve(generated second) error = %v", err)
+	}
+	if first != resolver.Seeded() || second != first {
+		t.Fatalf("resolved registries = %p, %p, seeded %p; want seeded reuse", first, second, resolver.Seeded())
+	}
+
+	changed := validRegistryList()
+	changed.NPCs[0].Description = "A changed generated description."
+	changedContent := encodeRegistry(t, changed)
+	changedReferences := registryReference(changedContent, "file:///changed.json")
+	resolved, err := resolver.Resolve(changedReferences)
+	if err != nil {
+		t.Fatalf("Resolve(changed) error = %v", err)
+	}
+	changedReferences.Slots[ReferenceSlot].Items[0].Content[0] = 'X'
+	if resolved == first || string(resolved.CanonicalBytes()) != string(changedContent) {
+		t.Fatalf("changed registry = %p/%s, want independent canonical cache entry", resolved, resolved.CanonicalBytes())
+	}
+}
+
+func TestResolverSharesOneCachedRegistryAcrossConcurrentOperations(t *testing.T) {
+	content := encodeRegistry(t, validRegistryList())
+	resolver, err := NewResolver(contracts.ReferenceSet{})
+	if err != nil {
+		t.Fatalf("NewResolver() error = %v", err)
+	}
+	references := registryReference(content, "file:///generated.json")
+	const callers = 32
+	results := make(chan *Registry, callers)
+	errors := make(chan error, callers)
+	var wait sync.WaitGroup
+	for index := 0; index < callers; index++ {
+		wait.Add(1)
+		go func() {
+			defer wait.Done()
+			resolved, resolveErr := resolver.Resolve(references)
+			if resolveErr != nil {
+				errors <- resolveErr
+				return
+			}
+			results <- resolved
+		}()
+	}
+	wait.Wait()
+	close(results)
+	close(errors)
+	for err := range errors {
+		t.Fatalf("concurrent Resolve() error = %v", err)
+	}
+	var first *Registry
+	for resolved := range results {
+		if first == nil {
+			first = resolved
+		} else if resolved != first {
+			t.Fatalf("concurrent resolved registry %p differs from cached %p", resolved, first)
+		}
+	}
+}
+
+func TestNewResolverAllowsGeneratedDeclarationButRejectsMalformedStaticItem(t *testing.T) {
+	placeholder := contracts.ReferenceSet{Slots: map[string]contracts.ResolvedReferenceSlot{
+		ReferenceSlot: {Slot: contracts.ReferenceSlot{Name: ReferenceSlot, AcceptedArtifactKinds: []contracts.ArtifactKind{dnd.NPCListKind}}},
+	}}
+	if _, err := NewResolver(placeholder); err != nil {
+		t.Fatalf("NewResolver(generated declaration) error = %v, want nil", err)
+	}
+	malformed := registryReference([]byte(`{"npcs":[`), "file:///runtime.json")
+	if _, err := NewResolver(malformed); err == nil || !strings.Contains(err.Error(), "invalid approved NPC JSON") {
+		t.Fatalf("NewResolver(malformed) error = %v, want bounded decode failure", err)
+	}
+}
+
 func validRegistryList() dnd.NPCList {
 	return dnd.NPCList{NPCs: []dnd.NPC{{
 		ID:          identity.DeriveID("Mira Thorn"),