diff --git a/docs/integrations/output-files.md b/docs/integrations/output-files.md index ab11e5b..b350da5 100644 --- a/docs/integrations/output-files.md +++ b/docs/integrations/output-files.md @@ -55,11 +55,12 @@ work unit form one error record. A record with scope `run` records a fatal processing failure or a separate output delivery failure. It identifies the phase, safe reason and message, and available origin. A processing origin can include the operation, validator, batch, proposal index, and repair attempt. -A delivery failure includes the output path when known. A record with scope -`interrupted` preserves an interrupted peer's cause and location when -available. These records do not add to the recoverable work-unit or run-error -counts. The work-unit matrix still marks the interrupted work. Raw provider -errors and transcript text are absent. +A delivery failure includes the output path when known. The initiating +processing failure can include an `interruptions` sequence with each +available peer's phase, safe reason and message, and available origin. +Peer details do not add to the recoverable work-unit or run-error counts. +The work-unit matrix marks interrupted work. Raw provider errors and +transcript text are absent. For `validation_decisions_invalid`, proposal indices identify only candidates whose required decisions were unavailable. Other candidates in the same batch may still be approved or rejected normally. diff --git a/docs/roadmap/remediation.md b/docs/roadmap/remediation.md index 47d4836..b870530 100644 --- a/docs/roadmap/remediation.md +++ b/docs/roadmap/remediation.md @@ -81,6 +81,11 @@ second write failure. Check failure attribution and counts as well as status. ### R2 — Preserve the Version 1 Error Record Discriminator (P2) +**Complete.** Version 1 retains the `work_unit` and `run` scopes. The +initiating run record carries available peer details in an optional +`interruptions` sequence. The mixed-run YAML and Markdown test verifies +peer attribution and unchanged counts. + **Affected plan:** Stage 17, item 1. **Evidence:** [Report projection](../../internal/framework/processreport/report.go#L108) diff --git a/internal/core/reporting/markdown_test.go b/internal/core/reporting/markdown_test.go index 5cc11ec..669055c 100644 --- a/internal/core/reporting/markdown_test.go +++ b/internal/core/reporting/markdown_test.go @@ -100,7 +100,7 @@ func TestStageIDIsLiteralInMarkdownAndExactInYAML(t *testing.T) { snapshot := Snapshot{ StageNames: []string{StageLabel(0, "grammar", &id), StageLabel(1, "grammar", nil)}, WorkUnits: []WorkUnit{{StageIndex: 0, ChunkIndex: 0, State: "completed", ErrorCount: 1}}, - Errors: []ErrorRecord{{Scope: "work_unit", StageID: &id}}, + Errors: []ErrorRecord{{Scope: "work_unit", FailureDetails: FailureDetails{StageID: &id}}}, } header := `| Chunk | 1: grammar (\[party\](https://example.invalid/) \*bold\* \_emphasis\_ \~\~strike\~\~ \\| <tag>) | 2: grammar |` if rows := markdownTableRows(string(Markdown(snapshot))); len(rows) == 0 || rows[0] != header { diff --git a/internal/core/reporting/report.go b/internal/core/reporting/report.go index c47d215..6ff1136 100644 --- a/internal/core/reporting/report.go +++ b/internal/core/reporting/report.go @@ -49,25 +49,31 @@ type Failure struct { } type ErrorRecord struct { - Scope string `yaml:"scope"` - StageIndex *int `yaml:"stage_index,omitempty"` - StageID *string `yaml:"stage_id,omitempty"` - ModuleKey string `yaml:"module_key,omitempty"` - ModuleInstance string `yaml:"module_instance,omitempty"` - ChunkIndex *int `yaml:"chunk_index,omitempty"` - StartSegmentID *int `yaml:"start_segment_id,omitempty"` - EndSegmentID *int `yaml:"end_segment_id,omitempty"` - CorrectionsApplied *int `yaml:"corrections_applied,omitempty"` - Failures []Failure `yaml:"failures,omitempty"` - Phase string `yaml:"phase,omitempty"` - Reason string `yaml:"reason,omitempty"` - Message string `yaml:"message,omitempty"` - Operation string `yaml:"operation,omitempty"` - Validator string `yaml:"validator,omitempty"` - BatchIndex *int `yaml:"batch_index,omitempty"` - ProposalIndex *int `yaml:"proposal_index,omitempty"` - RepairAttempt *int `yaml:"repair_attempt,omitempty"` - OutputPath string `yaml:"output_path,omitempty"` + Scope string `yaml:"scope"` + FailureDetails `yaml:",inline"` + StartSegmentID *int `yaml:"start_segment_id,omitempty"` + EndSegmentID *int `yaml:"end_segment_id,omitempty"` + CorrectionsApplied *int `yaml:"corrections_applied,omitempty"` + Failures []Failure `yaml:"failures,omitempty"` + OutputPath string `yaml:"output_path,omitempty"` + Interruptions []FailureDetails `yaml:"interruptions,omitempty"` +} + +// FailureDetails carries a run failure's classification and available origin. +type FailureDetails struct { + StageIndex *int `yaml:"stage_index,omitempty"` + StageID *string `yaml:"stage_id,omitempty"` + ModuleKey string `yaml:"module_key,omitempty"` + ModuleInstance string `yaml:"module_instance,omitempty"` + ChunkIndex *int `yaml:"chunk_index,omitempty"` + Phase string `yaml:"phase,omitempty"` + Reason string `yaml:"reason,omitempty"` + Message string `yaml:"message,omitempty"` + Operation string `yaml:"operation,omitempty"` + Validator string `yaml:"validator,omitempty"` + BatchIndex *int `yaml:"batch_index,omitempty"` + ProposalIndex *int `yaml:"proposal_index,omitempty"` + RepairAttempt *int `yaml:"repair_attempt,omitempty"` } type FilteredProposal struct { diff --git a/internal/core/reporting/report_test.go b/internal/core/reporting/report_test.go index 0eab73d..a431606 100644 --- a/internal/core/reporting/report_test.go +++ b/internal/core/reporting/report_test.go @@ -13,7 +13,7 @@ func TestYAMLPreservesScalarTypes(t *testing.T) { falseValue := false snapshot := Snapshot{RunID: "secret\\\"key", Status: StatusCompleted, StartedAt: time.Date(2026, 9, 24, 0, 0, 0, 0, time.UTC), Summary: Summary{RunErrors: &zero, CorrectionsApplied: &one}, - Errors: []ErrorRecord{{Scope: "run", Phase: "processing", Reason: "internal_failure", Message: "secret\\\"key 1"}}, + Errors: []ErrorRecord{{Scope: "run", FailureDetails: FailureDetails{Phase: "processing", Reason: "internal_failure", Message: "secret\\\"key 1"}}}, Recoveries: []RecoveryRecord{{StageIndex: 0, Reasons: []string{"service_recovered"}, ExecutionCounts: ExecutionCounts{RetriesExhausted: &falseValue}}}} for _, document := range []any{snapshot.ErrorsDocument(), snapshot.RecoveriesDocument()} { payload, err := YAML(document) diff --git a/internal/framework/processreport/report.go b/internal/framework/processreport/report.go index cc37b5d..b57d516 100644 --- a/internal/framework/processreport/report.go +++ b/internal/framework/processreport/report.go @@ -13,12 +13,13 @@ import ( // RunFailure describes a fatal or output failure without carrying its raw cause. type RunFailure struct { - Phase string - Reason outcomes.ReasonCode - OutputPath string - Origin *outcomes.Reference - StageIndex *int - HasSection bool + Phase string + Reason outcomes.ReasonCode + OutputPath string + Origin *outcomes.Reference + StageIndex *int + HasSection bool + interruptions []reporting.FailureDetails } type BuildInput struct { @@ -82,7 +83,7 @@ func Build(input BuildInput) reporting.Snapshot { } operations := append([]outcomes.Operation(nil), unit.Operations...) sort.SliceStable(operations, func(i, j int) bool { return operationLess(operations[i], operations[j]) }) - var failures []reporting.Failure + var unitFailures []reporting.Failure unitHasError := false unitRecoveries := 0 for _, operation := range operations { @@ -92,7 +93,7 @@ func Build(input BuildInput) reporting.Snapshot { } if operation.FailureClass == outcomes.FailureRecoverable { unitHasError = true - failures = append(failures, mapFailure(operation)) + unitFailures = append(unitFailures, mapFailure(operation)) } } row := reporting.WorkUnit{StageIndex: unit.ModuleIndex, StageID: unit.StageID, ModuleKey: unit.ModuleKey, ModuleInstance: unit.ModuleInstance, @@ -101,14 +102,13 @@ func Build(input BuildInput) reporting.Snapshot { if unitHasError { row.ErrorCount = 1 stage, chunk, start, end, applied := unit.ModuleIndex, unit.Section.Index, unit.Section.StartSegmentID, unit.Section.EndSegmentID, unit.CorrectionsApplied - snapshot.Errors = append(snapshot.Errors, reporting.ErrorRecord{Scope: "work_unit", StageIndex: &stage, StageID: unit.StageID, - ModuleKey: unit.ModuleKey, ModuleInstance: unit.ModuleInstance, ChunkIndex: &chunk, - StartSegmentID: &start, EndSegmentID: &end, CorrectionsApplied: &applied, Failures: failures}) + snapshot.Errors = append(snapshot.Errors, reporting.ErrorRecord{Scope: "work_unit", + FailureDetails: reporting.FailureDetails{StageIndex: &stage, StageID: unit.StageID, + ModuleKey: unit.ModuleKey, ModuleInstance: unit.ModuleInstance, ChunkIndex: &chunk}, + StartSegmentID: &start, EndSegmentID: &end, CorrectionsApplied: &applied, Failures: unitFailures}) } - if unit.Failure != nil && !errors.Is(input.ProcessingError, unit.Failure) { - record := failureRecord(processingFailure(unit.Failure, "processing")) - record.Scope = "interrupted" - snapshot.Errors = append(snapshot.Errors, record) + if input.ProcessingError != nil && unit.Failure != nil && !errors.Is(input.ProcessingError, unit.Failure) { + failures[0].interruptions = append(failures[0].interruptions, failureDetails(processingFailure(unit.Failure, "processing"))) } snapshot.WorkUnits = append(snapshot.WorkUnits, row) for _, repair := range unit.Repairs { @@ -148,8 +148,13 @@ func Build(input BuildInput) reporting.Snapshot { } func failureRecord(failure RunFailure) reporting.ErrorRecord { - record := reporting.ErrorRecord{Scope: "run", Phase: failure.Phase, Reason: string(failure.Reason), - Message: safeMessage(failure.Reason), OutputPath: failure.OutputPath, StageIndex: failure.StageIndex} + return reporting.ErrorRecord{Scope: "run", FailureDetails: failureDetails(failure), + OutputPath: failure.OutputPath, Interruptions: failure.interruptions} +} + +func failureDetails(failure RunFailure) reporting.FailureDetails { + record := reporting.FailureDetails{Phase: failure.Phase, Reason: string(failure.Reason), + Message: safeMessage(failure.Reason), StageIndex: failure.StageIndex} if failure.Origin != nil { record.ModuleKey, record.ModuleInstance = failure.Origin.ModuleKey, failure.Origin.ModuleInstance record.StageID = failure.Origin.StageID diff --git a/internal/framework/processreport/report_test.go b/internal/framework/processreport/report_test.go index fe2a7db..f704b35 100644 --- a/internal/framework/processreport/report_test.go +++ b/internal/framework/processreport/report_test.go @@ -233,20 +233,27 @@ func TestReportsDistinguishFatalPeerAndDeliveryFailures(t *testing.T) { t.Fatal(err) } if doc.Status != reporting.StatusFailed || *doc.Summary.WorkUnitsWithErrors != 1 || *doc.Summary.RunErrors != 2 || - *doc.Summary.WorkUnitsInterrupted != 2 || *doc.Summary.Recoveries != 1 || len(doc.Errors) != 4 { + *doc.Summary.WorkUnitsInterrupted != 2 || *doc.Summary.Recoveries != 1 || len(doc.Errors) != 3 { t.Fatalf("unexpected report: %s", raw) } - unit, secondary, initiating, delivery := doc.Errors[0], doc.Errors[1], doc.Errors[2], doc.Errors[3] + unit, initiating, delivery := doc.Errors[0], doc.Errors[1], doc.Errors[2] if unit.Scope != "work_unit" || len(unit.Failures) != 1 || !reflect.DeepEqual(unit.Failures[0].ProposalIndices, []int{4}) || unit.Failures[0].ProviderAttempts == nil || *unit.Failures[0].ProviderAttempts != 1 || - secondary.Scope != "interrupted" || !reflect.DeepEqual(secondary.ChunkIndex, intPtr(3)) || secondary.Reason != "canceled" || initiating.Scope != "run" || initiating.Phase != "validation" || initiating.Validator != "review" || !reflect.DeepEqual(initiating.ChunkIndex, intPtr(2)) || !reflect.DeepEqual(initiating.ProposalIndex, intPtr(3)) || !reflect.DeepEqual(initiating.RepairAttempt, intPtr(1)) || - delivery.Scope != "run" || delivery.Phase != "report_write" || delivery.OutputPath != "recoveries.yml" || + delivery.Scope != "run" || delivery.Phase != "report_write" || delivery.OutputPath != "recoveries.yml" || len(delivery.Interruptions) != 0 || strings.Contains(string(raw), defect.Error()) { t.Fatalf("failure facts were merged or lost: %s", raw) } + if len(initiating.Interruptions) != 1 { + t.Fatalf("missing peer interruption: %s", raw) + } + secondary := initiating.Interruptions[0] + if secondary.Phase != "validation" || secondary.Reason != "canceled" || secondary.Validator != "review" || + !reflect.DeepEqual(secondary.ChunkIndex, intPtr(3)) || !reflect.DeepEqual(secondary.StageIndex, intPtr(1)) { + t.Fatalf("peer lost its origin or reason: %+v", secondary) + } if markdown := string(reporting.Markdown(snapshot)); !strings.Contains(markdown, "Errors: 1 work units; 2 run errors") || !strings.Contains(markdown, "Recoveries: 1") { t.Fatalf("Markdown totals differ from YAML: %s", markdown)