audita/internal/framework/validators/models.go

package validators

import (
	"context"
	"fmt"
	"strings"

	"gitea.maximumdirect.net/eric/audita/v3/internal/core/config"
	"gitea.maximumdirect.net/eric/audita/v3/internal/core/modulecatalog"
	"gitea.maximumdirect.net/eric/audita/v3/internal/core/schema"
	"gitea.maximumdirect.net/eric/audita/v3/internal/framework/outcomes"
	"gitea.maximumdirect.net/eric/audita/v3/internal/framework/proposals"
)

const (
	ReasonApproved                    = "approved"
	ReasonLowConfidence               = "low_confidence"
	ReasonMissingOriginalText         = "missing_original_text"
	ReasonMissingTargetSegment        = "missing_target_segment"
	ReasonEmptyResultingText          = "empty_resulting_segment"
	ReasonNoEffect                    = "no_effect"
	ReasonProtectedGlossaryTerm       = "protected_glossary_term"
	ReasonInvalidTargetSegment        = "invalid_target_segment_id"
	ReasonEmptyOriginalText           = "empty_original_text"
	ReasonInvalidConfidence           = "invalid_confidence"
	ReasonValidatorMalformed          = "validator_response_malformed"
	ReasonValidatorInputTooLarge      = "validator_input_too_large"
	ReasonMissingValidationDecision   = "missing_validation_decision"
	ReasonDuplicateValidationDecision = "duplicate_validation_decision"
	ReasonInvalidValidationDecision   = "invalid_validation_decision"
)

// Request is the runtime input shared by deterministic validators.
type Request struct {
	// ReportDiagnosticError may be called concurrently; it must not affect processing.
	ReportDiagnosticError func(error)                            `json:"-"`
	SectionIndex          *int                                   `json:"section_index,omitempty"`
	WorkingTranscript     *schema.Transcript                     `json:"-"`
	CandidateProposal     []proposals.EnrichedCorrectionProposal `json:"candidate_proposals"`
	ModuleKey             string                                 `json:"module_key"`
	ModuleInstance        string                                 `json:"module_instance"`
	ValidatorOrder        *int                                   `json:"validator_order,omitempty"`
	ReplacementPolicy     proposals.ReplacementPolicy            `json:"replacement_policy"`
	Glossary              *schema.Glossary                       `json:"-"`
	Config                *config.Config                         `json:"-"`
	LLMClient             StructuredLLMClient                    `json:"-"`
	DiagnosticsWriter     InteractionDiagnosticsWriter           `json:"-"`
}

// Decision is one validator decision for one proposal index.
type Decision struct {
	ProposalIndex          int                 `json:"proposal_index"`
	Approved               bool                `json:"approved"`
	Disposition            DecisionDisposition `json:"disposition"`
	ReasonCode             string              `json:"reason_code"`
	Message                string              `json:"message"`
	DiagnosticArtifactPath string              `json:"diagnostic_artifact_path,omitempty"`
}

// DecisionDisposition separates normal editorial rejection from a candidate
// excluded because its model operation could not provide a trustworthy decision.
type DecisionDisposition string

const (
	DispositionApproved    DecisionDisposition = "approved"
	DispositionRejected    DecisionDisposition = "rejected"
	DispositionUnavailable DecisionDisposition = "unavailable"
)

// Result contains one decision per proposal index on success. Fatal returns may
// include completed partial decisions as evidence, never as application approval.
type Result struct {
	ValidatorName string               `json:"validator_name"`
	Decisions     []Decision           `json:"decisions"`
	Operations    []outcomes.Operation `json:"operations,omitempty"`
}

type InteractionDiagnosticsWriter interface {
	WriteInteraction(stage string, requestMetadata any, requestPayload any, responsePayload any, errorPayload any) (InteractionArtifacts, error)
}

type InteractionArtifacts struct {
	RequestMetadataPath string `json:"request_metadata_path,omitempty"`
	RequestPayloadPath  string `json:"request_payload_path,omitempty"`
	ResponsePayloadPath string `json:"response_payload_path,omitempty"`
	ErrorPayloadPath    string `json:"error_payload_path,omitempty"`
}

// Validator is the deterministic runtime validator interface.
type Validator interface {
	Name() string
	Validate(ctx context.Context, req Request) (Result, error)
}

// EnforceDecisionCardinality verifies every candidate proposal index receives exactly one decision.
func EnforceDecisionCardinality(candidate []proposals.EnrichedCorrectionProposal, decisions []Decision) error {
	return enforceDecisionCardinality(candidate, decisions, true)
}

// EnforcePartialDecisionCardinality accepts missing decisions on fatal returns,
// but still rejects duplicate and unknown proposal identities.
func EnforcePartialDecisionCardinality(candidate []proposals.EnrichedCorrectionProposal, decisions []Decision) error {
	return enforceDecisionCardinality(candidate, decisions, false)
}

func enforceDecisionCardinality(candidate []proposals.EnrichedCorrectionProposal, decisions []Decision, requireAll bool) error {
	expected := make(map[int]struct{}, len(candidate))
	for _, c := range candidate {
		expected[c.ProposalIndex] = struct{}{}
	}

	seen := make(map[int]int, len(decisions))
	for _, d := range decisions {
		if _, ok := expected[d.ProposalIndex]; !ok {
			return fmt.Errorf("unknown decision proposal index %d", d.ProposalIndex)
		}
		seen[d.ProposalIndex]++
		if seen[d.ProposalIndex] > 1 {
			return fmt.Errorf("duplicate decision proposal index %d", d.ProposalIndex)
		}
	}

	for idx := range expected {
		if requireAll && seen[idx] == 0 {
			return fmt.Errorf("missing decision proposal index %d", idx)
		}
	}

	return nil
}

func approval(index int) Decision {
	return Decision{ProposalIndex: index, Approved: true, Disposition: DispositionApproved, ReasonCode: ReasonApproved, Message: "approved"}
}

func rejection(index int, reasonCode string, msg string) Decision {
	return Decision{ProposalIndex: index, Approved: false, Disposition: DispositionRejected, ReasonCode: reasonCode, Message: strings.TrimSpace(msg)}
}

func unavailable(index int, reasonCode string, msg string) Decision {
	return Decision{ProposalIndex: index, Approved: false, Disposition: DispositionUnavailable, ReasonCode: reasonCode, Message: strings.TrimSpace(msg)}
}

func confidenceThresholdForModule(moduleKey string, cfg *config.Config) float64 {
	if cfg == nil {
		return 0.0
	}
	switch moduleKey {
	case modulecatalog.KeyGlossary:
		return cfg.Thresholds.Glossary
	case modulecatalog.KeyGrammar:
		return cfg.Thresholds.Grammar
	case modulecatalog.KeyHomophones:
		return cfg.Thresholds.Homophones
	case modulecatalog.KeySpokenWord:
		return cfg.Thresholds.SpokenWord
	default:
		return 0.0
	}
}