actionableerror

Documentation

Overview

Package actionableerror owns the stable CLI/MCP recovery guidance envelope.

Index

• Constants
• func WithDiagnostic(reason string, cause error) error
• type Contract
  • func Diagnostic(reason string) (Contract, bool)
  • func Diagnostics() []Contract
  • func FromError(err error) (Contract, bool)
  • func New(code, reason, message string, guidance []string, retryable bool) Contract
  • func (c Contract) Validate() error
• type RecordedFailure
  • func RecordedFailures() []RecordedFailure

Constants

const SchemaVersionV1 = "stackkit.actionable-error/v1"

Functions

func WithDiagnostic

func WithDiagnostic(reason string, cause error) error

WithDiagnostic attaches a known condition at its construction boundary. The original error remains available for evidence and errors.Is/As; public text contains only the authority-owned cause.

Types

type Contract

type Contract struct {
	SchemaVersion string   `json:"schemaVersion"`
	Code          string   `json:"code"`
	ReasonCode    string   `json:"reasonCode"`
	Message       string   `json:"message"`
	UserGuidance  []string `json:"userGuidance"`
	Retryable     bool     `json:"retryable"`
	// RetryAfter is the RFC 3339 UTC time an external authority named for the
	// next attempt; it is omitted when no authority named one.
	RetryAfter string `json:"retryAfter,omitempty"`
}

func Diagnostic

func Diagnostic(reason string) (Contract, bool)

Diagnostic is a closed lookup, never a classification of arbitrary reason text. RetryAfter remains supplied by the observed external authority.

func Diagnostics

func Diagnostics() []Contract

Diagnostics is the deterministic projection used by the self-check plan and troubleshooting generator. A catalog entry is guidance, not measured health.

func FromError

func FromError(err error) (Contract, bool)

FromError preserves typed recovery and denial contracts, including external RetryAfter. Callers still own redaction and the transport's outcome status.

func New

func New(code, reason, message string, guidance []string, retryable bool) Contract

func (Contract) Validate

func (c Contract) Validate() error

type RecordedFailure

type RecordedFailure struct {
	Failure string   `json:"failure"`
	Reasons []string `json:"reasonCodes"`
}

func RecordedFailures

func RecordedFailures() []RecordedFailure

RecordedFailures indexes the historical terminal conditions to the same contracts; consumers never maintain a separate copy of this mapping.