Share the D&D NPC registry and prompt grounding

This commit is contained in:
2026-07-21 04:34:56 +00:00
parent d3e171aa82
commit 92acb45775
23 changed files with 628 additions and 436 deletions

View File

@@ -1,53 +0,0 @@
// Package diagnostics provides bounded, safe text for deterministic NPC
// decisions and warnings.
package diagnostics
import (
"fmt"
"strconv"
"strings"
)
const (
MaxIssues = 20
MaxDisplayedRunes = 128
MaxMessageBytes = 4096
)
func Truncate(value string) string {
runes := []rune(value)
if len(runes) <= MaxDisplayedRunes {
return value
}
return string(runes[:MaxDisplayedRunes-1]) + "…"
}
func Quote(value string) string { return strconv.Quote(Truncate(value)) }
func Aggregate(prefix string, issues []string) string {
displayed := make([]string, 0, min(len(issues), MaxIssues))
for len(displayed) < len(issues) && len(displayed) < MaxIssues {
issue := Truncate(issues[len(displayed)])
candidate := aggregateMessage(prefix, append(displayed, issue), len(issues)-len(displayed)-1)
if len([]byte(candidate)) > MaxMessageBytes {
break
}
displayed = append(displayed, issue)
}
return aggregateMessage(prefix, displayed, len(issues)-len(displayed))
}
func aggregateMessage(prefix string, issues []string, omitted int) string {
message := prefix + ": " + strings.Join(issues, ", ")
if omitted > 0 {
message += fmt.Sprintf("; %d additional issue(s) omitted", omitted)
}
return message
}
func min(left, right int) int {
if left < right {
return left
}
return right
}

View File

@@ -1,28 +0,0 @@
package diagnostics
import (
"fmt"
"strings"
"testing"
"unicode/utf8"
)
func TestAggregateEnforcesByteBudgetAndReportsOmissions(t *testing.T) {
issues := make([]string, MaxIssues)
for index := range issues {
issues[index] = fmt.Sprintf("issue-%d-%s", index, strings.Repeat("火", MaxDisplayedRunes))
}
message := Aggregate("invalid NPC data", issues)
if !utf8.ValidString(message) || len([]byte(message)) > MaxMessageBytes {
t.Fatalf("Aggregate() returned invalid or oversized message: bytes=%d message=%q", len([]byte(message)), message)
}
displayed := strings.Count(message, "issue-")
if displayed == 0 || displayed >= len(issues) {
t.Fatalf("Aggregate() displayed %d issues, want byte-budget omission", displayed)
}
wantOmitted := fmt.Sprintf("%d additional issue(s) omitted", len(issues)-displayed)
if !strings.Contains(message, wantOmitted) {
t.Fatalf("Aggregate() = %q, want %q", message, wantOmitted)
}
}

View File

