fault

Documentation

Overview

Package fault is the agent's canonical error model: typed, wrapped errors classified by how a caller should react. The router, governor, and reconciler branch on a failure's Class, never on string matching, so behaviour stays consistent across processes (fleet/P2P) and through the event log and replay.

Index

• type Class
  • func Classify(err error) Class
• type Error
  • func New(class Class, code, message string) *Error
  • func Wrap(class Class, code string, err error) *Error
  • func (e *Error) Error() string
  • func (e *Error) Unwrap() error

Types

type Class

type Class string

Class is how a caller should react to a failure.

const (
	// Transient failures are worth retrying (network blips, rate limits, 5xx).
	Transient Class = "transient"
	// Terminal failures must not be retried (bad input, 4xx, programmer error).
	Terminal Class = "terminal"
	// NeedsApproval means a governance gate paused the action for a human.
	NeedsApproval Class = "needs_approval"
	// BudgetExceeded means the governor's token/cost ceiling was hit.
	BudgetExceeded Class = "budget_exceeded"
	// Forbidden means a governance gate denied the action outright: it is outside
	// the run's capability grant and must not be retried or escalated.
	Forbidden Class = "forbidden"
	// Cancelled means the context was cancelled or its deadline passed.
	Cancelled Class = "cancelled"
)

func Classify

func Classify(err error) Class

Classify returns the Class a caller should act on. It honours an explicit *Error in the chain, maps context cancellation/deadline, and otherwise treats the failure as Terminal - unknown errors are not retried by default; retry is opted into by classifying explicitly.

type Error

type Error struct {
	Code    string
	Class   Class
	Message string
	// contains filtered or unexported fields
}

Error is a classified, wrapped error. Code is a short stable identifier for the error kind (meaningful across processes and in the event log); Class is the reaction; the wrapped error, if any, is reachable via errors.Unwrap.

func New

func New(class Class, code, message string) *Error

New builds a classified Error with no wrapped cause.

func Wrap

func Wrap(class Class, code string, err error) *Error

Wrap builds a classified Error around an existing cause. The cause supplies the message; use New when there is no underlying error to wrap.

func (*Error) Error

func (e *Error) Error() string

Error implements error.

func (*Error) Unwrap

func (e *Error) Unwrap() error

Unwrap returns the wrapped error, if any.