Define invocation outcome reporting types

outcome.go

@@ -1,18 +1,23 @@
 package commandkit
 
 import (
+	"errors"
 	"io"
 	"strings"
 )
 
-// Severity classifies a neutral diagnostic.
+// Severity classifies a nonterminal diagnostic.
 type Severity string
 
 const (
-	// SeverityWarning indicates information that does not fail the operation.
+	// SeverityInfo marks informational content.
+	SeverityInfo Severity = "info"
+	// SeverityWarning marks a concern that does not fail the operation.
 	SeverityWarning Severity = "warning"
-	// SeverityError indicates a diagnostic associated with an error.
-	SeverityError Severity = "error"
+	// SeverityDebug marks diagnostic detail for debug output.
+	SeverityDebug Severity = "debug"
+	// SeverityProgress marks progress information.
+	SeverityProgress Severity = "progress"
 )
 
 // OutcomeKind classifies the result of a command invocation.
@@ -29,88 +34,134 @@ const (
 	OutcomeDomain OutcomeKind = "domain"
 )
 
-// DeliveryState describes whether CommandKit completed diagnostic delivery.
-type DeliveryState string
+// DeliveryState describes the result of presenting content to a destination.
+type DeliveryState uint8
 
 const (
-	// DeliveryNone indicates that no diagnostic delivery was attempted.
-	DeliveryNone DeliveryState = "none"
-	// DeliveryComplete indicates that diagnostic delivery completed.
-	DeliveryComplete DeliveryState = "complete"
-	// DeliveryIncomplete indicates that diagnostic delivery did not complete.
-	DeliveryIncomplete DeliveryState = "incomplete"
+	// DeliveryNone indicates that no content was submitted to the destination.
+	DeliveryNone DeliveryState = iota
+	// DeliverySuppressed indicates that all submitted content was intentionally hidden.
+	DeliverySuppressed
+	// DeliveryComplete indicates that all requested delivery completed.
+	DeliveryComplete
+	// DeliveryIncomplete indicates that rendering or destination writing failed.
+	DeliveryIncomplete
 )
 
-// Diagnostic is a deferred message written to an invocation's error stream.
+// ErrReporterClosed is returned when a reporting handle is used after invocation finalization.
+var ErrReporterClosed = errors.New("reporter is closed")
+
+// Detail renders optional content to the supplied writer.
+type Detail func(io.Writer) error
+
+// Explanation contains terminal content for a failed outcome.
+type Explanation struct {
+	// Message is the literal opening text.
+	Message string
+	// Details render additional content in order.
+	Details []Detail
+}
+
+// PresentationResult records delivery observations for the two output channels.
+type PresentationResult struct {
+	// Output records delivery to the result destination.
+	Output DeliveryResult
+	// Diagnostics records delivery to the diagnostic destination.
+	Diagnostics DeliveryResult
+}
+
+// DeliveryResult records rendering and writing errors for one destination.
+type DeliveryResult struct {
+	// State summarizes content delivery to the destination.
+	State DeliveryState
+	// RenderError is the first rendering error for the destination.
+	RenderError error
+	// WriteError is the first destination write error.
+	WriteError error
+}
+
+// Diagnostic is passive nonterminal message data returned by a provider.
 //
-// Write is called by CommandKit's diagnostic delivery path. It should return
-// any error encountered while writing. A nil Write function has no output.
+// Write renders the diagnostic to a supplied writer when the owning integration
+// submits it through the invocation reporter. A nil Write function has no detail.
 type Diagnostic struct {
 	// Severity classifies the diagnostic without depending on a provider library.
 	Severity Severity
-	// Write writes the diagnostic to the supplied writer.
-	Write func(io.Writer) error
+	// Write renders the diagnostic to the supplied writer.
+	Write Detail
 }
 
-// Acquired pairs a provider value with diagnostics emitted during acquisition.
+// Acquired pairs a provider value with independent diagnostics and failure context.
 type Acquired[T any] struct {
 	// Value is the value returned by the acquisition callback.
 	Value T
-	// Diagnostics are retained for delivery by the invocation coordinator.
+	// Diagnostics are passive nonterminal messages for the owning command to submit.
 	Diagnostics []Diagnostic
+	// Explanation provides terminal context if the owning command returns failure.
+	Explanation Explanation
 }
 
 // Outcome is the classified result of an operation.
 //
