Migrate NPC and location normalization to native correction and explicit fallback handling

This commit is contained in:
2026-11-22 00:27:34 +00:00
parent 772b8619c1
commit 4f82d01534
16 changed files with 1062 additions and 732 deletions

View File

@@ -15,23 +15,22 @@ import (
"gitea.maximumdirect.net/eric/notarius/internal/framework/pipeline"
"gitea.maximumdirect.net/eric/notarius/internal/framework/semanticreconcile"
"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd"
registrycodec "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/codec/locationregistry"
"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/locations/identity"
"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/shared"
"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/shared/diagnostics"
"go.maximumdirect.net/promptkit"
)
const (
Key = "dnd/location-registry"
PromptID = "dnd.location_registry.normalize"
PromptVersion = "v1"
normalizationPolicy = "dnd.location_registry.normalize.v4"
NormalizationPolicy = normalizationPolicy
Key = "dnd/location-registry"
PromptID = "notarius/dnd.location_registry.normalize"
CorrectionPromptID = "notarius/dnd.location_registry.normalize.repair"
ReasonCodeLocationFieldsNormalized = "location_fields_normalized"
ReasonCodeLocationIDRecomputed = "location_id_recomputed"
ReasonCodeSourceReferencesNormalized = "source_references_normalized"
ReasonCodeDuplicateLocationCollapsed = "duplicate_location_collapsed"
ReasonCodeLocationSemanticProposalInvalid = "location_semantic_proposal_invalid"
ReasonCodeLocationSemanticReconciliationExhausted = "location_semantic_reconciliation_exhausted"
)
@@ -39,28 +38,16 @@ var requiredCapabilities = []string{"merged"}
var providedCapabilities = []string{"normalized"}
var _ contracts.Normalizer[dnd.LocationRegistry] = (*Normalizer)(nil)
var _ contracts.ManifestMetadataProvider = (*Normalizer)(nil)
var _ pipeline.CheckpointFingerprintProvider = (*Normalizer)(nil)
type Options struct{}
type Normalizer struct {
engine *semanticreconcile.Engine
engine *promptkit.Engine
}
func New(llmClient contracts.StructuredLLMClient, _ Options) (*Normalizer, error) {
if llmClient == nil {
return nil, normalizerErrorf("LLM client must not be nil")
}
promptSHA, err := promptAssetMetadata()
if err != nil {
return nil, normalizerErrorf("load prompt metadata: %w", err)
}
engine, err := semanticreconcile.NewEngine(llmClient, semanticreconcile.PromptSpec{
ID: PromptID, Version: PromptVersion, SHA256: promptSHA,
}, semanticreconcile.DefaultLimits())
if err != nil {
return nil, normalizerErrorf("construct semantic reconciliation engine: %w", err)
func New(engine *promptkit.Engine, _ Options) (*Normalizer, error) {
if engine == nil {
return nil, normalizerErrorf("native engine must not be nil")
}
return &Normalizer{engine: engine}, nil
}
@@ -68,33 +55,12 @@ func New(llmClient contracts.StructuredLLMClient, _ Options) (*Normalizer, error
func (n *Normalizer) Key() string { return Key }
func (n *Normalizer) ReferenceSlots() []contracts.ReferenceSlot { return nil }
func (n *Normalizer) ManifestMetadata() map[string]any {
if n == nil || n.engine == nil {
return nil
}
metadata := n.engine.ManifestMetadata()
metadata["identity_policy"] = identity.Policy
metadata["normalization_policy"] = normalizationPolicy
return metadata
}
func (n *Normalizer) CheckpointFingerprints() []pipeline.CheckpointFingerprint {
if n == nil || n.engine == nil {
return nil
}
fingerprints := n.engine.CheckpointFingerprints()
return append(fingerprints,
pipeline.CheckpointFingerprint{Name: "identity_policy", Value: identity.Policy},
pipeline.CheckpointFingerprint{Name: "normalization_policy", Value: normalizationPolicy},
)
}
func (n *Normalizer) Normalize(ctx context.Context, req contracts.TypedNormalizeRequest[dnd.LocationRegistry]) (contracts.TypedNormalizeResult[dnd.LocationRegistry], error) {
if n == nil {
return contracts.TypedNormalizeResult[dnd.LocationRegistry]{}, normalizerErrorf("normalizer must not be nil")
}
if n.engine == nil {
return contracts.TypedNormalizeResult[dnd.LocationRegistry]{}, normalizerErrorf("semantic reconciliation engine must not be nil")
return contracts.TypedNormalizeResult[dnd.LocationRegistry]{}, normalizerErrorf("native engine must not be nil")
}
if ctx == nil {
return contracts.TypedNormalizeResult[dnd.LocationRegistry]{}, normalizerErrorf("context must not be nil")
@@ -106,68 +72,139 @@ func (n *Normalizer) Normalize(ctx context.Context, req contracts.TypedNormalize
return contracts.TypedNormalizeResult[dnd.LocationRegistry]{}, normalizerErrorf("source document must not be nil")
}
// Keep the already available merged artifact separate from preprocessed
// originals. A failed native response must not recover an earlier proposal.
merged := cloneRegistry(req.MergeOutput.Value)
order := shared.NewSourceRefOrder(req.Source)
records, findings := preprocessRecords(req.MergeOutput.Value, order)
records, baseFindings := preprocessRecords(merged, order)
deterministic := recordList(records)
if len(records) < 2 {
return normalizationResult(deterministic, findings, nil)
}
findings := append([]diagnostics.Finding(nil), baseFindings...)
discardedGroups := -1
var omissionDetails []string
fallback := func(_ context.Context, final *dnd.LocationRegistry) (dnd.LocationRegistry, error) {
value := cloneRegistry(merged)
if final != nil {
// Each interpreted candidate was built afresh from fixed original records,
// using only the final proposal's compatible, non-overlapping safe groups.
value = cloneRegistry(*final)
} else {
findings = nil
discardedGroups = -1
omissionDetails = nil
}
if err := validateFallback(value, req.Source); err != nil {
return dnd.LocationRegistry{}, err
}
return value, nil
}
finish := func(value dnd.LocationRegistry, outcome contracts.ProducerOutcome, err error) (contracts.TypedNormalizeResult[dnd.LocationRegistry], error) {
if err != nil {
return contracts.TypedNormalizeResult[dnd.LocationRegistry]{}, normalizerErrorf("normalize locations: %w", err)
}
result, err := normalizationResult(value, findings)
if err != nil {
return contracts.TypedNormalizeResult[dnd.LocationRegistry]{}, err
}
result.Outcome = outcome
if outcome.Disposition == contracts.ProducerFallback {
details := append([]string(nil), omissionDetails...)
details = append(details, outcome.FallbackReason)
groups, err := diagnostics.Collect([]diagnostics.Finding{semanticFallbackFinding(discardedGroups, details...)}, contracts.DiagnosticDispositionWarning, contracts.DiagnosticCategoryFallback)
if err != nil {
return contracts.TypedNormalizeResult[dnd.LocationRegistry]{}, normalizerErrorf("collect fallback diagnostic: %w", err)
}
result.Diagnostics = append(result.Diagnostics, groups...)
}
return result, nil
}
noModel := func() (contracts.TypedNormalizeResult[dnd.LocationRegistry], error) {
value, outcome, err := pipeline.AssessProducer(ctx, req.Operation, deterministic, func(ctx context.Context) (dnd.LocationRegistry, error) { return fallback(ctx, nil) })
return finish(value, outcome, err)
}
if len(records) < 2 {
return noModel()
}
candidates, envelopes, err := reconciliationInputs(records)
if err != nil {
return contracts.TypedNormalizeResult[dnd.LocationRegistry]{}, normalizerErrorf("prepare semantic reconciliation inputs: %w", err)
}
reconciliation, err := n.engine.Reconcile(ctx, semanticreconcile.Request{
StageName: Key, Source: req.Source, Candidates: candidates,
ProfileID: req.LLMProfile, SessionID: req.SessionID, StructuredOutputRepairAttempts: req.StructuredOutputRepairAttempts, Correction: req.Correction,
})
preparation, err := semanticreconcile.Prepare(req.Source, candidates, semanticreconcile.DefaultLimits())
if err != nil {
return contracts.TypedNormalizeResult[dnd.LocationRegistry]{}, normalizerErrorf("reconcile semantic duplicates: %w", err)
return contracts.TypedNormalizeResult[dnd.LocationRegistry]{}, normalizerErrorf("prepare semantic reconciliation: %w", err)
}
switch reconciliation.Disposition() {
case semanticreconcile.SkippedInsufficientCandidates:
return normalizationResult(deterministic, findings, nil)
case semanticreconcile.SkippedLimitExceeded:
return fallbackResult(deterministic, findings, semanticFallbackFinding(-1, "the candidate set exceeded the configured semantic-reconciliation limits"))
case semanticreconcile.RetryableInvalidStructuredOutput:
return n.invalidStructuredResult(deterministic, findings)
case semanticreconcile.Complete, semanticreconcile.RetryableDiscardedProposalGroups:
default:
return contracts.TypedNormalizeResult[dnd.LocationRegistry]{}, normalizerErrorf("unknown semantic reconciliation disposition %d", reconciliation.Disposition())
switch preparation.Disposition() {
case semanticreconcile.InsufficientCandidates:
return noModel()
case semanticreconcile.LimitExceeded:
value, outcome, err := pipeline.FinishProducerFailure(ctx, req.Operation.Controls.Mode, normalizerErrorf("candidate set exceeded semantic reconciliation preparation limits"), func(ctx context.Context) (dnd.LocationRegistry, error) { return fallback(ctx, nil) })
return finish(value, outcome, err)
}
applied, semanticFindings, err := applyReconciliationPlan(reconciliation.Plan(), records, envelopes, order)
initial, err := semanticreconcile.InitialRequest(preparation, PromptID, req.LLMProfile, req.SessionID)
if err != nil {
return contracts.TypedNormalizeResult[dnd.LocationRegistry]{}, normalizerErrorf("apply semantic reconciliation plan: %w", err)
return contracts.TypedNormalizeResult[dnd.LocationRegistry]{}, normalizerErrorf("build native request: %w", err)
}
findings = append(findings, semanticFindings...)
if reconciliation.Disposition() == semanticreconcile.Complete {
return normalizationResult(recordList(applied), findings, reconciliation.ModelCandidate())
}
return retryResult(recordList(applied), findings, reconciliation)
value, outcome, err := pipeline.RunProducer(ctx, n.engine, req.Operation, initial,
func(_ context.Context, result *promptkit.RunResult) (*dnd.LocationRegistry, []string, error) {
response, err := semanticreconcile.DecodeProposal(result.RawOutput)
if err != nil {
return nil, nil, err
}
assessment := preparation.Assess(response)
applied, semanticFindings, err := applyReconciliationPlan(assessment.Plan(), records, envelopes, order)
if err != nil {
return nil, nil, normalizerErrorf("apply semantic reconciliation plan: %w", err)
}
findings = append(append([]diagnostics.Finding(nil), baseFindings...), semanticFindings...)
discardedGroups = assessment.DiscardedGroupCount()
omissionDetails = semanticreconcile.IssueDetails(assessment.Issues())
guidance, err := semanticreconcile.CorrectionDetails(assessment.Issues(), preparation.CandidateNumberRange())
if err != nil {
return nil, nil, err
}
candidate := recordList(applied)
return &candidate, guidance, nil
},
func(_ context.Context, guidance []string) (promptkit.RunRequest, error) {
return semanticreconcile.CorrectionRequest(CorrectionPromptID, req.LLMProfile, req.SessionID, guidance), nil
}, fallback)
return finish(value, outcome, err)
}
func (n *Normalizer) invalidStructuredResult(value dnd.LocationRegistry, findings []diagnostics.Finding) (contracts.TypedNormalizeResult[dnd.LocationRegistry], error) {
return retryResultWithFallback(value, findings, nil, "", "semantic proposal requires retry: invalid structured output", semanticFallbackFinding(-1, "the final model response did not satisfy the structured-output contract"))
// validateFallback checks the durable artifact and the identity/source invariants
// used by registry consumers, not the configured ordinary validator chain.
func validateFallback(value dnd.LocationRegistry, document *source.SourceDocument) error {
if _, err := registrycodec.New().Encode(value); err != nil {
return normalizerErrorf("construct locations fallback: %w", err)
}
if issues := identity.ValidateList(value); len(issues) > 0 {
return normalizerErrorf("construct locations fallback: registry identity is not usable downstream")
}
index := source.NewDocumentIndex(document)
for _, location := range value.Locations {
for _, reference := range location.SourceRefs {
if err := index.ValidateRef(reference); err != nil {
return normalizerErrorf("construct locations fallback: %w", err)
}
}
}
return nil
}
func retryResult(value dnd.LocationRegistry, findings []diagnostics.Finding, reconciliation semanticreconcile.Result) (contracts.TypedNormalizeResult[dnd.LocationRegistry], error) {
issues := reconciliation.Issues()
correctionDetails, err := reconciliation.CorrectionDetails()
if err != nil {
return contracts.TypedNormalizeResult[dnd.LocationRegistry]{}, normalizerErrorf("build semantic correction details: %w", err)
func cloneRegistry(value dnd.LocationRegistry) dnd.LocationRegistry {
if value.Locations == nil {
return dnd.LocationRegistry{}
}
correctionGuidance, err := reconciliation.CorrectionGuidance()
if err != nil {
return contracts.TypedNormalizeResult[dnd.LocationRegistry]{}, normalizerErrorf("build semantic correction guidance: %w", err)
result := dnd.LocationRegistry{Locations: make([]dnd.Location, len(value.Locations))}
for i, location := range value.Locations {
result.Locations[i] = cloneLocation(location)
}
return retryResultWithFallback(value, findings, reconciliation.ModelCandidate(), correctionGuidance, diagnostics.Aggregate("semantic proposal requires retry", semanticreconcile.IssueDetails(issues)), semanticFallbackFinding(reconciliation.DiscardedGroupCount(), correctionDetails...))
return result
}
func semanticFallbackFinding(discarded int, details ...string) diagnostics.Finding {
message := "semantic reconciliation could not be completed; all affected candidates were preserved separately"
if discarded >= 0 {
message := "semantic reconciliation did not obtain ordinary acceptance; using supported fallback output"
if discarded > 0 {
message = fmt.Sprintf("%d proposal group(s) omitted from the final semantic proposal; all affected candidates were preserved separately", discarded)
}
if len(details) > 0 {
@@ -176,38 +213,12 @@ func semanticFallbackFinding(discarded int, details ...string) diagnostics.Findi
return diagnostics.Finding{Scope: "locations", ReasonCode: ReasonCodeLocationSemanticReconciliationExhausted, Message: message}
}
func normalizationResult(value dnd.LocationRegistry, findings []diagnostics.Finding, candidate *contracts.ModelCandidate) (contracts.TypedNormalizeResult[dnd.LocationRegistry], error) {
diagnosticGroups, err := diagnostics.Collect(findings, contracts.DiagnosticDispositionObservation, contracts.DiagnosticCategoryNormalization)
func normalizationResult(value dnd.LocationRegistry, findings []diagnostics.Finding) (contracts.TypedNormalizeResult[dnd.LocationRegistry], error) {
groups, err := diagnostics.Collect(findings, contracts.DiagnosticDispositionObservation, contracts.DiagnosticCategoryNormalization)
if err != nil {
return contracts.TypedNormalizeResult[dnd.LocationRegistry]{}, normalizerErrorf("collect normalization diagnostics: %w", err)
}
return contracts.TypedNormalizeResult[dnd.LocationRegistry]{Value: value, Diagnostics: diagnosticGroups, ModelCandidate: candidate}, nil
}
func fallbackResult(value dnd.LocationRegistry, findings []diagnostics.Finding, fallback diagnostics.Finding) (contracts.TypedNormalizeResult[dnd.LocationRegistry], error) {
result, err := normalizationResult(value, findings, nil)
if err != nil {
return contracts.TypedNormalizeResult[dnd.LocationRegistry]{}, err
}
fallbackGroups, err := diagnostics.Collect([]diagnostics.Finding{fallback}, contracts.DiagnosticDispositionWarning, contracts.DiagnosticCategoryFallback)
if err != nil {
return contracts.TypedNormalizeResult[dnd.LocationRegistry]{}, normalizerErrorf("collect fallback diagnostic: %w", err)
}
result.Diagnostics = append(result.Diagnostics, fallbackGroups...)
return result, nil
}
func retryResultWithFallback(value dnd.LocationRegistry, findings []diagnostics.Finding, candidate *contracts.ModelCandidate, correctionGuidance, message string, fallback diagnostics.Finding) (contracts.TypedNormalizeResult[dnd.LocationRegistry], error) {
result, err := normalizationResult(value, findings, candidate)
if err != nil {
return contracts.TypedNormalizeResult[dnd.LocationRegistry]{}, err
}
fallbackGroups, err := diagnostics.Collect([]diagnostics.Finding{fallback}, contracts.DiagnosticDispositionWarning, contracts.DiagnosticCategoryFallback)
if err != nil {
return contracts.TypedNormalizeResult[dnd.LocationRegistry]{}, normalizerErrorf("collect fallback diagnostic: %w", err)
}
result.Retry = &contracts.NormalizeRetry{ReasonCode: ReasonCodeLocationSemanticProposalInvalid, Message: message, CorrectionGuidance: correctionGuidance, FallbackDiagnostics: fallbackGroups}
return result, nil
return contracts.TypedNormalizeResult[dnd.LocationRegistry]{Value: value, Diagnostics: groups}, nil
}
type normalizedRecord struct {
@@ -373,7 +384,7 @@ func duplicateFinding(retainedIndex int, removed []int) diagnostics.Finding {
func locationScope(index int) string { return fmt.Sprintf("locations[%d]", index) }
func ModuleSpec() pipeline.ModuleSpec {
return pipeline.ModuleSpec{Key: Key, Stage: pipeline.StageNormalize, ExecutionClass: contracts.ExecutionClassLLMBacked, CorrectionProtocol: contracts.CorrectionProtocolSingleResponseV1, Requires: append([]string(nil), requiredCapabilities...), Provides: append([]string(nil), providedCapabilities...), ArtifactKind: dnd.LocationRegistryKind}
return pipeline.ModuleSpec{Key: Key, Stage: pipeline.StageNormalize, ExecutionClass: contracts.ExecutionClassLLMBacked, Prompts: []string{PromptID, CorrectionPromptID}, Requires: append([]string(nil), requiredCapabilities...), Provides: append([]string(nil), providedCapabilities...), ArtifactKind: dnd.LocationRegistryKind}
}
func Register(registry *pipeline.NormalizerRegistry) error {
return pipeline.RegisterNormalizerBuilder(registry, ModuleSpec(), validateOptions, func(request pipeline.BuildRequest) (contracts.Normalizer[dnd.LocationRegistry], error) {
@@ -381,7 +392,7 @@ func Register(registry *pipeline.NormalizerRegistry) error {
if err != nil {
return nil, err
}
return New(request.Dependencies.LLM, options)
return New(request.Dependencies.Engine, options)
})
}
func validateOptions(options map[string]any) error { _, err := DecodeOptions(options); return err }