@@ -0,0 +1,204 @@
// Package registry resolves normalized NPC artifacts into immutable grounding
// data for D&D extraction modules.
package registry
import (
"crypto/sha256"
"encoding/hex"
"fmt"
"mime"
"strings"
"gitea.maximumdirect.net/eric/notarius/internal/core/source"
"gitea.maximumdirect.net/eric/notarius/internal/framework/contracts"
"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd"
npccodec "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/codec/npcs"
"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/npcs/identity"
"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/shared/diagnostics"
)
const (
ReferenceSlot = "npcs"
MaxBytes = 1048576
emptyPrompt = `{"npcs":[]}`
)
// Registry is an immutable, validated NPC registry prepared for prompt
// grounding. All accessors return defensive copies.
type Registry struct {
bound bool
list dnd.NPCList
canonical []byte
digest string
promptInput contracts.LLMInputMaterial
lookupByKey map[string]int
}
// 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) {
slot, ok := references.Slots[ReferenceSlot]
if !ok {
content := []byte(emptyPrompt)
return &Registry{
list: dnd.NPCList{NPCs: []dnd.NPC{}},
canonical: append([]byte(nil), content...),
promptInput: contracts.NewLLMInputMaterial(ReferenceSlot, npccodec.MediaType, content, "", ""),
lookupByKey: 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, npccodec.MediaType) {
return nil, fmt.Errorf("reference slot %q item media type must be %s", ReferenceSlot, npccodec.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 := npccodec.New()
value, err := codec.Decode(item.Content)
if err != nil {
return nil, fmt.Errorf("decode NPC registry: invalid approved NPC 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 NPC registry: approved NPC value could not be encoded")
}
list := cloneNPCList(value)
lookupByKey := make(map[string]int, len(list.NPCs)*2)
for index, npc := range list.NPCs {
lookupByKey[identity.ComparisonKey(npc.Name)] = index
for _, alias := range npc.Aliases {
lookupByKey[identity.ComparisonKey(alias)] = index
}
}
digest := semanticDigest(content)
return &Registry{
bound: true,
list: list,
canonical: append([]byte(nil), content...),
digest: digest,
promptInput: contracts.NewLLMInputMaterial(ReferenceSlot, npccodec.MediaType, content, digest, ""),
lookupByKey: lookupByKey,
}, nil
}
// New is an alias for Resolve for callers constructing a prepared registry.
func New(references contracts.ReferenceSet) (*Registry, error) { return Resolve(references) }
// Bound reports whether an NPC reference was supplied and validated.
func (r *Registry) Bound() bool { return r != nil && r.bound }
// NPCs returns a defensive copy of the validated NPC records.
func (r *Registry) NPCs() []dnd.NPC {
if r == nil {
return nil
}
return cloneNPCs(r.list.NPCs)
}
// List returns a defensive copy of the validated NPC list.
func (r *Registry) List() dnd.NPCList {
if r == nil {
return dnd.NPCList{}
}
return cloneNPCList(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 SHA-256 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
}
// Count returns the number of validated NPC records.
func (r *Registry) Count() int {
if r == nil {
return 0
}
return len(r.list.NPCs)
}
// PromptInput returns the canonical registry as a content-safe prompt input.
// Reference provenance is deliberately omitted.
func (r *Registry) PromptInput() contracts.LLMInputMaterial {
if r == nil {
return contracts.LLMInputMaterial{}
}
return r.promptInput.Clone()
}
// Lookup returns the canonical NPC for an exact canonical-name or alias match
// under the NPC identity comparison policy.
func (r *Registry) Lookup(value string) (dnd.NPC, bool) {
if r == nil {
return dnd.NPC{}, false
}
index, ok := r.lookupByKey[identity.ComparisonKey(value)]
if !ok {
return dnd.NPC{}, false
}
return cloneNPC(r.list.NPCs[index]), true
}
func semanticDigest(content []byte) string {
sum := sha256.Sum256(content)
return "sha256:" + hex.EncodeToString(sum[:])
}
func formatIdentityIssues(issues []identity.Issue) string {
parts := make([]string, len(issues))
for index, issue := range issues {
location := fmt.Sprintf("record %d", issue.RecordIndex)
if issue.AliasIndex >= 0 {
location += fmt.Sprintf(" alias %d", issue.AliasIndex)
}
parts[index] = fmt.Sprintf("%s at %s", issue.Code, location)
}
return diagnostics.Aggregate("validate NPC registry identity", parts)
}
func cloneNPCList(value dnd.NPCList) dnd.NPCList {
return dnd.NPCList{NPCs: cloneNPCs(value.NPCs)}
}
func cloneNPCs(values []dnd.NPC) []dnd.NPC {
if values == nil {
return nil
}
cloned := make([]dnd.NPC, len(values))
for index, value := range values {
cloned[index] = cloneNPC(value)
}
return cloned
}
func cloneNPC(value dnd.NPC) dnd.NPC {
value.Aliases = append([]string(nil), value.Aliases...)
value.Relationships = append([]dnd.NPCRelationship(nil), value.Relationships...)
value.SourceRefs = append([]source.SourceRef(nil), value.SourceRefs...)
return value
}

View File

@@ -0,0 +1,224 @@
package registry
import (
"bytes"
"encoding/json"
"fmt"
"strings"
"testing"
"unicode/utf8"
"gitea.maximumdirect.net/eric/notarius/internal/core/source"
"gitea.maximumdirect.net/eric/notarius/internal/framework/contracts"
"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd"
npccodec "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/codec/npcs"
"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/npcs/identity"
"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/shared/diagnostics"
)
func TestResolveAbsentRegistryUsesExactEmptyPrompt(t *testing.T) {
resolved, err := Resolve(contracts.ReferenceSet{})
if err != nil {
t.Fatalf("Resolve() error = %v, want nil", err)
}
if resolved.Bound() || resolved.Digest() != "" || resolved.Count() != 0 {
t.Fatalf("resolved unbound registry = %#v, want no semantic metadata", resolved)
}
input := resolved.PromptInput()
if input.Name != ReferenceSlot || input.MediaType != npccodec.MediaType || input.Digest != "" || input.OriginURI != "" {
t.Fatalf("unbound prompt input metadata = %#v, want name/media type only", input)
}
if got := string(input.Content); got != emptyPrompt {
t.Fatalf("unbound prompt input = %q, want exact empty registry", got)
}
if got := string(resolved.CanonicalBytes()); got != emptyPrompt {
t.Fatalf("unbound canonical bytes = %q, want exact empty registry", got)
}
}
func TestResolveCanonicalizesAndProvidesSemanticIdentity(t *testing.T) {
value := validRegistryList()
canonical := encodeRegistry(t, value)
raw := append([]byte(" \n"), canonical...)
raw = append(raw, []byte("\n ")...)
resolved, err := Resolve(registryReference(raw, "file:///another-session/npcs.json"))
if err != nil {
t.Fatalf("Resolve() error = %v, want nil", err)
}
if !resolved.Bound() || resolved.Count() != len(value.NPCs) {
t.Fatalf("resolved registry = %#v, want bound registry with %d NPC", resolved, len(value.NPCs))
}
if !bytes.Equal(resolved.CanonicalBytes(), canonical) || !bytes.Equal(resolved.PromptInput().Content, canonical) {
t.Fatalf("canonical content = %s, want %s", resolved.CanonicalBytes(), canonical)
}
if resolved.PromptInput().Digest != resolved.Digest() || !strings.HasPrefix(resolved.Digest(), "sha256:") {
t.Fatalf("semantic digest = %q, want SHA-256 digest", resolved.Digest())
}
if resolved.PromptInput().OriginURI != "" {
t.Fatalf("prompt input origin = %q, want no provenance path", resolved.PromptInput().OriginURI)
}
}
func TestResolveRejectsInvalidBoundaryValuesWithoutContent(t *testing.T) {
valid := validRegistryList()
second := valid.NPCs[0]
second.ID = identity.DeriveID("Captain Vale")
second.Name = "Captain Vale"
second.Aliases = []string{"The Greencloak"}
valueWithAliasCollision := dnd.NPCList{NPCs: []dnd.NPC{valid.NPCs[0], second}}
invalidID := valid
invalidID.NPCs[0].ID = "not-an-npc-id"
tests := []struct {
name string
reference contracts.ReferenceSet
wantError string
forbidden []string
}{
{name: "zero items", reference: contracts.ReferenceSet{Slots: map[string]contracts.ResolvedReferenceSlot{ReferenceSlot: {Items: []contracts.ReferenceItem{}}}}, wantError: "exactly one"},
{name: "multiple", reference: contracts.ReferenceSet{Slots: map[string]contracts.ResolvedReferenceSlot{ReferenceSlot: {Items: []contracts.ReferenceItem{{Content: []byte(emptyPrompt)}, {Content: []byte(emptyPrompt)}}}}}, wantError: "exactly one"},
{name: "wrong media type", reference: registryReferenceWithMedia([]byte(emptyPrompt), "text/plain"), wantError: "must be application/json"},
{name: "malformed JSON", reference: registryReference([]byte(`{"npcs":[],"MALFORMED_REGISTRY_SECRET":`), "file:///private.json"), wantError: "invalid approved NPC JSON", forbidden: []string{"MALFORMED_REGISTRY_SECRET"}},
{name: "unknown field", reference: registryReference([]byte(`{"npcs":[],"UNKNOWN_FIELD_SECRET":true}`), "file:///private.json"), wantError: "invalid approved NPC JSON", forbidden: []string{"UNKNOWN_FIELD_SECRET"}},
{name: "invalid ID", reference: registryReference(marshalRegistry(t, invalidID), "file:///private.json"), wantError: "decode NPC registry"},
{name: "alias collision", reference: registryReference(encodeRegistry(t, valueWithAliasCollision), "file:///private.json"), wantError: string(identity.IssueAliasOwnershipCollision)},
{name: "byte limit", reference: registryReference(bytes.Repeat([]byte("x"), MaxBytes+1), "file:///private.json"), wantError: "limit"},
}
for _, test := range tests {
t.Run(test.name, func(t *testing.T) {
_, err := Resolve(test.reference)
if err == nil || !strings.Contains(err.Error(), test.wantError) {
t.Fatalf("Resolve() error = %v, want %q", err, test.wantError)
}
for _, forbidden := range append(test.forbidden, "Mira Thorn", "The Greencloak", "private.json") {
if strings.Contains(err.Error(), forbidden) {
t.Fatalf("error leaked registry content or provenance %q: %v", forbidden, err)
}
}
})
}
}
func TestResolveBoundsIdentityDiagnosticsWithoutContent(t *testing.T) {
const recordCount = 30
value := dnd.NPCList{NPCs: make([]dnd.NPC, recordCount)}
for index := range value.NPCs {
value.NPCs[index] = dnd.NPC{
ID: "npc:sha256:0000000000000000000000000000000000000000000000000000000000000000",
Name: fmt.Sprintf("PRIVATE NPC %d", index),
Aliases: []string{"PRIVATE SHARED ALIAS"},
Description: "PRIVATE DESCRIPTION",
Relationships: []dnd.NPCRelationship{},
SourceRefs: []source.SourceRef{{SourceID: "private-source", StartUnitID: 1, EndUnitID: 1}},
}
}
issues := identity.ValidateList(value)
if len(issues) <= diagnostics.MaxIssues {
t.Fatalf("identity issues = %d, want more than display limit", len(issues))
}
_, err := Resolve(registryReference(marshalRegistry(t, value), "file:///private-registry.json"))
if err == nil {
t.Fatal("Resolve() error = nil, want bounded identity rejection")
}
message := err.Error()
if !utf8.ValidString(message) || len([]byte(message)) > diagnostics.MaxMessageBytes {
t.Fatalf("identity error has invalid encoding or size: bytes=%d message=%q", len([]byte(message)), message)
}
wantOmitted := fmt.Sprintf("%d additional issue(s) omitted", len(issues)-diagnostics.MaxIssues)
if !strings.Contains(message, wantOmitted) {
t.Fatalf("identity error = %q, want %q", message, wantOmitted)
}
for _, forbidden := range []string{"PRIVATE NPC", "PRIVATE SHARED ALIAS", "PRIVATE DESCRIPTION", "private-source", "private-registry.json"} {
if strings.Contains(message, forbidden) {
t.Fatalf("identity error leaked %q: %s", forbidden, message)
}
}
}
func TestRegistryAccessorsAndLookupAreDefensive(t *testing.T) {
resolved, err := Resolve(registryReference(encodeRegistry(t, validRegistryList()), "file:///npc-registry.json"))
if err != nil {
t.Fatalf("Resolve() error = %v, want nil", err)
}
npcs := resolved.NPCs()
npcs[0].Name = "changed"
npcs[0].Aliases[0] = "changed alias"
npcs[0].Relationships[0].Target = "changed target"
npcs[0].SourceRefs[0].SourceID = "changed source"
if got, ok := resolved.Lookup("The Greencloak"); !ok || got.Name != "Mira Thorn" {
t.Fatalf("Lookup() after NPC mutation = %#v, %v, want original NPC", got, ok)
}
wantCanonical := string(resolved.CanonicalBytes())
content := resolved.CanonicalBytes()
content[0] = 'X'
input := resolved.PromptInput()
input.Content[0] = 'X'
if string(resolved.CanonicalBytes()) != wantCanonical || string(resolved.PromptInput().Content) != wantCanonical {
t.Fatal("registry content accessors share mutable state")
}
if got, ok := resolved.Lookup(" MIRA\u00a0THORN "); !ok || got.Name != "Mira Thorn" {
t.Fatalf("Lookup() canonical identity = %#v, %v, want Mira Thorn", got, ok)
}
if _, ok := resolved.Lookup("unknown NPC"); ok {
t.Fatal("Lookup() found unknown NPC")
}
}
func validRegistryList() dnd.NPCList {
return dnd.NPCList{NPCs: []dnd.NPC{{
ID: identity.DeriveID("Mira Thorn"),
Name: "Mira Thorn",
Aliases: []string{"The Greencloak"},
Description: "A guarded ranger who watches the northern road.",
Relationships: []dnd.NPCRelationship{{
Target: "Captain Vale", Relationship: "reports to",
}},
SourceRefs: []source.SourceRef{{SourceID: "npc-session", StartUnitID: 41, EndUnitID: 43}},
}}}
}
func encodeRegistry(t *testing.T, value dnd.NPCList) []byte {
t.Helper()
content, err := npccodec.New().Encode(value)
if err != nil {
t.Fatalf("encode NPC registry: %v", err)
}
return content
}
func marshalRegistry(t *testing.T, value dnd.NPCList) []byte {
t.Helper()
content, err := json.Marshal(value)
if err != nil {
t.Fatalf("marshal NPC registry: %v", err)
}
return content
}
func registryReference(content []byte, origin string) contracts.ReferenceSet {
references := registryReferenceWithMedia(content, "application/json; charset=utf-8")
item := references.Slots[ReferenceSlot].Items[0]
item.Origin.URI = origin
slot := references.Slots[ReferenceSlot]
slot.Items[0] = item
references.Slots[ReferenceSlot] = slot
return references
}
func registryReferenceWithMedia(content []byte, mediaType string) contracts.ReferenceSet {
return contracts.ReferenceSet{Slots: map[string]contracts.ResolvedReferenceSlot{
ReferenceSlot: {
Slot: contracts.ReferenceSlot{Name: ReferenceSlot, AcceptedMediaTypes: []string{npccodec.MediaType}, MaxBytes: MaxBytes},
Items: []contracts.ReferenceItem{{
SlotName: ReferenceSlot,
MediaType: mediaType,
Content: append([]byte(nil), content...),
Origin: contracts.ReferenceOrigin{Type: "file", URI: "file:///npc-registry.json"},
}},
},
}}
}