Files
audita/internal/framework/outcomes/outcomes.go

178 lines
6.5 KiB
Go

// Package outcomes contains processing facts shared by proposal generation,
// validation, and orchestration. Presentation and filesystem concerns live elsewhere.
package outcomes
// OperationKind identifies one logical model operation. Validation input failures
// occur before a model call and therefore have no batch index.
type OperationKind string
const (
OperationProposal OperationKind = "proposal"
OperationCorrectionRepair OperationKind = "correction_repair"
OperationValidation OperationKind = "validation"
OperationValidationInput OperationKind = "validation_input"
)
// Reference is the stable processing identity of an operation. Proposal indices
// are scoped to a module instance, while batch indices are local to a validator
// invocation within one section.
type Reference struct {
StageIndex *int `json:"stage_index,omitempty"`
StageID *string `json:"stage_id,omitempty"`
ModuleKey string `json:"module_key"`
ModuleInstance string `json:"module_instance"`
SectionIndex int `json:"section_index"`
Kind OperationKind `json:"operation"`
ProposalIndex *int `json:"proposal_index,omitempty"`
RepairAttempt *int `json:"repair_attempt,omitempty"`
ValidatorName string `json:"validator_name,omitempty"`
ValidatorOrder *int `json:"validator_order,omitempty"`
BatchIndex *int `json:"batch_index,omitempty"`
}
// ExecutionCounts describe one terminal structured-client call. Available is
// false when an external client provides no execution facts; zero is then unknown.
type ExecutionCounts struct {
Available bool `json:"available"`
ProviderAttempts int `json:"provider_attempts"`
TransientRetries int `json:"transient_retries"`
StructuralRepairs int `json:"structural_repairs"`
RetriesExhausted bool `json:"retries_exhausted"`
HTTPStatus *int `json:"http_status,omitempty"`
}
// FailureClass determines whether processing can skip an operation or must stop.
type FailureClass string
const (
FailureRecoverable FailureClass = "recoverable"
FailureFatal FailureClass = "fatal"
FailureCanceled FailureClass = "canceled"
)
// ReasonCode is a fixed explanation category for the serialized outcome.
type ReasonCode string
const (
ReasonOperationTimeout ReasonCode = "operation_timeout"
ReasonCapacityExceeded ReasonCode = "capacity_exceeded"
ReasonTransportFailed ReasonCode = "transport_failed"
ReasonProviderResponseInvalid ReasonCode = "provider_response_invalid"
ReasonProviderFailed ReasonCode = "provider_failed"
ReasonInvalidOutputExhausted ReasonCode = "invalid_output_exhausted"
ReasonInvalidOutput ReasonCode = "invalid_output"
ReasonValidationInputTooLarge ReasonCode = "validation_input_too_large"
ReasonValidationDecisionsInvalid ReasonCode = "validation_decisions_invalid"
ReasonInputInvalid ReasonCode = "input_invalid"
ReasonSetupFailure ReasonCode = "setup_failure"
ReasonCanceled ReasonCode = "canceled"
ReasonInternalFailure ReasonCode = "internal_failure"
)
type RecoveryReason string
const (
RecoveryCorrectionRevised RecoveryReason = "correction_revised"
RecoveryOutputRepaired RecoveryReason = "output_repaired"
RecoveryServiceRecovered RecoveryReason = "service_recovered"
RecoveryProposalsFiltered RecoveryReason = "proposals_filtered"
RecoveryValidationDecisionsFiltered RecoveryReason = "validation_decisions_filtered"
)
// FilteredProposal attributes a defective response item to its proposal identity.
// Ordinary editorial rejection is a decision, not a filtered proposal.
type FilteredProposal struct {
ProposalIndex int `json:"proposal_index"`
Reason ReasonCode `json:"reason"`
Count int `json:"count"`
}
// Operation is a compact terminal outcome. A successful operation may have one
// recovery with several reasons. A failed operation never has recovery reasons.
type Operation struct {
Reference Reference `json:"reference"`
Counts ExecutionCounts `json:"counts"`
Succeeded bool `json:"succeeded"`
FailureClass FailureClass `json:"-"`
Cause error `json:"-"`
FailureReason ReasonCode `json:"failure_reason,omitempty"`
RecoveryReasons []RecoveryReason `json:"recovery_reasons,omitempty"`
ProposalIndices []int `json:"proposal_indices,omitempty"`
Filtered []FilteredProposal `json:"filtered,omitempty"`
}
type WorkState string
const (
WorkNotStarted WorkState = "not_started"
WorkCompleted WorkState = "completed"
WorkInterrupted WorkState = "interrupted"
)
// ExecutionRecoveries classifies execution counts; callers decide whether their
// operation succeeded before recording these reasons.
func ExecutionRecoveries(counts ExecutionCounts) []RecoveryReason {
var reasons []RecoveryReason
if counts.StructuralRepairs > 0 {
reasons = append(reasons, RecoveryOutputRepaired)
}
if counts.TransientRetries > 0 {
reasons = append(reasons, RecoveryServiceRecovered)
}
return reasons
}
// WorkTotals retains the facts shared by the CLI summary and ordinary reports.
type WorkTotals struct {
Total int
Started int
Completed int
WithErrors int
Corrections int
ModelOperations int
ProposalResponses int
Recoveries int
FilteringResponses int
}
func (t *WorkTotals) Record(state WorkState, operations []Operation) {
if state != WorkNotStarted {
t.Started++
}
if state == WorkCompleted {
t.Completed++
}
hasError := false
for _, operation := range operations {
if operation.Reference.Kind != OperationValidationInput {
t.ModelOperations++
}
if operation.Succeeded {
if operation.Reference.Kind == OperationProposal {
t.ProposalResponses++
if len(operation.Filtered) > 0 {
t.FilteringResponses++
}
}
if len(operation.RecoveryReasons) > 0 {
t.Recoveries++
}
}
hasError = hasError || operation.FailureClass == FailureRecoverable
}
if hasError {
t.WithErrors++
}
}
func (t *WorkTotals) Add(module WorkTotals) {
t.Started += module.Started
t.Completed += module.Completed
t.WithErrors += module.WithErrors
t.Corrections += module.Corrections
t.ModelOperations += module.ModelOperations
t.ProposalResponses += module.ProposalResponses
t.Recoveries += module.Recoveries
t.FilteringResponses += module.FilteringResponses
}