// 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 }