Define processing outcomes and failure contracts

2026-09-24 17:01:19 +00:00
parent 8ffbf41b89
commit 7dc1be5a08
8 changed files with 221 additions and 43 deletions
--- a/internal/framework/outcomes/outcomes.go
+++ b/internal/framework/outcomes/outcomes.go
@@ -0,0 +1,92 @@
+// 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"
+	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 {
+	ModuleKey      string        `json:"module_key"`
+	ModuleInstance string        `json:"module_instance"`
+	SectionIndex   int           `json:"section_index"`
+	Kind           OperationKind `json:"operation"`
+	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"`
+}
+
+// ReasonCode is a fixed, safe explanation category. Raw provider errors and
+// prompt content are never stored in an operation 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"
+	ReasonSetupFailure               ReasonCode = "setup_failure"
+	ReasonCanceled                   ReasonCode = "canceled"
+	ReasonInternalFailure            ReasonCode = "internal_failure"
+)
+
+type RecoveryReason string
+
+const (
+	RecoveryOutputRepaired    RecoveryReason = "output_repaired"
+	RecoveryServiceRecovered  RecoveryReason = "service_recovered"
+	RecoveryProposalsFiltered RecoveryReason = "proposals_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"`
+	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"
+)