Add immutable D&D location registry

This commit is contained in:
2026-08-04 00:11:31 +00:00
parent 98506db1a9
commit 7715baa1f6
2 changed files with 527 additions and 0 deletions

View File

@@ -0,0 +1,329 @@
// Package registry resolves normalized location artifacts into immutable
// ID-grounding data for D&D extraction modules.
package registry
import (
"crypto/sha256"
"encoding/hex"
"encoding/json"
"fmt"
"mime"
"strings"
"sync"
"gitea.maximumdirect.net/eric/notarius/internal/core/source"
"gitea.maximumdirect.net/eric/notarius/internal/framework/contracts"
"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd"
locationcodec "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/codec/locations"
"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/locations/identity"
"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/shared/diagnostics"
)
const (
ReferenceSlot = "locations"
MaxBytes = 1048576
emptyPrompt = `{"locations":[]}`
)
// Registry is an immutable, validated location registry prepared for prompt
// grounding. All accessors return defensive copies.
type Registry struct {
bound bool
list dnd.LocationList
canonical []byte
digest string
projectionDigest string
promptInput contracts.LLMInputMaterial
lookupByID map[string]int
}
// Resolver retains the construction-time registry and memoizes immutable
// operation-time registries. It never retains caller-owned reference bytes.
type Resolver struct {
seeded *Registry
mu sync.Mutex
cache map[string]*Registry
rawCache map[string]*Registry
}
// NewResolver validates a materialized construction-time location reference.
// An empty slot is permitted because a generated reference is supplied only at
// operation time.
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 validated construction-time registry.
func (r *Resolver) Seeded() *Registry {
if r == nil {
return nil
}
return r.seeded
}
// Resolve returns the generated operation-time registry when the locations
// slot is present, otherwise it returns the construction-time registry.
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 validates an optional location-list reference. An absent reference
// uses the canonical empty projection and has no durable registry identity.
func Resolve(references contracts.ReferenceSet) (*Registry, error) {
slot, ok := references.Slots[ReferenceSlot]
if !ok {
content := []byte(emptyPrompt)
projectionDigest := semanticDigest(content)
return &Registry{
list: dnd.LocationList{Locations: []dnd.Location{}},
canonical: append([]byte(nil), content...),
projectionDigest: projectionDigest,
promptInput: contracts.NewLLMInputMaterial(ReferenceSlot, locationcodec.MediaType, content, projectionDigest, ""),
lookupByID: map[string]int{},
}, nil
}
if len(slot.Items) != 1 {
return nil, fmt.Errorf("reference slot %q must contain exactly one item", ReferenceSlot)
}
item := slot.Items[0]
mediaType, _, err := mime.ParseMediaType(item.MediaType)
if err != nil {
return nil, fmt.Errorf("reference slot %q item media type is invalid", ReferenceSlot)
}
if !strings.EqualFold(mediaType, locationcodec.MediaType) {
return nil, fmt.Errorf("reference slot %q item media type must be %s", ReferenceSlot, locationcodec.MediaType)
}
if len(item.Content) > MaxBytes {
return nil, fmt.Errorf("reference slot %q item is %d bytes, limit %d", ReferenceSlot, len(item.Content), MaxBytes)
}
codec := locationcodec.New()
value, err := codec.Decode(item.Content)
if err != nil {
return nil, fmt.Errorf("decode location registry: invalid approved location JSON")
}
if issues := identity.ValidateList(value); len(issues) > 0 {
return nil, fmt.Errorf("%s", formatIdentityIssues(issues))
}
content, err := codec.Encode(value)
if err != nil {
return nil, fmt.Errorf("encode canonical location registry: approved location value could not be encoded")
}
list := cloneLocationList(value)
lookupByID := make(map[string]int, len(list.Locations))
for index, location := range list.Locations {
lookupByID[location.ID] = index
}
projection, err := promptProjection(list)
if err != nil {
return nil, fmt.Errorf("encode location prompt projection: %w", err)
}
digest := semanticDigest(content)
projectionDigest := semanticDigest(projection)
return &Registry{
bound: true,
list: list,
canonical: append([]byte(nil), content...),
digest: digest,
projectionDigest: projectionDigest,
promptInput: contracts.NewLLMInputMaterial(ReferenceSlot, locationcodec.MediaType, projection, projectionDigest, ""),
lookupByID: lookupByID,
}, nil
}
// Bound reports whether a location reference was supplied and validated.
func (r *Registry) Bound() bool { return r != nil && r.bound }
// Locations returns a defensive copy of the validated location records.
func (r *Registry) Locations() []dnd.Location {
if r == nil {
return nil
}
return cloneLocations(r.list.Locations)
}
// List returns a defensive copy of the validated location list.
func (r *Registry) List() dnd.LocationList {
if r == nil {
return dnd.LocationList{}
}
return cloneLocationList(r.list)
}
// CanonicalBytes returns a defensive copy of the canonical durable JSON.
func (r *Registry) CanonicalBytes() []byte {
if r == nil {
return nil
}
return append([]byte(nil), r.canonical...)
}
// Digest returns the semantic digest of the canonical JSON, or an empty string
// when the registry is unbound.
func (r *Registry) Digest() string {
if r == nil {
return ""
}
return r.digest
}
// ProjectionDigest returns the digest of the exact source-free prompt
// projection, including for an unbound or empty registry.
func (r *Registry) ProjectionDigest() string {
if r == nil {
return ""
}
return r.projectionDigest
}
// Count returns the number of validated location records.
func (r *Registry) Count() int {
if r == nil {
return 0
}
return len(r.list.Locations)
}
// PromptInput returns the ordered ID-and-name projection without evidence or
// reference provenance.
func (r *Registry) PromptInput() contracts.LLMInputMaterial {
if r == nil {
return contracts.LLMInputMaterial{}
}
return r.promptInput.Clone()
}
// Lookup returns the canonical location for an exact durable location ID.
func (r *Registry) Lookup(id string) (dnd.Location, bool) {
if r == nil {
return dnd.Location{}, false
}
index, ok := r.lookupByID[id]
if !ok {
return dnd.Location{}, false
}
return cloneLocation(r.list.Locations[index]), true
}
// Matches reports whether id resolves to exactly the supplied canonical name.
func (r *Registry) Matches(id, name string) bool {
location, ok := r.Lookup(id)
return ok && location.Name == name
}
func semanticDigest(content []byte) string {
sum := sha256.Sum256(content)
return "sha256:" + hex.EncodeToString(sum[:])
}
type projectedLocation struct {
ID string `json:"id"`
Name string `json:"name"`
}
type projectedLocationList struct {
Locations []projectedLocation `json:"locations"`
}
func promptProjection(list dnd.LocationList) ([]byte, error) {
projection := projectedLocationList{Locations: make([]projectedLocation, len(list.Locations))}
for index, location := range list.Locations {
projection.Locations[index] = projectedLocation{ID: location.ID, Name: location.Name}
}
return json.Marshal(projection)
}
func formatIdentityIssues(issues []identity.Issue) string {
parts := make([]string, len(issues))
for index, issue := range issues {
parts[index] = fmt.Sprintf("%s at record %d", issue.Code, issue.RecordIndex)
}
return diagnostics.Aggregate("validate location registry identity", parts)
}
func cloneLocationList(value dnd.LocationList) dnd.LocationList {
return dnd.LocationList{Locations: cloneLocations(value.Locations)}
}
func cloneLocations(values []dnd.Location) []dnd.Location {
if values == nil {
return nil
}
cloned := make([]dnd.Location, len(values))
for index, value := range values {
cloned[index] = cloneLocation(value)
}
return cloned
}
func cloneLocation(value dnd.Location) dnd.Location {
value.SourceRefs = append([]source.SourceRef(nil), value.SourceRefs...)
return value
}

