Document invocation reporting contracts

outcome.go

@@ -6,7 +6,8 @@ import (
 	"strings"
 )
 
-// Severity classifies a nonterminal diagnostic.
+// Severity classifies a nonterminal provider diagnostic. Terminal failure
+// context belongs in an Outcome explanation instead.
 type Severity string
 
 const (
@@ -48,13 +49,18 @@ const (
 	DeliveryIncomplete
 )
 
-// ErrReporterClosed is returned when a reporting handle is used after invocation finalization.
+// 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.
+// Detail renders optional content to the writer supplied by the reporter.
+// Use that writer only during the callback. A callback must not submit another
+// message, queue deferred work, or start another rendering operation through
+// the same invocation's reporter.
 type Detail func(io.Writer) error
 
-// Explanation contains terminal content for a failed outcome.
+// Explanation contains terminal content for a failed outcome. CommandKit
+// presents it during invocation finalization, including in quiet mode.
 type Explanation struct {
 	// Message is the literal opening text.
 	Message string
@@ -62,7 +68,9 @@ type Explanation struct {
 	Details []Detail
 }
 
-// PresentationResult records delivery observations for the two output channels.
+// PresentationResult records output and diagnostic delivery observations
+// populated by CommandKit during invocation finalization. It is not a message
+// submission path or a transcript.
 type PresentationResult struct {
 	// Output records delivery to the result destination.
 	Output DeliveryResult
@@ -71,6 +79,9 @@ type PresentationResult struct {
 }
 
 // DeliveryResult records rendering and writing errors for one destination.
+// The state distinguishes no submitted content, intentionally suppressed
+// content, completed delivery, and incomplete delivery. RenderError and
+// WriteError retain the first error of their kind for that destination.
 type DeliveryResult struct {
 	// State summarizes content delivery to the destination.
 	State DeliveryState
@@ -80,7 +91,9 @@ type DeliveryResult struct {
 	WriteError error
 }
 
-// Diagnostic is passive nonterminal message data returned by a provider.
+// Diagnostic is passive nonterminal message data returned by a provider. It
+// does not emit output or select an invocation outcome; the owning integration
+// submits it through the invocation reporter.
 //
 // 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.
@@ -91,7 +104,9 @@ type Diagnostic struct {
 	Write Detail
 }
 
-// Acquired pairs a provider value with independent diagnostics and failure context.
+// Acquired pairs a provider value with independent diagnostics and failure
+// context. The owning command chooses how to submit each diagnostic and whether
+// to attach the explanation to a failed outcome.
 type Acquired[T any] struct {
 	// Value is the value returned by the acquisition callback.
 	Value T
@@ -101,11 +116,16 @@ type Acquired[T any] struct {
 	Explanation Explanation
 }
 
-// Outcome is the classified result of an operation.
+// Outcome is the classified result of an operation. Constructing or returning
+// an outcome does not itself write output; Execute presents its explanation
+// during finalization.
 //
 // 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.
+// separately. Invocation coordination treats a zero Outcome as success with
+// status 0. Presentation failures change a success or usage outcome to
+// operational status 1; a domain outcome keeps its classification and nonzero
+// status, while a zero domain status becomes 1.
 type Outcome struct {
 	// Kind classifies the result.
 	Kind OutcomeKind
@@ -126,28 +146,38 @@ func Success() Outcome {
 	return Outcome{Kind: OutcomeSuccess}
 }
 
-// Failure returns an operational outcome with status 1 and a terminal explanation.
+// Failure returns an operational outcome with status 1 and a terminal
+// explanation. The message and details are presented once when the outcome is
+// returned from an invocation; an optional operation error can be attached with
+// WithCause and is not rendered automatically.
 func Failure(message string, details ...Detail) Outcome {
 	return Outcome{Kind: OutcomeOperational, Status: 1, Explanation: Explanation{Message: message, Details: cloneDetails(details)}}
 }
 
-// Usage returns a usage outcome with status 2 and a terminal explanation.
+// Usage returns a usage outcome with status 2 and a terminal explanation. The
+// message and details are presented when the outcome is returned from an
+// invocation; an optional cause is preserved separately with WithCause.
 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 with the supplied name and status.
+// Domain returns an application-domain outcome with the supplied name and
+// status. The application owns the classification and status decision.
 func Domain(name string, status int) Outcome {
 	return Outcome{Kind: OutcomeDomain, Status: status, Domain: name}
 }
 
-// WithExplanation returns a copy of the outcome with the supplied terminal explanation.
+// WithExplanation returns a copy of the outcome with the supplied terminal
+// explanation, replacing any existing explanation. CommandKit presents it once
+// during finalization, including in quiet mode.
 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.
+// WithCause returns a copy of the outcome with the supplied optional operation
+// cause. The cause is preserved for caller inspection and does not select an
+// outcome or generate operator-facing text.
 func (o Outcome) WithCause(cause error) Outcome {
 	o.Cause = cause
 	return o