-// Cause records the operation error. DeliveryError records an error encountered
-// while presenting diagnostics or reports; it is kept separate from Cause so
-// both failures remain inspectable. Outcome does not implement error.
-// Invocation coordination treats a zero Outcome as success with status 0.
+// Cause records an optional operation error without selecting the outcome or
+// generating operator-facing text. Presentation records delivery observations
+// separately. Invocation coordination treats a zero Outcome as success with status 0.
 type Outcome struct {
 	// Kind classifies the result.
 	Kind OutcomeKind
 	// Status is the suggested process status for this result.
 	Status int
-	// Domain names the application-defined classification when Kind is
-	// OutcomeDomain.
+	// Domain names the application-defined classification when Kind is OutcomeDomain.
 	Domain string
-	// Cause is the error returned by the operation.
+	// Cause is the optional operation error, preserved for caller inspection.
 	Cause error
-	// DeliveryError is an error encountered while writing a report or
-	// diagnostics.
-	DeliveryError error
-	// DiagnosticDelivery records whether diagnostic writing completed. Its zero
-	// value is treated as DeliveryNone by invocation coordination.
-	DiagnosticDelivery DeliveryState
-	// ReportIncomplete is true when a failed write left a report incomplete.
-	ReportIncomplete bool
-	// Diagnostics are delivered in slice order by invocation coordination.
-	Diagnostics []Diagnostic
+	// Explanation contains terminal content for a failed outcome.
+	Explanation Explanation
+	// Presentation records delivery observations populated by CommandKit.
+	Presentation PresentationResult
 }
 
 // Success returns a successful outcome with status 0.
 func Success() Outcome {
-	return Outcome{Kind: OutcomeSuccess, Status: 0, DiagnosticDelivery: DeliveryNone}
+	return Outcome{Kind: OutcomeSuccess}
 }
 
-// Usage returns a usage outcome with status 2 and the supplied cause.
-func Usage(cause error) Outcome {
-	return Outcome{Kind: OutcomeUsage, Status: 2, Cause: cause, DiagnosticDelivery: DeliveryNone}
+// Failure returns an operational outcome with status 1 and a terminal explanation.
+func Failure(message string, details ...Detail) Outcome {
+	return Outcome{Kind: OutcomeOperational, Status: 1, Explanation: Explanation{Message: message, Details: cloneDetails(details)}}
 }
 
-// Failure returns an operational outcome with status 1 and the supplied cause.
-func Failure(cause error) Outcome {
-	return Outcome{Kind: OutcomeOperational, Status: 1, Cause: cause, DiagnosticDelivery: DeliveryNone}
+// Usage returns a usage outcome with status 2 and a terminal explanation.
+func Usage(message string, details ...Detail) Outcome {
+	return Outcome{Kind: OutcomeUsage, Status: 2, Explanation: Explanation{Message: message, Details: cloneDetails(details)}}
 }
 
-// Domain returns an application-domain outcome preserving the supplied name,
-// status, and cause.
-func Domain(name string, status int, cause error) Outcome {
-	return Outcome{Kind: OutcomeDomain, Status: status, Domain: name, Cause: cause, DiagnosticDelivery: DeliveryNone}
+// Domain returns an application-domain outcome with the supplied name and status.
+func Domain(name string, status int) Outcome {
+	return Outcome{Kind: OutcomeDomain, Status: status, Domain: name}
 }
 
-// MessageDiagnostic returns a diagnostic that writes message followed by a
-// newline. The writer's error is returned to the caller.
+// WithExplanation returns a copy of the outcome with the supplied terminal explanation.
+func (o Outcome) WithExplanation(message string, details ...Detail) Outcome {
+	o.Explanation = Explanation{Message: message, Details: cloneDetails(details)}
+	return o
+}
+
+// WithCause returns a copy of the outcome with the supplied optional cause.
+func (o Outcome) WithCause(cause error) Outcome {
+	o.Cause = cause
+	return o
+}
+
+func cloneDetails(details []Detail) []Detail {
+	if details == nil {
+		return nil
+	}
+	return append([]Detail{}, details...)
+}
+
+// MessageDiagnostic returns passive diagnostic data that writes message followed
+// by a newline when submitted through a reporter.
 func MessageDiagnostic(severity Severity, message string) Diagnostic {
 	return Diagnostic{
 		Severity: severity,