View File

@@ -0,0 +1,198 @@
package registry
import (
"bytes"
"fmt"
"strings"
"sync"
"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"
locationcodec "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/codec/locations"
"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/locations/identity"
)
func TestResolveUnboundRegistryHasEmptyProjection(t *testing.T) {
registry, err := Resolve(contracts.ReferenceSet{})
if err != nil {
t.Fatal(err)
}
input := registry.PromptInput()
if registry.Bound() || registry.Digest() != "" || registry.Count() != 0 || string(input.Content) != emptyPrompt {
t.Fatalf("unbound registry = %#v, input = %#v", registry, input)
}
if registry.ProjectionDigest() == "" || input.Digest != registry.ProjectionDigest() || input.OriginURI != "" {
t.Fatalf("projection digest/input = %q/%#v", registry.ProjectionDigest(), input)
}
}
func TestResolveProjectsOrderedLocationsWithoutEvidence(t *testing.T) {
registry := resolveList(t, registryFixture())
if !registry.Bound() || registry.Count() != 2 || registry.Digest() == "" {
t.Fatalf("registry identity = bound %t count %d digest %q", registry.Bound(), registry.Count(), registry.Digest())
}
projection := string(registry.PromptInput().Content)
if !strings.Contains(projection, `"locations":[{"id":`) || !strings.Contains(projection, `"name":"The Tavern"`) || !strings.Contains(projection, `"name":"The Tavern"},{"id":`) {
t.Fatalf("projection ordering = %s", projection)
}
for _, forbidden := range []string{"source_refs", "source_id", "session-alpha"} {
if strings.Contains(projection, forbidden) {
t.Fatalf("projection leaked %q: %s", forbidden, projection)
}
}
if registry.PromptInput().Digest != registry.ProjectionDigest() || registry.Digest() == registry.ProjectionDigest() {
t.Fatalf("full/projection digests = %q/%q", registry.Digest(), registry.ProjectionDigest())
}
}
func TestRegistryLookupUsesIDAndReturnsDefensiveCopies(t *testing.T) {
registry := resolveList(t, registryFixture())
first := registry.Locations()[0]
if got, ok := registry.Lookup(first.ID); !ok || got.Name != first.Name || !registry.Matches(first.ID, first.Name) || registry.Matches(first.ID, "Other Tavern") {
t.Fatalf("ID lookup/match = %#v, %t", got, ok)
}
if _, ok := registry.Lookup("The Tavern"); ok {
t.Fatal("Lookup accepted a name as an ID")
}
locations := registry.Locations()
locations[0].Name = "changed"
locations[0].SourceRefs[0].SourceID = "changed"
canonical := registry.CanonicalBytes()
canonical[0] = '['
input := registry.PromptInput()
input.Content[0] = '['
if next, ok := registry.Lookup(first.ID); !ok || next.Name != first.Name || next.SourceRefs[0].SourceID != "session-alpha" {
t.Fatalf("registry mutated through accessor: %#v, %t", next, ok)
}
if registry.CanonicalBytes()[0] != '{' || registry.PromptInput().Content[0] != '{' {
t.Fatal("registry bytes mutated through accessor")
}
}
func TestResolveRejectsInvalidReferenceInputs(t *testing.T) {
valid := registryFixture()
content, err := locationcodec.New().Encode(valid)
if err != nil {
t.Fatal(err)
}
invalidIdentity := append([]byte(nil), content...)
invalidIdentity = bytes.Replace(invalidIdentity, []byte(valid.Locations[0].ID), []byte("location:sha256:0000000000000000000000000000000000000000000000000000000000000000"), 1)
for _, test := range []struct {
name string
set contracts.ReferenceSet
want string
}{
{"empty bound slot", referenceSet(), "exactly one item"},
{"multiple items", referenceSet(item(content), item(content)), "exactly one item"},
{"malformed JSON", referenceSet(item([]byte(`{"locations":[`))), "invalid approved"},
{"wrong media type", referenceSet(contracts.ReferenceItem{MediaType: "text/plain", Content: content}), "media type must be"},
{"oversized", referenceSet(item(make([]byte, MaxBytes+1))), "limit"},
{"invalid identity", referenceSet(item(invalidIdentity)), "id_mismatch"},
} {
t.Run(test.name, func(t *testing.T) {
if _, err := Resolve(test.set); err == nil || !strings.Contains(err.Error(), test.want) {
t.Fatalf("Resolve() error = %v, want %q", err, test.want)
}
})
}
}
func TestNewResolverValidatesStaticReferenceBeforeOperations(t *testing.T) {
if _, err := NewResolver(referenceSet(item([]byte(`{"locations":[`)))); err == nil || !strings.Contains(err.Error(), "invalid approved") {
t.Fatalf("NewResolver() error = %v, want malformed static reference failure", err)
}
resolver, err := NewResolver(referenceSet(item(encodeList(t, registryFixture()))))
if err != nil || !resolver.Seeded().Bound() || resolver.Seeded().Count() != 2 {
t.Fatalf("NewResolver() = %#v, %v", resolver, err)
}
}
func TestResolverCachesRawAndSemanticallyEquivalentRegistriesConcurrently(t *testing.T) {
resolver, err := NewResolver(contracts.ReferenceSet{})
if err != nil {
t.Fatal(err)
}
content, err := locationcodec.New().Encode(registryFixture())
if err != nil {
t.Fatal(err)
}
firstSet := referenceSet(item(content))
first, err := resolver.Resolve(firstSet)
if err != nil {
t.Fatal(err)
}
second, err := resolver.Resolve(firstSet)
if err != nil || first != second {
t.Fatalf("raw cache Resolve() = %p, %p, %v", first, second, err)
}
spaced := append([]byte("\n "), content...)
spaced = append(spaced, '\n')
third, err := resolver.Resolve(referenceSet(item(spaced)))
if err != nil || third != first {
t.Fatalf("semantic cache Resolve() = %p, %p, %v", first, third, err)
}
var group sync.WaitGroup
errs := make(chan error, 24)
for range 24 {
group.Add(1)
go func() {
defer group.Done()
resolved, err := resolver.Resolve(firstSet)
if err != nil || resolved != first {
errs <- fmt.Errorf("resolved %p, want %p: %w", resolved, first, err)
}
}()
}
group.Wait()
close(errs)
for err := range errs {
t.Error(err)
}
firstSet.Slots[ReferenceSlot].Items[0].Content[0] = '['
if registry, err := resolver.Resolve(contracts.ReferenceSet{}); err != nil || registry != resolver.Seeded() || registry.Count() != 0 {
t.Fatalf("caller bytes affected resolver: %#v, %v", registry, err)
}
if got, ok := first.Lookup(registryFixture().Locations[0].ID); !ok || got.Name != "The Tavern" {
t.Fatalf("cached registry retained caller bytes: %#v, %t", got, ok)
}
}
func registryFixture() dnd.LocationList {
firstRefs := []source.SourceRef{{SourceID: "session-alpha", StartUnitID: 1, EndUnitID: 1}}
secondRefs := []source.SourceRef{{SourceID: "session-alpha", StartUnitID: 2, EndUnitID: 2}}
return dnd.LocationList{Locations: []dnd.Location{
{ID: identity.DeriveID("The Tavern", firstRefs), Name: "The Tavern", SourceRefs: firstRefs},
{ID: identity.DeriveID("The Tavern", secondRefs), Name: "The Tavern", SourceRefs: secondRefs},
}}
}
func resolveList(t *testing.T, list dnd.LocationList) *Registry {
t.Helper()
registry, err := Resolve(referenceSet(item(encodeList(t, list))))
if err != nil {
t.Fatalf("Resolve() error = %v", err)
}
return registry
}
func encodeList(t *testing.T, list dnd.LocationList) []byte {
t.Helper()
content, err := locationcodec.New().Encode(list)
if err != nil {
t.Fatalf("Encode() error = %v", err)
}
return content
}
func item(content []byte) contracts.ReferenceItem {
return contracts.ReferenceItem{SlotName: ReferenceSlot, MediaType: locationcodec.MediaType, Content: content}
}
func referenceSet(items ...contracts.ReferenceItem) contracts.ReferenceSet {
return contracts.ReferenceSet{Slots: map[string]contracts.ResolvedReferenceSlot{ReferenceSlot: {Items: items}}}
}