Use contextual descriptors for entity reconciliation

internal/modules/dnd/normalize/npcregistry/normalizer.go

@@ -23,7 +23,7 @@ import (
 const (
 	Key                   = "dnd/npc-registry"
 	PromptID              = "dnd.npc_registry.normalize"
-	normalizationPolicy   = "dnd.npc_registry.normalize.v3"
+	normalizationPolicy   = "dnd.npc_registry.normalize.v4"
 	semanticContextPolicy = "dnd.entity_reconcile.context.v1"
 	NormalizationPolicy   = normalizationPolicy
 

internal/modules/dnd/normalize/npcregistry/normalizer_test.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"encoding/json"
 	"reflect"
+	"strconv"
 	"strings"
 	"testing"
 
@@ -156,10 +157,51 @@ func (c *recordingNPCNormalizerClient) CompleteStructured(_ context.Context, req
 	if response == "" {
 		response = `{"duplicate_groups":[]}`
 	}
-	if err := json.Unmarshal([]byte(response), output); err != nil {
+	content, err := contextualProposalResponse(response, request.Inputs["candidates"].Content)
+	if err != nil {
 		return contracts.StructuredCompletionResponse{}, err
 	}
-	return contracts.StructuredCompletionResponse{Content: json.RawMessage(response)}, nil
+	if err := json.Unmarshal(content, output); err != nil {
+		return contracts.StructuredCompletionResponse{}, err
+	}
+	return contracts.StructuredCompletionResponse{Content: content}, nil
+}
+
+func contextualProposalResponse(response string, candidateContent []byte) ([]byte, error) {
+	if !strings.Contains(response, "candidate-") {
+		return []byte(response), nil
+	}
+	var selection struct {
+		DuplicateGroups []struct {
+			Members   []string `json:"members"`
+			Canonical string   `json:"canonical"`
+		} `json:"duplicate_groups"`
+	}
+	if err := json.Unmarshal([]byte(response), &selection); err != nil {
+		return nil, err
+	}
+	var candidates struct {
+		Candidates []entityreconcile.Selector `json:"candidates"`
+	}
+	if err := json.Unmarshal(candidateContent, &candidates); err != nil {
+		return nil, err
+	}
+	selector := func(key string) entityreconcile.Selector {
+		index, err := strconv.Atoi(strings.TrimPrefix(key, "candidate-"))
+		if err != nil || index < 1 || index > len(candidates.Candidates) {
+			return entityreconcile.Selector{Name: key, SourceRefs: []entityreconcile.SourceRange{}}
+		}
+		return candidates.Candidates[index-1].Clone()
+	}
+	proposal := entityreconcile.ProposalResponse{DuplicateGroups: make([]entityreconcile.DuplicateGroup, len(selection.DuplicateGroups))}
+	for index, group := range selection.DuplicateGroups {
+		members := make([]entityreconcile.Selector, len(group.Members))
+		for memberIndex, key := range group.Members {
+			members[memberIndex] = selector(key)
+		}
+		proposal.DuplicateGroups[index] = entityreconcile.DuplicateGroup{Members: members, Canonical: selector(group.Canonical)}
+	}
+	return json.Marshal(proposal)
 }
 
 func newNormalizer(t *testing.T, client contracts.StructuredLLMClient) *Normalizer {

internal/modules/dnd/normalize/npcregistry/prompt_assets_test.go

@@ -36,7 +36,7 @@ func TestRegisterPromptAssetsPreparesNormalizationPrompt(t *testing.T) {
 	prepared, err := engine.Prepare(context.Background(), promptkit.RunRequest{
 		PromptID: PromptID, PromptVersion: entityreconcile.SchemaVersion, ProfileID: "normalize-test-profile",
 		Inputs: map[string]promptkit.ArtifactRef{
-			"candidates": promptkit.Inline(`{"candidates":[{"key":"candidate-000001","name":"Mira","source_refs":[]}]}`),
+			"candidates": promptkit.Inline(`{"candidates":[{"name":"Mira","source_refs":[{"start_unit_id":1,"end_unit_id":1}]}]}`),
 			"transcript": promptkit.Inline(`{"windows":[{"units":[]}]}`),
 		},
 	})

internal/modules/dnd/normalize/npcregistry/semantic_normalizer_test.go

@@ -2,6 +2,7 @@ package npcregistry
 
 import (
 	"context"
+	"encoding/json"
 	"errors"
 	"math"
 	"reflect"
@@ -174,8 +175,8 @@ func TestNormalizeDoesNotAccumulateSafeGroupsAcrossAttempts(t *testing.T) {
 	}
 }
 
-func TestNormalizeExcludesIneligibleRecordsFromSemanticGroups(t *testing.T) {
-	client := &recordingNPCNormalizerClient{response: `{"duplicate_groups":[{"members":["candidate-000001","candidate-000002"],"canonical":"candidate-000001"}]}`}
+func TestNormalizeRetainsRecordsWhenAProposalUsesAnUnknownDescriptor(t *testing.T) {
+	client := &recordingNPCNormalizerClient{response: `{"duplicate_groups":[{"members":["candidate-000001","unknown"],"canonical":"candidate-000001"}]}`}
 	normalizer := newNormalizer(t, client)
 	doc := semanticDocument()
 	input := dnd.NPCRegistry{NPCs: []dnd.NPC{
@@ -187,8 +188,8 @@ func TestNormalizeExcludesIneligibleRecordsFromSemanticGroups(t *testing.T) {
 	if err != nil || result.Retry == nil || len(result.Value.NPCs) != 3 {
 		t.Fatalf("Normalize() = %#v, %v; want unchanged retry fallback", result, err)
 	}
-	if !strings.Contains(result.Retry.Message, "member_ineligible") || result.Value.NPCs[1].Name != "Broken" {
-		t.Fatalf("result = %#v, want ineligible record excluded but preserved", result)
+	if !strings.Contains(result.Retry.Message, "member_unknown") || result.Value.NPCs[1].Name != "Broken" {
+		t.Fatalf("result = %#v, want unknown descriptor rejected without dropping a record", result)
 	}
 }
 
@@ -206,8 +207,14 @@ func TestReconciliationCandidatesKeepEqualDisplayNamesDistinct(t *testing.T) {
 	if !reflect.DeepEqual(keys, []string{"candidate-000001", "candidate-000002"}) || strings.Count(string(materials.Candidates.Content), `"The Guard"`) != 2 {
 		t.Fatalf("candidate keys and inputs = %#v, %s; want distinct equal-display candidates", keys, materials.Candidates.Content)
 	}
+	var candidateInput struct {
+		Candidates []entityreconcile.Selector `json:"candidates"`
+	}
+	if err := json.Unmarshal(materials.Candidates.Content, &candidateInput); err != nil {
+		t.Fatal(err)
+	}
 	assessment := materials.Assess(entityreconcile.ProposalResponse{DuplicateGroups: []entityreconcile.DuplicateGroup{{
-		Members: keys, Canonical: keys[1],
+		Members: candidateInput.Candidates, Canonical: candidateInput.Candidates[1],
 	}}})
 	groups := reconciliationGroups(assessment, keys)
 	if assessment.DiscardedGroups() != 0 || len(groups) != 1 || groups[0].canonical != 1 {